wyrd-spec 0.4.0

//! `OpenAI`-compatible public operation contracts of the gateway.
//!
//! Chat Completions, Responses, and Embeddings requests reuse the exact Skald
//! wire shapes, which the translating adapters already decode, through
//! transparent newtypes so this crate owns their public schema. Media, file,
//! batch, model, and error envelopes that Skald does not model are declared
//! here. Every envelope the provider may extend keeps unmodeled members in a
//! flattened `extra` map, so supported extension fields survive a decode and
//! re-encode. Numbers in `multipart/form-data` forms travel as text, so form
//! contracts publish the fields a form carries rather than decode one.
//!
//! With the `server` feature each contract also implements
//! [`utoipa::ToSchema`] by converting its generated JSON Schema, so the
//! published OpenAPI document shows the same concrete fields as the schema.

use std::collections::BTreeMap;

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use skald_spec::wire::openai_chat::{OpenAiChatRequest, OpenAiChatResponse};
use skald_spec::wire::openai_embeddings::{OpenAiEmbeddingUsage, OpenAiEmbeddingsRequest};
use skald_spec::wire::openai_responses::{OpenAiResponsesRequest, OpenAiResponsesResponse};

/// `POST /v1/chat/completions` request: the `OpenAI` Chat Completions body
/// whose `model` is an exact `<provider>/<model>` projection.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(transparent)]
pub struct GatewayChatCompletionsRequest(
    /// The Chat Completions body, decoded and relayed as the native `OpenAI` shape.
    pub OpenAiChatRequest,
);

/// Buffered `POST /v1/chat/completions` answer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(transparent)]
pub struct GatewayChatCompletion(
    /// The provider's Chat Completions answer in the native `OpenAI` shape.
    pub OpenAiChatResponse,
);

/// `POST /v1/responses` request: the `OpenAI` Responses body whose `model` is
/// an exact `<provider>/<model>` projection.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(transparent)]
pub struct GatewayResponsesRequest(
    /// The Responses body, decoded and relayed as the native `OpenAI` shape.
    pub OpenAiResponsesRequest,
);

/// Buffered `POST /v1/responses` answer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(transparent)]
pub struct GatewayResponse(
    /// The provider's Responses answer in the native `OpenAI` shape.
    pub OpenAiResponsesResponse,
);

/// `POST /v1/embeddings` request: the `OpenAI` Embeddings body whose `model`
/// is an exact `<provider>/<model>` projection.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(transparent)]
pub struct GatewayEmbeddingsRequest(
    /// The Embeddings body, decoded and relayed as the native `OpenAI` shape.
    pub OpenAiEmbeddingsRequest,
);

/// `POST /v1/embeddings` answer: one embedding per input, in input order.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayEmbeddings {
    /// Always `list`.
    pub object: String,
    /// Model that produced the embeddings.
    pub model: String,
    /// Embeddings whose `index` equals their position.
    pub data: Vec<GatewayEmbedding>,
    /// Token usage of the call.
    pub usage: OpenAiEmbeddingUsage,
    /// Unmodeled provider members.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// One embedding of a [`GatewayEmbeddings`] answer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayEmbedding {
    /// Always `embedding`.
    pub object: String,
    /// Position of the input this embedding represents.
    pub index: u32,
    /// Vector in the requested `encoding_format`.
    pub embedding: GatewayEmbeddingVector,
}

/// An embedding vector in its requested representation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(untagged)]
pub enum GatewayEmbeddingVector {
    /// `float` (or omitted) encoding: the components.
    Float(Vec<f32>),
    /// `base64` encoding: little-endian `f32` components.
    Base64(String),
}

/// `POST /v1/images/generations` request.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayImageGenerationRequest {
    /// Exact `<provider>/<model>` projection.
    pub model: String,
    /// Description of the images to generate.
    pub prompt: String,
    /// Number of images.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub n: Option<u32>,
    /// Image size, such as `1024x1024`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub size: Option<String>,
    /// Image quality.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quality: Option<String>,
    /// `url` or `b64_json`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub response_format: Option<String>,
    /// End-user identifier.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub user: Option<String>,
    /// Supported provider extensions, relayed unchanged.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// Binary content published as an `OpenAPI` binary string: one uploaded file
