liter_llm 1.0.0.pre.rc.6

data/vendor/liter-llm/src/tower/tests_common.rs

@@ -0,0 +1,252 @@
+//! Shared test helpers for tower middleware tests.
+//!
+//! This module provides a [`MockClient`] and helper functions used across
+//! multiple middleware test modules.
+#![allow(dead_code)]
+
+use std::pin::Pin;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::task::{Context, Poll};
+
+use futures_core::Stream;
+
+use crate::client::{BoxFuture, BoxStream, LlmClient};
+use crate::error::{LiterLlmError, Result};
+use crate::types::audio::{CreateSpeechRequest, CreateTranscriptionRequest, TranscriptionResponse};
+use crate::types::image::{CreateImageRequest, ImagesResponse};
+use crate::types::moderation::{ModerationRequest, ModerationResponse};
+use crate::types::ocr::{OcrRequest, OcrResponse};
+use crate::types::rerank::{RerankRequest, RerankResponse};
+use crate::types::search::{SearchRequest, SearchResponse};
+use crate::types::{
+    AssistantMessage, ChatCompletionChunk, ChatCompletionRequest, ChatCompletionResponse, Choice, EmbeddingObject,
+    EmbeddingRequest, EmbeddingResponse, FinishReason, Message, ModelsListResponse, SystemMessage, Usage,
+};
+
+/// A stream that yields no items.
+pub struct EmptyStream;
+
+impl Stream for EmptyStream {
+    type Item = Result<ChatCompletionChunk>;
+    fn poll_next(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        Poll::Ready(None)
+    }
+}
+
+/// A serializable subset of [`LiterLlmError`] variants used in tests.
+/// `LiterLlmError` is not `Clone`, so we store an enum of the variants we care about.
+pub enum LiterLlmErrorKind {
+    RateLimited { message: String },
+    ServiceUnavailable { message: String },
+    Timeout,
+    Authentication { message: String },
+}
+
+impl LiterLlmErrorKind {
+    pub fn to_error(&self) -> LiterLlmError {
+        match self {
+            Self::RateLimited { message } => LiterLlmError::RateLimited {
+                message: message.clone(),
+                retry_after: None,
+            },
+            Self::ServiceUnavailable { message } => LiterLlmError::ServiceUnavailable {
+                message: message.clone(),
+            },
+            Self::Timeout => LiterLlmError::Timeout,
+            Self::Authentication { message } => LiterLlmError::BadRequest {
+                message: message.clone(),
+            },
+        }
+    }
+}
+
+/// A synchronous mock client. All methods return configurable canned
+/// responses or errors.
+#[derive(Clone)]
+pub struct MockClient {
+    /// When set, `chat` returns this error instead of the canned response.
+    chat_error: Option<Arc<LiterLlmErrorKind>>,
+    /// Number of times `chat` / `chat_stream` has been called.
+    pub call_count: Arc<AtomicUsize>,
+}
+
+pub fn make_chat_response(model: &str) -> ChatCompletionResponse {
+    ChatCompletionResponse {
+        id: "test-id".into(),
+        object: "chat.completion".into(),
+        created: 0,
+        model: model.into(),
+        choices: vec![Choice {
+            index: 0,
+            message: AssistantMessage {
+                content: Some("Hello!".into()),
+                name: None,
+                tool_calls: None,
+                refusal: None,
+                function_call: None,
+            },
+            finish_reason: Some(FinishReason::Stop),
+        }],
+        usage: Some(Usage {
+            prompt_tokens: 10,
+            completion_tokens: 5,
+            total_tokens: 15,
+        }),
+        system_fingerprint: None,
+        service_tier: None,
+    }
+}
+
+impl MockClient {
+    fn new_with_error(error: Option<LiterLlmErrorKind>) -> Self {
+        Self {
+            chat_error: error.map(Arc::new),
+            call_count: Arc::new(AtomicUsize::new(0)),
+        }
+    }
+
+    pub fn ok() -> Self {
+        Self::new_with_error(None)
+    }
+
+    pub fn failing_rate_limited() -> Self {
+        Self::new_with_error(Some(LiterLlmErrorKind::RateLimited {
+            message: "too many requests".into(),
+        }))
+    }
+
+    pub fn failing_service_unavailable() -> Self {
+        Self::new_with_error(Some(LiterLlmErrorKind::ServiceUnavailable { message: "503".into() }))
+    }
+
+    pub fn failing_auth() -> Self {
+        Self::new_with_error(Some(LiterLlmErrorKind::Authentication {
+            message: "invalid key".into(),
+        }))
+    }
+
+    pub fn failing_timeout() -> Self {
+        Self::new_with_error(Some(LiterLlmErrorKind::Timeout))
+    }
+}
+
+impl LlmClient for MockClient {
+    fn chat(&self, req: ChatCompletionRequest) -> BoxFuture<'_, ChatCompletionResponse> {
+        self.call_count.fetch_add(1, Ordering::SeqCst);
+        let result = match &self.chat_error {
+            Some(kind) => Err(kind.to_error()),
+            None => Ok(make_chat_response(&req.model)),
+        };
+        Box::pin(async move { result })
+    }
+
+    fn chat_stream(&self, _req: ChatCompletionRequest) -> BoxFuture<'_, BoxStream<'_, ChatCompletionChunk>> {
+        self.call_count.fetch_add(1, Ordering::SeqCst);
+        Box::pin(async move {
+            let stream: BoxStream<'_, ChatCompletionChunk> = Box::pin(EmptyStream);
+            Ok(stream)
+        })
+    }
+
+    fn embed(&self, req: EmbeddingRequest) -> BoxFuture<'_, EmbeddingResponse> {
+        let resp = EmbeddingResponse {
+            object: "list".into(),
+            data: vec![EmbeddingObject {
+                object: "embedding".into(),
+                embedding: vec![0.1, 0.2, 0.3],
+                index: 0,
+            }],
+            model: req.model.clone(),
+            usage: Some(Usage {
+                prompt_tokens: 4,
+                completion_tokens: 0,
+                total_tokens: 4,
+            }),
+        };
+        Box::pin(async move { Ok(resp) })
+    }
+
+    fn list_models(&self) -> BoxFuture<'_, ModelsListResponse> {
+        Box::pin(async move {
+            Ok(ModelsListResponse {
+                object: "list".into(),
+                data: vec![],
+            })
+        })
+    }
+
+    fn image_generate(&self, _req: CreateImageRequest) -> BoxFuture<'_, ImagesResponse> {
+        Box::pin(async move {
+            Ok(ImagesResponse {
+                created: 0,
+                data: vec![],
+            })
+        })
+    }
+
+    fn speech(&self, _req: CreateSpeechRequest) -> BoxFuture<'_, bytes::Bytes> {
+        Box::pin(async move { Ok(bytes::Bytes::new()) })
+    }
+
+    fn transcribe(&self, _req: CreateTranscriptionRequest) -> BoxFuture<'_, TranscriptionResponse> {
+        Box::pin(async move {
+            Ok(TranscriptionResponse {
+                text: String::new(),
+                language: None,
+                duration: None,
+                segments: None,
+            })
+        })
+    }
+
+    fn moderate(&self, _req: ModerationRequest) -> BoxFuture<'_, ModerationResponse> {
+        Box::pin(async move {
+            Ok(ModerationResponse {
+                id: String::new(),
+                model: String::new(),
+                results: vec![],
+            })
+        })
+    }
+
+    fn rerank(&self, _req: RerankRequest) -> BoxFuture<'_, RerankResponse> {
+        Box::pin(async move {
+            Ok(RerankResponse {
+                id: None,
+                results: vec![],
+                meta: None,
+            })
+        })
+    }
+
+    fn search(&self, _req: SearchRequest) -> BoxFuture<'_, SearchResponse> {
+        Box::pin(async {
+            Err(LiterLlmError::EndpointNotSupported {
+                endpoint: "search".into(),
+                provider: "mock".into(),
+            })
+        })
+    }
+
+    fn ocr(&self, _req: OcrRequest) -> BoxFuture<'_, OcrResponse> {
+        Box::pin(async {
+            Err(LiterLlmError::EndpointNotSupported {
+                endpoint: "ocr".into(),
+                provider: "mock".into(),
+            })
+        })
+    }
+}
+
+/// Build a [`ChatCompletionRequest`] with the given model name.
+pub fn chat_req(model: &str) -> ChatCompletionRequest {
+    ChatCompletionRequest {
+        model: model.into(),
+        messages: vec![Message::System(SystemMessage {
+            content: "test".into(),
+            name: None,
+        })],
+        ..Default::default()
+    }
+}

