Design Principles
These are non-negotiable. Every feature request is evaluated against all six. If a proposed feature violates one, it is rejected.P1 — Zero Silent Failures
Every failure mode has a name and a type.EmptyRetrievalError, EmbeddingModelMismatchError,
ContextBudgetExceededError, ScoreCollapseWarning are first-class citizens.
An HTTP 200 that returns wrong content is not a success.
P2 — Cost Is Not Optional Instrumentation
Every result object carries aCostReport: tokens consumed per stage, latency per stage, estimated cost.
This is part of the core return type. It is not a logging feature.
P3 — Explicit Over Magic
No hidden routing. No undocumented base class behaviour. No auto-configuration. Every pipeline step is a function the user can read, modify, and reason about independently.P4 — Contracts Are Versioned
Every adapter carriesmodel_version, schema_version, and corpus_version.
The library validates these at initialisation time.
Embedding model mismatch raises at startup, not mid-query.
P5 — Composable Primitives, Not Monolithic Pipelines
Components are small, typed, and independently testable. Pipelines are explicit compositions the user assembles. The library provides typed building blocks and enforces contracts between them.P6 — Boundaries Absorb Provider Volatility
The adapter layer shields the core pipeline from upstream LLM and vector DB API churn. When OpenAI changes its response schema, the adapter updates. TheLLMAdapter Protocol does not change.