---
title: Configuration reference
description: Runtime environment variables and domain profile fields, generated from the current Pydantic models.
---

# Configuration reference

<!-- Generated by scripts/render_config_docs.py; do not edit by hand. -->

Runtime settings and scientific-domain settings are intentionally
separate. Runtime values come from `Settings` and use the
`SCI_RAG_` prefix; scientific semantics live in
`domain/domain.yaml` and are validated by `DomainConfig`.
Run `make docs-reference` after either model changes.

## Runtime environment variables

Pydantic settings resolve explicit constructor values first, then
environment variables, then the local `.env` file, then the defaults
below. `.env.example` names every field and is checked by this
renderer, including commented optional values.

| Environment variable | Type | Default | Purpose |
|---|---|---|---|
| `SCI_RAG_DATABASE_URL` | str | postgresql+asyncpg://sci_rag:sci_rag@localhost:5433/sci_rag | Async SQLAlchemy URL for Postgres with pgvector. |
| `SCI_RAG_GOOGLE_API_KEY` | str \| NoneType | unset | Google AI Studio key. It takes precedence over Vertex when both are set. |
| `SCI_RAG_GCP_PROJECT` | str \| NoneType | unset | Google Cloud project used for Vertex AI credentials. |
| `SCI_RAG_GCP_LOCATION` | str | us-central1 | Vertex AI region. |
| `SCI_RAG_ANTHROPIC_API_KEY` | str \| NoneType | unset | Key for the direct Anthropic API. Unset uses Vertex AI, which needs only a GCP project. |
| `SCI_RAG_OPENAI_API_KEY` | str \| NoneType | unset | Key for the OpenAI-compatible provider. Unset uses Vertex AI credentials against Model Garden. |
| `SCI_RAG_OPENAI_BASE_URL` | str \| NoneType | unset | Endpoint for the OpenAI-compatible provider. Unset derives the Vertex Model Garden URL from the project and location. |
| `SCI_RAG_EMBEDDING_PROVIDER` | 'google' \| 'local-hash' | google | Embedding route: Google semantic embeddings or the deterministic offline hash provider. |
| `SCI_RAG_EMBEDDING_MODEL` | str | gemini-embedding-001 | Provider model identifier stamped into stored embedding versions. |
| `SCI_RAG_EMBEDDING_DIM` | int | 1536 | Fixed vector width. Changing it on a populated schema requires migration and re-embedding. |
| `SCI_RAG_LLM_PROVIDER` | 'google' \| 'anthropic' \| 'openai-compatible' | google | Backend a bare model id belongs to. Any model setting may override it inline as `provider:model`. |
| `SCI_RAG_LLM_MODEL` | str | gemini-2.5-flash | Generation model for answers, HyDE, communities, reranking, and judging. |
| `SCI_RAG_EXTRACTION_MODEL` | str \| NoneType | unset | Optional high-volume extraction model; unset inherits the generation model. |
| `SCI_RAG_JUDGE_MODEL` | str \| NoneType | unset | Optional evaluation judge model; unset inherits the generation model. Naming a different provider avoids self-graded answers. |
| `SCI_RAG_INTERACTIVE_STAGE_TIMEOUT_S` | float | 8.0 | Per-stage timeout for the low-latency interactive profile. |
| `SCI_RAG_DEEP_STAGE_TIMEOUT_S` | float | 30.0 | Per-stage timeout for deep and agent-oriented retrieval. |
| `SCI_RAG_DOMAIN_DIR` | Path | domain | Path to the validated domain profile and prompts. |
| `SCI_RAG_DATA_DIR` | Path | data | Base path for corpus data and snapshots. |
| `SCI_RAG_SERVER_HOST` | str | 127.0.0.1 | Host interface for the FastAPI server. |
| `SCI_RAG_SERVER_PORT` | int | 8000 | Port for REST, OpenAPI, and streamable HTTP MCP. |
| `SCI_RAG_API_KEYS` | str \| NoneType | unset | JSON map of bearer key to scopes, rate limit, and optional model-key binding. Unset is open localhost mode. |
| `SCI_RAG_CORS_ORIGINS` | str | * | Comma-separated origins accepted by the server CORS middleware. |

!!! warning "Keep credentials out of Git"
    Copy `.env.example` to `.env`; the latter is ignored. Never put
    API keys, bearer-key maps, database passwords, or request-supplied
    model credentials into documentation, logs, issues, or commits.

