car_inference/

intent.rs

//! Caller-facing routing intent — express requirements, not model IDs.
//!
//! Tracks Parslee-ai/car-releases#18. The motivation is that callers
//! today choose between two extremes:
//!
//! - `model = None` → the adaptive router picks. Quality on average is
//!   good but per-request variability surfaces as UX inconsistency.
//! - `model = Some("claude-sonnet-4-7")` → the caller pins. Provider
//!   awareness leaks up the stack — exactly what CAR is supposed to
//!   prevent.
//!
//! `IntentHint` is the middle ground. The caller expresses *what* they
//! need; the router resolves intent → model. Existing `model = None`
//! and `model = Some(...)` paths are unchanged when no intent is
//! supplied.
//!
//! ## MVP scope
//!
//! Just `task`, `prefer_local`, `require`. Cost/latency ceilings wait
//! for clean registry numbers; `prefer_family` was cut as a soft
//! routing knob that accumulates tweaks without clear semantics
//! (Linus design review, 2026-05-04).
//!
//! ## Routing semantics
//!
//! `prefer_local: true` maps to a dedicated
//! [`crate::RoutingWorkload::LocalPreferred`] variant. Distinct from
//! `Background` (which is "this is a background job, latency barely
//! matters") — `LocalPreferred` keeps a quality-aware weight profile
//! and a strong local_bonus so the hint wins ties decisively.

use serde::{Deserialize, Serialize};

use crate::schema::ModelCapability;

/// What the caller is doing — coarse-grained categories the adaptive
/// router maps to `InferenceTask`. A closed enum so adding a new task
/// type is a deliberate FFI-visible change rather than a silent
/// fallback when the router doesn't recognize a string.
///
/// The MVP intentionally ships only the variants that map to a
/// distinct `InferenceTask` today. `Summarize` / `Extract` were cut
/// because both would have collapsed to `Generate` with no observable
/// behavior change — shipping enum variants that are accepted, parsed,
/// and silently discarded is exactly the routing variability the
/// intent surface is designed to remove. Add them back when the
/// registry actually distinguishes summarize-tuned or extract-tuned
/// models.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TaskHint {
    /// Conversational chat — maps to `InferenceTask::Generate`.
    Chat,
    /// Label assignment / categorization. Maps to
    /// `InferenceTask::Classify`.
    Classify,
    /// Chain-of-thought, planning, multi-step analysis. Maps to
    /// `InferenceTask::Reasoning` and tends to favor frontier
    /// reasoning models.
    Reasoning,
    /// Code generation, repair, refactoring. Maps to
    /// `InferenceTask::Code`.
    Code,
}

