Skip to content

configuration.md

Latest commit

 

History

History
59 lines (46 loc) · 2.56 KB

configuration.md

File metadata and controls

59 lines (46 loc) · 2.56 KB
Raw

Configuration

rag-engine.yaml is the only non-secret application configuration and rag-engine.schema.json validates it. Set RAG_CONFIG_PATH to load it from elsewhere. The embedding section contains one endpoint_env and one api_key_env, along with the model, dimension, prefixes, batch size, input reserve, and pinned artifact metadata.

Three keys are parsed but currently have no effect, which is worth knowing before you spend time tuning them:

  • mcp.filters — the real filter set is fixed in each tool signature in app/mcp/tools.py.
  • project.resource_prefix — read into config and never used.
  • content.chunking.strategy — the schema constrains it to consecutive_units and no code branches on it. ConsecutiveUnitChunker is constructed directly, so chunking is not pluggable despite the Chunker protocol existing.

The model artifact revision and SHA-256 are mandatory. The embedding image verifies the downloaded artifact before startup. The service advertises an immutable alias derived from the model name, full artifact SHA-256, pooling, context size, and normalization mode. The server receives the corresponding explicit normalization flag; clients reject any different model identity from both /v1/models and embedding responses.

The chunker conservatively limits UTF-8 bytes to the model context ceiling minus input_reserve_tokens and the document prefix. Oversized units are split at sensible boundaries with character-range locators. Chunk hashes include text and source span, so repeated passages remain distinct citations.

MCP

The authenticated MCP service exposes schema, source, document, keyword, semantic, and hybrid search tools. Every result contains canonical citation information.

Clients connect over Streamable HTTP at /mcp, sending Authorization: Bearer <RAG_MCP_API_KEY>; anything else returns 401. Tool names are prefixed with mcp.namespace, so hybrid search is rag.search.hybrid by default. The default port is 3011 when PORT is unset, and startup hard-fails if the token variable is empty.

python -m app.mcp.server

/health and /livez return constant-time process liveness and perform no database or embedding-provider I/O. Render uses /health.

Diagnostics

python scripts/doctor.py --timeout-seconds 10

The doctor checks every enabled adapter and reports one aggregated list of missing environment variables. It also synchronously checks bounded database connectivity, exactly one active profile, vector dimension, model identity and inference, and complete fingerprint-matched coverage.