Crate ratel_ai_core

Expand description

Tool and skill retrieval for AI agents — the Rust core of the Ratel context engineering platform.

Agents degrade when every tool definition is stuffed into the context window. This crate keeps the full catalog outside the context and retrieves only the entries relevant to the task at hand: register tools and skills once, then search them per turn. The engine runs in-process; BM25 and local dense retrieval need no server, while dense retrieval may instead use a configured OpenAI-compatible embedding endpoint.

§Mental model

Three registries hold the corpus, one per capability kind:

ToolRegistry indexes Tools — callable endpoints ranked by name plus description and JSON schema tokens, or by a searchable-description override that replaces both.
SkillRegistry indexes Skills — reusable instruction playbooks whose body is dispatched on demand (a pull).
FactRegistry indexes Facts — constant grounding content whose body the higher layers push into the context, always-on or retrieval-gated per PinMode.

All rank a query with one of three engines, selected by SearchMethod:

SearchMethod::Bm25 (default) — lexical BM25. Needs no model and never fails; ToolRegistry::search and SkillRegistry::search use it unconditionally.
SearchMethod::Semantic — cosine similarity over dense embeddings from a configurable in-process HuggingFace/local model (default bge-small-en-v1.5) or OpenAI-compatible endpoint (ADR-0011/ADR-0012).
SearchMethod::Hybrid — the BM25 and dense rankings fused with Reciprocal Rank Fusion.

Semantic and hybrid searches rank against an embedding cache built by ToolRegistry::build_embeddings / SkillRegistry::build_embeddings; a search itself never embeds the corpus and never downloads the model.

Every register and search also emits a TraceEvent on the registry’s TraceSink — the local trace stream behind the inspector and usage reporting (ADR-0007). The default sink is NoopSink (discard); MemorySink buffers for tests and introspection, JsonlSink appends to a local file, and FnSink hands each line to a closure for hosts whose destination this crate cannot own.

§Example: register and search (BM25)

use ratel_ai_core::{Tool, ToolRegistry};

let mut registry = ToolRegistry::new();
registry.register(Tool {
    id: "read_file".into(),
    name: "read_file".into(),
    description: "Read a file from disk".into(),
    experimental_searchable_description: None,
    input_schema: serde_json::json!({
        "properties": {
            "path": { "type": "string", "description": "absolute path" }
        }
    }),
    output_schema: serde_json::json!({}),
});
registry.register(Tool {
    id: "send_email".into(),
    name: "send_email".into(),
    description: "Send an email to a recipient".into(),
    experimental_searchable_description: None,
    input_schema: serde_json::json!({}),
    output_schema: serde_json::json!({}),
});

let hits = registry.search("read a file", 5);
assert_eq!(hits[0].tool_id, "read_file");

The language SDKs (@ratel-ai/sdk on npm, ratel-ai on PyPI) bundle this crate and surface the same model; the agent-facing capability tools (search_capabilities / invoke_tool / get_skill_content) sit on top of them. Design rationale lives in the repo’s docs/adr/.

Structs§

