car-inference 0.61.2

//! Provider model auto-discovery (Phase E2).
//!
//! Keeps the catalog current *without a release*: queries a remote provider's
//! model list (OpenAI `/v1/models`) and registers previously-unknown
//! chat/reasoning models as [`TrustTier::Community`] entries. Each discovered
//! model clones the schema of a curated same-provider model as a template (the
//! caller picks the most-capable one), so routing metadata (capabilities,
//! endpoint, key env, protocol) is inherited and the actual quality is learned
//! over time via outcomes.
//!
//! Community trust means discovered models are *routable* (incl. under the
//! `prefer_quality` workload) but never background-auto-applied — a deliberate
//! curated/discovered split. The HTTP fetch is the only impure part; the
//! filter and schema-mapping are pure and unit-tested below.

use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::schema::{CostModel, ModelSchema, TrustTier};

/// Cached discovered models, loaded into the registry at startup (alongside the
/// built-in and signed catalogs). Unsigned/best-effort: a corrupt file is
/// ignored, never fatal.
#[derive(Debug, Default, Serialize, Deserialize)]
pub struct DiscoveryDoc {
    #[serde(default)]
    pub models: Vec<ModelSchema>,
}

/// Cache file name, inside the `models/` subdirectory of the CAR state root.
pub const DISCOVERED_MODELS_FILE: &str = "discovered_models.json";

/// Where discovered models are cached, given the *state* models dir —
/// `<CAR state root>/models`, i.e. [`InferenceConfig::state_models_dir`].
///
/// Not the weights dir, even though the two are the same directory
/// (`~/.car/models`) whenever `CAR_HOME` is unset. The weights cache is
/// deliberately machine-shared, so anchoring this there would have a relocated
/// daemon writing its discovery cache into the primary daemon's tree — the
/// shared-state clobber `CAR_HOME` exists to prevent. Keeping the `models/`
/// segment means no existing install's file moves.
///
/// [`InferenceConfig::state_models_dir`]: crate::InferenceConfig::state_models_dir
pub fn cache_path(state_models_dir: &Path) -> PathBuf {
    state_models_dir.join(DISCOVERED_MODELS_FILE)
}

/// Load cached discovered models. Best-effort: returns empty on missing/corrupt.
pub fn load_cache(path: &Path) -> Vec<ModelSchema> {
    std::fs::read_to_string(path)
        .ok()
        .and_then(|s| serde_json::from_str::<DiscoveryDoc>(&s).ok())
        .map(|d| {
            d.models
                .into_iter()
                .map(|mut schema| {
                    // This cache is unsigned and user-writable. Discovery's
                    // provenance, not a serialized field, determines trust.
                    schema.mark_user_registered();
                    schema
                })
                .collect()
        })
        .unwrap_or_default()
}

/// Persist discovered models (overwrites; discovery is idempotent).
pub fn save_cache(path: &Path, models: &[ModelSchema]) -> Result<(), String> {
    let models = models
        .iter()
        .cloned()
        .map(|mut schema| {
            // Defense in depth with `load_cache`: the unsigned cache must stay
            // visibly Community-tier even before its next read.
            schema.mark_user_registered();
            schema
        })
        .collect();
    let doc = DiscoveryDoc { models };
    let json = serde_json::to_string_pretty(&doc).map_err(|e| e.to_string())?;
    // The directory used to be guaranteed by the weight downloader, because
    // this file lived in the weights dir. Now that it lives under the state
    // root, a freshly relocated `CAR_HOME` has no `models/` yet.
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
    }
    std::fs::write(path, json).map_err(|e| e.to_string())
}