/// of a `multipart/form-data` form, or a raw `application/octet-stream` body.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct GatewayFormFile;

impl JsonSchema for GatewayFormFile {
    /// Names the shared binary part schema.
    fn schema_name() -> std::borrow::Cow<'static, str> {
        "GatewayFormFile".into()
    }

    /// Publishes a binary string, the `OpenAPI` shape of a file part.
    fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
        schemars::json_schema!({ "type": "string", "format": "binary" })
    }
}

/// `POST /v1/images/edits` form.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayImageEditForm {
    /// Exact `<provider>/<model>` projection.
    pub model: String,
    /// One to sixteen images, sent as `image` or `image[]` parts.
    pub image: Vec<GatewayFormFile>,
    /// Optional mask image.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mask: Option<GatewayFormFile>,
    /// Description of the edit.
    pub prompt: String,
    /// Number of images.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub n: Option<u32>,
    /// Image size.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub size: Option<String>,
    /// `url` or `b64_json`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub response_format: Option<String>,
    /// End-user identifier.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub user: Option<String>,
    /// Supported provider extensions, relayed unchanged.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// `POST /v1/images/variations` form.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayImageVariationForm {
    /// Exact `<provider>/<model>` projection.
    pub model: String,
    /// The one source image.
    pub image: GatewayFormFile,
    /// Number of images.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub n: Option<u32>,
    /// Image size.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub size: Option<String>,
    /// `url` or `b64_json`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub response_format: Option<String>,
    /// End-user identifier.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub user: Option<String>,
    /// Supported provider extensions, relayed unchanged.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// Images answer of generations, edits, and variations.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayImages {
    /// Unix time the images were created.
    pub created: u64,
    /// Generated images.
    pub data: Vec<GatewayImage>,
    /// Unmodeled provider members, such as `usage`.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// One image of a [`GatewayImages`] answer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayImage {
    /// Base64 image data, for `b64_json`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub b64_json: Option<String>,
    /// Image URL, for `url`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    /// Prompt the provider actually used.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub revised_prompt: Option<String>,
    /// Unmodeled provider members.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// `POST /v1/audio/speech` request.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewaySpeechRequest {
    /// Exact `<provider>/<model>` projection.
    pub model: String,
    /// Text to speak.
    pub input: String,
    /// Voice name.
    pub voice: String,
    /// Delivery instructions.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub instructions: Option<String>,
    /// Audio format, such as `mp3`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub response_format: Option<String>,
    /// Playback speed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub speed: Option<f64>,
    /// Supported provider extensions, relayed unchanged.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// `POST /v1/audio/transcriptions` form.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayTranscriptionForm {
    /// Exact `<provider>/<model>` projection.
    pub model: String,
    /// The one audio file.
    pub file: GatewayFormFile,
    /// ISO-639-1 input language.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub language: Option<String>,
    /// Style or context prompt.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub prompt: Option<String>,
    /// `json`, `text`, `srt`, `verbose_json`, or `vtt`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub response_format: Option<String>,
    /// Sampling temperature.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub temperature: Option<f64>,
    /// Supported provider extensions, such as `timestamp_granularities[]`.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// `POST /v1/audio/translations` form.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayTranslationForm {
    /// Exact `<provider>/<model>` projection.
    pub model: String,
    /// The one audio file.
    pub file: GatewayFormFile,
    /// Style or context prompt.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub prompt: Option<String>,
    /// `json`, `text`, `srt`, `verbose_json`, or `vtt`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub response_format: Option<String>,
    /// Sampling temperature.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub temperature: Option<f64>,
    /// Supported provider extensions, relayed unchanged.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// JSON transcript or translation answer.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayTranscription {
    /// The text.
    pub text: String,
    /// Unmodeled provider members, such as `segments` or `usage`.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// `GET /v1/models` answer.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayModelList {
    /// Always `list`.
    pub object: String,
    /// Invocable model projections.
    pub data: Vec<GatewayModel>,
}