EmbeddingSpec: Normalized, cross-SDK embedding config as forwarded by the native bindings. Exactly one primary source must be set: either spec (the raw string shortcut) or one of huggingface / local / ollama / url. The rest are modifiers.
Fact: A fact registered for grounding — constant, declarative context an agent needs to have on hand (a barbershop’s address and hours, a brand’s voice). The push-path analog of a crate::Skill: where a skill is a playbook the agent pulls and runs on demand, a fact is content the grounding layer pushes into the context so the model is never missing it.
FactHit: One ranked match from a FactRegistry search, best-first in the returned Vec — the fact-side twin of crate::SkillHit.
FactHitTrace: One ranked fact hit inside a TraceEvent::FactSearch event — the fact-side twin of SkillHitTrace.
FactRegistry: Retrieval index over Facts — the push-path analog of crate::SkillRegistry. Same selectable BM25/semantic/hybrid engines; a parallel type keeps the skill path untouched and lets fact telemetry (fact_search / fact_churn / fact_inject) stand on its own.
FanoutSink: A sink that wraps each event once, then asynchronously dispatches the same envelope to any number of bounded subscribers.
FanoutSubscription: A handle to one FanoutSink subscriber.
FnSink: A sink that hands each enveloped event to a closure, for hosts whose trace destination this crate cannot own — a process-per-request server writing to a database, a language binding forwarding to its runtime, anything distributed enough that a local file is the wrong answer.
Intent: One cluster: the queries it covers and the capabilities invoked after them.
IntentGraph: The usage-ranking read model — a set of query clusters with capability edges.
JsonlSink: A sink that appends events to a JSONL file, one TraceEnvelope per line — local persistence for the offline inspector and reporting (ADR-0007; the consuming shells bucket files under ~/.ratel/telemetry/, but the sink accepts any path). Writes are best-effort: a serialization or I/O failure drops the event rather than disturb the agent loop.
MemorySink: A sink that buffers enveloped events in memory, for tests and in-process introspection: record, then assert on Self::snapshot or Self::drain. The buffer is unbounded, so drain it periodically if the producer is long-lived.
NoopSink: A sink that discards every event — the default of a registry built with crate::ToolRegistry::new / crate::SkillRegistry::new, and the right choice when tracing is off.
ObservationPolicy: How a UsageLearner turns a trace stream into observations.
ParseOnArtifactMissError: Rejected OnArtifactMiss string from the SDK binding.
ParsePinModeError: The identifier did not name a known pin mode.
ParseSearchMethodError: The identifier did not name a known method.
ReplaceOutcome: What a whole-corpus SkillRegistry::replace_all actually changed, counted by id. updated covers any field edit (including a body-only rewrite); unchanged ids are byte-identical and keep their cached embedding. A reload that changed nothing reports zeros across added/removed/updated — the cheap case a periodic source hits most of the time.
SearchHit: One ranked match from a ToolRegistry search, best-first in the returned Vec.
SearchHitTrace: One ranked tool hit inside a TraceEvent::Search event.
SearchStage: Timing and top score of one engine stage of a search. BM25 searches emit one bm25 stage, semantic searches one dense stage; hybrid emits bm25, dense, and rrf, in that order. Semantic and hybrid searches that short-circuit on an empty corpus or top_k == 0 emit no stages.
Skill: A skill registered for retrieval — the on-demand analog of a crate::Tool.
SkillHit: One ranked match from a SkillRegistry search, best-first in the returned Vec — the skill-side twin of crate::SearchHit.
SkillHitTrace: One ranked skill hit inside a TraceEvent::SkillSearch event — the skill-side twin of SearchHitTrace.
SkillRegistry: Retrieval index over Skills — the on-demand analog of crate::ToolRegistry. Same selectable BM25/semantic/hybrid engines; a parallel type keeps the tool path untouched and lets skill telemetry stand on its own.
Tool: A tool registered for retrieval — one entry in a crate::ToolRegistry corpus.
ToolRegistry: Retrieval index over Tools — the registry behind the SDKs’ tool catalogs.
TraceEnvelope: The versioned wrapper a sink writes around each TraceEvent: schema version, stable identity, timestamp, and correlation fields. On the wire the event is flattened (#[serde(flatten)]), so its type tag and fields sit beside v / ts / session_id in one JSON object.
TraceEventContext: Per-event correlation fields supplied by the emitting integration.
UsageLearner: A TraceSink decorator that grows an IntentGraph from the events passing through it, then forwards them unchanged.

Enums§

AdaptiveRankingStatus: Whether adaptive usage ranking is currently contributing to a registry’s results — the SDK-facing view of the model-compatibility check (ADR-0014).
ArtifactError: Failure building or loading a binary embedding artifact.
ArtifactWarmError: Failure of crate::ToolRegistry::warm_embeddings_from_artifact / crate::SkillRegistry::warm_embeddings_from_artifact.
CatalogKind: Catalog entry type carried by TraceEvent::CatalogDefinition.
ChurnKind: How a registry corpus changed — carried by TraceEvent::IndexChurn (tools), TraceEvent::SkillChurn (skills), and TraceEvent::FactChurn (facts).
EmbedderError: A recoverable embedder failure. Returned instead of panicking so a load or inference problem surfaces to the SDK as a catchable error (with a remediation hint in Display) rather than aborting the host process.
EmbedderLoadStatus: Outcome of the one-time embedding-model load. Slow flags a machine that may be underpowered for the model; Failed a load that errored (network, cache, corrupt weights).
EmbeddingModel: The embedding model backing a catalog’s semantic/hybrid engines.
FactInjectReason: Why a fact’s body was (re-)injected into the context, carried by TraceEvent::FactInject. The grounding layer decides this by scanning the transcript for the fact’s own body text (content presence); it is the observable half of the re-injection freshness gate.
IntentGraphError: A graph that could not be adopted.
OnArtifactMiss: What to do when some corpus ids are not covered by the artifact.
Origin: Where a search came from. Trace consumers separate the paths: rerankers train on agent calls, the inspector shows all of them, and offline graph construction reads only the baseline ones.
OriginFilter: Which searches may open an observation window.
PinMode: Whether a Fact is always injected or only surfaced when a query retrieves it — the one bit that splits the always-on tier from the retrieval-gated tier.
Pooling: How a BERT model’s per-token outputs are collapsed into one sentence vector. A model is trained with one mode — using the other silently degrades ranking — so it is auto-detected from the repo’s 1_Pooling/config.json, with this as an explicit override.
Provenance: Whether observations are recorded as seeded evidence.
SearchMethod: Which ranking engine a search uses.
TraceEvent: Every event produced by any layer of Ratel. New variants are additive; renames or removals are breaking — see ADR-0007.
WarmError: Failure loading or applying an embedding artifact into the dense cache.

Traits§

TraceSink: A best-effort sink for trace events. Implementations must be cheap on the hot path — see ADR-0007 for the query-log reliability profile (lossy on backpressure is fine, blocking the agent loop is not).

Functions§

merge_embedding_artifacts: Merge valid RAT1 parts into one artifact. Empty parts are skipped; nonempty parts must share format/projection version, fingerprint, and dim. Duplicate (kind, id) → ArtifactError::IncompatibleMerge.