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