data/vendor/liter-llm/src/tower/tracing.rs

@@ -0,0 +1,209 @@
+use std::task::{Context, Poll};
+
+use tower::Layer;
+use tower::Service;
+use tracing::Instrument as _;
+
+use super::types::{LlmRequest, LlmResponse};
+use crate::client::BoxFuture;
+use crate::error::{LiterLlmError, Result};
+use crate::types::FinishReason;
+
+/// Tower [`Layer`] that wraps a service with OpenTelemetry GenAI semantic
+/// convention tracing spans.
+///
+/// Each call creates a [`tracing::info_span`] named `"gen_ai"` with the
+/// following attributes:
+///
+/// - `gen_ai.operation.name` — `"chat"`, `"embeddings"`, or `"list_models"`.
+/// - `gen_ai.request.model` — the model name from the request, or `""` for
+///   [`LlmRequest::ListModels`].
+/// - `gen_ai.system` — the provider prefix extracted from the model name (e.g.
+///   `"openai"` for `"openai/gpt-4"`), or `""` when absent.
+/// - `gen_ai.usage.input_tokens` — populated on successful chat / embed
+///   responses where usage data is present.
+/// - `gen_ai.usage.output_tokens` — populated on successful chat responses.
+/// - `gen_ai.response.id` — the completion ID from the response.
+/// - `gen_ai.response.model` — the actual model used (may differ from requested).
+/// - `gen_ai.response.finish_reasons` — space-separated finish reasons from
+///   all choices (e.g. `"stop"`).
+/// - `error.type` — set to the error variant name if the inner service returns
+///   an error.
+pub struct TracingLayer;
+
+impl<S> Layer<S> for TracingLayer {
+    type Service = TracingService<S>;
+
+    fn layer(&self, inner: S) -> Self::Service {
+        TracingService { inner }
+    }
+}
+
+/// Tower service produced by [`TracingLayer`].
+pub struct TracingService<S> {
+    inner: S,
+}
+
+impl<S> Clone for TracingService<S>
+where
+    S: Clone,
+{
+    fn clone(&self) -> Self {
+        Self {
+            inner: self.inner.clone(),
+        }
+    }
+}
+
+impl<S> Service<LlmRequest> for TracingService<S>
+where
+    S: Service<LlmRequest, Response = LlmResponse, Error = LiterLlmError> + Send + 'static,
+    S::Future: Send + 'static,
+{
+    type Response = LlmResponse;
+    type Error = LiterLlmError;
+    type Future = BoxFuture<'static, LlmResponse>;
+
+    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<()>> {
+        self.inner.poll_ready(cx)
+    }
+
+    fn call(&mut self, req: LlmRequest) -> Self::Future {
+        let operation_name = req.operation_name();
+        // Borrow the model string from the request; split_once gives a &str
+        // slice so we avoid an extra allocation for the provider prefix.
+        let model_str = req.model().unwrap_or("");
+        let system = model_str.split_once('/').map_or("", |(prefix, _)| prefix);
+        // Clone once so the span owns the string values (required by tracing
+        // macros, which store field values inside the span).
+        let model = model_str.to_owned();
+
+        let span = tracing::info_span!(
+            "gen_ai",
+            gen_ai.operation.name = operation_name,
+            gen_ai.request.model = %model,
+            gen_ai.system = system,
+            gen_ai.usage.input_tokens = tracing::field::Empty,
+            gen_ai.usage.output_tokens = tracing::field::Empty,
+            gen_ai.response.id = tracing::field::Empty,
+            gen_ai.response.model = tracing::field::Empty,
+            gen_ai.usage.cost = tracing::field::Empty,
+            gen_ai.response.finish_reasons = tracing::field::Empty,
+            error.type = tracing::field::Empty,
+        );
+
+        let fut = self.inner.call(req);
+
+        // Use `.instrument(span)` rather than `span.enter()` in the async
+        // block.  `span.enter()` in an async context is incorrect because the
+        // guard is dropped when the future suspends at an await point, causing
+        // the span to close prematurely.  `Instrument` attaches the span to
+        // the future so it is entered and exited correctly around each poll.
+        Box::pin(
+            async move {
+                match fut.await {
+                    Ok(resp) => {
+                        // Record usage statistics and response metadata from the response when available.
+                        record_response(&tracing::Span::current(), &resp);
+                        Ok(resp)
+                    }
+                    Err(e) => {
+                        tracing::Span::current().record("error.type", e.error_type());
+                        Err(e)
+                    }
+                }
+            }
+            .instrument(span),
+        )
+    }
+}
+
+/// Re-export `tracing_opentelemetry` when the `otel` feature is active.
+///
+/// This lets callers compose a subscriber that exports spans to an
+/// OpenTelemetry collector without taking a direct dependency on the crate:
+///
+/// ```rust,ignore
+/// use liter_llm::tower::tracing::otel::tracing_opentelemetry::OpenTelemetryLayer;
+/// ```
+#[cfg(feature = "otel")]
+pub use tracing_opentelemetry;
+
+/// Re-export `opentelemetry` when the `otel` feature is active.
+///
+/// Provides access to tracer/provider types needed to build a full
+/// OpenTelemetry pipeline (e.g. `opentelemetry::global::tracer`).
+#[cfg(feature = "otel")]
+pub use opentelemetry;
+
+/// Record span attributes from the response according to GenAI semantic conventions.
+fn record_response(span: &tracing::Span, resp: &LlmResponse) {
+    match resp {
+        LlmResponse::Chat(r) => {
+            span.record("gen_ai.response.id", r.id.as_str());
+            span.record("gen_ai.response.model", r.model.as_str());
+
+            let finish_reasons = finish_reasons_str(r.choices.iter().map(|c| c.finish_reason.as_ref()));
+            if !finish_reasons.is_empty() {
+                span.record("gen_ai.response.finish_reasons", finish_reasons.as_str());
+            }
+        }
+        LlmResponse::Embed(r) => {
+            span.record("gen_ai.response.model", r.model.as_str());
+        }
+        // Other response variants do not carry aggregated usage or response metadata.
+        LlmResponse::ChatStream(_)
+        | LlmResponse::ListModels(_)
+        | LlmResponse::ImageGenerate(_)
+        | LlmResponse::Speech(_)
+        | LlmResponse::Transcribe(_)
+        | LlmResponse::Moderate(_)
+        | LlmResponse::Rerank(_)
+        | LlmResponse::Search(_)
+        | LlmResponse::Ocr(_) => {}
+    }
+
+    // Record usage tokens from the shared accessor — avoids duplicating the
+    // match arms that extract `Option<&Usage>` from each response variant.
+    if let Some(usage) = resp.usage() {
+        span.record("gen_ai.usage.input_tokens", usage.prompt_tokens);
+        span.record("gen_ai.usage.output_tokens", usage.completion_tokens);
+    }
+}
+
+/// Build a space-separated string of finish reason names from an iterator of
+/// optional [`FinishReason`] values.  `None` entries are skipped.
+///
+/// Optimised for the common single-choice case: when there is exactly one
+/// reason, the static `&str` is returned directly as an owned `String` without
+/// an intermediate `Vec` or repeated `push_str` calls.
+fn finish_reasons_str<'a>(reasons: impl Iterator<Item = Option<&'a FinishReason>>) -> String {
+    // Fast path: single reason (the overwhelmingly common case).
+    let first = reasons.filter_map(|r| r.map(finish_reason_name));
+    // We need to re-bind after filter_map, so use a peekable to check length.
+    let mut iter = first.peekable();
+    let Some(first_name) = iter.next() else {
+        return String::new();
+    };
+    if iter.peek().is_none() {
+        return first_name.to_owned();
+    }
+    // Multi-choice path: fold remaining names with space separator.
+    iter.fold(first_name.to_owned(), |mut acc, name| {
+        acc.push(' ');
+        acc.push_str(name);
+        acc
+    })
+}
+
+/// Map a [`FinishReason`] variant to its GenAI semantic convention string.
+const fn finish_reason_name(reason: &FinishReason) -> &'static str {
+    match reason {
+        FinishReason::Stop => "stop",
+        FinishReason::Length => "length",
+        FinishReason::ToolCalls => "tool_calls",
+        FinishReason::ContentFilter => "content_filter",
+        FinishReason::FunctionCall => "function_call",
+        FinishReason::Other => "other",
+    }
+}

