Configuration

ServiceConfig environment variables, retrieval selectors, workflow execution gates, public API credentials, and CompanyProfile.

ServiceConfig.from_env() maps dataclass field name to RAGSPINE_NAME. Three legacy aliases remain supported: RAGSPINE_PROVIDER → provider_type, RAGSPINE_COMPANY_PROFILE → company_profile_path, and RAGSPINE_FAQ_SOURCE → faq_source. A canonical field-name variable takes precedence over its alias.

Core and storage

Variable	Default	Purpose
`RAGSPINE_DB_PATH`	`data/fact_metric.db`	structured fact SQLite store
`RAGSPINE_CHUNK_DB_PATH`	unset	narrative chunk store; unset degrades honestly
`RAGSPINE_MAPPING_DB_PATH`	unset	mapping store
`RAGSPINE_QUEUE_DB_PATH`	unset	SME review queue, not the RQ job queue
`RAGSPINE_MANIFEST_DB_PATH`	unset	structured-ingestion manifest
`RAGSPINE_REDIS_URL`	`redis://localhost:6379/0`	RQ/Redis connection
`RAGSPINE_ALLOWED_UPLOAD_ROOT`	unset	resolved ingestion-path allowlist
`RAGSPINE_FAQ_SOURCE`	unset	vetted FAQ JSON; unset means empty cache
`RAGSPINE_REFERENCE_DATE`	unset	ISO date for relative-period resolution

Provider and retrieval

Variable	Default	Values / purpose
`RAGSPINE_PROVIDER`	`mock`	`mock` or `anthropic`
`RAGSPINE_MODEL`	provider default	server-side model ID
`RAGSPINE_BASE_URL`	unset	server-side provider gateway URL
`RAGSPINE_TOKENS_PER_MINUTE`	`0`	corespine sliding-window provider throttle; 0 is off
`RAGSPINE_RETRIEVAL_MODE`	`auto`	`auto`/`hybrid`/`vector`, or zero-embedding `economy`/`bm25`/`lexical`
`RAGSPINE_EMBEDDING`	`auto`	`none`, `auto`, `onnx`, `deterministic`, or `openai`
`RAGSPINE_RERANKER`	`none`	`cross_encoder`, `colbert`, `splade`, `auto`, or none
`RAGSPINE_POSTPROCESSOR`	`none`	comma chain such as `mmr,lost_in_middle`
`RAGSPINE_QUERY_DECOMPOSE`	`none`	optional LLM query decomposition
`RAGSPINE_CORRECTIVE`	`none`	optional `crag` wrapper
`RAGSPINE_QUERY_TRANSFORM`	`none`	`hyde`, `rag_fusion`, or `step_back`
`RAGSPINE_ADAPTIVE`	`none`	optional heuristic/LLM complexity routing
`RAGSPINE_CHUNKER`	`none`	default, parent-child/small-to-big, layout, laws, QA, book, sentence-window, or semantic
`RAGSPINE_VECTOR_STORE`	`none`	none, in-process, or configured persistent adapter
`RAGSPINE_PERSISTENCE_POLICY`	`default`	isolation-first default or `persist_everything`

Economy mode is stronger than setting a cheap embedding: it does not construct an embedding backend or vector store at all.

Workflows and public compatibility APIs

Variable	Default	Purpose
`RAGSPINE_WORKFLOW_MATCHER`	`auto`	workflow matcher selection; auto can fall back to lexical
`RAGSPINE_DIFY_RUN_ENABLED`	`false`	master gate for Dify/n8n-compatible execution
`RAGSPINE_DIFY_RUN_TIMEOUT_S`	`10.0`	execution timeout in seconds
`RAGSPINE_DIFY_RUN_ISOLATION`	`inprocess`	`inprocess` or Linux-enhanced `subprocess`
`RAGSPINE_STUDIO_DIR`	empty	existing static directory mounted at `/studio`
`RAGSPINE_DIFY_PUBLIC_APPS`	empty	`key=/path/workflow.yml;...`; empty disables public Dify API
`RAGSPINE_N8N_API_KEY`	unset	expected `X-N8N-API-KEY`; unset disables `/api/v1/*`
`RAGSPINE_N8N_STORE_PATH`	`data/n8n_store`	n8n-compatible file-store root

Enabling execution is a trust-boundary decision, not authentication. The internal run routes still need reverse-proxy/network protection. Public Dify and n8n APIs have their own keys; webhooks are intentionally unauthenticated.

CompanyProfile

The company profile controls home identity, entity aliases, labels/geography, competitor scope, and sensitivity classification. The loader used by the engine reads RAGSPINE_COMPANY_CONFIG or an explicit path:

RAGSPINE_COMPANY_CONFIG=config/company.toml \
  .venv/bin/python scripts/run_server.py

ServiceConfig.company_profile_path is populated by the canonical RAGSPINE_COMPANY_PROFILE_PATH or legacy RAGSPINE_COMPANY_PROFILE, but current company-profile loading has a separate RAGSPINE_COMPANY_CONFIG path. Prefer the latter until those assembly surfaces are unified.

[home]
company_name = "YourCo"
entity_code = "YOURCO_GROUP"

[home.synonyms]
"yourco" = "YOURCO_GROUP"

[external_entities]
"globex" = "Globex"

[sensitivity]
default_level = "INTERNAL"
restricted_keywords = ["board_minutes", "绩效"]

No production company identity should be hardcoded in the engine. Competitor/refusal decisions and restricted-content classification derive from this profile.

Provider testing note

The deterministic mock path is the fully exercised offline baseline. The project author is based in China and cannot access the Anthropic API, so Anthropic-specific behavior has not received the same direct integration testing. Users of that adapter should validate their model ID, credentials, gateway behavior, and rate limits in their own environment.