kitt_score 0.1.0

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

pub mod backends;
pub mod score_result;
pub mod vector;

use crate::location::state::LocationView;
use crate::schema::schema::Schema;

pub use score_result::{Candidate, ScoreResult};

/// Runtime scoring function for a single action.
pub trait Scorer: Send + Sync {
    /// Return a scalar score; higher = better.
    fn score(&self, state: &LocationView<'_>) -> f32;
}

/// Build a [`Scorer`] from a declarative spec at registration time.
///
/// Invoked once per `ActionIngest`, so parsing/compilation cost is
/// amortized over every subsequent trigger.
pub trait ScorerBuilder: Send + Sync {
    /// Concrete `Scorer` type produced by this builder.
    type Scorer: Scorer + 'static;
    /// Compile a `ScorerSpec` into a `Scorer`.
    ///
    /// # Errors
    ///
    /// Returns [`BuildErr`] when the spec fails to parse, typecheck, or
    /// reference the schema correctly.
    fn build(&self, spec: &ScorerSpec<'_>, schema: &Schema) -> Result<Self::Scorer, BuildErr>;
}

/// Declarative specification of a scoring function.
#[derive(Clone, Debug)]
pub enum ScorerSpec<'a> {
    /// Backend B: predicate DSL source text.
    Predicate(&'a str),
    /// Backend C: dense `f32` target vector + metric.
    Vector {
        /// Target embedding.
        target: &'a [f32],
        /// Similarity metric used against the target.
        metric: VectorMetric,
    },
}

/// Vector similarity metrics supported by the vector backend.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum VectorMetric {
    /// Plain dot product.
    Dot,
    /// Cosine similarity.
    Cosine,
}

/// Which implementation of the vector backend to use.
///
/// Only `Linear` is shipped; the enum exists so a future HNSW (or other ANN)
/// backend can be added without an API break.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum VectorBackend {
    /// Dense linear-scan SIMD backend (see M5).
    Linear,
}

/// Errors raised while compiling a `ScorerSpec` into a `Scorer`.
#[derive(Debug, thiserror::Error)]
pub enum BuildErr {
    /// Parse failure for the predicate DSL.
    #[error("parse error: {0}")]
    Parse(String),
    /// Referenced kind is not declared in the schema.
    #[error("unknown kind referenced: {0}")]
    UnknownKind(String),
    /// Referenced attribute is not declared in the schema (or not in the given kind).
    #[error("unknown attribute referenced: {0}")]
    UnknownAttr(String),
    /// Type error during typecheck (e.g., string where number expected).
    #[error("type error: {0}")]
    Type(String),
    /// Vector backend mismatch or target shape error.
    #[error("vector backend mismatch: {0}")]
    Vector(String),
}