Crate kitt_score 

kitt_score

The decision engine at the core of Project KITT. See docs/superpowers/specs/2026-04-20-kitt-score-design.md for the full design; this crate-level doc gives a one-screen orientation only.

Model

• A Location is an abstract entity carrying (a) reference data loaded in bulk at startup, and (b) dynamic state updated by events.
• An Event is one of three flavors: StateUpdate, ActionIngest, or Trigger. They are separate types — there is no runtime discrimination on the hot path.
• An Action binds a scoring function + a generic payload T + start/end validity window at a location.
• The Engine<T> receives events and, on a Trigger, picks the highest-scoring valid action and returns its payload.

The crate is deliberately transport-agnostic: there is no networking, no persistence, no renderer. See the integration section of the spec for the axum/tokio host pattern.

Feature flags

• serde — derives serde::Serialize on MetricsSnapshot, enabling JSON serialisation in host integrations (e.g. the axum_host example).

Re-exports

pub use ids::ActionId;

pub use ids::AttrId;

pub use ids::KindId;

pub use ids::LocId;

pub use ids::UnixTime;

pub use schema::AttrType;

pub use schema::OwnedValue;

pub use schema::Schema;

pub use schema::SchemaBuilder;

pub use schema::Value;

pub use clock::Clock;

pub use clock::SystemClock;

pub use clock::TestClock;

pub use location::LocationDef;

pub use location::LocationView;

pub use scoring::BuildErr;

pub use scoring::Candidate;

pub use scoring::ScoreResult;

pub use scoring::Scorer;

pub use scoring::ScorerBuilder;

pub use scoring::ScorerSpec;

pub use scoring::VectorBackend;

pub use scoring::VectorMetric;

pub use event::ActionIngest;

pub use event::AttrSet;

pub use event::Event;

pub use event::KindRef;

pub use event::StateUpdate;

pub use event::Trigger;

pub use decide::Decide;

pub use decide::DefaultDecider;

pub use engine::BuildError;

pub use engine::Engine;

pub use engine::EngineBuilder;

pub use engine::Ingested;

pub use engine::Outcome;

pub use errors::IngestErr;

pub use metrics::EngineMetrics;

pub use metrics::MetricsSnapshot;

Modules

clock

Time source abstraction.

decide

Choose the winner among scored candidates.

engine

The Engine<T> — the crate’s primary orchestrator.

errors

Public error types.

event

Event types — three distinct structs plus an optional dispatch enum.

ids

Newtype wrappers for the identifier types used across the crate.

location

Location state, bulk-updatable table, per-location mutex.

metrics

Aggregate engine metrics — counters and a decide-latency histogram.

schema

Immutable schema: interners, attribute types, slot layout.

scoring

Scoring core: traits, spec enum, and shared result types.