Struct UsageLearner 

pub struct UsageLearner { /* private fields */ }

A TraceSink decorator that grows an IntentGraph from the events passing through it, then forwards them unchanged.

Install it in place of the sink you would otherwise use, and hand the same graph handle to the registries so searches read what invocations write:

use std::sync::{Arc, RwLock};
use ratel_ai_core::{IntentGraph, NoopSink, Tool, ToolRegistry, UsageLearner};

let graph = Arc::new(RwLock::new(IntentGraph::empty()));
let learner = Arc::new(UsageLearner::new(graph.clone(), Arc::new(NoopSink)));

let mut registry = ToolRegistry::new();
registry.set_trace_sink(learner);                  // writes the graph
registry.set_intent_graph(Some(graph.clone()));    // reads it
registry.register(Tool {
    id: "gh_run_list".into(),
    name: "gh_run_list".into(),
    description: "List CI runs".into(),
    experimental_searchable_description: None,
    input_schema: serde_json::json!({}),
    output_schema: serde_json::json!({}),
});

registry.search("why is the build broken", 5);
registry.record_event(ratel_ai_core::TraceEvent::InvokeStart {
    tool_id: "gh_run_list".into(),
    args_size_bytes: 0,
});
assert_eq!(graph.read().unwrap().len(), 1); // learned

Implementations

impl UsageLearner

pub fn new(graph: Arc<RwLock<IntentGraph>>, inner: Arc<dyn TraceSink>) -> Self

Wrap inner, learning into graph under ObservationPolicy::default. Pass crate::NoopSink for inner when the only thing you want is the learning.

pub fn with_policy( graph: Arc<RwLock<IntentGraph>>, inner: Arc<dyn TraceSink>, policy: ObservationPolicy, ) -> Self

Wrap inner, learning into graph under policy — the entry point a baseline capture or a replay uses. Self::new is this at the default policy.

pub fn policy(&self) -> ObservationPolicy

The policy in force.

pub fn graph(&self) -> Arc<RwLock<IntentGraph>>

The graph this learner writes — hand it to a registry to read.

pub fn replay(&self, envelope: &TraceEnvelope)

Learn from a historical envelope instead of a live event.

Identical to TraceSink::record except that the observation is stamped with the envelope’s own ts rather than the wall clock, so decay reflects when the work actually happened. Replaying a trace log through this therefore reproduces the graph the live path would have grown — which is what makes a JSONL replay a faithful reconstruction rather than an approximation.

Does not forward to the inner sink: replaying an old log must not re-emit its events into a live stream.

One learner covers one session. Feed envelopes from different session_ids through separate learners, or their searches and invokes cross-pair into edges nobody produced.

Trait Implementations

impl TraceSink for UsageLearner

fn record(&self, event: TraceEvent)

Record one event. Called synchronously on the hot path, so it must be cheap and non-blocking; on failure, drop the event rather than propagate (trace events are observations, never load-bearing).

fn record_with_context(&self, event: TraceEvent, context: TraceEventContext)

Record an event with correlation fields known at the emission site. Legacy sinks may ignore the context; envelope-aware sinks preserve it.

fn record_envelope(&self, envelope: TraceEnvelope)

Accept an event already wrapped by an upstream fan-out sink. Envelope-aware sinks override this so identity survives fan-out; legacy sinks still see the underlying event.

fn sample_rate(&self) -> f64

Per-sink rate limit hint. Currently a documentation knob — nothing rate-limits yet — but the contract is in place so consumers can adopt it without a breaking change.