/// Caller-supplied routing intent. All fields are optional / additive.
/// An `IntentHint` with default values matches the no-intent path
/// exactly, so threading `Option<IntentHint>` through is safe.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct IntentHint {
    /// What the caller is doing. None = let the router infer from the
    /// prompt as today.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub task: Option<TaskHint>,

    /// Hard filter — every required capability must be present on the
    /// candidate. Empty = no extra filter.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub require: Vec<ModelCapability>,

    /// Hard exclusion — model ids the router must NOT pick on the unpinned
    /// adaptive arm. The motivating case is adversarial-reviewer
    /// separation (car#358): "any capable model that is *not* the one that
    /// just did the work", so a model never grades its own output. Each entry
    /// is matched against `ModelSchema.id` *or* `ModelSchema.name` — the two
    /// differ for most models, and `name` is what
    /// [`InferenceResult::model_used`](crate::InferenceResult::model_used)
    /// reports, so a caller who has only just seen a result can name the model
    /// it holds and have it actually excluded (car#889).
    /// Empty = no exclusion. Soft by default — if excluding leaves no
    /// candidate, the exclusion is dropped rather than failing the request (a
    /// same-model review beats no review). Set [`Self::strict_exclusions`] when
    /// using an excluded model would invalidate the operation itself.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub exclude_models: Vec<String>,

    /// Refuse adaptive routing when every otherwise-eligible model appears in
    /// [`Self::exclude_models`]. This is for separation boundaries such as an
    /// unattended self-heal coder that must not share a model with its review
    /// panel. It has no effect when `exclude_models` is empty or the caller pins
    /// an explicit model outside adaptive routing.
    #[serde(default, skip_serializing_if = "is_false")]
    pub strict_exclusions: bool,

    /// Route only to models CAR runs on this machine ([`ModelSchema::is_local`]
    /// — MLX, Candle GGUF, a CAR-managed vLLM-MLX, Apple's on-device model; an
    /// Ollama or external vLLM-MLX endpoint does not count, since it may be on
    /// another machine). Hard, and checked against the registry the request
    /// is routed with when it is routed: every other model is removed before
    /// any routing path (adaptive, a preferred-model override, cold start,
    /// fallbacks) sees it, a requested model that is not on this machine is
    /// refused, and with none left the request fails with
    /// [`InferenceError::NoEligibleModel`] before anything is sent. For a
    /// caller whose data must not leave the machine, such as an agent whose
    /// person asked to keep everything on it.
    ///
    /// [`ModelSchema::is_local`]: crate::schema::ModelSchema::is_local
    /// [`InferenceError::NoEligibleModel`]: crate::InferenceError::NoEligibleModel
    #[serde(default, skip_serializing_if = "is_false")]
    pub on_device_only: bool,

    /// Bias the score profile toward local models (cost over quality).
    /// Internally this maps to `RoutingWorkload::Background` until the
    /// follow-up split lands (parslee-ai/car#106).
    #[serde(default, skip_serializing_if = "is_false")]
    pub prefer_local: bool,

    /// Bias the score profile aggressively toward latency. Maps to
    /// [`crate::tasks::RoutingWorkload::Fastest`] — a weight profile
    /// that downweights quality and cost in favour of time-to-first-token.
    /// Designed for voice turns where a sub-500ms first-audio target
    /// beats a richer-but-slower answer. Takes precedence over
    /// `prefer_local`; if both are set, the request is routed by
    /// `Fastest` rules.
    #[serde(default, skip_serializing_if = "is_false")]
    pub prefer_fast: bool,

    /// Bias the score profile toward the most capable model — quality
    /// dominates, latency and cost are near-floor (maps to
    /// [`crate::tasks::RoutingWorkload::Quality`]). For quality-critical,
    /// infrequent work where a weak model fails (building/verifying an agent,
    /// deriving a contract, structured extraction): the strongest candidate
    /// wins, not the cheapest. Precedence: `prefer_fast` wins outright
    /// (latency is the most extreme need), then `prefer_quality`, then
    /// `prefer_local`.
    #[serde(default, skip_serializing_if = "is_false")]
    pub prefer_quality: bool,

    /// The operation is high-stakes — consequential or irreversible (e.g. the
    /// session is authorized for `FullAccess`/externally-consequential actions).
    /// Forces the strongest quality posture
    /// ([`crate::tasks::RoutingWorkload::Quality`]) regardless of task,
    /// complexity, or any cost/latency preference: never economize on what you
    /// can't take back. Highest precedence — wins over `prefer_fast`,
    /// `prefer_quality`, and `prefer_local`. Distinct from `prefer_quality`
    /// because it has different *precedence* (it outranks `prefer_fast`, which
    /// `prefer_quality` does not) — a stakes-driven quality need must beat even
    /// the latency lane. Callers set it from the action/session permission tier.
    #[serde(default, skip_serializing_if = "is_false")]
    pub high_stakes: bool,

    /// Only consider models usable **right now, without a download**.
    ///
    /// For a local MLX model, `available` is true as soon as an `hf_repo` is
    /// declared, because `ensure_local()` lazy-downloads on first use (#164).
    /// That is right for open-ended work and wrong for work on a deadline: a
    /// step with a bounded budget that selects a model it must first fetch
    /// spends the entire budget downloading and then fails.
    ///
    /// `car code`'s contract derivation is the motivating case
    /// (Parslee-ai/car#638). It runs under a 120s cap, routed with
    /// `require: [Code], prefer_quality: true`, and on a machine with no local
    /// weights that selected a 4.8 GB model it had to download first — timing
    /// out three times while cloud models capable of answering in ~2s sat in
    /// the fallback list, unreached. Set this whenever a bounded timeout is
    /// enforced around the call.
    ///
    /// Soft by necessity, like [`Self::exclude_models`]: if requiring readiness
    /// leaves no candidate, the constraint is dropped rather than failing the
    /// request — a slow answer beats no answer.
    #[serde(default, skip_serializing_if = "is_false")]
    pub require_ready: bool,

    /// Never start a model download for this request. Hard, where
    /// [`Self::require_ready`] is soft: every model CAR would have to fetch
    /// files for first (its weights, a missing GGUF tokenizer, or a declared
    /// speculative-decoding drafter) is removed before any routing path
    /// (adaptive, a preferred-model override, cold start, fallbacks) sees it,
    /// a requested model that is not installed is refused, and with nothing
    /// usable left the request fails with
    /// [`InferenceError::NoEligibleModel`] before anything is sent, naming
    /// the model it would have used and the `car models pull` command that
    /// installs it. On the inference generate and stream paths, the model,
    /// drafter and tokenizer acquisitions the request reaches also refuse to
    /// fetch, the self-heal re-pull included, and a child process CAR starts
    /// for it with the Hugging Face environment (the mlx-vlm CLI, the vllm-mlx
    /// server) runs with `HF_HUB_OFFLINE=1`. Nothing is installed either: a
    /// CAR-managed vLLM-MLX model whose vllm-mlx runtime is missing or too old counts as
    /// not installed, and CAR's runtime install refuses. For work nobody asked to
    /// download for, such as checking an agent while it is built
    /// (Parslee-ai/car#3718).
    ///
    /// [`InferenceError::NoEligibleModel`]: crate::InferenceError::NoEligibleModel
    #[serde(default, skip_serializing_if = "is_false")]
    pub never_download: bool,
}

