Configuration¶

Runtime settings use SCI_RAG_ environment variables. Domain concepts and retrieval settings live in domain/domain.yaml.

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-3.6-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_PROVIDER_CALL_TIMEOUT_S`	float	60.0	Extra budget for a stage that calls an embedding or generation provider before its database work: vector, community, graph, and HyDE.
`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 LLM provider 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 types and schema defaults below come from the live validation models. compression.enabled is different by design: it is a corpus-gated setting, so the table reads its shipped value from domain/domain.yaml. 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	true	Shipped domain-profile default; change only after paired judged-answer evidence.
`compression.relevance_floor`	float	0.0	Drop a model-scored chunk below this relevance score. The default 0.0 summarizes every source and drops none. A v0.3 sweep found groundedness and citation accuracy both fall off their ceiling at 0.15 and above. Raise it only behind a paired judged-answer run that holds. See docs/evaluation.md.
`compression.max_tokens_per_chunk`	int	160	Maximum accepted tokens per summary; over-budget output falls back to full text.

`data/corpus.jsonl`¶

The corpus manifest: one JSON object per document. sci-rag ingest --manifest and sci-rag build --manifest read it; sci-rag draft manifest writes a first version from the files in a folder; sci-rag manifest lint checks it. Paths resolve relative to the manifest file.

Field	Type	Default	Purpose
`path`	Path	required	Where the file is, relative to the manifest. The only required field.
`title`	str \| NoneType	unset	The document title, used in citations. Drafted from the first pages when missing.
`authors`	list[str]	[]	Author names, as a list.
`year`	int \| NoneType	unset	Publication year.
`doi`	str \| NoneType	unset	Digital object identifier. Enables Crossref enrichment and retraction checks.
`journal`	str \| NoneType	unset	Journal or venue. Becomes a retrieval filter.
`url`	str \| NoneType	unset	Where the document came from, for the citation.
`license_class`	str	unknown	Redistribution rights: `public`, `open_commercial`, `open_noncommercial`, `restricted`, or `unknown`. Never drafted; `unknown` is excluded from any request that restricts rights.
`license_source`	str \| NoneType	unset	The sentence or signal the license class was based on, kept as evidence.
`source`	str	local	Your own grouping label, such as `journal_papers` or `agency_reports`. Becomes a retrieval filter.

`domain/eval_seed_questions.jsonl`¶

The test questions: one JSON object per question, with the evidence a correct answer rests on. sci-rag eval retrieval and sci-rag eval answers score against them; sci-rag draft questions writes a first version from your corpus. Lines starting with # are comments.

Field	Type	Default	Purpose
`id`	str	required	A short stable identifier, used in reports.
`question`	str	required	The question as a user would ask it.
`reference_answer`	str \| NoneType	unset	What a correct answer must say. Used by the correctness grader; optional for retrieval scoring.
`reference_titles`	list[str]	[]	Titles of the documents that contain the answer. A retrieved chunk from one of them counts as relevant.
`evidence_phrases`	list[str]	[]	Distinctive strings from the answering passages; numbers with units work best. A retrieved chunk containing one counts as relevant.
`tags`	list[str]	[]	Your own labels, plus two with meaning: `unanswerable` marks a question the corpus cannot answer, and `drafted` marks a model-written question no expert has reviewed.

Files beside the YAML profile¶

Path	Contract
`domain/prompts/*.md`	`string.Template` prompt files. Preserve every required `$UPPER_CASE` slot.
`domain/eval_calibration_labels.jsonl`	Human scores for a set of graded answers, used to check the model grader. Never drafted.

Bring your own domain explains how to change these together. Evaluate your pipeline explains why a tuning value should move only behind measured evidence.