RAG-POC/docs/configuration.md

80 lines
3.3 KiB
Markdown

# Configuration reference
`Settings` reads environment variables and `.env` values. The complete starter
set is in [`.env.example`](../.env.example). Values below are grouped by
responsibility; names are case-insensitive through Pydantic settings.
## Database and source
| Variable | Purpose | Default |
|---|---|---|
| `DATABASE_URL` | canonical checkpoint database | PostgreSQL on localhost |
| `SOURCE_DATABASE_URL` | optional external source database | empty |
| `SOURCE_TABLE_NAME` | source table | `external_documents` |
| `ANALYTICS_DATABASE_URL` | reserved analytics setting | empty |
| `AUTO_CREATE_SCHEMA` | test-only schema creation | `false` |
| `ARTIFACT_DIR` | local handoff/artifact directory | `artifacts` |
## Corpus and model
| Variable | Purpose | Default |
|---|---|---|
| `CORPUS_NAME` | corpus namespace | `default-corpus` |
| `ENTITY_TYPES` | comma-separated allowed entity types | Person, Organization, Product, Concept, Event, Location |
| `RELATIONSHIP_TYPES` | comma-separated allowed edge types | AFFILIATED_WITH, CREATED, DEPENDS_ON, MENTIONS, PART_OF, RELATED_TO |
| `NODE_TEMPLATE` | JSON extraction shape | template in `.env.example` |
| `EDGE_TEMPLATE` | JSON extraction shape | template in `.env.example` |
| `EXTRACTION_INSTRUCTIONS` | additional extraction guardrail | source-grounded extraction |
Use [the model template](../src/templates/knowledge_model.json) when invoking
stage 3 with `--model-file`.
## LLM provider
| Variable | Purpose | Default |
|---|---|---|
| `LLM_BASE_URL` | OpenAI-compatible API root | `https://api.openai.com/v1` |
| `LLM_API_KEY` | provider credential | empty |
| `LLM_CHAT_MODEL` | chat/completion model | `gpt-4.1-mini` |
| `LLM_EMBEDDING_MODEL` | embedding model | `text-embedding-3-small` |
| `LLM_EMBEDDING_DIMENSIONS` | expected vector length | `1536` |
| `LLM_TIMEOUT_SECONDS` | request timeout | `60` |
| `LLM_MAX_RETRIES` | retry count | `4` |
| `LLM_RETRY_INITIAL_SECONDS` | initial backoff | `1` |
| `LLM_RETRY_MAX_SECONDS` | maximum backoff | `30` |
Retries cover 429, 500/502/503/504, connection failures, and timeouts.
Numeric `Retry-After` is honored. Authentication and validation failures are
not retried.
## Processing and retrieval
| Variable | Purpose | Default |
|---|---|---:|
| `CHUNK_SIZE` | chunk target size | `1200` |
| `CHUNK_OVERLAP` | chunk overlap | `150` |
| `COMMUNITY_RESOLUTION` | NetworkX community resolution | `1.0` |
| `RETRIEVAL_TOP_K` | vector result count | `8` |
| `RETRIEVAL_GRAPH_HOPS` | graph expansion depth | `2` |
| `RETRIEVAL_GRAPH_LIMIT` | graph expansion cap | `50` |
| `RETRIEVAL_HNSW_EF_SEARCH` | PgVector search breadth | `100` |
`CHUNK_OVERLAP` must be smaller than `CHUNK_SIZE`. Embedding dimensions must
match the provider output and the PgVector index dimension.
## Security and worker
| Variable | Purpose |
|---|---|
| `INTERNAL_JWT_SECRET` | HS256 verification secret |
| `INTERNAL_JWT_ISSUER` | expected JWT issuer |
| `INTERNAL_JWT_AUDIENCE` | expected JWT audience |
| `INTERNAL_FEATURE_NAME` | feature key containing permission bits |
| `LOG_LEVEL` | structured log level |
| `WORKER_POLL_SECONDS` | idle worker polling interval |
| `WORKER_STALE_RUN_SECONDS` | stale-run recovery threshold |
Change every development secret before shared or production use. Prefer workload
identity, mTLS, or asymmetric/JWKS verification in production.