data/vendor/liter-llm/src/tower/types.rs

@@ -0,0 +1,170 @@
+use serde::Serialize;
+
+use crate::client::BoxStream;
+use crate::types::audio::{CreateSpeechRequest, CreateTranscriptionRequest, TranscriptionResponse};
+use crate::types::image::{CreateImageRequest, ImagesResponse};
+use crate::types::moderation::{ModerationRequest, ModerationResponse};
+use crate::types::ocr::{OcrRequest, OcrResponse};
+use crate::types::rerank::{RerankRequest, RerankResponse};
+use crate::types::search::{SearchRequest, SearchResponse};
+use crate::types::{
+    ChatCompletionChunk, ChatCompletionRequest, ChatCompletionResponse, EmbeddingRequest, EmbeddingResponse,
+    ModelsListResponse, Usage,
+};
+
+/// The request variant passed through the tower `Service` stack.
+///
+/// Each variant corresponds to one method on [`crate::client::LlmClient`].
+#[derive(Debug, Clone, Serialize)]
+pub enum LlmRequest {
+    /// Non-streaming chat completion.
+    Chat(ChatCompletionRequest),
+    /// Streaming chat completion — yields a stream of chunks.
+    ChatStream(ChatCompletionRequest),
+    /// Text embedding.
+    Embed(EmbeddingRequest),
+    /// List available models from the provider.
+    ListModels,
+    /// Image generation.
+    ImageGenerate(CreateImageRequest),
+    /// Text-to-speech audio generation.
+    Speech(CreateSpeechRequest),
+    /// Audio transcription.
+    Transcribe(CreateTranscriptionRequest),
+    /// Content moderation.
+    Moderate(ModerationRequest),
+    /// Document reranking.
+    Rerank(RerankRequest),
+    /// Web/document search.
+    Search(SearchRequest),
+    /// Document OCR.
+    Ocr(OcrRequest),
+}
+
+impl LlmRequest {
+    /// OpenTelemetry GenAI `gen_ai.operation.name` value for this request.
+    ///
+    /// Maps each variant to one of the canonical GenAI semantic convention
+    /// operation names: `"chat"`, `"embeddings"`, or `"list_models"`.
+    /// Both streaming and non-streaming chat map to `"chat"`.
+    #[must_use]
+    pub fn operation_name(&self) -> &'static str {
+        match self {
+            Self::Chat(_) | Self::ChatStream(_) => "chat",
+            Self::Embed(_) => "embeddings",
+            Self::ListModels => "list_models",
+            Self::ImageGenerate(_) => "image_generate",
+            Self::Speech(_) => "speech",
+            Self::Transcribe(_) => "transcribe",
+            Self::Moderate(_) => "moderate",
+            Self::Rerank(_) => "rerank",
+            Self::Search(_) => "search",
+            Self::Ocr(_) => "ocr",
+        }
+    }
+
+    /// Human-readable name of the request type; used as a span / metric label.
+    #[must_use]
+    pub fn request_type(&self) -> &'static str {
+        match self {
+            Self::Chat(_) => "chat",
+            Self::ChatStream(_) => "chat_stream",
+            Self::Embed(_) => "embeddings",
+            Self::ListModels => "list_models",
+            Self::ImageGenerate(_) => "image_generate",
+            Self::Speech(_) => "speech",
+            Self::Transcribe(_) => "transcribe",
+            Self::Moderate(_) => "moderate",
+            Self::Rerank(_) => "rerank",
+            Self::Search(_) => "search",
+            Self::Ocr(_) => "ocr",
+        }
+    }
+
+    /// Return the model name embedded in the request, if any.
+    #[must_use]
+    pub fn model(&self) -> Option<&str> {
+        match self {
+            Self::Chat(r) | Self::ChatStream(r) => Some(r.model.as_str()),
+            Self::Embed(r) => Some(r.model.as_str()),
+            Self::ImageGenerate(r) => r.model.as_deref(),
+            Self::Speech(r) => Some(r.model.as_str()),
+            Self::Transcribe(r) => Some(r.model.as_str()),
+            Self::Moderate(r) => r.model.as_deref(),
+            Self::Rerank(r) => Some(r.model.as_str()),
+            Self::Search(r) => Some(r.model.as_str()),
+            Self::Ocr(r) => Some(r.model.as_str()),
+            Self::ListModels => None,
+        }
+    }
+}
+
+/// The response variant returned through the tower `Service` stack.
+pub enum LlmResponse {
+    /// Non-streaming chat completion.
+    Chat(ChatCompletionResponse),
+    /// Streaming chat completion.
+    ChatStream(BoxStream<'static, ChatCompletionChunk>),
+    /// Text embedding.
+    Embed(EmbeddingResponse),
+    /// Model list.
+    ListModels(ModelsListResponse),
+    /// Image generation.
+    ImageGenerate(ImagesResponse),
+    /// Text-to-speech audio (raw bytes).
+    Speech(bytes::Bytes),
+    /// Audio transcription.
+    Transcribe(TranscriptionResponse),
+    /// Content moderation.
+    Moderate(ModerationResponse),
+    /// Document reranking.
+    Rerank(RerankResponse),
+    /// Search results.
+    Search(SearchResponse),
+    /// OCR results.
+    Ocr(OcrResponse),
+}
+
+impl LlmResponse {
+    /// Return the usage data from the response, if present.
+    ///
+    /// Streaming, model-list, and non-chat responses do not carry aggregated
+    /// usage data and always return `None`.
+    #[must_use]
+    pub fn usage(&self) -> Option<&Usage> {
+        match self {
+            Self::Chat(r) => r.usage.as_ref(),
+            Self::Embed(r) => r.usage.as_ref(),
+            Self::Ocr(r) => r.usage.as_ref(),
+            Self::ChatStream(_)
+            | Self::ListModels(_)
+            | Self::ImageGenerate(_)
+            | Self::Speech(_)
+            | Self::Transcribe(_)
+            | Self::Moderate(_)
+            | Self::Rerank(_)
+            | Self::Search(_) => None,
+        }
+    }
+}
+
+impl std::fmt::Debug for LlmResponse {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Chat(r) => f.debug_tuple("Chat").field(r).finish(),
+            Self::ChatStream(_) => f.write_str("ChatStream(<stream>)"),
+            Self::Embed(r) => f.debug_tuple("Embed").field(r).finish(),
+            Self::ListModels(r) => f.debug_tuple("ListModels").field(r).finish(),
+            Self::ImageGenerate(r) => f.debug_tuple("ImageGenerate").field(r).finish(),
+            Self::Speech(b) => f
+                .debug_tuple("Speech")
+                .field(&format_args!("<{} bytes>", b.len()))
+                .finish(),
+            Self::Transcribe(r) => f.debug_tuple("Transcribe").field(r).finish(),
+            Self::Moderate(r) => f.debug_tuple("Moderate").field(r).finish(),
+            Self::Rerank(r) => f.debug_tuple("Rerank").field(r).finish(),
+            Self::Search(r) => f.debug_tuple("Search").field(r).finish(),
+            Self::Ocr(r) => f.debug_tuple("Ocr").field(r).finish(),
+        }
+    }
+}

data/vendor/liter-llm/src/types/audio.rs

@@ -0,0 +1,52 @@
+use serde::{Deserialize, Serialize};
+
+/// Request to generate speech audio from text.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CreateSpeechRequest {
+    pub model: String,
+    pub input: String,
+    pub voice: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub response_format: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub speed: Option<f64>,
+}
+
+/// Request to transcribe audio into text.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CreateTranscriptionRequest {
+    pub model: String,
+    /// Base64-encoded audio file data.
+    pub file: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub language: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub prompt: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub response_format: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub temperature: Option<f64>,
+}
+
+/// Response from a transcription request.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct TranscriptionResponse {
+    pub text: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub language: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub duration: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub segments: Option<Vec<TranscriptionSegment>>,
+}
+
+/// A segment of transcribed audio with timing information.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct TranscriptionSegment {
+    pub id: u32,
+    pub start: f64,
+    pub end: f64,
+    pub text: String,
+}