3.2 KiB
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.
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
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. For a
file handoff, use .\artifacts\mcp-documents.jsonl.
4. Run a durable build
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:
podman compose logs --follow api worker
5. Query and answer
For direct local stage execution:
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.
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:
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
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
pytest --ignore=.\tests\integration\test_pgvector_postgres.py
For the real PgVector integration:
$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
podman compose down
This retains the database volume. To delete all local PostgreSQL data:
podman compose down --volumes
Volume removal is destructive.