harn-vm 0.10.64

//! Catalog-authored presentation metadata for model pickers.
//!
//! Runtime routing does not consume these records. They let hosts render
//! recommendation presets and one- or two-dimensional model families without
//! hardcoding provider/model names in each UI. A recommendation may also carry
//! the reviewed measurement receipts that make it eligible as a host default.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Default, Deserialize, Serialize, PartialEq, Eq)]
pub struct PresentationConfig {
    /// Stable recommendation id -> authored display copy and generic selector.
    #[serde(default)]
    pub variants: BTreeMap<String, PresentationVariantDef>,
    /// Stable presentation-family id -> ordered dimensions and presets.
    #[serde(default)]
    pub families: BTreeMap<String, ModelFamilyDef>,
}

impl PresentationConfig {
    pub fn is_empty(&self) -> bool {
        self.variants.is_empty() && self.families.is_empty()
    }
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
pub struct PresentationVariantDef {
    /// Ascending display order in the resolved recommendation array.
    pub order: u16,
    pub label: String,
    pub description: String,
    pub selector: PresentationVariantSelector,
    /// Reviewed evidence authorizing this concrete route as the automatic host
    /// default. Absence means the variant is picker-only.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub automatic_eligibility: Option<AutomaticModelEligibility>,
}

/// Catalog-owned decision that a measured route may be selected automatically.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
pub struct AutomaticModelEligibility {
    pub schema: AutomaticModelEligibilitySchema,
    pub decision: AutomaticModelEligibilityDecision,
    pub receipts: Vec<ModelEligibilityMeasurement>,
}

#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq)]
pub enum AutomaticModelEligibilitySchema {
    #[serde(rename = "harn.automatic_model_eligibility.v1")]
    V1,
}

#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum AutomaticModelEligibilityDecision {
    Eligible,
}

/// One exact, reproducible measured input to an automatic-eligibility review.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
pub struct ModelEligibilityMeasurement {
    pub kind: ModelEligibilityMeasurementKind,
    pub source: String,
    pub observed_at: String,
    pub harn_version: String,
    pub passed: u32,
    pub trials: u32,
}

#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ModelEligibilityMeasurementKind {
    MeterHoldout,
    ToolCallFidelity,
    ProviderHealth,
}

/// Small, deliberately closed selector vocabulary for global recommendations.
///
/// This keeps labels and choices in catalog data without growing a second
/// model-query language. The resolved artifact always contains a concrete
/// provider/model pair.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum PresentationVariantSelector {
    Alias { name: String },
    Model { model_id: String },
    BestLocal,
    CheapestHosted,
    LargestVisionContext,
    LargestContext,
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
pub struct ModelFamilyDef {
    pub label: String,
    pub plain_description: String,
    /// Concrete model for families without a model/variant dimension, such as
    /// a one-dimensional reasoning-effort family.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub model_id: Option<String>,
    pub dimensions: Vec<ModelFamilyDimensionDef>,
    pub presets: Vec<ModelFamilyPresetDef>,
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
pub struct ModelFamilyDimensionDef {
    pub key: String,
    pub label: String,
    pub plain_description: String,
    pub kind: ModelFamilyDimensionKind,
    pub ordered_values: Vec<ModelFamilyValueDef>,
}

#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ModelFamilyDimensionKind {
    /// Each value selects a concrete model id.
    Model,
    /// Each value is a provider reasoning-effort token.
    ReasoningEffort,
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
pub struct ModelFamilyValueDef {
    pub value: String,
    pub label: String,
    pub plain_description: String,
    pub relative_cost_hint: u8,
    pub relative_speed_hint: u8,
    /// Required only for values on a `model` dimension.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub model_id: Option<String>,
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
pub struct ModelFamilyPresetDef {
    pub id: String,
    pub label: String,
    pub plain_blurb: String,
    pub coordinates: BTreeMap<String, String>,
}