impl IntentHint {
    /// `Some(IntentHint { high_stakes: true, .. })` when `b`, else `None`.
    ///
    /// The single source of truth for "mark this generation high-stakes" so the
    /// in-process autonomous loops (active-planner, reason, agents) don't each
    /// hand-roll the struct literal — keeping the `intent: None` fast path and
    /// the high-stakes path identical across call sites. `None` is a true no-op
    /// (a default `IntentHint` doesn't trigger the Quality posture either), so a
    /// benign loop routes exactly as it did before stakes-awareness existed.
    pub fn high_stakes_if(b: bool) -> Option<IntentHint> {
        b.then(|| IntentHint {
            high_stakes: true,
            ..Default::default()
        })
    }
}

fn is_false(b: &bool) -> bool {
    !*b
}

// ---------------------------------------------------------------------------
// Acquisition intent — which model to *recommend/install* for this machine.
//
// Distinct layer from `TaskHint`/`IntentHint` above, which are *inference-time*
// routing intent (which already-installed model should serve this request).
// The types below answer the earlier question: "given this hardware and what
// the user wants to do, which model should they acquire?" They are consumed by
// `ModelRecommender` (see docs/solutions/first-class-model-ux.md) and never
// expose model IDs, quantization, or HF repos to the caller.
// ---------------------------------------------------------------------------

/// The kind of model a use case needs. The recommender ranks only *within*
/// a role's lane — an embedding model and a chat model are not comparable,
/// so a retrieval pick never competes with a generative one. A use case that
/// spans roles resolves to a bundle (one recommendation per role).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum UseCaseRole {
    /// Produces text/tokens (chat, code, vision-to-text, summarize).
    Generative,
    /// Produces vectors / relevance scores (embeddings, rerank).
    Retrieval,
    /// Consumes audio (transcription).
    Audio,
}

/// What the user wants to do, in their terms — not a model ID. Closed enum:
/// adding a use case is a deliberate FFI-visible change, never a silent
/// string fallback. Each variant maps to a [`UseCaseRole`] and a required /
/// preferred [`ModelCapability`] set (see [`UseCase::required_capabilities`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[derive(Default)]
pub enum UseCase {
    /// General chat / Q&A. The default.
    #[default]
    Assistant,
    /// Code generation, repair, refactoring.
    Coding,
    /// Text condensation.
    Summarize,
    /// Image understanding (a generative model that also sees).
    Vision,
    /// Audio → text.
    Transcription,
    /// Semantic search — an embedding model for retrieval. NOT an LLM
    /// performing web search with tools; this is the `Retrieval` role and
    /// maps to the `Embed` capability, so it is ranked separately from any
    /// generative chat model.
    Search,
}

impl UseCase {
    /// The role lane this use case is ranked within.
    pub fn role(self) -> UseCaseRole {
        match self {
            UseCase::Assistant | UseCase::Coding | UseCase::Summarize | UseCase::Vision => {
                UseCaseRole::Generative
            }
            UseCase::Search => UseCaseRole::Retrieval,
            UseCase::Transcription => UseCaseRole::Audio,
        }
    }

