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

Two registries hold the corpus, one per capability kind:

ToolRegistry indexes Tools — callable endpoints described by a name, a description, and JSON schemas.
SkillRegistry indexes Skills — reusable instruction playbooks whose body is dispatched on demand.

Both 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.

§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(),
    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(),
    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.
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.
ParseSearchMethodError: The identifier did not name a known method.
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, timestamp, and session id. 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.

Enums§

ChurnKind: How a registry corpus changed — carried by TraceEvent::IndexChurn (tools) and TraceEvent::SkillChurn (skills).
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.
Origin: Distinguishes a direct API call (pre-fetch helpers, library callers, benchmarks) from one the agent synthesized inside its loop (capability tool). Used to separate the two paths in trace consumers (rerankers train on agent calls, inspector shows both).
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.
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.

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).