# Step-by-step runbook Commands use PowerShell on Windows and assume the repository root is current. ## 1. Prepare tools and environment Prerequisites: Python 3.11+, Podman 5+, a running `podman machine`, and an OpenAI-compatible chat/embedding endpoint. ```powershell Copy-Item .env.example .env py -3.12 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip python -m pip install -e ".[test]" ``` Edit `.env`: set `POSTGRES_PASSWORD`, matching `DATABASE_URL` credentials, `LLM_API_KEY`, model names/dimensions, and a random `INTERNAL_JWT_SECRET` of at least 32 bytes. ## 2. Start the stack ```powershell podman machine start podman compose up --detach --build podman compose ps Invoke-RestMethod http://127.0.0.1:8080/internal/knowledge-graph/health Invoke-RestMethod http://127.0.0.1:8080/internal/knowledge-graph/ready ``` Compose starts PostgreSQL, applies migrations, and then starts API and worker. The migration service must complete before the application services start. ## 3. Supply a source handoff Place a UTF-8 JSONL file in `.\artifacts`, or configure a PostgreSQL source table. Validate it against the [source contract](./source-contract.md). For a file handoff, use `.\artifacts\mcp-documents.jsonl`. ## 4. Run a durable build ```powershell knowledgegraph run ` --corpus product-knowledge ` --from-stage 1 ` --through-stage 8 ` --input-jsonl .\artifacts\mcp-documents.jsonl ` --model-file .\src\templates\knowledge_model.json ` --requested-by local-developer ``` Watch progress: ```powershell podman compose logs --follow api worker ``` ## 5. Query and answer For direct local stage execution: ```powershell python .\src\09_query_graphrag.py ` --corpus product-knowledge ` --question "Who created Atlas?" ` --top-k 8 python .\src\10_generate_answer.py ` --corpus product-knowledge ` --question "Who created Atlas?" ``` For the API, obtain a BFF-issued JWT and call `/query` or `/answer` as described in the [API reference](./api.md). ## 6. Rebuild downstream data Use `--from-stage` to avoid repeating valid upstream work. Use `--reset` when the selected stage or any downstream data is inconsistent: ```powershell knowledgegraph run ` --corpus product-knowledge ` --from-stage 4 ` --through-stage 8 ` --reset ` --requested-by rebuild ``` Do not run two builds for the same corpus concurrently; the PostgreSQL advisory lock will defer one, but coordinating callers is clearer. ## 7. Apply or inspect migrations ```powershell alembic current alembic history alembic upgrade head ``` `AUTO_CREATE_SCHEMA=true` is for isolated tests only. Review generated migrations before applying them. ## 8. Run tests ```powershell pytest --ignore=.\tests\integration\test_pgvector_postgres.py ``` For the real PgVector integration: ```powershell $env:TEST_POSTGRES_URL = "postgresql+psycopg://knowledgegraph_app:password@localhost:5432/knowledgegraph" pytest .\tests\integration\test_pgvector_postgres.py Remove-Item Env:TEST_POSTGRES_URL ``` ## 9. Stop or reset local services ```powershell podman compose down ``` This retains the database volume. To delete all local PostgreSQL data: ```powershell podman compose down --volumes ``` Volume removal is destructive.