Runbook: Environment Bootstrap (Phase 0)¶

Operational guide for standing up and validating a development environment.

Prerequisites¶

Tool	Min version	Check
Python	3.11 (3.14 verified)	`py --version`
Node.js	20 (22 verified)	`node --version`
pnpm	10	`pnpm --version`
Docker + Compose	24 / v2	`docker compose version`
Ollama	0.12+	`ollama --version`

1. Start Ollama and pull the default models¶

ollama serve            # if not already running as a service
ollama pull llama3.2:3b
ollama pull nomic-embed-text
ollama list

2. Bootstrap the backend¶

.\scripts\bootstrap.ps1            # venv + install + .env + diagnose
# or manually:
py -3.14 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".\backend[dev]"
Copy-Item .env.example .env

3. Validate (the Phase 0 gate)¶

.\.venv\Scripts\aop.exe diagnose

diagnose exits non-zero if any required check fails (those marked *: Ollama daemon, default chat model, default embed model). Cloud keys and data services are optional in Phase 0.

Smoke-test the unified adapter against the local model:

.\.venv\Scripts\aop.exe chat "Reply with one word: pong"
.\.venv\Scripts\aop.exe embed "hello world"

4. (Optional) bring up data infrastructure¶

Not required for Phase 0; needed from Phase 1 onward.

docker compose up -d
.\.venv\Scripts\aop.exe diagnose      # data-source rows flip to OK

Troubleshooting¶

Symptom	Cause	Fix
`ollama daemon ... DOWN`	daemon not running	`ollama serve`; confirm `AOP_OLLAMA_BASE_URL`.
`default chat/embed model ... MISSING`	model not pulled	`ollama pull <model>`.
`pip install` builds from source / fails	no wheels for this Python	Use a Python 3.11/3.12 venv (see ADR-0002 / runtime warning).
cloud provider `DOWN` under `--probe`	bad/expired key	re-check `AOP_<PROVIDER>_API_KEY`.
mypy passes locally but CI differs	config not loaded	run mypy from `backend/` (`cd backend; mypy aop`).

Quality gates (run before pushing)¶

.\.venv\Scripts\ruff.exe check backend
.\.venv\Scripts\ruff.exe format --check backend
cd backend; ..\.venv\Scripts\mypy.exe aop; cd ..
cd backend; ..\.venv\Scripts\python.exe -m pytest -m "not live"; cd ..