    /// Hard eligibility filter — a model missing any of these is excluded.
    pub fn required_capabilities(self) -> &'static [ModelCapability] {
        use ModelCapability::*;
        match self {
            UseCase::Assistant => &[Generate],
            UseCase::Coding => &[Generate, Code],
            UseCase::Summarize => &[Generate],
            UseCase::Vision => &[Vision, Generate],
            UseCase::Transcription => &[SpeechToText],
            UseCase::Search => &[Embed],
        }
    }

    /// Soft preference — present capabilities add a ranking bonus but are
    /// never required for eligibility.
    pub fn preferred_capabilities(self) -> &'static [ModelCapability] {
        use ModelCapability::*;
        match self {
            UseCase::Assistant => &[ToolUse],
            UseCase::Coding => &[ToolUse, Reasoning],
            UseCase::Summarize => &[Summarize],
            UseCase::Vision => &[],
            UseCase::Transcription => &[],
            UseCase::Search => &[Rerank],
        }
    }
}

/// Speed/quality knob. Each tier is a fixed weighting over the recommender's
/// soft-score axes, applied *after* the hard eligibility filter, so tier
/// semantics are explicit rather than reinvented per call site.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[derive(Default)]
pub enum QualityTier {
    /// Smallest eligible model; lowest latency.
    Fastest,
    /// Best quality that fits with KV-cache headroom. The default.
    #[default]
    Balanced,
    /// Largest model that fits at all; accepts slower output.
    MostCapable,
}

/// Relative weights a [`QualityTier`] places on each soft-score axis. The
/// recommender normalizes each axis to `[0,1]` and combines them with these.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct TierWeights {
    /// Toward higher-quality models (benchmarks / param-count prior).
    pub quality: f32,
    /// Toward lower-latency models (smaller, better-accelerated).
    pub latency: f32,
    /// Toward leaving memory headroom (smaller fraction of budget used).
    pub memory_pressure: f32,
}

impl QualityTier {
    /// The fixed axis weighting for this tier. Mirrors the table in
    /// docs/solutions/first-class-model-ux.md.
    pub fn weights(self) -> TierWeights {
        match self {
            QualityTier::Fastest => TierWeights {
                quality: 0.2,
                latency: 0.6,
                memory_pressure: 0.2,
            },
            QualityTier::Balanced => TierWeights {
                quality: 0.5,
                latency: 0.2,
                memory_pressure: 0.3,
            },
            // Memory is a *fit* question on this tier, and fit is already a hard
            // constraint: `FitStatus` and `within_recommendation_target` exclude
            // anything the machine cannot hold. Leaving 0.2 on the soft penalty
            // on top of that made "most capable" contradict its own name — on a
            // 64 GB Mac, Qwen3-8B (judged 0.770, 4.7 GB) beat
            // Qwen3.6-35B-A3B (judged 0.830, 19.9 GB) by 0.007, entirely because
            // the larger model used more of the memory the user has and asked to
            // use. A measured quality difference should not lose to that here.
            // Some pressure term remains, so among models of equal measured
            // quality the leaner one still wins.
            QualityTier::MostCapable => TierWeights {
                quality: 0.9,
                latency: 0.0,
                memory_pressure: 0.1,
            },
        }
    }
}

/// Where the user is willing to run inference. Orthogonal to [`QualityTier`].
/// Choosing the cloud is never silent — `CloudOk` only makes remote models
/// *eligible*; the recommender still flags them as requiring one-time consent.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[derive(Default)]
pub enum Privacy {
    /// Local models only.
    #[default]
    OnDevice,
    /// Remote APIs / the Parslee gateway may compete and win.
    CloudOk,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn empty_intent_serializes_compactly() {
        // No-intent must round-trip through serde without verbose
        // null fields — the FFI layer transmits as JSON and clients
        // shouldn't see {"task":null,"require":[],"prefer_local":false}.
        let hint = IntentHint::default();
        let json = serde_json::to_string(&hint).unwrap();
        assert_eq!(json, "{}");
    }

    #[test]
    fn round_trip_with_capability_require() {
        let hint = IntentHint {
            task: Some(TaskHint::Code),
            require: vec![ModelCapability::Code, ModelCapability::ToolUse],
            prefer_local: true,
            ..Default::default()
        };
        let json = serde_json::to_string(&hint).unwrap();
        let back: IntentHint = serde_json::from_str(&json).unwrap();
        assert_eq!(back.task, Some(TaskHint::Code));
        assert_eq!(
            back.require,
            vec![ModelCapability::Code, ModelCapability::ToolUse]
        );
        assert!(back.prefer_local);
        assert!(!back.prefer_fast);
    }

