DigitalOcean Inference Error Explainer

This is the runnable companion to the blog post. Use it to try the error explainer, inspect the API request, run mocked tests, and compare models with the included evaluation dataset.

The blog post contains the architecture, reasoning, and evaluation results. This repository stays focused on running the experiment.

Run it

make install
cp .env.example .env

Add your model access key to .env:

DIGITALOCEAN_INFERENCE_KEY=replace-with-your-model-access-key

Then start the app:

make run

Open http://localhost:8080. Load the Python, Docker, or Postgres example—or paste your own error—and select Explain this error.

Each submitted explanation is a billable DigitalOcean Inference request.

Run the tests

make check

The tests mock DigitalOcean Inference, so they do not use the key or create Inference charges.

Try another model

Change the model ID in .env and restart the app:

DIGITALOCEAN_INFERENCE_MODEL=mimo-v2.5-pro

The result shows the actual model, latency, and token usage.

Evaluate models

The evaluation/ directory contains:

• errors.jsonl — 16 errors with expected diagnoses.
• system-prompt.txt — the prompt used for model comparisons.
• README.md — recommended evaluation metrics.

Upload errors.jsonl in DigitalOcean Inference → Evaluations to compare candidate models on the same workload.

Try an Inference Router

After creating a router named error-explainer, scope the model access key to it and change:

DIGITALOCEAN_INFERENCE_MODEL=router:error-explainer

The app does not need a code change. Its result metadata shows the selected model and route.

Repository map

.
├── app/
│   ├── config.py       # Environment configuration
│   ├── inference.py    # DigitalOcean request and response validation
│   ├── main.py         # FastAPI routes
│   ├── models.py       # Pydantic request and result schemas
│   └── static/         # Browser interface
├── evaluation/         # Model-comparison inputs and prompt
├── tests/              # Mocked API and inference tests
├── .env.example        # Safe configuration template
├── Makefile            # Install, run, and test commands
└── pyproject.toml      # Dependencies and tooling

Do not paste credentials or unnecessary personal data into error logs. Review all AI-generated diagnoses and commands before acting on them.