Compile Models to DXNN With an AI Coding Agent

With agent-driven development for DX-COM, you describe your model in plain English and an AI coding agent compiles it for the DEEPX DX-M1 NPU. The agent writes the config.json, prepares calibration data, runs the DX-COM compiler, and checks that the compiled model still gives the right answers.

This guide walks you through the whole path: setup, your first prompt, the questions the agent asks, and what you get back. At the end you'll have a .dxnn model and an inference app you can run.

The short version

1. Open the dx-compiler folder in your AI coding tool.
2. Tell the agent what you want, for example: "Convert my yolo26x-custom.pt to DXNN for DX-M1."
3. Answer the agent's questions (up to three).
4. Wait while it converts, compiles, and verifies.
5. Run bash setup.sh && bash run.sh from the session folder.

Key terms

• ONNX is a common file format for trained models. PyTorch and most other frameworks can export to it.
• DXNN is DEEPX's compiled model format. The DX-M1 NPU runs .dxnn files.
• Quantization converts a model to INT8 numbers so it runs fast on an NPU.
• Calibration data is a set of sample images the compiler uses to learn what typical inputs look like during quantization.
• NMS (non-maximum suppression) removes duplicate detection boxes from a detector's output.
• PPU lets the DX-M1 run detection postprocessing in hardware.

How the pipeline works

PyTorch (.pt)  ──►  ONNX (.onnx)  ──►  DXNN (.dxnn)
      dx-model-converter    dx-dxnn-compiler
                 (routed by dx-compiler-builder)

Three agents split the work. dx-model-converter handles PyTorch to ONNX. dx-dxnn-compiler handles ONNX to DXNN. dx-compiler-builder is the router: it reads your request and hands it to the right one. In most tools you never name an agent yourself.

The target is always the DX-M1, so the agent never asks about hardware.

Before you start

Compile on a PC, run on your device. DX-COM needs an x86_64 machine. It doesn't support ARM64, so it doesn't run on a Raspberry Pi 5. You compile on the PC, then copy the finished .dxnn file to your device however you prefer. That device can be a Sixfab AI HAT+, a Sixfab Edge AI Expansion Board, or an ALPON X5 AI. One compiled .dxnn file works on all three. For the full two-machine picture, see the AI model deployment overview.

Choose your tool

Every tool loads the project's configuration on its own when you open dx-compiler. You don't set anything up.

Step 1: Get the project and open it

Clone the repository on your compile PC and install DX-COM:

git clone https://github.com/DEEPX-AI/dx-compiler
cd dx-compiler

./install.sh

cd dx_com
pip install dx_com*.whl

dxcom --version

cd ..

Expected result: dxcom --version prints the installed DX-COM version. The last cd .. takes you back to the repository root, where you start your tool.

Then start your tool from inside that folder. Each tool finds its configuration file there (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, or .cursor/rules/).

# Claude Code
claude

# OpenCode
opencode

# Codex CLI
codex

# GitHub Copilot: open the folder in VS Code
code .

# Cursor: open the folder in Cursor
cursor .

Step 2: Tell the agent what you want

State your model, the result you want, and any settings you already know. Pick the case that fits.

Convert a PyTorch model to ONNX

Convert my yolo26x-custom.pt to ONNX with opset 17 and input shape [1, 3, 640, 640]

In Copilot, start with @dx-model-converter. In OpenCode, use /dx-agent-compiler-convert or @dx-model-converter.

Compile an ONNX model to DXNN

Compile model.onnx to DXNN with INT8 quantization using EMA calibration with 200 samples from ./calibration_images/

In Copilot, start with @dx-dxnn-compiler. In OpenCode, use /dx-agent-compiler-compile or @dx-dxnn-compiler.

Go from PyTorch to DXNN in one request

Convert my yolo26x-custom.pt to DXNN for DX-M1

In Copilot and OpenCode, start with @dx-compiler-builder. In Claude Code, the router coordinates both stages for you.

Get better results with your prompt

• Name the exact file (yolo26x-custom.pt works better than "my model").
• Include the input shape if you know it.
• Point the agent at your own calibration images. Images from your real use case give better accuracy than generic ones.
• Skip settings you're unsure about. The agent fills them in (see What the agent decides for you).

Step 3: Answer the agent's questions

Before it compiles anything, the agent asks up to three questions. They're mandatory, so expect them every time.

1. Should the exported model be NMS-free? (PyTorch to ONNX)

The agent detects your YOLO version and recommends a mode:

2. Should the agent simplify the ONNX model?

The default is no. Simplifying gives you a cleaner graph and a smaller file. The cost: possible precision loss, harder debugging, a small risk of breaking the model, and changed input names. Say yes only if you have a reason. If you do, the agent runs onnx-simplifier after export.

3. Should the model compile with PPU? (ONNX to DXNN, detection models)

If you choose PPU, the agent sets the type for you: type 0 for anchor-based YOLOv3 to v7, type 1 for anchor-free YOLOv8 and later.

Step 4: Review the results

The agent saves everything for a run in its own session folder, so runs never overwrite each other:

dx-agent-dev/<session_id>/
├── calibration_dataset   → ../../dx_com/calibration_dataset/ (symlink)
├── config.json           (auto-generated)
├── model.onnx            (your input, or the converted result)
├── model.dxnn            (the compiled model)
├── compiler.log          (compilation log)
├── detect_model.py       (inference application)
├── verify.py             (ONNX vs DXNN comparison)
├── setup.sh              (environment setup)
├── run.sh                (inference launcher)
└── README.md             (session report with file list)

The session ID looks like YYYYMMDD-HHMMSS_<agent>_<model>_<task>, where <agent> is claude, codex, copilot, cursor, or opencode. To save somewhere else, say so in your prompt and the agent uses a custom path.

The agent checks its own work

Before it reports success, the agent runs verify.py. The script feeds the same sample image to your original ONNX model and to the compiled DXNN model, then compares the outputs:

On a pass, the compiled model and the generated app agree with your original. On a fail, the agent debugs and fixes the problem before it tells you it's done.

This check exists for a reason: a compiled model can hit a great FPS number while the generated app still returns wrong results, for example from a class-index mix-up or a bounding box decoding bug. Speed doesn't prove correctness.

Step 5: Run the model

Every session that creates an inference app also creates setup.sh and run.sh. From the session folder, run:

bash setup.sh && bash run.sh

setup.sh checks for dx-runtime (and installs missing parts), checks that dxcom is available, creates a virtual environment, and installs dx_engine, opencv-python, numpy, and onnxruntime. run.sh then runs inference on a sample image that matches your model's task.

Expected result: the app processes a sample image and prints or draws the model's output. For a detection model, you'll see detected objects with labels and boxes.

Note: setup.sh installs software on your machine. Read it first if you want to know what it changes.

Warm up with the sample models

If this is your first run, start with DEEPX's bundled samples. They confirm your setup works before you bring your own model.

cd dx-compiler

./example/1-download_sample_models.sh                # Download ONNX + JSON configs
./example/2-download_sample_calibration_dataset.sh   # Download calibration dataset
./example/3-compile_sample_models.sh                 # Compile all sample models to .dxnn

The samples are YOLOV5S-1, YOLOV5S_Face-1, and MobileNetV2-1. The downloaded JSON files double as reference configs: the agent reads them when it writes a config.json for your model.

What the agent decides for you

Give the agent a model and calibration data, and it fills in these config.json fields:

Calibration data is handled too. The agent looks for dx_com/calibration_dataset/ (100 JPEG images). If it's missing, the agent downloads the sample set with example/2-download_sample_calibration_dataset.sh, links it into your session folder, and writes the relative path ./calibration_dataset into config.json.

The sample set is fine for a first run. For better accuracy, point the agent at images from your real use case.

Limits to know

Troubleshooting

Still stuck? Ask the agent to debug it. It has a debugging skill (/dx-swe-debugging) that finds the cause before it proposes a fix.

Optional skills

You can call these by name in tools that support slash commands, or describe the same intent in plain language.

Next steps

1. Copy the .dxnn file to your device. Use whatever method you prefer: scp, a USB drive, or your own tooling.
2. Install the runtime on the device. Follow the quickstart for your product: Sixfab AI HAT+, Sixfab Edge AI Expansion Board, or ALPON X5 AI.
3. Build an app around your model. The DX-APP guide shows how to generate a Python or C++ inference app with an AI coding agent.
4. Tune the compile. The DX-COM configuration reference explains every config.json field, and the deployment workflow covers the manual path.

FAQ

What is agent-driven development for DX-COM?

It's a way to compile models for the DEEPX DX-M1 NPU by talking to an AI coding agent. You describe your model and goal, and the agent handles config.json, calibration data, compilation, and verification.

Which AI coding tools work with it?

Claude Code, GitHub Copilot in VS Code, Cursor, OpenCode, and Codex CLI. Each one loads the project's configuration automatically when you open the dx-compiler folder.

Can I compile on a Raspberry Pi 5?

No. DX-COM doesn't support ARM64, so it needs an x86_64 PC running Ubuntu 20.04, 22.04, 24.04, or 26.04. Compile there, then copy the .dxnn file to your Sixfab AI HAT+, Edge AI Expansion Board, or ALPON X5 AI.

Do I need to write config.json myself?

No. The agent generates it from your model and calibration data. You can still ask it to change any value.

What do the [DX-AGENT-DEV: START] and [DX-AGENT-DEV: DONE ...] lines mean?

They're fixed markers the agent prints at the start and end of each task, mainly for automated testing. The DONE line includes your output folder, for example [DX-AGENT-DEV: DONE (output-dir: dx-agent-dev/<session_id>)], so you can see where your files went.

Does it work with models other than YOLO?

Yes for classification: the bundled samples include MobileNetV2, and the agent applies classification preprocessing defaults. NMS-free export and PPU apply to detection models only.

Why do my compiled model and ONNX model give different results?

INT8 quantization causes small differences. Large ones usually mean unrepresentative calibration images or a postprocessing bug. Run verify.py on the same image, and try 200 or more real calibration images.