/// One model of a [`GatewayModelList`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayModel {
    /// Exact `<provider>/<model>` projection.
    pub id: String,
    /// Always `model`.
    pub object: String,
    /// Always `0`: the gateway records no provider release time.
    pub created: u64,
    /// The provider.
    pub owned_by: String,
}

/// `POST /v1/files` form.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayFileUploadForm {
    /// Always `batch`.
    pub purpose: String,
    /// Batch JSONL whose request lines target one endpoint and one model.
    pub file: GatewayFormFile,
}

/// `OpenAI` file object of an uploaded batch input file.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayFile {
    /// Wyrd file id.
    pub id: String,
    /// Always `file`.
    pub object: String,
    /// Size in bytes.
    pub bytes: i64,
    /// Unix upload time.
    pub created_at: i64,
    /// Uploaded file name.
    pub filename: String,
    /// Always `batch`.
    pub purpose: String,
}

/// `DELETE /v1/files/{file_id}` answer.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayFileDeleted {
    /// Deleted Wyrd file id.
    pub id: String,
    /// Always `file`.
    pub object: String,
    /// Always `true`.
    pub deleted: bool,
}

/// `POST /v1/batches` request; an identical request converges on one batch.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayBatchCreateRequest {
    /// Wyrd id of the uploaded input file.
    pub input_file_id: String,
    /// The endpoint every input file request targets.
    pub endpoint: String,
    /// Completion window, such as `24h`.
    pub completion_window: String,
    /// Caller metadata.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub metadata: Option<BTreeMap<String, String>>,
    /// Supported provider extensions, relayed unchanged.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// `OpenAI` batch object with Wyrd batch and file ids.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayBatch {
    /// Wyrd batch id.
    pub id: String,
    /// Always `batch`.
    pub object: String,
    /// Endpoint of the batch requests.
    pub endpoint: String,
    /// Wyrd id of the input file.
    pub input_file_id: String,
    /// Completion window.
    pub completion_window: String,
    /// Last observed provider status.
    pub status: String,
    /// Wyrd id of the output file, once observed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub output_file_id: Option<String>,
    /// Wyrd id of the error file, once observed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error_file_id: Option<String>,
    /// Unix creation time.
    pub created_at: i64,
    /// Caller metadata.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub metadata: Option<BTreeMap<String, String>>,
    /// Unmodeled provider members, such as `request_counts`.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// `GET /v1/batches` answer, newest first.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct GatewayBatchList {
    /// Always `list`.
    pub object: String,
    /// Visible batches.
    pub data: Vec<GatewayBatch>,
    /// Id of the first listed batch.
    pub first_id: Option<String>,
    /// Id of the last listed batch, the next page's `after`.
    pub last_id: Option<String>,
    /// Whether a later page exists.
    pub has_more: bool,
}

/// `GET /v1/batches` query.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[cfg_attr(feature = "server", derive(utoipa::IntoParams))]
#[cfg_attr(feature = "server", into_params(parameter_in = Query))]
pub struct GatewayBatchListQuery {
    /// Last batch id of the previous page.
    #[serde(default)]
    pub after: Option<String>,
    /// Page size between 1 and 100; default 20.
    #[serde(default)]
    #[schemars(range(min = 1, max = 100))]
    #[cfg_attr(feature = "server", param(minimum = 1, maximum = 100))]
    pub limit: Option<u32>,
}

/// `OpenAI` error envelope of every gateway-originated refusal.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct OpenAiErrorEnvelope {
    /// The error.
    pub error: OpenAiError,
}

