SovAIHub

Labs / Coding Agent v0.1

Basic local coding workflow

A hands-on Python bug fix with local inference, human approval, and a separate container test run.

Get the code on GitHubAll labs

In this basic AI coding agent lab, use a local coding model to fix a small Python bug, review its proposed change, and approve it before running tests in a container.

This lab uses SovAIHub Coding Agent v0.1, Ollama, and qwen2.5-coder:7b. The agent reads one selected file and requests a correction from Ollama on your machine. It previews a diff and requires explicit approval before writing a change.

This is a local coding prototype. The test container has networking disabled, but the agent and Ollama run on the host. This lab does not establish a complete air-gapped security boundary.

What you will demonstrate

  1. Agent safety tests pass.
  2. Calculator tests fail because of a deliberate bug.
  3. The agent previews a proposed correction without modifying the file.
  4. You review a fresh proposal and type APPROVE to apply it.
  5. Calculator tests pass in the isolated Docker container.

The agent safety tests and calculator tests are separate suites. An initial calculator failure is an expected part of this exercise.

Prerequisites

  • Python 3.10 or newer.
  • Ollama installed and running locally.
  • Docker Engine and Docker Compose. On Windows, start Docker Desktop and use its Linux container engine.
  • A copy of this repository, downloaded from GitHub or cloned locally.
  • Internet access for the initial model and container image downloads.

Open a terminal in the repository root, where README.md and compose.test.yaml are located. All commands below run from that directory and work in PowerShell.

Check the installed tools:

python --version
ollama --version
docker version
docker compose version

docker version must show both client and server information. A client-only result with a connection error means the engine is not ready.

No third-party Python packages are required.

1. Download the model and test image

While connected to the internet, run:

ollama pull qwen2.5-coder:7b
docker pull python:3.12-slim

Verify both artifacts are available locally:

ollama list
docker image inspect python:3.12-slim

Keep Ollama and Docker running throughout the exercise. After these downloads, the commands in this lab use the local model and image. You can repeat the exercise with external networking disconnected; that is a functional offline check, not a certification of host isolation.

2. Run the agent safety tests

python -m unittest discover -s tests -v

Expected result: OK.

On Windows without permission to create symlinks, the symlink test is skipped and the result includes OK (skipped=1). That means the remaining checks passed; symlink rejection has not been exercised in that run. Windows Developer Mode or an elevated terminal allows that test to run.

These tests check file-path guards. They do not invoke the model or test the calculator.

3. Prepare the deliberately broken calculator

The calculator might already be fixed if you have run the exercise before. For a reproducible starting point, open examples/buggy_calc/calculator.py and set its contents to:

def add(a, b):
    return a - b

The subtraction is intentional. Keep the test in examples/buggy_calc/test_calculator.py unchanged: it expects add(2, 3) to return 5.

Only reset this example file; preserve any unrelated work.

4. Observe the calculator test fail

docker compose -f compose.test.yaml run --rm --pull never tests

Expected result includes:

AssertionError: -1 != 5
...
FAILED (failures=1)

A nonzero exit code is expected here. It demonstrates the calculator bug, not a Docker or agent setup failure.

The container uses the downloaded image, has networking disabled, and mounts the example directory read-only. --pull never prevents an image download and fails if the image is missing.

5. Preview the proposed correction

python -m sovai.agent --repo examples/buggy_calc --file calculator.py --task "Fix the add function so it returns the sum of its arguments"

The agent prints a proposed diff. A suitable correction would look like:

-    return a - b
+    return a + b

Model output can vary. Review the full diff and ensure it addresses the requested bug without unrelated edits.

This command is preview-only: calculator.py should still contain the subtraction afterward.

6. Review and approve the change

python -m sovai.agent --repo examples/buggy_calc --file calculator.py --task "Fix the add function so it returns the sum of its arguments" --apply

This makes a fresh model request. It does not apply a saved copy of the previous preview, so review the displayed diff again.

If the proposal is correct, enter:

APPROVE

Expected confirmation:

Applied. Review the file and run isolated tests separately.

Any other response rejects the proposal without applying it. If the source changes during review, the agent refuses to overwrite it.

7. Confirm the calculator test passes

Run the same container test command again:

docker compose -f compose.test.yaml run --rm --pull never tests

Expected result:

Ran 1 test in ...

OK

The exact timing varies. The important result is that the same test which failed before the correction now passes.

The agent does not run tests automatically. Running this command is a separate, explicit step.

Repeat the exercise

Restore the subtraction shown in step 3 and repeat steps 4–7. There is no need to download the model or image again while they remain installed.

Try your own Python file

After completing the calculator example, try a small file in a trusted workspace:

python -m sovai.agent --repo path/to/your-project --file example.py --task "Describe the specific correction you want"

Use a relative file path with forward slashes. v0.1 reads only the selected file, with a maximum size of 20 KB; it does not discover dependencies or make multi-file changes. Review file contents before sending them to the local model.

Start with a preview, then add --apply when you are ready to review and approve a fresh proposal.

The supplied compose.test.yaml only tests examples/buggy_calc. It does not follow the agent's --repo argument. Testing another project requires its own test configuration.

Troubleshooting

  • Docker reports that dockerDesktopLinuxEngine cannot be found: Start Docker Desktop, wait for the Linux engine to be ready, and rerun docker version.

  • Docker cannot find python:3.12-slim with --pull never: While connected, run docker pull python:3.12-slim using the same Docker engine/context.

  • The agent cannot connect to Ollama: Start Ollama. If it is not managed by the desktop application, run ollama serve in another terminal.

  • Ollama cannot find the model: Check ollama list; download qwen2.5-coder:7b while connected if it is missing.

  • Inference times out or is very slow: Confirm the model runs locally and inspect available memory and Ollama's runtime status. The agent uses a 240-second request timeout.

  • The agent says “Model proposed no changes”: Check whether the calculator already contains return a + b; restore the deliberate bug to repeat the lab.

  • The baseline calculator test passes: Confirm step 3 was completed and that the example contains subtraction.

  • The calculator test still fails after approval: Inspect the applied file and the failure output. Model proposals are not guaranteed to be correct.

Scope and next steps

v0.1 demonstrates local inference, single-file proposals, explicit approval, and a separate container test run. Its local audit log is stored at ~/.sovai/audit.jsonl and is not tamper-proof.

Future milestones:

  • v0.2 — Repository-aware agent: relevant-file discovery, dependency context, and multi-file changes.
  • v0.3 — Security and approvals: secure patch staging, command allowlists, separate execution isolation, and policy-driven approvals.
  • v0.4 — Air-gapped distribution: verified offline model import, OCI images, artifact manifests, and egress validation.

Before publishing a release, record an actual end-to-end run on the target laptop. Include the operating system, Python version, model tag, image digest, and before/after test results. Report GPU acceleration only if it was separately observed. Expected output in this guide is instructional and is not evidence that a particular machine has completed the workflow.