/// Heuristic: is this OpenAI model id a chat/reasoning *generation* model, vs.
/// an embedding/audio/image/moderation endpoint we don't route generations to?
///
/// Allow `gpt-*`, `chatgpt-*`, and `o<digit>*` (o3, o4-mini, …); deny anything
/// whose id names a non-generation modality. Conservative-but-permissive: a new
/// `gpt-5.5` passes; `text-embedding-3-large`, `gpt-4o-audio`, `dall-e-3`,
/// `whisper-1`, `omni-moderation-*` are rejected.
pub fn is_chat_model(id: &str) -> bool {
    let id = id.to_ascii_lowercase();
    let is_gen_family = id.starts_with("gpt-")
        || id.starts_with("chatgpt-")
        || (id.starts_with('o') && id[1..].chars().next().is_some_and(|c| c.is_ascii_digit()));
    if !is_gen_family {
        return false;
    }
    const DENY: &[&str] = &[
        "embedding",
        "audio",
        "realtime",
        "transcribe",
        "tts",
        "image",
        "moderation",
        "search",
        "dall",
        "whisper",
        "instruct",
    ];
    !DENY.iter().any(|d| id.contains(d))
}

/// Derive a provider's `/models` listing URL from a catalog endpoint.
///
/// Two shapes are recognized:
/// - a **bare host** (`https://api.openai.com`, with or without a trailing
///   `/`) — the shape every curated OpenAI row carries, because the protocol
///   handler appends `/v1/responses` or `/v1/chat/completions` itself. The
///   listing is `<host>/v1/models`.
/// - an endpoint **with a `/v1` segment** (`…/v1`, `…/v1/chat/completions`) —
///   truncated at that segment, then `/models`.
///
/// Anything else (a non-URL, or a path with no `/v1` segment such as
/// `https://example.com/openai`) returns None: there is no version segment to
/// anchor on, and guessing would send the key somewhere unintended. Before the
/// bare-host case existed, discovery returned `Ok(0)` without a single request
/// for every curated OpenAI row (car-releases#106).
pub fn models_url_from_endpoint(endpoint: &str) -> Option<String> {
    let url = reqwest::Url::parse(endpoint.trim()).ok()?;
    if !matches!(url.scheme(), "http" | "https") || url.host_str().is_none() {
        return None;
    }
    let origin = url.origin().ascii_serialization();
    let path = url.path();
    if path.is_empty() || path == "/" {
        return Some(format!("{origin}/v1/models"));
    }
    // Search the path, not the raw string, so a host such as
    // `v1.example.com` is not mistaken for the version segment.
    let marker = "/v1";
    let idx = path.find(marker)?;
    Some(format!("{origin}{}/models", &path[..idx + marker.len()]))
}

/// The context window a discovered row is given, whatever its template says.
///
/// A discovered id is anything `/v1/models` lists — `gpt-4o`, `gpt-4.1`, dated
/// snapshots, legacy families — and nothing about the template's window holds
/// for it. Inheriting a frontier row's 922K would let context-aware routing
/// send a prompt several times the size of a 128K model's window to it. 128K
/// is the window of every current OpenAI chat family; only the legacy
/// `gpt-4`/`gpt-3.5` snapshots are smaller, and they are rarely routed to.
pub const DISCOVERED_CONTEXT_LENGTH: usize = 128_000;

/// Pick the curated row a discovered model clones its transport from.
///
/// Among curated OpenAI `remote_api` rows: the most capabilities, then the
/// greatest id, so the choice is deterministic over the HashMap-ordered
/// registry. The choice only decides the transport a discovered row inherits
/// (endpoint, credential variable, protocol): [`discovered_schema`] resets the
/// window, capabilities, parameters, price and benchmarks, so a new or
/// unconfirmed template row cannot leak its claims into discovered ones.
pub fn select_template<'a>(rows: impl IntoIterator<Item = &'a ModelSchema>) -> Option<ModelSchema> {
    rows.into_iter()
        .filter(|m| {
            m.provider.eq_ignore_ascii_case("openai")
                && m.trust_tier == TrustTier::Curated
                && matches!(m.source, crate::schema::ModelSource::RemoteApi { .. })
        })
        .max_by(|a, b| {
            a.capabilities
                .len()
                .cmp(&b.capabilities.len())
                .then_with(|| a.id.cmp(&b.id))
        })
        .cloned()
}

