Struct IntentGraph 

pub struct IntentGraph {
    pub v: u32,
    pub built_from_ts: u64,
    pub rev: u64,
    pub intents: Vec<Intent>,
    pub model: Option<String>,
    /* private fields */
}

The usage-ranking read model — a set of query clusters with capability edges.

Built either in-process by the local learner or offline by Ratel Cloud; both emit the shape in protocol/v1. Attach one to a registry to add the usage arm to its ranking.

Fields

v: u32

Schema version. Always [GRAPH_VERSION] for a graph this build accepts.

built_from_ts: u64

Epoch-millis of the newest event folded in. Provenance only — it says how current the graph is, and nothing reads it during ranking.

rev: u64

Monotonic write counter, bumped once on every mutation (Self::observe, a centroid rebuild). Nothing reads it during ranking; it exists for the caller’s storage layer, which owns persistence (the graph is in-process only). Two uses: save-when-changed — persist only when rev differs from the last saved value; and stale-base detection — before overwriting a stored graph, compare its rev to the one you loaded, and if it advanced another writer got there first (single-writer is the supported model; this makes a clobber detectable, not merged). Carried in the wire form; an older graph without it loads as 0 and continues up.

intents: Vec<Intent>

The clusters. Order is not significant.

model: Option<String>

Fingerprint of the embedding model the centroids were built with, or None for a lexically-grown graph that has none.

Centroids are only comparable to a query embedded by the same model. This lets a consumer detect a model swap (GraphModelStatus) instead of cosine-ing across incompatible vector spaces. Stamped when the first centroid is grown, or by a producer (e.g. Ratel Cloud) that builds centroids offline.

Implementations

impl IntentGraph

pub fn from_json(json: &str) -> Result<Self, IntentGraphError>

Parse a graph from its JSON wire form.

Errors

IntentGraphError::Malformed if the bytes are not the expected shape, or IntentGraphError::UnsupportedVersion if v is not 1.

pub fn empty() -> Self

An empty graph at the current version — the starting state of a learner.

pub fn len(&self) -> usize

Number of clusters.

pub fn is_empty(&self) -> bool

Whether the graph holds no clusters — the cold-start state, in which it contributes no arm to any query.

pub fn rev(&self) -> u64

The write counter — see Self::rev. Snapshot it after each save; a later value means unsaved learning, or another writer moved ahead of you.

pub fn labeled(&self) -> Vec<Intent>

The clusters with their display fields materialized against the graph as it is now.

Labels are derived rather than stored for two reasons. c-TF-IDF ranks a term by how rare it is across the other clusters, so a value computed when a cluster was last written goes stale as soon as the graph grows. And computing them on write meant re-tokenizing every member of every cluster on every invocation — for strings ranking never reads.

The whole-corpus token index (per_cluster, global, avg) is built once here and shared by every cluster’s c-TF-IDF; building it inside each call made this quadratic in cluster count.

Trait Implementations

impl Clone for IntentGraph

fn clone(&self) -> IntentGraph

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for IntentGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for IntentGraph

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for IntentGraph

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for IntentGraph

fn eq(&self, other: &IntentGraph) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for IntentGraph

Serializing materializes the derived display fields, so the wire form always carries labels computed against the graph being written — never a stale snapshot from whenever a cluster last happened to change.

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for IntentGraph