/// Body of an [`OpenAiErrorEnvelope`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct OpenAiError {
    /// Human-readable message.
    pub message: String,
    /// `OpenAI` error type, such as `invalid_request_error`.
    #[serde(rename = "type")]
    pub kind: String,
    /// Offending request member.
    pub param: Option<String>,
    /// Stable Wyrd error code.
    pub code: Option<String>,
}

/// Implements [`utoipa::ToSchema`] for contracts from their JSON Schema.
#[cfg(feature = "server")]
macro_rules! openapi_schema {
    ($($name:ident),+ $(,)?) => {$(
        impl utoipa::PartialSchema for $name {
            /// Converts the contract's root JSON Schema.
            fn schema() -> utoipa::openapi::RefOr<utoipa::openapi::schema::Schema> {
                $crate::gateway::openai::openapi::component::<Self>().0
            }
        }

        impl utoipa::ToSchema for $name {
            /// The contract's type name.
            fn name() -> std::borrow::Cow<'static, str> {
                std::borrow::Cow::Borrowed(stringify!($name))
            }

            /// Registers every named JSON Schema definition the contract uses.
            fn schemas(
                schemas: &mut Vec<(String, utoipa::openapi::RefOr<utoipa::openapi::schema::Schema>)>,
            ) {
                schemas.extend($crate::gateway::openai::openapi::component::<Self>().1);
            }
        }
    )+};
}

#[cfg(feature = "server")]
pub(crate) use openapi_schema;

#[cfg(feature = "server")]
openapi_schema!(
    GatewayChatCompletionsRequest,
    GatewayChatCompletion,
    GatewayResponsesRequest,
    GatewayResponse,
    GatewayEmbeddingsRequest,
    GatewayEmbeddings,
    GatewayImageGenerationRequest,
    GatewayImageEditForm,
    GatewayImageVariationForm,
    GatewayImages,
    GatewaySpeechRequest,
    GatewayTranscriptionForm,
    GatewayTranslationForm,
    GatewayTranscription,
    GatewayModelList,
    GatewayFileUploadForm,
    GatewayFile,
    GatewayFileDeleted,
    GatewayFormFile,
    GatewayBatchCreateRequest,
    GatewayBatch,
    GatewayBatchList,
    OpenAiErrorEnvelope,
);

/// Structural JSON Schema to `OpenAPI` schema conversion.
///
/// Converting through the `utoipa` builders, rather than deserializing JSON
/// into `utoipa`'s untagged schema enum, keeps composite schemas: that enum
/// would accept an `anyOf` as an empty object and silently drop its
/// alternatives.
#[cfg(feature = "server")]
pub(crate) mod openapi {
    use schemars::JsonSchema;
    use schemars::generate::SchemaSettings;
    use serde_json::{Map, Value};
    use utoipa::openapi::schema::{
        AdditionalProperties, AllOfBuilder, AnyOfBuilder, ArrayBuilder, ObjectBuilder,
        OneOfBuilder, Schema, SchemaFormat, SchemaType, Type,
    };
    use utoipa::openapi::{Ref, RefOr};

    /// Named `OpenAPI` components of one converted definition set.
    pub(crate) type Components = Vec<(String, RefOr<Schema>)>;

    /// Root schema of `T` and its named definitions, referenced as components.
    ///
    /// A `#[serde(transparent)]` root is generated as a reference to the type
    /// it wraps; the root then publishes that definition's own schema.
    pub(crate) fn component<T: JsonSchema>() -> (RefOr<Schema>, Components) {
        /// Where schemars places definitions and where they are read back:
        /// the `OpenAPI` components pointer, so generated `$ref`s already
        /// name the published components.
        const PATH: &str = "/components/schemas";
        let mut settings = SchemaSettings::draft2020_12();
        settings.definitions_path = PATH.into();
        settings.meta_schema = None;
        let root = settings
            .into_generator()
            .into_root_schema_for::<T>()
            .to_value();
        let schemas = root
            .pointer(PATH)
            .and_then(Value::as_object)
            .cloned()
            .unwrap_or_default();
        let wrapped = root
            .get("$ref")
            .and_then(Value::as_str)
            .and_then(|reference| reference.strip_prefix('#'))
            .and_then(|pointer| root.pointer(pointer));
        let definitions = schemas
            .iter()
            .map(|(name, schema)| (name.clone(), convert(schema)))
            .collect();
        (convert(wrapped.unwrap_or(&root)), definitions)
    }

