Ratel Context Engineering Layer

Ratel provides several runnable demos that show how to wire Ratel into real agent frameworks and protocol surfaces. These examples are organized as private workspace packages and cover various integration patterns including adaptive ranking, Vercel AI SDK, Mastra, Pydantic AI, and OpenTelemetry.

Available Integration Patterns

Adaptive Ranking

• TypeScript: adaptive-ranking-ts — Learn from invocations and persist/reload the graph.
• Python: adaptive-ranking-python — The Python mirror of the TS version, including model-swap recovery.
• Configurable (TS): configurable-adaptive-ranking-ts — Seed an intent graph from a baseline capture, then switch ranking on.
• Configurable (Python): configurable-adaptive-ranking-python — The Python mirror for seeding.

Agent Framework Integrations

• Vercel AI SDK: ai-sdk — Demonstrates top-K filtering and capability tools within ToolLoopAgent.generate.
• Mastra: mastra — Demonstrates capability tools and per-turn recall processors via @ratel-ai/mastra.
• Pydantic AI (Python): pydantic-ai — Demonstrates top-K filtering and capability tools in the agent loop.
• MCP Chat: mcp-chat — An interactive REPL against an MCP-backed agent using Vercel AI SDK and OpenAI.

Telemetry

• TypeScript: telemetry-ts — Emits ratel.* spans via the OpenTelemetry JS SDK.
• Python: telemetry-python — Emits ratel.* spans via the OpenTelemetry Python SDK.

When monitoring a seeded graph, do not rely solely on support or obs (observations). A healthy-looking graph can still fail if it doesn't generalize to your actual traffic.

The Metric to Watch: coverage

• Definition: The number of held-out queries (invented agent-style queries) that matched a cluster.
• Why it matters: If coverage is low even while support is high, it means your graph is learning from the baseline but failing to generalize to the way users actually phrase questions (e.g., users describing a symptom while the agent searches by action).

Other Metrics:

• clusters: Distinct intents found so far.
• support: Observations behind the cluster this turn landed in (scaled by how close it is to full strength).
• obs: Total confirmed observations across every cluster.
• from_baseline: Count of observations originating from the initial capture (stays constant after the 'flip' to live serving).

To tune how tools, skills, and facts are retrieved (via BM25 or dense retrieval) without changing the descriptions or schemas seen by the LLM, you can use the experimental experimental_searchable_description field.

When this field is provided, the retrieval engine uses a specific projection order instead of the default schema-inclusive projection. This allows catalog operators to optimize for recall and ranking independently of the model-facing payload.

Projection Order for Opted-in Entries:

1. name (both whole and identifier-split)
2. The experimental_searchable_description override (verbatim)
3. tags (whole and identifier-split, applicable to skills and facts)

Key Behaviors:

• Tool Isolation: For tools with an override, input and output schemas are used for the model but are not indexed for retrieval. Tools without an override continue to use the stable schema-inclusive projection.
• Partial Override: The override only replaces the description component. name and tags are always indexed, even if the override is empty.
• Cache Invalidation: Editing the experimental_searchable_description counts as catalog churn. The system uses a SHA-256 hash of the projected text to manage embedding caches; changing the override will invalidate the cached vector for that entry.

Adaptive usage ranking introduces an online learning layer that adjusts retrieval results based on actual user choices (what users chose when the ranker was wrong). This provides a signal that goes beyond manual description-writing.

Key behaviors to note:

• Order-dependence: Ranking is no longer strictly deterministic. The same events in a different order can produce a different graph. To achieve reproducible results for CI, benchmarks, or bug reports, you must replay the JSONL trace log.
• Persistence is the caller's responsibility: Ratel provides toJson and fromJson methods along with a monotonic rev (revision) field. You must implement the logic to save and detect stale bases (single-writer supported; no built-in merge).
• Repair via Replay: If events are dropped from the stream, they are lost permanently. The repair path is to replay the ~/.ratel/telemetry log at construction.
• Feedback Loops: Boosting used capabilities makes them more likely to be used. While W < 1 and support ramp bounds limit this, a feedback loop is inherent. Seeding from a trusted agent is recommended to provide a high-quality starting point.
• Rebuilding is expensive: Rebuilding the graph is an $O(\text{whole log})$ operation. It should be used for bootstrapping or repairing, not as a per-turn serving operation.

The searchable_text projection determines which parts of a tool are indexed for retrieval. To prevent tool arguments from competing with the tool's actual purpose for ranking priority, the projection is restricted to specific semantic elements.

Indexed elements:

• Tool name: The identifier of the tool.
• Tool description: The primary prose describing what the tool does.
• Input-schema property names: The names of parameters (recursively including nested objects and array items). These are included because parameter names (e.g., branch) often contain semantic signal useful for matching queries.

Excluded elements (not indexed):

• Property descriptions: Prose intended to help a model fill an argument is excluded to prevent length imbalance.
• Enum values: These are treated as data rather than semantic meaning.
• Output schema: The shape of the returned data is not indexed, as it does not describe the caller's intent.

Key takeaway for developers: If you want to improve tool retrieval, focus on the tool description. Writing richer documentation inside the parameter schema (property descriptions) will not change the retrieval/ranking behavior.