RAG-DEMO/docs/runbook.md

132 lines
3.2 KiB
Markdown

# 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.