    /// Converts one schema; a boolean schema accepts any value.
    fn convert(schema: &Value) -> RefOr<Schema> {
        match schema {
            Value::Object(schema) => object(schema),
            _ => ObjectBuilder::new()
                .schema_type(SchemaType::AnyValue)
                .build()
                .into(),
        }
    }

    /// Converts a schema object: a reference, a composite joined with its own
    /// constraints, or a plain schema.
    fn object(schema: &Map<String, Value>) -> RefOr<Schema> {
        if let Some(Value::String(reference)) = schema.get("$ref") {
            return Ref::new(reference.clone()).into();
        }
        let description = schema
            .get("description")
            .and_then(Value::as_str)
            .map(str::to_owned);
        let items = |keyword: &str| {
            schema
                .get(keyword)
                .and_then(Value::as_array)
                .map(|schemas| schemas.iter().map(convert).collect::<Vec<_>>())
        };
        let composite: Option<Schema> = if let Some(one_of) = items("oneOf") {
            Some(
                one_of
                    .into_iter()
                    .fold(OneOfBuilder::new(), OneOfBuilder::item)
                    .into(),
            )
        } else if let Some(any_of) = items("anyOf") {
            Some(
                any_of
                    .into_iter()
                    .fold(AnyOfBuilder::new(), AnyOfBuilder::item)
                    .into(),
            )
        } else {
            items("allOf").map(|all_of| {
                all_of
                    .into_iter()
                    .fold(AllOfBuilder::new(), AllOfBuilder::item)
                    .into()
            })
        };
        let constrained = ["type", "properties", "items", "enum", "const"]
            .iter()
            .any(|keyword| schema.contains_key(*keyword));
        match composite {
            Some(composite) if constrained => AllOfBuilder::new()
                .item(plain(schema, None))
                .item(composite)
                .description(description)
                .into(),
            Some(composite) => wrap_description(composite, description),
            None => plain(schema, description).into(),
        }
    }

    /// Attaches `description` to a composite schema.
    fn wrap_description(composite: Schema, description: Option<String>) -> RefOr<Schema> {
        match (composite, description) {
            (Schema::OneOf(mut one_of), description) => {
                one_of.description = description;
                Schema::OneOf(one_of).into()
            }
            (Schema::AnyOf(mut any_of), description) => {
                any_of.description = description;
                Schema::AnyOf(any_of).into()
            }
            (Schema::AllOf(mut all_of), description) => {
                all_of.description = description;
                Schema::AllOf(all_of).into()
            }
            (other, _) => other.into(),
        }
    }