`SCI_RAG_EXTRACTION_MODEL` inherits `SCI_RAG_LLM_MODEL` when unset.
Changing the embedding model is a versioned data operation; changing
its dimension additionally requires a schema migration.

## `domain/domain.yaml`

The committed demo values are examples, while the types and defaults
below come from the live validation models. List paths use `[]` to
show the shape of each entry.

| Field path | Type | Default | Purpose |
|---|---|---|---|
| `name` | str | required | Human-readable name for the scientific knowledge base. |
| `description` | str | "" | Short statement of the corpus domain and intended questions. |
| `entity_types` | list[EntityTypeSpec] | [] | Ontology concepts the graph extractor may emit. |
| `entity_types[].name` | str | required | Canonical entity-type identifier used in prompts and validation. |
| `entity_types[].description` | str | "" | Domain explanation sent to the extraction model. |
| `relation_types` | list[RelationTypeSpec] | [] | Directed relationship types the graph extractor may emit. |
| `relation_types[].name` | str | required | Canonical relation identifier. |
| `relation_types[].description` | str | "" | Meaning of source RELATION target for the model. |
| `query_classes` | list[QueryClassSpec] | [] | Keyword-routed question families used to shape HyDE passages. |
| `query_classes[].name` | str | required | Query-class identifier. |
| `query_classes[].keywords` | list[str] | [] | Lowercase terms matched against tokenized questions. |
| `query_classes[].hyde_instruction` | str | "" | Domain-specific style for the hypothetical evidence passage. |
| `retrieval` | RetrievalTuning | see nested fields | Fusion, candidate, graph-confidence, and optional reranker tuning. |
| `retrieval.weights` | dict[str, float] | {"community": 0.6, "graph": 0.8, "hyde": 1.2, "keyword": 1.0, "vector": 1.5} | Per-layer multipliers used by weighted reciprocal rank fusion. |
| `retrieval.rrf_k` | int | 60 | RRF smoothing constant. |
| `retrieval.candidate_limits` | dict[str, int] | {"community": 5, "graph": 20, "hyde": 20, "keyword": 20, "vector": 20} | Maximum candidates requested from each layer before fusion. |
| `retrieval.graph` | GraphTuning | see nested fields | Relationship-confidence controls for graph traversal; off by default. |
| `retrieval.graph.min_confidence` | float | 0.0 | Minimum relationship confidence allowed to extend a graph walk. |
| `retrieval.graph.confidence_weighted` | bool | false | Order graph candidates by minimum path confidence before hop distance. |
| `retrieval.graph.include_citations` | bool | false | Expand graph candidates by one resolved document-citation hop. |
| `retrieval.reranker` | RerankerTuning | see nested fields | Post-fusion second-look configuration; off by default. |
| `retrieval.reranker.enabled` | bool | false | Whether the configured adapter reranks the fused pool. |
| `retrieval.reranker.adapter` | 'llm' \| 'local' | llm | Reranker implementation: LLM or local cross-encoder. |
| `retrieval.reranker.pool` | int | 20 | Number of fused candidates presented to the reranker. |
| `retrieval.reranker.timeout_s` | float | 15.0 | Maximum reranker duration before fused-order fallback. |
| `retrieval.reranker.model` | str \| NoneType | unset | Optional model override for the local cross-encoder. |
| `compression` | CompressionTuning | see nested fields | Question-aware chunk compression before answer prompt assembly. |
| `compression.enabled` | bool | false | Domain default; enable only after paired judged-answer evidence. |
| `compression.relevance_floor` | float | 0.3 | Drop a model-scored chunk below this relevance score. |
| `compression.max_tokens_per_chunk` | int | 160 | Maximum accepted tokens per summary; over-budget output falls back to full text. |

## Files beside the YAML profile

| Path | Contract |
|---|---|
| `domain/prompts/*.md` | `string.Template` prompt files. Preserve every required `$UPPER_CASE` slot. |
| `domain/eval_seed_questions.jsonl` | Retrieval ground truth and optional expert answers for the target corpus. |
| `domain/eval_calibration_labels.jsonl` | Independent human labels used to calibrate the model judge. |

The [Bring your own domain](bring-your-own-domain.md) guide explains
how to change these together, and [Evaluation](evaluation.md) explains
why tuning values should move only with measured evidence.
