Configuration reference¶
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' | 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' | 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. |
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 guide explains how to change these together, and Evaluation explains why tuning values should move only with measured evidence.