    /// Converts a schema's type, format, values, and array or object members.
    fn plain(schema: &Map<String, Value>, description: Option<String>) -> Schema {
        let schema_type = match schema.get("type") {
            Some(Value::String(kind)) => SchemaType::Type(type_of(kind)),
            Some(Value::Array(kinds)) => SchemaType::Array(
                kinds
                    .iter()
                    .filter_map(Value::as_str)
                    .map(type_of)
                    .collect(),
            ),
            _ => SchemaType::AnyValue,
        };
        let count = |keyword: &str| {
            schema
                .get(keyword)
                .and_then(Value::as_u64)
                .and_then(|n| usize::try_from(n).ok())
        };
        if schema.get("type").and_then(Value::as_str) == Some("array")
            || schema.contains_key("items")
        {
            let items = match schema.get("items") {
                Some(item @ Value::Object(_)) => convert(item),
                _ => convert(&Value::Bool(true)),
            };
            return ArrayBuilder::new()
                .schema_type(schema_type)
                .items(items)
                .min_items(count("minItems"))
                .max_items(count("maxItems"))
                .description(description)
                .into();
        }
        let values = schema
            .get("enum")
            .and_then(Value::as_array)
            .cloned()
            .or_else(|| schema.get("const").map(|value| vec![value.clone()]));
        let mut builder = ObjectBuilder::new()
            .schema_type(schema_type)
            .format(
                schema
                    .get("format")
                    .and_then(Value::as_str)
                    .map(|format| SchemaFormat::Custom(format.to_owned())),
            )
            .description(description)
            .enum_values(values)
            .minimum(schema.get("minimum").and_then(Value::as_f64))
            .maximum(schema.get("maximum").and_then(Value::as_f64));
        if let Some(Value::Object(properties)) = schema.get("properties") {
            for (name, property) in properties {
                builder = builder.property(name, convert(property));
            }
        }
        if let Some(Value::Array(required)) = schema.get("required") {
            for name in required.iter().filter_map(Value::as_str) {
                builder = builder.required(name);
            }
        }
        builder =
            builder.additional_properties(schema.get("additionalProperties").map(
                |extra| match extra {
                    Value::Bool(allowed) => AdditionalProperties::FreeForm(*allowed),
                    extra => AdditionalProperties::RefOr(convert(extra)),
                },
            ));
        builder.into()
    }

    /// The `OpenAPI` type of a JSON Schema instance type.
    fn type_of(kind: &str) -> Type {
        match kind {
            "null" => Type::Null,
            "boolean" => Type::Boolean,
            "object" => Type::Object,
            "array" => Type::Array,
            "number" => Type::Number,
            "integer" => Type::Integer,
            _ => Type::String,
        }
    }
}

#[cfg(test)]
mod tests {
    use serde_json::json;

    use super::*;

    /// Every extensible envelope decodes and re-encodes a body with supported
    /// extension fields unchanged.
    ///
    /// # Panics
    ///
    /// Panics when a decode fails or an extension member is lost or altered.
    #[test]
    fn supported_extensions_round_trip() {
        fn round_trip<T: serde::de::DeserializeOwned + Serialize>(body: &Value) {
            let decoded: T = serde_json::from_value(body.clone()).expect("contract decodes");
            assert_eq!(&serde_json::to_value(decoded).expect("encodes"), body);
        }
        round_trip::<GatewayChatCompletionsRequest>(&json!({
            "model": "acme/m", "messages": [{"role": "user", "content": "hi"}],
            "vendor_hint": {"cache": true}
        }));
        round_trip::<GatewayResponsesRequest>(&json!({
            "model": "acme/m", "input": [], "vendor_hint": 1
        }));
        round_trip::<GatewayImageGenerationRequest>(&json!({
            "model": "acme/i", "prompt": "a fox", "n": 2, "background": "transparent"
        }));
        round_trip::<GatewaySpeechRequest>(&json!({
            "model": "acme/t", "input": "hi", "voice": "alloy", "stream_format": "audio"
        }));
        round_trip::<GatewayBatchCreateRequest>(&json!({
            "input_file_id": "file-1", "endpoint": "/v1/chat/completions",
            "completion_window": "24h", "metadata": {"k": "v"}, "output_expires_after": {"seconds": 3600}
        }));
        round_trip::<GatewayEmbeddings>(&json!({
            "object": "list", "model": "acme/e",
            "data": [{"object": "embedding", "index": 0, "embedding": "AAAAAA=="}],
            "usage": {"prompt_tokens": 1, "total_tokens": 1}, "vendor": "x"
        }));
        round_trip::<GatewayBatch>(&json!({
            "id": "batch_1", "object": "batch", "endpoint": "/v1/chat/completions",
            "input_file_id": "file-1", "completion_window": "24h", "status": "completed",
            "output_file_id": "file-1-output", "created_at": 1,
            "request_counts": {"total": 1, "completed": 1, "failed": 0}
        }));
    }
}