/// Build a Community-tier schema for a newly-discovered model from a template
/// (see [`select_template`]).
///
/// Only the transport is inherited: provider, endpoint, credential variable and
/// protocol. Everything that describes the *model* is reset to what an unknown
/// chat model can be assumed to do, because the template's values describe a
/// different model:
/// - `context_length` is [`DISCOVERED_CONTEXT_LENGTH`] and `max_output_tokens`
///   is unknown;
/// - capabilities are `generate` and `code` only — no `vision`, `reasoning` or
///   tool claims;
/// - `supported_params` is `max_tokens` only, so no `extended_thinking` is
///   sent and temperature is omitted (an empty list would mean "all
///   supported");
/// - pricing and benchmarks are cleared. The router damps Community quality and
///   treats unknown cost as non-free; observed quality is learned over time.
pub fn discovered_schema(provider: &str, bare_id: &str, template: &ModelSchema) -> ModelSchema {
    use crate::schema::{GenerateParam, ModelCapability};
    let mut s = template.clone();
    s.id = format!("{provider}/{bare_id}:latest");
    s.name = bare_id.to_string();
    s.version = bare_id.to_string();
    s.trust_tier = TrustTier::Community;
    s.capabilities = vec![ModelCapability::Generate, ModelCapability::Code];
    s.context_length = DISCOVERED_CONTEXT_LENGTH;
    s.max_output_tokens = None;
    s.supported_params = vec![GenerateParam::MaxTokens];
    s.cost = CostModel::default();
    s.public_benchmarks = vec![];
    s.deprecated = false;
    s.available = false; // refresh_availability() decides at registration
    s
}

/// Add every listed chat model that nothing else owns to `cached`.
///
/// `is_registered` answers whether the constructed id is already in the live
/// registry (curated, signed or previously loaded discovered rows); discovery
/// only ever adds ids nothing else owns. Keying on the constructed id is more
/// robust than matching the provider's bare id against curated `name`s.
pub fn merge_discovered(
    cached: &mut Vec<ModelSchema>,
    ids: impl IntoIterator<Item = String>,
    template: &ModelSchema,
    is_registered: impl Fn(&str) -> bool,
) {
    let mut have: std::collections::HashSet<String> = cached.iter().map(|m| m.id.clone()).collect();
    for id in ids {
        if !is_chat_model(&id) {
            continue;
        }
        let schema = discovered_schema("openai", &id, template);
        if is_registered(&schema.id) {
            continue;
        }
        if have.insert(schema.id.clone()) {
            cached.push(schema);
        }
    }
}

