CODI The Offline-Rules-First Dockerfile Optimizer

CODI Installation & Setup Guide

This guide covers prerequisites, installation paths, environment configuration, and troubleshooting tips for running CODI locally or in CI.

1. Prerequisites

Component Requirement Notes
Python 3.12.x System Python or pyenv virtualenv.
pip / venv Latest python3 -m venv used by make setup.
Docker 24+ with BuildKit Required for container workflows.
Make Optional Simplifies scripted tasks.
Git Latest stable Needed to clone repositories and manage adapters.

Platform Notes

2. Clone Repository

git clone <repository-url>
cd AI-Hackathon

3. Local CLI Setup

3.1 Create Virtual Environment

make setup
source .venv/bin/activate

make setup creates .venv/, upgrades pip, installs CODI in editable mode with dev dependencies, and prepares CLI entrypoint codi.

3.2 Verify Installation

codi --version
python -m pytest -q

3.3 Environment Variables

Variable Purpose Default
CODI_OUTPUT_ROOT Run artefact root runs/
RULES_PATH Alternate rules file patterns/rules.yml
AIRGAP Block outbound HTTP true
AIRGAP_ALLOWLIST Comma-separated hosts (empty)
LLM_ENABLED Enable assist calls false (Slim)
LLM_ENDPOINT Remote LLM URL http://127.0.0.1:8081
CODE_MODEL Base model id qwen2.5-coder-1.5b
ADAPTER_PATH Adapter directory /models/adapters/qwen15b-lora-v0.1

Set them in your shell profile or prefix CLI commands:

export CODI_OUTPUT_ROOT="$HOME/codi-runs"
export AIRGAP_ALLOWLIST="internal.registry.local"

4. Running the CLI

4.1 End-to-End Optimisation

codi run demo/node
LATEST=$(ls -dt runs/* | head -n 1)
codi report "$LATEST"

4.2 Single Command (codi all)

codi all demo/python

4.3 Smoke Tests

python -m pytest tests/test_smoke.py

5. Container Workflows

5.1 Build Images

make build-slim
make build-complete

5.2 Run Slim Container (API)

docker run --rm -it -v "$PWD:/work" -p 8000:8000 codi:slim

5.3 Run CLI Inside Slim Container

docker run --rm -v "$PWD:/work" codi:slim \
  codi all /work/demo/java --dry-run

5.4 Run Complete Container (LLM enabled)

docker run --rm -it \
  -v "$PWD:/work" \
  -v "$HOME/.codi-models/adapters:/models/adapters" \
  -e AIRGAP=true \
  -e LLM_ENABLED=true \
  -p 8000:8000 -p 8081:8081 \
  codi:complete

Mount /models with adapters and weights before enabling LLM services. Use docker/scripts/verify_adapter.py to validate adapters.

6. IDE Integration

7. Troubleshooting

Symptom Resolution
ModuleNotFoundError: core Activate .venv or run make setup to install editable package.
codi: command not found Ensure .venv/bin is on PATH or run python -m cli.main.
Docker build fails due to permissions Use sudo usermod -aG docker $USER (Linux) and re-login.
Adapter validation fails Check that adapter_config.json and adapter_model.safetensors exist and match metadata checksums.
AIRGAP blocking API tests Set AIRGAP_ALLOWLIST="testserver" when running FastAPI test client.
CLI cannot write to runs/ Set CODI_OUTPUT_ROOT to a directory where the user has write permissions.

8. Maintenance Commands

make clean           # Remove venv, caches, runs/
make lint            # Ruff + Black (check mode)
make format          # Ruff imports + Black formatter
make test            # Full pytest suite
make data-prepare    # Run data pipeline (incremental)

9. Next Steps