80 lines
3.3 KiB
Markdown
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.
|
|
|