/// Fetch the provider's model ids from its `/models` endpoint (OpenAI shape:
/// `{"data":[{"id":...}, ...]}`). Impure (network); kept thin so the logic
/// above stays testable.
pub async fn fetch_model_ids(
    http: &reqwest::Client,
    models_url: &str,
    api_key: &str,
) -> Result<Vec<String>, String> {
    let resp = http
        .get(models_url)
        .bearer_auth(api_key)
        .send()
        .await
        .map_err(|e| format!("discovery fetch: {e}"))?;
    if !resp.status().is_success() {
        return Err(format!("discovery fetch: HTTP {}", resp.status()));
    }
    let body: serde_json::Value = resp
        .json()
        .await
        .map_err(|e| format!("discovery parse: {e}"))?;
    Ok(body
        .get("data")
        .and_then(|d| d.as_array())
        .map(|arr| {
            arr.iter()
                .filter_map(|m| m.get("id").and_then(|i| i.as_str()).map(String::from))
                .collect()
        })
        .unwrap_or_default())
}

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

    #[test]
    fn chat_models_pass_non_generation_rejected() {
        for ok in [
            "gpt-5.5",
            "gpt-5.5-mini",
            "gpt-4.1",
            "o3",
            "o4-mini",
            "chatgpt-4o-latest",
        ] {
            assert!(is_chat_model(ok), "{ok} should be a chat model");
        }
        for no in [
            "text-embedding-3-large",
            "gpt-4o-audio-preview",
            "gpt-realtime",
            "dall-e-3",
            "whisper-1",
            "omni-moderation-latest",
            "gpt-4o-transcribe",
            "tts-1",
            "gpt-image-1",
            "babbage-002",
        ] {
            assert!(!is_chat_model(no), "{no} should be rejected");
        }
    }

    #[test]
    fn models_url_derives_from_chat_endpoint() {
        assert_eq!(
            models_url_from_endpoint("https://api.openai.com/v1/chat/completions").as_deref(),
            Some("https://api.openai.com/v1/models"),
        );
        assert_eq!(
            models_url_from_endpoint("https://api.openai.com/v1/responses").as_deref(),
            Some("https://api.openai.com/v1/models"),
        );
        assert_eq!(models_url_from_endpoint("https://example.com/openai"), None);
        assert_eq!(models_url_from_endpoint("not a url"), None);
        assert_eq!(
            models_url_from_endpoint("https://v1.example.com/openai"),
            None,
            "a v1 host name is not a version segment"
        );
    }

    /// car-releases#106: every curated OpenAI row carries a bare-host endpoint
    /// (the protocol handler appends the `/v1/...` path), and discovery takes
    /// its URL from the most-capable curated OpenAI row. Read the endpoint from
    /// the real catalog rather than restating it, so a catalog change that
    /// moves the endpoint shape is caught here.
    #[test]
    fn models_url_derives_from_the_curated_catalog_endpoint() {
        let catalog: Vec<ModelSchema> =
            serde_json::from_str(include_str!("builtin_catalog.json")).unwrap();
        let mut openai_endpoints: Vec<&str> = catalog
            .iter()
            .filter(|m| m.provider == "openai" && m.trust_tier == TrustTier::Curated)
            .filter_map(|m| match &m.source {
                crate::schema::ModelSource::RemoteApi { endpoint, .. } => Some(endpoint.as_str()),
                _ => None,
            })
            .collect();
        openai_endpoints.dedup();
        assert!(
            !openai_endpoints.is_empty(),
            "catalog must carry OpenAI rows"
        );
        for endpoint in openai_endpoints {
            assert_eq!(
                models_url_from_endpoint(endpoint).as_deref(),
                Some("https://api.openai.com/v1/models"),
                "curated endpoint {endpoint:?} must derive the models listing"
            );
        }
        assert_eq!(
            models_url_from_endpoint("https://api.openai.com/").as_deref(),
            Some("https://api.openai.com/v1/models"),
        );
        assert_eq!(
            models_url_from_endpoint("http://localhost:8080").as_deref(),
            Some("http://localhost:8080/v1/models"),
        );
    }

    #[test]
    fn discovered_schema_inherits_template_and_marks_community() {
        // Use the real gpt-5.4 entry as the template (clone-and-override).
        let catalog: Vec<ModelSchema> =
            serde_json::from_str(include_str!("builtin_catalog.json")).unwrap();
        let template = catalog
            .iter()
            .find(|m| m.id == "openai/gpt-5.4:latest")
            .expect("gpt-5.4 present in builtin catalog");

        let s = discovered_schema("openai", "gpt-5.5", template);
        assert_eq!(s.id, "openai/gpt-5.5:latest");
        assert_eq!(s.name, "gpt-5.5");
        assert_eq!(s.provider, "openai"); // inherited from template
        assert_eq!(s.trust_tier, TrustTier::Community);
        assert!(s.cost.input_per_mtok.is_none()); // pricing cleared (unknown)
        assert!(!s.available);
        assert_eq!(
            serde_json::to_value(&s.source).unwrap(),
            serde_json::to_value(&template.source).unwrap(),
            "transport is inherited"
        );
    }

    /// A discovered row runs end to end through the provider listing: fetch
    /// from a stand-in for `/v1/models` (a system-boundary fake), merge, and
    /// check which rows are cached and what each one inherits. The template is
    /// whatever `select_template` picks from the real catalog, so a new
    /// frontier row becoming the template cannot hand its window, vision,
    /// reasoning or extended-thinking claims to `gpt-4o`.
    #[tokio::test]
    async fn discovered_rows_inherit_transport_only_from_the_live_listing() {
        use crate::schema::{GenerateParam, ModelCapability, ModelSource};
        use wiremock::matchers::{header, method, path};
        use wiremock::{Mock, MockServer, ResponseTemplate};

        let catalog: Vec<ModelSchema> =
            serde_json::from_str(include_str!("builtin_catalog.json")).unwrap();
        let mut template = select_template(&catalog).expect("curated OpenAI template");
        assert!(
            template.context_length > DISCOVERED_CONTEXT_LENGTH,
            "the template must claim more than a discovered row may, or this test proves nothing"
        );
        assert!(template.has_capability(ModelCapability::Vision));
        assert!(template
            .supported_params
            .contains(&GenerateParam::ExtendedThinking));

        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/v1/models"))
            .and(header("authorization", "Bearer test-key"))
            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
                "data": [
                    {"id": "gpt-4o"},
                    {"id": "text-embedding-3-large"},
                    {"id": "gpt-5.6-sol"},
                    {"id": "gpt-4o"}
                ]
            })))
            .expect(1)
            .mount(&server)
            .await;
        if let ModelSource::RemoteApi { endpoint, .. } = &mut template.source {
            *endpoint = server.uri();
        }
        let ModelSource::RemoteApi { endpoint, .. } = &template.source else {
            panic!("template is a remote_api row");
        };
        let url = models_url_from_endpoint(endpoint).expect("bare mock host derives a URL");
        let ids = fetch_model_ids(
            &crate::tls_client::test_seam::trust_store_independent_client(),
            &url,
            "test-key",
        )
        .await
        .unwrap();

        let mut cached = Vec::new();
        merge_discovered(&mut cached, ids, &template, |id| {
            catalog.iter().any(|m| m.id == id)
        });

        let got: Vec<&str> = cached.iter().map(|m| m.id.as_str()).collect();
        assert_eq!(
            got,
            vec!["openai/gpt-4o:latest"],
            "embeddings are filtered, curated ids are not shadowed, duplicates collapse"
        );
        let row = &cached[0];
        assert_eq!(row.trust_tier, TrustTier::Community);
        assert_eq!(row.context_length, DISCOVERED_CONTEXT_LENGTH);
        assert_eq!(row.max_output_tokens, None);
        assert_eq!(
            row.capabilities,
            vec![ModelCapability::Generate, ModelCapability::Code]
        );
        assert_eq!(row.supported_params, vec![GenerateParam::MaxTokens]);
        assert!(row.cost.output_per_mtok.is_none());
        assert!(row.public_benchmarks.is_empty());
        assert_eq!(
            serde_json::to_value(&row.source).unwrap(),
            serde_json::to_value(&template.source).unwrap(),
            "endpoint, key and protocol inherited"
        );
    }

    #[test]
    fn cached_rows_are_always_community_even_when_curated_or_omitted() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join("discovered_models.json");
        let catalog: Vec<ModelSchema> =
            serde_json::from_str(include_str!("builtin_catalog.json")).unwrap();
        let template = catalog
            .iter()
            .find(|m| m.id == "openai/gpt-5.4:latest")
            .expect("gpt-5.4 present in builtin catalog");

        let mut explicit = discovered_schema("openai", "forged-explicit", template);
        explicit.trust_tier = TrustTier::Curated;
        let explicit_for_save = explicit.clone();
        let omitted = discovered_schema("openai", "forged-omitted", template);
        let mut omitted_value = serde_json::to_value(omitted).unwrap();
        omitted_value.as_object_mut().unwrap().remove("trust_tier");
        std::fs::write(
            &path,
            serde_json::to_vec_pretty(&serde_json::json!({
                "models": [explicit, omitted_value]
            }))
            .unwrap(),
        )
        .unwrap();

        let loaded = load_cache(&path);
        assert_eq!(loaded.len(), 2);
        assert!(
            loaded
                .iter()
                .all(|schema| schema.trust_tier == TrustTier::Community),
            "unsigned discovery cache rows must never manufacture project curation: {loaded:?}"
        );

        save_cache(&path, &[explicit_for_save]).unwrap();
        let raw: DiscoveryDoc = serde_json::from_slice(&std::fs::read(&path).unwrap()).unwrap();
        assert_eq!(raw.models[0].trust_tier, TrustTier::Community);
    }
}