RAG-DEMO/docs/configuration.md

3.3 KiB

Configuration reference

Settings reads environment variables and .env values. The complete starter set is in .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 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.