Configuration¶

Configuration is a Rust value, not a config server. Because uniko runs entirely in-process, every model, threshold, and pipeline cadence is a field on one struct — UnikoConfig, in uniko-store — that you set before the KnowledgeBase opens. Start from UnikoConfig::default(), override what you care about, and call validate() to catch constraint violations before they reach the database.

use uniko_store::config::{UnikoConfig, EmbeddingConfig};

let mut config = UnikoConfig::default();
config.embedding = EmbeddingConfig::nomic_v15(); // swap the embedder
config.recall_limit = 20;                        // widen the recall bundle
config.validate()?;                              // fail fast on bad combos

Swappable models¶

uniko's NLP, embedding, and reranking models all resolve through the uni-xervo provider layer. A model is named by a provider id (e.g. local/onnx, local/mistralrs, remote/openai) plus a model id; xervo loads and warms it. Because the model selection is data, not code, you swap a model by editing config fields — no recompile of the pipeline.

flowchart LR
    UC[UnikoConfig] --> E[embedding: EmbeddingConfig]
    UC --> N[nlp: NlpConfig]
    UC --> R[reranker: RerankerConfig]
    E --> X[uni-xervo provider layer]
    N --> X
    R --> X
    X --> ONNX[local/onnx]
    X --> MRS[local/mistralrs]
    X --> REMOTE[remote/openai · remote/voyageai · ...]

The embedder¶

The embedder controls auto-embedding (Message, Chunk, Observation, Summary) and the computed embeddings on Entity, Fact, Topic, Session, and the rest of the graph. The default is BGE-small-en-v1.5 at 384 dimensions, served by the bundled local/onnx provider.

EmbeddingConfig ships several presets as constructor functions, plus a preset(name) lookup for string-keyed selection:

use uniko_store::config::EmbeddingConfig;

// 384d, BERT-based, query-side prefix only — the default.
let embed = EmbeddingConfig::bge_small_en_v15();

// 768d, 8192 context. Adds search_document:/search_query: prefixes.
let embed = EmbeddingConfig::nomic_v15();

// Returns None for an unknown name — callers print the canonical list.
let embed = EmbeddingConfig::preset("bge-large")
    .expect("known preset");

The presets and their key properties, all defined in uniko-store::config:

Each preset also sets the right task prefixes. Nomic uses document_prefix = "search_document: " and query_prefix = "search_query: "; BGE uses a query-only prefix ("Represent this sentence for searching relevant passages: "); MiniLM uses none. These are baked into the preset because the retriever was trained on those literal strings.

By default the embedder resolves through local/onnx. To route embeddings to an OpenAI-compatible endpoint instead, set the provider to "remote/openai" and pass provider_options (this is where a base_url lands):

let mut embed = EmbeddingConfig::bge_small_en_v15();
embed.provider = "remote/openai".into();
embed.provider_options = Some(serde_json::json!({
    "base_url": "http://litellm-cloud:4000/v1"
}));

The NLP cascade¶

NER and observation extraction run through a single ONNX cascade model, kniv-deberta. NlpConfig exposes the model id, the ONNX artifact to load, and a batch size:

use uniko_store::config::NlpConfig;

let nlp = NlpConfig::default();
// model_id:        "dragonscale-ai/kniv-deberta-nlp-base-en-xsmall"
// artifact:        "onnx/cascade-int8.onnx"
// max_batch_size:  16

Swapping the cascade variant (xsmall ↔ small, INT8 ↔ FP32) is a config edit — change model_id or artifact and the loader picks it up.

The cascade's SRL (semantic-role-labelling) head is gated separately on the main config:

config.nlp_srl_enabled = true; // default: true

When true, the pipeline computes SRL frames (one extra ONNX forward per VERB per sentence) and downstream extraction uses them. Set it to false if profiling shows the per-verb re-forward cost is unacceptable for a workload; NlpResult.srl_frames then stays empty and extraction behaves as before.

The reranker¶

After hybrid recall fuses candidates with reciprocal rank fusion, an optional cross-encoder re-scores the top top_n items. The reranker is enabled by default with cross-encoder/ms-marco-MiniLM-L-6-v2:

use uniko_store::config::RerankerConfig;

let rr = RerankerConfig::default();
// enabled:       true
// model_id:      "cross-encoder/ms-marco-MiniLM-L-6-v2"
// top_n:         50
// apply_sigmoid: true
// style:         "cross-encoder"

RerankerConfig ships two presets: RerankerConfig::minilm_l6() (22M params, the default model) and RerankerConfig::bge_base() (BAAI/bge-reranker-base, 278M params, more accurate, CPU-feasible). Both construct with enabled: false; the Default impl flips MiniLM on.

config.reranker = RerankerConfig { enabled: false, ..Default::default() };

Tunable thresholds¶

UnikoConfig exposes the numeric knobs that govern the recall cascade, hybrid fusion, consolidation, and memory decay. All defaults below are from UnikoConfig::default().

Recall and fusion¶

Cascade phase gates¶

The recall cascade runs in phases and exits early once a phase covers the query. Coverage gates and the Phase 1 strategy live here:

Entity admission¶

Strict admission keeps NER noise out of the :Entity graph at ingest time — temporal, measurement, and quoted-string spans (already captured as observations) and greeting/discourse fragments mis-tagged as people are dropped, and the low-confidence catch-all is gated:

Consolidation¶

Consolidation (P4) collapses near-duplicate Facts and refreshes their embeddings:

Memory decay¶

Importance decays exponentially and low-importance nodes are pruned:

config.half_life_days = 30.0; // importance * exp(-ln(2)/half_life * age_days)
config.prune_below   = 0.05;  // prune nodes below this importance

Chunking and sessions¶

The chunking thresholds match the ingest pipeline's content router:

Vector index¶

The index algorithm and distance metric are set once at database creation:

use uniko_store::config::{VectorAlgorithm, VectorMetricChoice};

config.vector_algorithm = VectorAlgorithm::HnswSq { m: 16, ef_construction: 100 };
config.vector_metric    = VectorMetricChoice::Cosine;

The default is HnswSq { m: 16, ef_construction: 100 } with Cosine distance. Other variants cover HnswFlat, HnswPq, IvfSq, IvfPq, and IvfRq for different scale / recall / memory trade-offs.

Pipelines, retries, and circuit breaker¶

validate() requires retry_initial_delay_ms <= retry_max_delay_ms.

Blob storage and external files¶

Cargo feature flags¶

A few capabilities are gated behind Cargo features so a CPU-only or offline build stays lean. Enable them per crate.

See also¶

• Architecture — how the layers and the KnowledgeBase fit together.
• Recall — what the cascade phases and fusion weights actually do.