    #[test]
    fn exclude_models_round_trips_and_skips_when_empty() {
        // Empty exclusion must keep the compact `{}` wire shape (car#358).
        let off = IntentHint::default();
        assert_eq!(serde_json::to_string(&off).unwrap(), "{}");

        let on = IntentHint {
            exclude_models: vec!["author-model-id".to_string()],
            ..Default::default()
        };
        let json = serde_json::to_string(&on).unwrap();
        assert!(json.contains("exclude_models"));
        let back: IntentHint = serde_json::from_str(&json).unwrap();
        assert_eq!(back.exclude_models, vec!["author-model-id".to_string()]);
    }

    #[test]
    fn missing_fields_default_cleanly() {
        // Pre-MVP clients that don't know about IntentHint may send
        // partial JSON. Defaults must match the no-intent path.
        let hint: IntentHint = serde_json::from_str("{}").unwrap();
        assert_eq!(hint.task, None);
        assert!(hint.require.is_empty());
        assert!(!hint.prefer_local);
        assert!(!hint.prefer_fast);
    }

    #[test]
    fn prefer_fast_round_trips_and_skips_when_false() {
        let off = IntentHint::default();
        assert_eq!(serde_json::to_string(&off).unwrap(), "{}");

        let on = IntentHint {
            prefer_fast: true,
            ..IntentHint::default()
        };
        let json = serde_json::to_string(&on).unwrap();
        assert!(json.contains("prefer_fast"));
        let back: IntentHint = serde_json::from_str(&json).unwrap();
        assert!(back.prefer_fast);
    }

    // --- acquisition intent (UseCase / QualityTier / Privacy) ---

    #[test]
    fn use_case_defaults_to_assistant_and_balanced_on_device() {
        assert_eq!(UseCase::default(), UseCase::Assistant);
        assert_eq!(QualityTier::default(), QualityTier::Balanced);
        assert_eq!(Privacy::default(), Privacy::OnDevice);
    }

    #[test]
    fn coding_requires_both_generate_and_code() {
        // Regression guard for the design-review point that a coding
        // model that can't generate is useless — Code alone is not enough.
        let req = UseCase::Coding.required_capabilities();
        assert!(req.contains(&ModelCapability::Generate));
        assert!(req.contains(&ModelCapability::Code));
    }

    #[test]
    fn search_is_a_retrieval_role_not_generative() {
        // Search must never be ranked against chat models.
        assert_eq!(UseCase::Search.role(), UseCaseRole::Retrieval);
        assert_eq!(UseCase::Assistant.role(), UseCaseRole::Generative);
        assert_eq!(UseCase::Transcription.role(), UseCaseRole::Audio);
        assert_eq!(
            UseCase::Search.required_capabilities(),
            &[ModelCapability::Embed]
        );
    }

    #[test]
    fn required_and_preferred_are_disjoint() {
        // A capability listed as required must not also be "preferred" —
        // that would double-count it in scoring.
        for uc in [
            UseCase::Assistant,
            UseCase::Coding,
            UseCase::Summarize,
            UseCase::Vision,
            UseCase::Transcription,
            UseCase::Search,
        ] {
            for p in uc.preferred_capabilities() {
                assert!(
                    !uc.required_capabilities().contains(p),
                    "{uc:?}: {p:?} is both required and preferred"
                );
            }
        }
    }

    #[test]
    fn tier_weights_match_documented_table() {
        let b = QualityTier::Balanced.weights();
        assert_eq!((b.quality, b.latency, b.memory_pressure), (0.5, 0.2, 0.3));
        let f = QualityTier::Fastest.weights();
        assert!(f.latency > f.quality, "Fastest must favor latency");
        let c = QualityTier::MostCapable.weights();
        assert!(c.quality > c.latency, "MostCapable must favor quality");
    }

    #[test]
    fn tier_weights_are_non_negative_and_sum_to_one() {
        // Guards against a future edit silently letting one axis dominate
        // by making weights sum to ≠ 1.0. Epsilon compare for floats.
        for tier in [
            QualityTier::Fastest,
            QualityTier::Balanced,
            QualityTier::MostCapable,
        ] {
            let w = tier.weights();
            for axis in [w.quality, w.latency, w.memory_pressure] {
                assert!(axis >= 0.0, "{tier:?}: negative weight {axis}");
            }
            let sum = w.quality + w.latency + w.memory_pressure;
            assert!(
                (sum - 1.0).abs() < 1e-6,
                "{tier:?}: weights sum to {sum}, expected 1.0"
            );
        }
    }

    #[test]
    fn use_case_round_trips_snake_case() {
        let json = serde_json::to_string(&UseCase::Coding).unwrap();
        assert_eq!(json, "\"coding\"");
        let back: UseCase = serde_json::from_str("\"search\"").unwrap();
        assert_eq!(back, UseCase::Search);
    }
}