RAG-POC/docs/runbook.md

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.