Skip to main content

mutil_ai/
profile.rs

1use std::fmt;
2use std::sync::Arc;
3
4use reqwest::header::{HeaderMap, HeaderName};
5use serde_json::{Map, Value};
6
7/// Protocol surface of an endpoint, re-exported from the normalize module.
8///
9/// See [`crate::normalize::Protocol`] for the available values.
10pub use crate::normalize::Protocol as ProtocolSurface;
11use crate::normalize::SystemPlacement;
12
13/// Stable identifier for a provider profile.
14#[derive(Debug, Clone, PartialEq, Eq, Hash)]
15pub struct ProfileId(String);
16
17impl ProfileId {
18    /// Creates a profile identifier from any string-like value.
19    pub fn new(id: impl Into<String>) -> Self {
20        Self(id.into())
21    }
22
23    /// Returns the identifier as a string slice.
24    pub fn as_str(&self) -> &str {
25        &self.0
26    }
27}
28
29impl From<&str> for ProfileId {
30    fn from(value: &str) -> Self {
31        Self::new(value)
32    }
33}
34
35impl From<String> for ProfileId {
36    fn from(value: String) -> Self {
37        Self::new(value)
38    }
39}
40
41impl fmt::Display for ProfileId {
42    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
43        formatter.write_str(&self.0)
44    }
45}
46
47/// How the generic adapter authenticates a request.
48#[derive(Debug, Clone, PartialEq, Eq)]
49pub enum AuthStyle {
50    /// `Authorization: Bearer <key>`.
51    Bearer,
52    /// A provider-specific API-key header such as `x-api-key`.
53    XApiKey { header: HeaderName },
54    /// A query parameter such as Gemini's `key=...`.
55    QueryKey { parameter: String },
56    /// A custom header, optionally with a value prefix such as `Token `.
57    Custom {
58        header: HeaderName,
59        value_prefix: Option<String>,
60    },
61    /// No authentication. Intended for local gateways and test servers.
62    None,
63}
64
65/// Which profile implementation should be used for an endpoint.
66#[derive(Debug, Clone, Default)]
67pub enum ProfileSelector {
68    /// Protocol defaults only.
69    #[default]
70    Generic,
71    /// Provider-specific behavior supplied by the application.
72    Custom(Arc<ProviderProfile>),
73    /// A future registry lookup. The registry is intentionally not guessed
74    /// from a base URL.
75    Builtin(ProfileId),
76}
77
78/// Explicit description of one HTTP endpoint.
79///
80/// A protocol surface is always chosen by the caller. The SDK never infers it
81/// from the base URL.
82#[derive(Debug, Clone)]
83pub struct EndpointSpec {
84    /// Protocol surface used to encode requests and decode responses.
85    pub protocol: ProtocolSurface,
86    /// Provider base URL, for example `https://api.openai.com/v1`.
87    pub base_url: String,
88    /// Path appended to [`Self::base_url`]; may contain a `{model}` placeholder.
89    pub path: String,
90    /// Optional path used for streaming requests; falls back to [`Self::path`].
91    pub stream_path: Option<String>,
92    /// Authentication scheme applied to every request.
93    pub auth: AuthStyle,
94    /// Which profile implementation supplies provider-specific behavior.
95    pub profile: ProfileSelector,
96}
97
98impl EndpointSpec {
99    /// Creates a spec with no streaming path and generic profile behavior.
100    pub fn new(
101        protocol: ProtocolSurface,
102        base_url: impl Into<String>,
103        path: impl Into<String>,
104        auth: AuthStyle,
105    ) -> Self {
106        Self {
107            protocol,
108            base_url: base_url.into(),
109            path: path.into(),
110            stream_path: None,
111            auth,
112            profile: ProfileSelector::Generic,
113        }
114    }
115
116    /// Creates a spec for OpenAI Chat Completions at `/chat/completions`.
117    pub fn openai_chat(base_url: impl Into<String>) -> Self {
118        Self::new(
119            ProtocolSurface::OpenAiChat,
120            base_url,
121            "/chat/completions",
122            AuthStyle::Bearer,
123        )
124    }
125
126    /// Creates a spec for OpenAI Responses at `/responses`.
127    pub fn openai_responses(base_url: impl Into<String>) -> Self {
128        Self::new(
129            ProtocolSurface::OpenAiResponses,
130            base_url,
131            "/responses",
132            AuthStyle::Bearer,
133        )
134    }
135
136    /// Creates a spec for Anthropic Messages at `/messages` using `x-api-key`.
137    pub fn anthropic_messages(base_url: impl Into<String>) -> Self {
138        Self::new(
139            ProtocolSurface::AnthropicMessages,
140            base_url,
141            "/messages",
142            AuthStyle::XApiKey {
143                header: HeaderName::from_static("x-api-key"),
144            },
145        )
146    }
147
148    /// Creates a spec for Gemini `generateContent` with a dedicated streaming
149    /// path and `key` query-parameter authentication.
150    pub fn gemini_generate_content(base_url: impl Into<String>) -> Self {
151        let mut endpoint = Self::new(
152            ProtocolSurface::GeminiGenerateContent,
153            base_url,
154            "/models/{model}:generateContent",
155            AuthStyle::QueryKey {
156                parameter: "key".to_string(),
157            },
158        );
159        endpoint.stream_path = Some("/models/{model}:streamGenerateContent".to_string());
160        endpoint
161    }
162
163    /// Sets the path used for streaming requests.
164    pub fn stream_path(mut self, path: impl Into<String>) -> Self {
165        self.stream_path = Some(path.into());
166        self
167    }
168
169    /// Attaches a custom [`ProviderProfile`] to this endpoint.
170    pub fn profile(mut self, profile: ProviderProfile) -> Self {
171        self.profile = ProfileSelector::Custom(Arc::new(profile));
172        self
173    }
174
175    /// Sets the profile selector, including registry-backed
176    /// [`ProfileSelector::Builtin`].
177    pub fn profile_selector(mut self, profile: ProfileSelector) -> Self {
178        self.profile = profile;
179        self
180    }
181
182    /// Build the non-streaming endpoint URL after substituting `{model}`.
183    pub fn url(&self, model: &str) -> crate::Result<String> {
184        self.url_for(model, false)
185    }
186
187    /// Build the endpoint URL for either the normal or streaming operation.
188    pub fn url_for(&self, model: &str, streaming: bool) -> crate::Result<String> {
189        let path = if streaming {
190            self.stream_path.as_deref().unwrap_or(&self.path)
191        } else {
192            &self.path
193        };
194        if self.base_url.trim().is_empty() {
195            return Err(crate::Error::InvalidEndpoint(
196                "base_url cannot be empty".to_string(),
197            ));
198        }
199        if path.trim().is_empty() {
200            return Err(crate::Error::InvalidEndpoint(
201                "path cannot be empty".to_string(),
202            ));
203        }
204
205        let base = self.base_url.trim_end_matches('/');
206        let path = path.trim_start_matches('/').replace("{model}", model);
207        Ok(format!("{base}/{path}"))
208    }
209
210    /// Returns the attached custom profile, if any.
211    pub fn provider_profile(&self) -> Option<&ProviderProfile> {
212        match &self.profile {
213            ProfileSelector::Custom(profile) => Some(profile),
214            ProfileSelector::Generic | ProfileSelector::Builtin(_) => None,
215        }
216    }
217
218    /// Resolve custom or built-in behavior without changing protocol/path.
219    pub fn resolved_profile(&self) -> Option<ProviderProfile> {
220        match &self.profile {
221            ProfileSelector::Generic => None,
222            ProfileSelector::Custom(profile) => Some(profile.as_ref().clone()),
223            ProfileSelector::Builtin(id) => ProfileRegistry::new().resolve(id),
224        }
225    }
226}
227
228/// Normalization behavior attached to a provider profile.
229#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
230pub struct NormalizeProfile {
231    /// How system/developer messages are placed.
232    ///
233    /// `FirstToTopRestInPlace` is honored only by the OpenAI Chat Completions
234    /// and OpenAI Responses adapters; Anthropic and Gemini always merge
235    /// system text into the top-level entry.
236    pub system_placement: SystemPlacement,
237}
238
239/// Provider-level defaults and behavior switches.
240#[derive(Debug, Clone)]
241pub struct ProviderProfile {
242    /// Stable identifier, also used for built-in registry lookup.
243    pub id: ProfileId,
244    /// Extra body, header, and query defaults applied to every request.
245    pub request: RequestProfile,
246    /// Typed request switches shared across OpenAI-compatible APIs.
247    pub request_options: ProviderRequestOptions,
248    /// Normalization behavior for requests sent to this provider.
249    pub normalize: NormalizeProfile,
250    /// Reasoning field names, replay policy, and thinking request controls.
251    pub reasoning: ReasoningProfile,
252    /// Tool-call encoding and ID handling behavior.
253    pub tools: ToolProfile,
254    /// Streaming terminal event and usage delivery behavior.
255    pub stream: StreamProfile,
256    /// Where usage information appears in streamed responses.
257    pub usage: UsageProfile,
258    /// Feature switches used to reject unsupported requests early.
259    pub capabilities: Capabilities,
260    /// Which request field carries the output token limit.
261    pub max_tokens_semantics: MaxTokensSemantics,
262}
263
264impl ProviderProfile {
265    /// Returns the built-in profile for a provider id such as `"deepseek"`.
266    ///
267    /// Common aliases are accepted, for example `"moonshot"` for Kimi or
268    /// `"bailian"` for Qwen.
269    pub fn builtin(id: &str) -> Option<Self> {
270        match id.trim().to_ascii_lowercase().as_str() {
271            "deepseek" => Some(Self::deepseek_compatible()),
272            "qwen" | "bailian" | "dashscope" => Some(Self::qwen_compatible()),
273            "kimi" | "moonshot" => Some(Self::kimi_compatible()),
274            "glm" | "zhipu" | "bigmodel" => Some(Self::glm_compatible()),
275            "doubao" | "ark" | "volcengine" => Some(Self::doubao_compatible()),
276            "openai" => Some(Self::new("openai")),
277            "anthropic" => Some(Self::new("anthropic")),
278            "gemini" | "google" => Some(Self::new("gemini")),
279            "openai-compatible" => Some(Self::new("openai-compatible")),
280            _ => None,
281        }
282    }
283
284    /// Creates a profile with default behavior for the given identifier.
285    pub fn new(id: impl Into<ProfileId>) -> Self {
286        Self {
287            id: id.into(),
288            request: RequestProfile::default(),
289            request_options: ProviderRequestOptions::default(),
290            normalize: NormalizeProfile::default(),
291            reasoning: ReasoningProfile::default(),
292            tools: ToolProfile::default(),
293            stream: StreamProfile::default(),
294            usage: UsageProfile::default(),
295            capabilities: Capabilities::default(),
296            max_tokens_semantics: MaxTokensSemantics::MaxCompletionTokens,
297        }
298    }
299
300    /// Common OpenAI-compatible behavior documented by DeepSeek.
301    ///
302    /// This is a behavior profile, not an endpoint. The caller still provides
303    /// the protocol, base URL, path, and auth through [`EndpointSpec`].
304    pub fn deepseek_compatible() -> Self {
305        let mut profile = Self::new("deepseek");
306        profile.reasoning.aliases = ReasoningAliases::empty()
307            .text("reasoning_content")
308            .replay("reasoning_content");
309        profile.reasoning.replay = ReasoningReplayPolicy::SameProvider;
310        profile.reasoning.thinking = ThinkingRequestProfile::Composite(vec![
311            ThinkingRequestProfile::ThinkingObject,
312            ThinkingRequestProfile::MappedEffort {
313                field: "reasoning_effort".to_string(),
314                mapping: EffortMapping::deepseek(),
315            },
316        ]);
317        profile
318    }
319
320    /// Common OpenAI-compatible behavior documented by Qwen / Bailian.
321    pub fn qwen_compatible() -> Self {
322        let mut profile = Self::new("qwen");
323        profile.reasoning.aliases = ReasoningAliases::empty()
324            .text("reasoning_content")
325            .replay("reasoning_content");
326        profile.reasoning.replay = ReasoningReplayPolicy::SameProvider;
327        profile.reasoning.thinking = ThinkingRequestProfile::Composite(vec![
328            ThinkingRequestProfile::EnabledFlag("enable_thinking".to_string()),
329            ThinkingRequestProfile::BudgetTokens("thinking_budget".to_string()),
330        ]);
331        profile
332    }
333
334    /// Common OpenAI-compatible behavior documented by Moonshot Kimi.
335    ///
336    /// Kimi K3 and K2.x use different thinking controls. Add a matching
337    /// [`ModelProfile`] for those model-specific fields.
338    pub fn kimi_compatible() -> Self {
339        let mut profile = Self::new("kimi");
340        profile.reasoning.aliases = ReasoningAliases::empty()
341            .text("reasoning_content")
342            .replay("reasoning_content");
343        profile.reasoning.replay = ReasoningReplayPolicy::SameProvider;
344        profile
345    }
346
347    /// Common OpenAI-compatible behavior documented by Zhipu GLM.
348    pub fn glm_compatible() -> Self {
349        let mut profile = Self::new("glm");
350        profile.reasoning.aliases = ReasoningAliases::empty()
351            .text("reasoning_content")
352            .replay("reasoning_content");
353        profile.reasoning.replay = ReasoningReplayPolicy::SameProvider;
354        profile.reasoning.thinking = ThinkingRequestProfile::ThinkingObject;
355        profile
356    }
357
358    /// Conservative OpenAI-compatible behavior for Volcengine Ark / Doubao.
359    ///
360    /// Reasoning state is replayed only for tool-call turns because Ark uses
361    /// `encrypted_content` to preserve tool-call continuity.
362    pub fn doubao_compatible() -> Self {
363        let mut profile = Self::new("doubao");
364        profile.reasoning.aliases = ReasoningAliases::empty()
365            .text("reasoning_content")
366            .replay("reasoning_content")
367            .encrypted("encrypted_content");
368        profile.reasoning.replay = ReasoningReplayPolicy::RequiredForToolCalls;
369        profile.reasoning.thinking = ThinkingRequestProfile::ThinkingObject;
370        profile
371    }
372}
373
374/// Explicit registry for built-in behavior profiles.
375///
376/// Registry lookup never changes the protocol or endpoint. Those remain owned
377/// by [`EndpointSpec`].
378#[derive(Debug, Clone, Copy, Default)]
379pub struct ProfileRegistry;
380
381impl ProfileRegistry {
382    /// Creates an empty registry handle. Lookup uses built-in tables only.
383    pub const fn new() -> Self {
384        Self
385    }
386
387    /// Resolves a built-in [`ProviderProfile`] by id, or `None` if unknown.
388    pub fn resolve(&self, id: &ProfileId) -> Option<ProviderProfile> {
389        ProviderProfile::builtin(id.as_str())
390    }
391
392    /// Lists every id accepted by [`Self::resolve`], including aliases.
393    pub const fn builtin_ids(&self) -> &'static [&'static str] {
394        &[
395            "deepseek",
396            "qwen",
397            "bailian",
398            "dashscope",
399            "kimi",
400            "moonshot",
401            "glm",
402            "zhipu",
403            "bigmodel",
404            "doubao",
405            "ark",
406            "volcengine",
407            "openai",
408            "anthropic",
409            "gemini",
410            "google",
411            "openai-compatible",
412        ]
413    }
414}
415
416/// How an assistant tool-call message should encode empty content.
417///
418/// These modes only canonicalize content that is absent, `null`, or an empty
419/// string. Non-empty assistant text is real transcript data and is **always
420/// preserved verbatim** — stripping it would blind the model to its own prior
421/// narration. Consumers that genuinely need to drop non-empty content must use
422/// `RequestOptions::request_transform`.
423#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
424pub enum ToolCallContentMode {
425    /// Preserve the adapter's documented default.
426    #[default]
427    Auto,
428    /// Encode empty content as an explicit `null`.
429    Null,
430    /// Omit the `content` field entirely.
431    Omit,
432    /// Encode empty content as an empty string.
433    Empty,
434}
435
436/// Typed provider request switches that are common across compatible APIs.
437///
438/// `None` means "inherit the next lower-priority layer". Request-level values
439/// override provider-profile defaults.
440#[derive(Debug, Clone, Default, PartialEq, Eq)]
441pub struct ProviderRequestOptions {
442    /// How assistant tool-call messages encode empty content.
443    pub tool_call_content: Option<ToolCallContentMode>,
444    /// Whether provider-specific parameters must be present in requests.
445    pub require_provider_parameters: Option<bool>,
446    /// Enables sampling for providers that default to greedy decoding (Qwen).
447    pub do_sample: Option<bool>,
448    /// Requests a trailing usage chunk via `stream_options.include_usage`.
449    pub include_stream_usage: Option<bool>,
450    /// Cache key routed to provider-side prompt caching.
451    pub prompt_cache_key: Option<String>,
452    /// End-user identifier forwarded to the provider.
453    pub user: Option<String>,
454}
455
456/// Request fields that are applied before per-call `extra_*` values.
457#[derive(Debug, Clone, Default)]
458pub struct RequestProfile {
459    /// JSON body fields merged into every request.
460    pub extra_body: Map<String, Value>,
461    /// HTTP headers added to every request.
462    pub extra_headers: HeaderMap,
463    /// Query parameters appended to every request URL.
464    pub extra_query: Vec<(String, String)>,
465}
466
467impl RequestProfile {
468    /// Adds a JSON body field, returning the profile for chaining.
469    pub fn body(mut self, key: impl Into<String>, value: impl Into<Value>) -> Self {
470        self.extra_body.insert(key.into(), value.into());
471        self
472    }
473
474    /// Adds an HTTP header, returning the profile for chaining.
475    pub fn header(mut self, name: HeaderName, value: reqwest::header::HeaderValue) -> Self {
476        self.extra_headers.insert(name, value);
477        self
478    }
479
480    /// Appends a query parameter, returning the profile for chaining.
481    pub fn query(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
482        self.extra_query.push((name.into(), value.into()));
483        self
484    }
485}
486
487/// Names observed in provider responses for each neutral reasoning category.
488#[derive(Debug, Clone, PartialEq, Eq)]
489pub struct ReasoningAliases {
490    /// Response field names holding free-form reasoning text.
491    pub response_text: Vec<String>,
492    /// Response field names holding reasoning summaries.
493    pub response_summary: Vec<String>,
494    /// Request field names used to replay reasoning into follow-up turns.
495    pub request_replay: Vec<String>,
496    /// Request field names holding opaque encrypted reasoning blobs.
497    pub encrypted: Vec<String>,
498    /// Request field names holding reasoning signatures.
499    pub signature: Vec<String>,
500}
501
502impl Default for ReasoningAliases {
503    fn default() -> Self {
504        Self {
505            response_text: vec!["reasoning_content".to_string(), "reasoning".to_string()],
506            response_summary: Vec::new(),
507            request_replay: vec![
508                "reasoning_content".to_string(),
509                "reasoning".to_string(),
510                "reasoning_details".to_string(),
511            ],
512            encrypted: vec!["reasoning_details".to_string()],
513            signature: Vec::new(),
514        }
515    }
516}
517
518impl ReasoningAliases {
519    /// Creates an alias set with no recognized field names.
520    pub fn empty() -> Self {
521        Self {
522            response_text: Vec::new(),
523            response_summary: Vec::new(),
524            request_replay: Vec::new(),
525            encrypted: Vec::new(),
526            signature: Vec::new(),
527        }
528    }
529
530    /// Returns `true` when no field names are registered in any category.
531    pub fn is_empty(&self) -> bool {
532        self.response_text.is_empty()
533            && self.response_summary.is_empty()
534            && self.request_replay.is_empty()
535            && self.encrypted.is_empty()
536            && self.signature.is_empty()
537    }
538
539    /// Adds a response field name for free-form reasoning text.
540    pub fn text(mut self, field: impl Into<String>) -> Self {
541        self.response_text.push(field.into());
542        self
543    }
544
545    /// Adds a response field name for reasoning summaries.
546    pub fn summary(mut self, field: impl Into<String>) -> Self {
547        self.response_summary.push(field.into());
548        self
549    }
550
551    /// Adds a request field name used to replay reasoning.
552    pub fn replay(mut self, field: impl Into<String>) -> Self {
553        self.request_replay.push(field.into());
554        self
555    }
556
557    /// Adds a request field name for encrypted reasoning blobs.
558    pub fn encrypted(mut self, field: impl Into<String>) -> Self {
559        self.encrypted.push(field.into());
560        self
561    }
562
563    /// Adds a request field name for reasoning signatures.
564    pub fn signature(mut self, field: impl Into<String>) -> Self {
565        self.signature.push(field.into());
566        self
567    }
568}
569
570/// Whether and how reasoning state captured from a response is replayed on
571/// follow-up requests.
572#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
573pub enum ReasoningReplayPolicy {
574    /// Reasoning state is never sent back to the provider.
575    Never,
576    /// Replays reasoning fields only when the follow-up request targets the
577    /// same provider.
578    #[default]
579    SameProvider,
580    /// Keeps reasoning fields inside the conversation history as-is.
581    PreserveInHistory,
582    /// Replays reasoning only on tool-call turns, where continuity is
583    /// required (for example Volcengine Ark's `encrypted_content`).
584    RequiredForToolCalls,
585    /// Replays only opaque encrypted reasoning blobs, never plaintext.
586    EncryptedOnly,
587    /// Replay behavior is decided by model-specific profiles.
588    ModelDefined,
589}
590
591/// Reasoning-related defaults for a provider.
592#[derive(Debug, Clone, Default, PartialEq, Eq)]
593pub struct ReasoningProfile {
594    /// Field names recognized in responses and replayed in requests.
595    pub aliases: ReasoningAliases,
596    /// Whether and how reasoning state is replayed across turns.
597    pub replay: ReasoningReplayPolicy,
598    /// How thinking controls are encoded into requests.
599    pub thinking: ThinkingRequestProfile,
600}
601
602/// How tool-call identifiers are handled when translating between protocols.
603#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
604pub enum ToolCallIdPolicy {
605    /// Keeps the provider's tool-call ID unchanged.
606    #[default]
607    Preserve,
608    /// Generates a new ID when the upstream format is not representable.
609    Synthesize,
610    /// Encodes IDs as `name`/`id` pairs for providers without ID support.
611    NamePair,
612}
613
614/// Tool-call encoding behavior for a provider.
615#[derive(Debug, Clone, Copy, PartialEq, Eq)]
616pub struct ToolProfile {
617    /// How tool-call IDs are translated between protocols.
618    pub call_id_policy: ToolCallIdPolicy,
619    /// Whether the provider accepts parallel tool calls.
620    pub parallel_tool_calls: bool,
621    /// Whether tool-call arguments are streamed incrementally.
622    pub stream_arguments: bool,
623}
624
625impl Default for ToolProfile {
626    fn default() -> Self {
627        Self {
628            call_id_policy: ToolCallIdPolicy::Preserve,
629            parallel_tool_calls: true,
630            stream_arguments: true,
631        }
632    }
633}
634
635/// The event that marks the end of a provider's response stream.
636#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
637pub enum StreamTerminal {
638    /// An SSE `data: [DONE]` sentinel (OpenAI-style).
639    #[default]
640    DataDone,
641    /// A `response.completed` event (OpenAI Responses-style).
642    ResponseCompleted,
643    /// A `message_stop` event (Anthropic-style).
644    MessageStop,
645    /// End of the stream without an explicit terminal event (Gemini-style).
646    Eof,
647}
648
649/// Where usage (token counts) appears in a streamed response.
650#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
651pub enum UsagePlacement {
652    /// Usage arrives only on the final chunk.
653    #[default]
654    LastChunk,
655    /// Usage is repeated on every chunk.
656    EveryChunk,
657    /// Usage arrives in a dedicated event or chunk.
658    UsageEvent,
659    /// Streaming never reports usage.
660    None,
661}
662
663/// Streaming behavior for a provider.
664#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
665pub struct StreamProfile {
666    /// Event that marks the end of the stream.
667    pub terminal: StreamTerminal,
668    /// Where usage appears inside the stream.
669    pub usage: UsagePlacement,
670}
671
672/// Usage reporting behavior for a provider.
673#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
674pub struct UsageProfile {
675    /// Where usage appears in streamed responses.
676    pub placement: UsagePlacement,
677}
678
679/// Capability switches used to reject requests before they reach a provider.
680#[derive(Debug, Clone, PartialEq, Eq)]
681pub struct Capabilities {
682    /// Reasoning-related feature switches.
683    pub reasoning: ReasoningCapabilities,
684    /// Tool-call feature switches.
685    pub tools: ToolCapabilities,
686    /// Streaming feature switches.
687    pub streaming: StreamCapabilities,
688    /// Whether the provider supports a tool-choice control.
689    pub tool_choice: bool,
690    /// Whether the provider supports structured (JSON schema) output.
691    pub structured_output: bool,
692    /// Whether the provider supports a deterministic `seed` parameter.
693    pub seed: bool,
694    /// Whether the provider supports stop sequences.
695    pub stop: bool,
696    /// Whether the provider supports multimodal (image/audio) input.
697    pub multimodal: bool,
698    /// Whether conversation state is stored server-side between requests.
699    pub server_side_state: bool,
700}
701
702impl Default for Capabilities {
703    fn default() -> Self {
704        Self {
705            reasoning: ReasoningCapabilities::default(),
706            tools: ToolCapabilities::default(),
707            streaming: StreamCapabilities::default(),
708            tool_choice: true,
709            structured_output: true,
710            seed: true,
711            stop: true,
712            multimodal: true,
713            server_side_state: false,
714        }
715    }
716}
717
718/// Reasoning feature switches for a provider.
719#[derive(Debug, Clone, Copy, PartialEq, Eq)]
720pub struct ReasoningCapabilities {
721    /// Whether reasoning is supported at all.
722    pub supported: bool,
723    /// Whether free-form reasoning text is exposed.
724    pub text: bool,
725    /// Whether reasoning summaries are exposed.
726    pub summary: bool,
727    /// Whether encrypted reasoning blobs are supported.
728    pub encrypted: bool,
729    /// Whether reasoning can be replayed on follow-up requests.
730    pub replay: bool,
731}
732
733impl Default for ReasoningCapabilities {
734    fn default() -> Self {
735        Self {
736            supported: true,
737            text: true,
738            summary: true,
739            encrypted: true,
740            replay: true,
741        }
742    }
743}
744
745/// Tool-call feature switches for a provider.
746#[derive(Debug, Clone, Copy, PartialEq, Eq)]
747pub struct ToolCapabilities {
748    /// Whether tool calling is supported at all.
749    pub supported: bool,
750    /// Whether parallel tool calls are supported.
751    pub parallel: bool,
752    /// Whether tool-call arguments can be streamed.
753    pub streaming: bool,
754}
755
756impl Default for ToolCapabilities {
757    fn default() -> Self {
758        Self {
759            supported: true,
760            parallel: true,
761            streaming: true,
762        }
763    }
764}
765
766/// Streaming feature switches for a provider.
767#[derive(Debug, Clone, Copy, PartialEq, Eq)]
768pub struct StreamCapabilities {
769    /// Whether streaming is supported at all.
770    pub supported: bool,
771    /// Whether usage can be reported inside a stream.
772    pub usage: bool,
773}
774
775impl Default for StreamCapabilities {
776    fn default() -> Self {
777        Self {
778            supported: true,
779            usage: true,
780        }
781    }
782}
783
784/// Model-level policy selected after the endpoint protocol is known.
785#[derive(Debug, Clone, PartialEq, Eq)]
786pub struct ModelProfile {
787    /// Selects which model names this profile applies to.
788    pub matcher: ModelMatcher,
789    /// How thinking controls are encoded in requests.
790    pub thinking: ThinkingRequestProfile,
791    /// Model-specific reasoning response and replay field names.
792    pub reasoning_aliases: ReasoningAliases,
793    /// Overrides the provider-level replay policy when set.
794    pub replay: Option<ReasoningReplayPolicy>,
795    /// Overrides which request field carries the output token limit.
796    pub max_tokens_semantics: MaxTokensSemantics,
797    /// Whether `function.arguments` is streamed incrementally.
798    pub stream_function_arguments: bool,
799    /// Overrides provider capabilities for this model when set.
800    pub capabilities: Option<Capabilities>,
801}
802
803impl Default for ModelProfile {
804    fn default() -> Self {
805        Self {
806            matcher: ModelMatcher::Any,
807            thinking: ThinkingRequestProfile::None,
808            reasoning_aliases: ReasoningAliases::empty(),
809            replay: None,
810            max_tokens_semantics: MaxTokensSemantics::MaxOutputTokens,
811            stream_function_arguments: true,
812            capabilities: None,
813        }
814    }
815}
816
817impl ModelProfile {
818    /// Kimi K3 reasoning controls.
819    pub fn kimi_k3() -> Self {
820        Self {
821            matcher: ModelMatcher::Prefix("kimi-k3".to_string()),
822            thinking: ThinkingRequestProfile::Effort("reasoning_effort".to_string()),
823            reasoning_aliases: ReasoningAliases::empty()
824                .text("reasoning_content")
825                .replay("reasoning_content"),
826            replay: Some(ReasoningReplayPolicy::SameProvider),
827            ..Self::default()
828        }
829    }
830
831    /// Kimi K2.6 reasoning controls, including preserved thinking history.
832    pub fn kimi_k2_6() -> Self {
833        Self {
834            matcher: ModelMatcher::Prefix("kimi-k2.6".to_string()),
835            thinking: ThinkingRequestProfile::Composite(vec![
836                ThinkingRequestProfile::ThinkingObject,
837                ThinkingRequestProfile::Field {
838                    path: "thinking.keep".to_string(),
839                    value: Value::String("all".to_string()),
840                },
841            ]),
842            reasoning_aliases: ReasoningAliases::empty()
843                .text("reasoning_content")
844                .replay("reasoning_content"),
845            replay: Some(ReasoningReplayPolicy::SameProvider),
846            ..Self::default()
847        }
848    }
849
850    /// Returns `true` when this profile applies to the given model name.
851    pub fn matches(&self, model: &str) -> bool {
852        self.matcher.matches(model)
853    }
854}
855
856/// Selects which model names a [`ModelProfile`] applies to.
857#[derive(Debug, Clone, Default, PartialEq, Eq)]
858pub enum ModelMatcher {
859    /// Matches every model.
860    #[default]
861    Any,
862    /// Matches exactly one model name.
863    Exact(String),
864    /// Matches any model name starting with the given prefix.
865    Prefix(String),
866}
867
868impl ModelMatcher {
869    /// Returns `true` when this matcher selects the given model name.
870    pub fn matches(&self, model: &str) -> bool {
871        match self {
872            Self::Any => true,
873            Self::Exact(expected) => model == expected,
874            Self::Prefix(prefix) => model.starts_with(prefix),
875        }
876    }
877}
878
879/// How a neutral thinking configuration is encoded into a provider request.
880#[derive(Debug, Clone, Default, PartialEq, Eq)]
881pub enum ThinkingRequestProfile {
882    /// No thinking controls are sent.
883    #[default]
884    None,
885    /// Sends a boolean flag such as `enable_thinking`.
886    EnabledFlag(String),
887    /// Sends a `thinking` object such as `{"type": "enabled"}`.
888    ThinkingObject,
889    /// Sends neutral effort values under the given field name.
890    Effort(String),
891    /// Sends effort values translated through an [`EffortMapping`].
892    MappedEffort {
893        /// Request field that receives the mapped effort value.
894        field: String,
895        /// Translation table from neutral effort to provider values.
896        mapping: EffortMapping,
897    },
898    /// Sends a numeric thinking token budget under the given field name.
899    BudgetTokens(String),
900    /// Set a static or nested JSON field, for example `thinking.keep`.
901    ///
902    /// Static fields are applied even when the request has no
903    /// `ReasoningConfig`; dynamic thinking controls are still ignored unless a
904    /// config is present.
905    Field {
906        path: String,
907        value: Value,
908    },
909    /// Applies several encodings together, in order.
910    Composite(Vec<ThinkingRequestProfile>),
911}
912
913/// Provider-specific translation for neutral reasoning effort values.
914#[derive(Debug, Clone, Default, PartialEq, Eq)]
915pub struct EffortMapping {
916    /// Provider value for the neutral `none` effort; `None` means unsupported.
917    pub none: Option<String>,
918    /// Provider value for the neutral `minimal` effort; `None` means unsupported.
919    pub minimal: Option<String>,
920    /// Provider value for the neutral `low` effort; `None` means unsupported.
921    pub low: Option<String>,
922    /// Provider value for the neutral `medium` effort; `None` means unsupported.
923    pub medium: Option<String>,
924    /// Provider value for the neutral `high` effort; `None` means unsupported.
925    pub high: Option<String>,
926    /// Provider value for the neutral `xhigh` effort; `None` means unsupported.
927    pub xhigh: Option<String>,
928    /// Provider value for the neutral `max` effort; `None` means unsupported.
929    pub max: Option<String>,
930    /// Provider value for the neutral `ultra` effort; `None` means unsupported.
931    pub ultra: Option<String>,
932}
933
934impl EffortMapping {
935    /// Maps every neutral effort value to its lowercase name unchanged.
936    pub fn identity() -> Self {
937        Self {
938            none: Some("none".to_string()),
939            minimal: Some("minimal".to_string()),
940            low: Some("low".to_string()),
941            medium: Some("medium".to_string()),
942            high: Some("high".to_string()),
943            xhigh: Some("xhigh".to_string()),
944            max: Some("max".to_string()),
945            ultra: Some("ultra".to_string()),
946        }
947    }
948
949    /// DeepSeek's mapping, which collapses most levels into `low`/`high`.
950    pub fn deepseek() -> Self {
951        Self {
952            none: Some("none".to_string()),
953            minimal: Some("low".to_string()),
954            low: Some("low".to_string()),
955            medium: Some("high".to_string()),
956            high: Some("high".to_string()),
957            xhigh: Some("high".to_string()),
958            max: Some("max".to_string()),
959            // DeepSeek 没有比 `max` 更高的档:取它的顶,而不是丢掉这个请求
960            // (`None` = 不支持 → 调用方不发 effort,等于回退到 provider 缺省)。
961            ultra: Some("max".to_string()),
962        }
963    }
964
965    /// Kimi K3's mapping, which supports only `low`, `high`, and `max`.
966    pub fn kimi_k3() -> Self {
967        Self {
968            low: Some("low".to_string()),
969            high: Some("high".to_string()),
970            max: Some("max".to_string()),
971            ..Self::default()
972        }
973    }
974
975    /// Translates a neutral effort value into the provider's value, or `None`
976    /// when that level is unsupported.
977    pub fn map(&self, effort: crate::types::ReasoningEffort) -> Option<&str> {
978        match effort {
979            crate::types::ReasoningEffort::None => self.none.as_deref(),
980            crate::types::ReasoningEffort::Minimal => self.minimal.as_deref(),
981            crate::types::ReasoningEffort::Low => self.low.as_deref(),
982            crate::types::ReasoningEffort::Medium => self.medium.as_deref(),
983            crate::types::ReasoningEffort::High => self.high.as_deref(),
984            crate::types::ReasoningEffort::XHigh => self.xhigh.as_deref(),
985            crate::types::ReasoningEffort::Max => self.max.as_deref(),
986            crate::types::ReasoningEffort::Ultra => self.ultra.as_deref(),
987        }
988    }
989}
990
991/// Which request field carries the maximum output token limit.
992#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
993pub enum MaxTokensSemantics {
994    /// `max_output_tokens` (OpenAI Responses-style).
995    #[default]
996    MaxOutputTokens,
997    /// `max_tokens` (legacy OpenAI Chat and most compatible APIs).
998    MaxTokens,
999    /// `max_completion_tokens` (newer OpenAI Chat Completions).
1000    MaxCompletionTokens,
1001}