Skip to main content

graphrt_llm/
typesafe.rs

1//! Client for TypeSafe's System One decision API (model family "Jev").
2//!
3//! A System One request sends one `state` (text, JSON, or images) plus named,
4//! typed questions; every question is evaluated in parallel and answered with a
5//! typed, calibrated result:
6//!
7//! | Question | Answer |
8//! |---|---|
9//! | [`Question::Choice`] | selected option, a probability per option, confidence |
10//! | [`Question::Score`]  | expected score over ordered levels, probabilities, confidence |
11//! | [`Question::Noul`]   | probability that the yes/no statement is true |
12//! | [`Question::Box`]    | box edges (fractions of the image) and optional confidence |
13//!
14//! Requests go to `POST {base_url}/v1/systemone` with `Authorization: Bearer <key>`.
15//! The key is static ([`SystemOneConfig::api_key`]) or fetched per request from a
16//! [`CredentialSource`]; a 401/403 invalidates the credential and retries once.
17//!
18//! The client validates the documented request rules before sending (at least one
19//! question, 1–255 choice options, 1–10 score levels, nesting depth, referenced
20//! assets, body size) and sets the `TypeSafe-Danger-Zone-Images` header whenever
21//! a request carries images or a box question.
22
23use std::fmt;
24use std::sync::Arc;
25use std::time::Duration;
26
27use futures::StreamExt;
28use indexmap::IndexMap;
29use serde::{Deserialize, Serialize};
30use serde_json::Value as Json;
31
32use crate::credentials::{Credential, CredentialSource};
33use crate::error::LlmError;
34
35/// Default API endpoint.
36pub const DEFAULT_BASE_URL: &str = "https://api.typesafe.ai";
37/// Default model alias: the newest stable Jev release.
38pub const DEFAULT_MODEL: &str = "jev-latest";
39/// Registry / service name used by nodes (`model.provider: typesafe`).
40pub const PROVIDER: &str = "typesafe";
41
42/// Documented maximum request body (32 MiB).
43pub const MAX_BODY_BYTES: usize = 32 * 1024 * 1024;
44/// Documented maximum nesting of `state`, `instructions` and `criteria`.
45pub const MAX_NESTING: usize = 64;
46/// Documented maximum options of a choice question.
47pub const MAX_CHOICE_OPTIONS: usize = 255;
48/// Documented maximum levels of a score question.
49pub const MAX_SCORE_LEVELS: usize = 10;
50/// Documented maximum length of one asset reference, in bytes.
51pub const MAX_REFERENCE_BYTES: usize = 1024;
52/// Documented maximum total length of all asset references, in bytes.
53pub const MAX_REFERENCES_BYTES: usize = 65_536;
54
55const IMAGES_HEADER: &str = "TypeSafe-Danger-Zone-Images";
56const LONG_CONTEXT_HEADER: &str = "TypeSafe-Danger-Zone-Long-Context";
57const MAX_ERROR_BODY_BYTES: usize = 64 * 1024;
58
59/// Client configuration.
60#[derive(Clone)]
61pub struct SystemOneConfig {
62    pub base_url: String,
63    /// Static API key. Ignored when `credentials` is set.
64    pub api_key: Option<String>,
65    /// Per-request credential source (e.g. a token broker on a phone).
66    pub credentials: Option<Arc<dyn CredentialSource>>,
67    /// Whole-request timeout.
68    pub timeout: Duration,
69    /// Request bodies above this size are rejected before sending (capped at 32 MiB).
70    pub max_request_bytes: usize,
71    /// Responses above this size are rejected.
72    pub max_response_bytes: usize,
73    /// Extra headers (e.g. a tenant header). Not sent when a credential moves the
74    /// request to a different origin.
75    pub headers: Vec<(String, String)>,
76}
77
78impl Default for SystemOneConfig {
79    fn default() -> Self {
80        Self {
81            base_url: DEFAULT_BASE_URL.to_owned(),
82            api_key: None,
83            credentials: None,
84            timeout: Duration::from_secs(60),
85            max_request_bytes: MAX_BODY_BYTES,
86            max_response_bytes: 8 * 1024 * 1024,
87            headers: Vec::new(),
88        }
89    }
90}
91
92impl fmt::Debug for SystemOneConfig {
93    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
94        f.debug_struct("SystemOneConfig")
95            .field("base_url", &self.base_url)
96            .field("api_key", &self.api_key.as_ref().map(|_| "<redacted>"))
97            .field("credentials", &self.credentials.as_ref().map(|_| "<source>"))
98            .field("timeout", &self.timeout)
99            .field("max_request_bytes", &self.max_request_bytes)
100            .field("max_response_bytes", &self.max_response_bytes)
101            .field("headers", &self.headers.iter().map(|(k, _)| k).collect::<Vec<_>>())
102            .finish()
103    }
104}
105
106impl SystemOneConfig {
107    /// Configuration with a static API key.
108    pub fn with_api_key(api_key: impl Into<String>) -> Self {
109        Self { api_key: Some(api_key.into()), ..Self::default() }
110    }
111
112    pub fn base_url(mut self, base_url: impl Into<String>) -> Self {
113        self.base_url = base_url.into();
114        self
115    }
116
117    pub fn credentials(mut self, source: Arc<dyn CredentialSource>) -> Self {
118        self.credentials = Some(source);
119        self
120    }
121
122    pub fn timeout(mut self, timeout: Duration) -> Self {
123        self.timeout = timeout;
124        self
125    }
126}
127
128/// Criteria of a yes/no question: what counts as yes and as no.
129#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
130pub struct NoulCriteria {
131    #[serde(rename = "true", default, skip_serializing_if = "Option::is_none")]
132    pub yes: Option<Json>,
133    #[serde(rename = "false", default, skip_serializing_if = "Option::is_none")]
134    pub no: Option<Json>,
135}
136
137/// A typed question.
138#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
139#[serde(tag = "type", rename_all = "lowercase")]
140#[non_exhaustive]
141pub enum Question {
142    /// Select one option. `criteria` maps option names to descriptions (may be `null`).
143    Choice {
144        #[serde(default, skip_serializing_if = "Option::is_none")]
145        instructions: Option<Json>,
146        criteria: IndexMap<String, Json>,
147    },
148    /// Rate against ordered levels; level `i` scores `i`.
149    Score {
150        #[serde(default, skip_serializing_if = "Option::is_none")]
151        instructions: Option<Json>,
152        criteria: Vec<Json>,
153    },
154    /// Probability that a statement is true / the answer is yes.
155    Noul {
156        #[serde(default, skip_serializing_if = "Option::is_none")]
157        instructions: Option<Json>,
158        #[serde(default, skip_serializing_if = "Option::is_none")]
159        criteria: Option<NoulCriteria>,
160    },
161    /// Locate something in the request's image.
162    Box {
163        #[serde(default, skip_serializing_if = "Option::is_none")]
164        instructions: Option<Json>,
165    },
166}
167
168impl Question {
169    pub fn choice(instructions: impl Into<String>, criteria: IndexMap<String, Json>) -> Self {
170        Question::Choice { instructions: Some(Json::String(instructions.into())), criteria }
171    }
172
173    pub fn score(instructions: impl Into<String>, levels: Vec<Json>) -> Self {
174        Question::Score { instructions: Some(Json::String(instructions.into())), criteria: levels }
175    }
176
177    pub fn noul(instructions: impl Into<String>) -> Self {
178        Question::Noul { instructions: Some(Json::String(instructions.into())), criteria: None }
179    }
180
181    pub fn noul_with(instructions: impl Into<String>, criteria: NoulCriteria) -> Self {
182        Question::Noul { instructions: Some(Json::String(instructions.into())), criteria: Some(criteria) }
183    }
184
185    pub fn bounding_box(instructions: impl Into<String>) -> Self {
186        Question::Box { instructions: Some(Json::String(instructions.into())) }
187    }
188
189    /// Wire name of the question type.
190    pub fn kind(&self) -> &'static str {
191        match self {
192            Question::Choice { .. } => "choice",
193            Question::Score { .. } => "score",
194            Question::Noul { .. } => "noul",
195            Question::Box { .. } => "box",
196        }
197    }
198}
199
200/// An image asset, referenced by its key wherever it appears in a request string.
201#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
202pub struct ImageAsset {
203    #[serde(rename = "type")]
204    pub kind: String,
205    /// `png`, `jpg` or `jpeg`.
206    pub format: String,
207    /// Standard base64 with padding, no `data:` prefix.
208    pub data_base64: String,
209}
210
211impl fmt::Debug for ImageAsset {
212    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
213        f.debug_struct("ImageAsset")
214            .field("format", &self.format)
215            .field("data_base64", &format_args!("<{} bytes>", self.data_base64.len()))
216            .finish()
217    }
218}
219
220impl ImageAsset {
221    /// Asset from raw image bytes. `format` must be `png`, `jpg` or `jpeg`.
222    pub fn new(format: &str, bytes: &[u8]) -> Result<Self, LlmError> {
223        let format = normalize_format(format)
224            .ok_or_else(|| LlmError::BadRequest(format!("unsupported image format `{format}` (png or jpg)")))?;
225        Ok(Self {
226            kind: "image".to_owned(),
227            format: format.to_owned(),
228            data_base64: graphrt_core::file::base64_encode(bytes),
229        })
230    }
231}
232
233/// Map a format name or media type to `png` / `jpg`.
234pub fn normalize_format(raw: &str) -> Option<&'static str> {
235    let lowered = raw.trim().to_ascii_lowercase();
236    let short = lowered.rsplit('/').next().unwrap_or(&lowered);
237    match short {
238        "png" => Some("png"),
239        "jpg" | "jpeg" | "pjpeg" => Some("jpg"),
240        _ => None,
241    }
242}
243
244/// A System One request.
245#[derive(Clone, Debug, PartialEq, Serialize)]
246pub struct SystemOneRequest {
247    pub model: String,
248    pub state: Json,
249    pub questions: IndexMap<String, Question>,
250    #[serde(skip_serializing_if = "IndexMap::is_empty")]
251    pub assets: IndexMap<String, ImageAsset>,
252    /// Send `TypeSafe-Danger-Zone-Long-Context: true` (262k-token limits, slower).
253    #[serde(skip)]
254    pub long_context: bool,
255}
256
257impl SystemOneRequest {
258    pub fn new(model: impl Into<String>, state: Json) -> Self {
259        Self { model: model.into(), state, questions: IndexMap::new(), assets: IndexMap::new(), long_context: false }
260    }
261
262    pub fn question(mut self, name: impl Into<String>, question: Question) -> Self {
263        self.questions.insert(name.into(), question);
264        self
265    }
266
267    pub fn asset(mut self, reference: impl Into<String>, asset: ImageAsset) -> Self {
268        self.assets.insert(reference.into(), asset);
269        self
270    }
271
272    /// Whether the images header must be sent.
273    pub fn needs_images_header(&self) -> bool {
274        !self.assets.is_empty() || self.questions.values().any(|q| matches!(q, Question::Box { .. }))
275    }
276
277    /// Check the documented request rules. Returns the serialized body.
278    pub fn validate(&self, max_bytes: usize) -> Result<Vec<u8>, LlmError> {
279        let bad = |m: String| Err(LlmError::BadRequest(m));
280        if self.model.trim().is_empty() {
281            return bad("model must not be empty".into());
282        }
283        if self.questions.is_empty() {
284            return bad("a request needs at least one question".into());
285        }
286        check_depth("state", &self.state)?;
287        for (name, question) in &self.questions {
288            if name.is_empty() {
289                return bad("question names must not be empty".into());
290            }
291            match question {
292                Question::Choice { instructions, criteria } => {
293                    if criteria.is_empty() || criteria.len() > MAX_CHOICE_OPTIONS {
294                        return bad(format!(
295                            "choice question `{name}` needs 1 to {MAX_CHOICE_OPTIONS} options, got {}",
296                            criteria.len()
297                        ));
298                    }
299                    check_opt_depth(name, instructions.as_ref())?;
300                    for value in criteria.values() {
301                        check_depth(name, value)?;
302                    }
303                }
304                Question::Score { instructions, criteria } => {
305                    if criteria.is_empty() || criteria.len() > MAX_SCORE_LEVELS {
306                        return bad(format!(
307                            "score question `{name}` needs 1 to {MAX_SCORE_LEVELS} levels, got {}",
308                            criteria.len()
309                        ));
310                    }
311                    check_opt_depth(name, instructions.as_ref())?;
312                    for value in criteria {
313                        check_depth(name, value)?;
314                    }
315                }
316                Question::Noul { instructions, criteria } => {
317                    check_opt_depth(name, instructions.as_ref())?;
318                    if let Some(c) = criteria {
319                        check_opt_depth(name, c.yes.as_ref())?;
320                        check_opt_depth(name, c.no.as_ref())?;
321                    }
322                }
323                Question::Box { instructions } => check_opt_depth(name, instructions.as_ref())?,
324            }
325        }
326        let mut total_reference_bytes = 0usize;
327        for (reference, asset) in &self.assets {
328            if reference.trim().is_empty() || reference.len() > MAX_REFERENCE_BYTES {
329                return bad(format!("asset references must be 1 to {MAX_REFERENCE_BYTES} bytes"));
330            }
331            total_reference_bytes = total_reference_bytes.saturating_add(reference.len());
332            if normalize_format(&asset.format).is_none() {
333                return bad(format!("asset `{reference}` has unsupported format `{}`", asset.format));
334            }
335        }
336        if total_reference_bytes > MAX_REFERENCES_BYTES {
337            return bad(format!("asset references exceed {MAX_REFERENCES_BYTES} bytes in total"));
338        }
339        if !self.assets.is_empty() {
340            // Every asset must be referenced somewhere in the request's strings.
341            let mut text = String::new();
342            collect_strings(&self.state, &mut text);
343            for q in self.questions.values() {
344                if let Ok(json) = serde_json::to_value(q) {
345                    collect_strings(&json, &mut text);
346                }
347            }
348            if let Some(unused) = self.assets.keys().find(|r| !text.contains(r.as_str())) {
349                return bad(format!("asset `{unused}` is not referenced in the state or any question"));
350            }
351        }
352        let body = serde_json::to_vec(self).map_err(|e| LlmError::BadRequest(format!("cannot encode request: {e}")))?;
353        let limit = max_bytes.min(MAX_BODY_BYTES);
354        if body.len() > limit {
355            return bad(format!("request body is {} bytes, over the {limit}-byte limit", body.len()));
356        }
357        Ok(body)
358    }
359}
360
361fn check_opt_depth(name: &str, value: Option<&Json>) -> Result<(), LlmError> {
362    match value {
363        Some(v) => check_depth(name, v),
364        None => Ok(()),
365    }
366}
367
368fn check_depth(what: &str, value: &Json) -> Result<(), LlmError> {
369    fn depth(value: &Json) -> usize {
370        match value {
371            Json::Array(items) => 1 + items.iter().map(depth).max().unwrap_or(0),
372            Json::Object(map) => 1 + map.values().map(depth).max().unwrap_or(0),
373            _ => 0,
374        }
375    }
376    if depth(value) > MAX_NESTING {
377        return Err(LlmError::BadRequest(format!("`{what}` is nested deeper than {MAX_NESTING} levels")));
378    }
379    Ok(())
380}
381
382fn collect_strings(value: &Json, out: &mut String) {
383    match value {
384        Json::String(s) => {
385            out.push_str(s);
386            out.push('\n');
387        }
388        Json::Array(items) => items.iter().for_each(|v| collect_strings(v, out)),
389        Json::Object(map) => map.values().for_each(|v| collect_strings(v, out)),
390        _ => {}
391    }
392}
393
394/// Box edges as fractions of the image (top/bottom from the top, left/right from the left).
395#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
396pub struct BoxCoordinates {
397    pub top: f64,
398    pub bottom: f64,
399    pub left: f64,
400    pub right: f64,
401}
402
403/// A typed answer.
404#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
405#[serde(tag = "type", rename_all = "lowercase")]
406#[non_exhaustive]
407pub enum Answer {
408    Choice {
409        choice: String,
410        confidence: f64,
411        probabilities: IndexMap<String, f64>,
412    },
413    Score {
414        score: f64,
415        confidence: f64,
416        #[serde(default)]
417        legend: IndexMap<String, Json>,
418        probabilities: IndexMap<String, f64>,
419    },
420    Noul {
421        noul: f64,
422    },
423    Box {
424        #[serde(rename = "box")]
425        coordinates: BoxCoordinates,
426        #[serde(default)]
427        confidence: Option<f64>,
428    },
429}
430
431impl Answer {
432    /// Probability of the selected choice, for choice answers.
433    pub fn choice_probability(&self) -> Option<f64> {
434        match self {
435            Answer::Choice { choice, probabilities, .. } => probabilities.get(choice).copied(),
436            _ => None,
437        }
438    }
439
440    /// Confidence, when the answer carries one.
441    pub fn confidence(&self) -> Option<f64> {
442        match self {
443            Answer::Choice { confidence, .. } | Answer::Score { confidence, .. } => Some(*confidence),
444            Answer::Box { confidence, .. } => *confidence,
445            Answer::Noul { .. } => None,
446        }
447    }
448}
449
450/// Token usage of a request.
451#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
452pub struct SystemOneUsage {
453    pub input_tokens: u64,
454    pub output_tokens: u64,
455}
456
457impl SystemOneUsage {
458    /// As the runtime's usage type.
459    pub fn to_usage(self) -> graphrt_core::Usage {
460        graphrt_core::Usage {
461            prompt_tokens: self.input_tokens,
462            completion_tokens: self.output_tokens,
463            total_tokens: self.input_tokens.saturating_add(self.output_tokens),
464        }
465    }
466}
467
468/// A System One response.
469#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
470pub struct SystemOneResponse {
471    /// Versioned model id that answered (may differ from the requested alias).
472    pub model: String,
473    pub answers: IndexMap<String, Answer>,
474    pub usage: SystemOneUsage,
475}
476
477impl SystemOneResponse {
478    pub fn answer(&self, name: &str) -> Option<&Answer> {
479        self.answers.get(name)
480    }
481}
482
483/// System One API client. Register it in [`graphrt_core::Services`] as `Arc<SystemOneClient>`.
484#[derive(Clone)]
485pub struct SystemOneClient {
486    config: SystemOneConfig,
487    client: reqwest::Client,
488}
489
490impl fmt::Debug for SystemOneClient {
491    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
492        f.debug_struct("SystemOneClient").field("config", &self.config).finish_non_exhaustive()
493    }
494}
495
496impl SystemOneClient {
497    pub fn new(config: SystemOneConfig) -> Result<Self, LlmError> {
498        if config.api_key.is_none() && config.credentials.is_none() {
499            return Err(LlmError::Config("TypeSafe client needs an API key or a credential source".into()));
500        }
501        let client = crate::http::build_client(Duration::from_secs(10))?;
502        Ok(Self { config, client })
503    }
504
505    /// Build from `TYPESAFE_API_KEY` (required) and `TYPESAFE_BASE_URL` (optional).
506    /// Returns `Ok(None)` when no key is set.
507    pub fn from_vars(vars: &[(String, String)]) -> Result<Option<Self>, LlmError> {
508        let get = |k: &str| vars.iter().find(|(name, v)| name == k && !v.is_empty()).map(|(_, v)| v.clone());
509        let Some(key) = get("TYPESAFE_API_KEY") else {
510            if get("TYPESAFE_BASE_URL").is_some() {
511                return Err(LlmError::Config("TYPESAFE_BASE_URL is set but TYPESAFE_API_KEY is not".into()));
512            }
513            return Ok(None);
514        };
515        let mut config = SystemOneConfig::with_api_key(key);
516        if let Some(base) = get("TYPESAFE_BASE_URL") {
517            config.base_url = base;
518        }
519        Self::new(config).map(Some)
520    }
521
522    /// Build from the process environment (see [`SystemOneClient::from_vars`]).
523    pub fn from_env() -> Result<Option<Self>, LlmError> {
524        let vars: Vec<(String, String)> = std::env::vars().collect();
525        Self::from_vars(&vars)
526    }
527
528    pub fn config(&self) -> &SystemOneConfig {
529        &self.config
530    }
531
532    fn endpoint(base_url: &str) -> String {
533        format!("{}/v1/systemone", base_url.trim_end_matches('/'))
534    }
535
536    async fn credential(&self) -> Result<Credential, LlmError> {
537        match (&self.config.credentials, &self.config.api_key) {
538            (Some(source), _) => source.credential(PROVIDER).await,
539            (None, Some(key)) => Ok(Credential::new(key.clone())),
540            (None, None) => Err(LlmError::Config("no TypeSafe credentials configured".into())),
541        }
542    }
543
544    /// Evaluate the request's questions.
545    pub async fn ask(&self, request: &SystemOneRequest) -> Result<SystemOneResponse, LlmError> {
546        let body = request.validate(self.config.max_request_bytes)?;
547        let mut refreshed = false;
548        loop {
549            let credential = self.credential().await?;
550            match self.send_once(request, &body, &credential).await {
551                Err(LlmError::Auth(_)) if !refreshed && self.config.credentials.is_some() => {
552                    // The credential was rejected: drop any cached value and retry once.
553                    if let Some(source) = &self.config.credentials {
554                        source.invalidate(PROVIDER);
555                    }
556                    refreshed = true;
557                }
558                other => return other,
559            }
560        }
561    }
562
563    async fn send_once(
564        &self,
565        request: &SystemOneRequest,
566        body: &[u8],
567        credential: &Credential,
568    ) -> Result<SystemOneResponse, LlmError> {
569        // A credential may move the request to a proxy (thin-proxy pattern).
570        let endpoint = crate::http::resolve_endpoint(&self.config.base_url, credential.base_url.as_deref())?;
571        let mut builder = self
572            .client
573            .post(Self::endpoint(&endpoint.base_url))
574            .timeout(self.config.timeout)
575            .bearer_auth(&credential.secret)
576            .header(reqwest::header::CONTENT_TYPE, "application/json")
577            .body(body.to_vec());
578        if endpoint.send_static {
579            for (name, value) in &self.config.headers {
580                builder = builder.header(name.as_str(), value.as_str());
581            }
582        }
583        for (name, value) in &credential.headers {
584            builder = builder.header(name.as_str(), value.as_str());
585        }
586        if request.needs_images_header() {
587            builder = builder.header(IMAGES_HEADER, "true");
588        }
589        if request.long_context {
590            builder = builder.header(LONG_CONTEXT_HEADER, "true");
591        }
592        let response = builder.send().await.map_err(network_error)?;
593        let status = response.status().as_u16();
594        let retry_after = retry_after_ms(response.headers());
595        if (300..400).contains(&status) {
596            return Err(LlmError::BadRequest(format!(
597                "TypeSafe endpoint answered with a redirect (HTTP {status}); redirects are not followed"
598            )));
599        }
600        if !(200..300).contains(&status) {
601            let body = match read_capped(response, MAX_ERROR_BODY_BYTES).await {
602                Ok(bytes) => String::from_utf8_lossy(&bytes).into_owned(),
603                Err(e) => format!("(error body unreadable: {e})"),
604            };
605            return Err(error_for_status(status, &body, retry_after));
606        }
607        let bytes = read_capped(response, self.config.max_response_bytes).await?;
608        if bytes.len() > self.config.max_response_bytes {
609            return Err(LlmError::Decode(format!(
610                "response exceeds the {}-byte limit",
611                self.config.max_response_bytes
612            )));
613        }
614        let parsed: SystemOneResponse = serde_json::from_slice(&bytes)
615            .map_err(|e| LlmError::Decode(format!("unexpected System One response: {e}")))?;
616        if let Some(missing) = request.questions.keys().find(|name| !parsed.answers.contains_key(*name)) {
617            return Err(LlmError::Decode(format!("response has no answer for question `{missing}`")));
618        }
619        for (name, question) in &request.questions {
620            if let Some(answer) = parsed.answers.get(name) {
621                check_answer(name, question, answer)?;
622            }
623        }
624        Ok(parsed)
625    }
626}
627
628/// Check that an answer matches its question: same type, the chosen option is one
629/// of the criteria, and the probability of the chosen option is present.
630fn check_answer(name: &str, question: &Question, answer: &Answer) -> Result<(), LlmError> {
631    let bad = |msg: String| Err(LlmError::Decode(format!("answer to `{name}`: {msg}")));
632    match (question, answer) {
633        (Question::Choice { criteria, .. }, Answer::Choice { choice, probabilities, .. }) => {
634            if !criteria.contains_key(choice) {
635                return bad(format!("chose `{choice}`, which is not one of the options"));
636            }
637            if !probabilities.contains_key(choice) {
638                return bad(format!("no probability for the chosen option `{choice}`"));
639            }
640            Ok(())
641        }
642        (Question::Score { .. }, Answer::Score { probabilities, .. }) => {
643            if probabilities.is_empty() {
644                return bad("score answer without probabilities".into());
645            }
646            Ok(())
647        }
648        (Question::Noul { .. }, Answer::Noul { .. }) | (Question::Box { .. }, Answer::Box { .. }) => Ok(()),
649        (q, _) => bad(format!("answer type does not match the `{}` question", q.kind())),
650    }
651}
652
653fn network_error(e: reqwest::Error) -> LlmError {
654    if e.is_timeout() {
655        return LlmError::Network("request timed out".into());
656    }
657    LlmError::Network(e.without_url().to_string())
658}
659
660/// Read a body, stopping one byte past `limit` so callers can detect overflow.
661async fn read_capped(response: reqwest::Response, limit: usize) -> Result<Vec<u8>, LlmError> {
662    let mut bytes = Vec::new();
663    let mut stream = response.bytes_stream();
664    while let Some(chunk) = stream.next().await {
665        let chunk = chunk.map_err(network_error)?;
666        let room = limit.saturating_add(1).saturating_sub(bytes.len());
667        bytes.extend(chunk.iter().take(room));
668        if bytes.len() > limit {
669            break;
670        }
671    }
672    Ok(bytes)
673}
674
675fn retry_after_ms(headers: &reqwest::header::HeaderMap) -> Option<u64> {
676    if let Some(ms) = headers.get("retry-after-ms").and_then(|v| v.to_str().ok()) {
677        return ms.trim().parse::<u64>().ok();
678    }
679    let text = headers.get(reqwest::header::RETRY_AFTER)?.to_str().ok()?.trim();
680    let seconds: f64 = text.parse().ok()?;
681    if seconds.is_finite() && seconds >= 0.0 {
682        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
683        Some((seconds * 1000.0) as u64)
684    } else {
685        None
686    }
687}
688
689/// Human-readable summary of an error body (`detail` string, object or validation list).
690fn summarize(body: &str) -> String {
691    const MAX: usize = 1000;
692    let text = match serde_json::from_str::<Json>(body) {
693        Ok(json) => match json.get("detail") {
694            Some(Json::String(s)) => s.clone(),
695            Some(Json::Array(items)) => items
696                .iter()
697                .map(|item| {
698                    let loc = item
699                        .get("loc")
700                        .and_then(Json::as_array)
701                        .map(|l| {
702                            l.iter()
703                                .map(|p| p.as_str().map(str::to_owned).unwrap_or_else(|| p.to_string()))
704                                .collect::<Vec<_>>()
705                                .join(".")
706                        })
707                        .unwrap_or_default();
708                    let msg = item.get("msg").and_then(Json::as_str).unwrap_or("invalid");
709                    if loc.is_empty() { msg.to_owned() } else { format!("{loc}: {msg}") }
710                })
711                .collect::<Vec<_>>()
712                .join("; "),
713            Some(other) => {
714                other.get("message").and_then(Json::as_str).map(str::to_owned).unwrap_or_else(|| other.to_string())
715            }
716            None => body.trim().to_owned(),
717        },
718        Err(_) => body.trim().to_owned(),
719    };
720    if text.chars().count() > MAX {
721        let mut cut: String = text.chars().take(MAX).collect();
722        cut.push('…');
723        cut
724    } else {
725        text
726    }
727}
728
729/// Map a documented HTTP status to an error.
730pub fn error_for_status(status: u16, body: &str, retry_after_ms: Option<u64>) -> LlmError {
731    let message = summarize(body);
732    match status {
733        401 | 403 => LlmError::Auth(message),
734        429 => LlmError::RateLimit { message, retry_after_ms },
735        408 => LlmError::Network(message),
736        400 if body.contains("max_tokens_exceeded") => LlmError::ContextLength(message),
737        413 => LlmError::BadRequest(format!("request body too large: {message}")),
738        s if s >= 500 => {
739            if s == 529 && retry_after_ms.is_some() {
740                // Overloaded: surface the server's hint through the rate-limit variant.
741                LlmError::RateLimit { message: format!("overloaded: {message}"), retry_after_ms }
742            } else {
743                LlmError::Server { status: s, message }
744            }
745        }
746        _ => LlmError::BadRequest(message),
747    }
748}
749
750#[cfg(test)]
751mod tests {
752    use super::*;
753
754    fn tone_request() -> SystemOneRequest {
755        let mut criteria = IndexMap::new();
756        criteria.insert("angry".to_owned(), Json::from("An upset or hostile message"));
757        criteria.insert("calm".to_owned(), Json::from("A neutral or polite message"));
758        criteria.insert("excited".to_owned(), Json::from("An enthusiastic or eager message"));
759        SystemOneRequest::new(
760            DEFAULT_MODEL,
761            Json::from("I was charged twice for my subscription this month. Please refund the extra charge."),
762        )
763        .question("tone", Question::choice("What is the tone of this message?", criteria))
764    }
765
766    #[test]
767    fn serializes_like_the_documented_example() {
768        let body = tone_request().validate(MAX_BODY_BYTES).unwrap();
769        let json: Json = serde_json::from_slice(&body).unwrap();
770        assert_eq!(
771            json,
772            serde_json::json!({
773                "model": "jev-latest",
774                "state": "I was charged twice for my subscription this month. Please refund the extra charge.",
775                "questions": {"tone": {"type": "choice", "instructions": "What is the tone of this message?",
776                    "criteria": {"angry": "An upset or hostile message", "calm": "A neutral or polite message",
777                                 "excited": "An enthusiastic or eager message"}}}
778            })
779        );
780    }
781
782    #[test]
783    fn parses_documented_answers() {
784        let raw = r#"{"model":"jev-latest","answers":{
785            "billing":{"type":"noul","noul":0.98},
786            "tone":{"type":"choice","choice":"calm","confidence":0.7,"probabilities":{"angry":0.15,"calm":0.8,"excited":0.05}},
787            "urgency":{"type":"score","score":1.7,"confidence":0.55,"legend":{"0":"Can wait","1":"Needs attention this week","2":"Needs attention today"},"probabilities":{"0":0.1,"1":0.1,"2":0.8}},
788            "red_rectangle":{"type":"box","box":{"top":0.2,"bottom":0.66,"left":0.19,"right":0.68},"confidence":null}},
789            "usage":{"input_tokens":120,"output_tokens":12}}"#;
790        let r: SystemOneResponse = serde_json::from_str(raw).unwrap();
791        assert_eq!(r.answer("billing"), Some(&Answer::Noul { noul: 0.98 }));
792        assert_eq!(r.answer("tone").and_then(Answer::choice_probability), Some(0.8));
793        assert_eq!(r.answer("tone").and_then(Answer::confidence), Some(0.7));
794        assert!(matches!(r.answer("red_rectangle"), Some(Answer::Box { confidence: None, .. })));
795        assert_eq!(r.usage.to_usage().total_tokens, 132);
796    }
797
798    #[test]
799    fn validation_rules() {
800        let empty = SystemOneRequest::new(DEFAULT_MODEL, Json::from("x"));
801        assert!(empty.validate(MAX_BODY_BYTES).is_err());
802
803        let too_many: IndexMap<String, Json> = (0..256).map(|i| (format!("o{i}"), Json::Null)).collect();
804        let r = SystemOneRequest::new(DEFAULT_MODEL, Json::from("x")).question("c", Question::choice("?", too_many));
805        assert!(r.validate(MAX_BODY_BYTES).unwrap_err().to_string().contains("255"));
806
807        let levels: Vec<Json> = (0..11).map(|i| Json::from(i.to_string())).collect();
808        let r = SystemOneRequest::new(DEFAULT_MODEL, Json::from("x")).question("s", Question::score("?", levels));
809        assert!(r.validate(MAX_BODY_BYTES).is_err());
810
811        let mut deep = Json::from("leaf");
812        for _ in 0..70 {
813            deep = Json::Array(vec![deep]);
814        }
815        let r = SystemOneRequest::new(DEFAULT_MODEL, deep).question("n", Question::noul("?"));
816        assert!(r.validate(MAX_BODY_BYTES).unwrap_err().to_string().contains("nested"));
817
818        let asset = ImageAsset::new("image/png", b"\x89PNG").unwrap();
819        let r = SystemOneRequest::new(DEFAULT_MODEL, Json::from("no reference"))
820            .question("n", Question::noul("?"))
821            .asset("ref-1234", asset.clone());
822        assert!(r.validate(MAX_BODY_BYTES).unwrap_err().to_string().contains("not referenced"));
823        let r = SystemOneRequest::new(DEFAULT_MODEL, serde_json::json!({"photo": "ref-1234"}))
824            .question("n", Question::noul("?"))
825            .asset("ref-1234", asset);
826        assert!(r.validate(MAX_BODY_BYTES).is_ok());
827        assert!(r.needs_images_header());
828
829        assert!(tone_request().validate(10).unwrap_err().to_string().contains("limit"));
830        assert!(ImageAsset::new("gif", b"x").is_err());
831    }
832
833    #[test]
834    fn status_mapping() {
835        assert!(matches!(error_for_status(401, "{\"detail\":\"bad key\"}", None), LlmError::Auth(m) if m == "bad key"));
836        let rl = error_for_status(429, "{}", Some(1500));
837        assert_eq!(rl, LlmError::RateLimit { message: "{}".into(), retry_after_ms: Some(1500) });
838        let v = error_for_status(
839            422,
840            r#"{"detail":[{"loc":["body","state"],"msg":"Field required","type":"missing"}]}"#,
841            None,
842        );
843        assert!(matches!(&v, LlmError::BadRequest(m) if m == "body.state: Field required"), "{v:?}");
844        assert!(!v.is_retryable());
845        assert!(matches!(
846            error_for_status(400, "{\"detail\":\"max_tokens_exceeded\"}", None),
847            LlmError::ContextLength(_)
848        ));
849        assert!(error_for_status(529, "overloaded", None).is_retryable());
850        assert!(error_for_status(529, "overloaded", Some(10)).is_retryable());
851    }
852
853    #[test]
854    fn debug_redacts_key() {
855        let c = SystemOneConfig::with_api_key("ts-secret");
856        assert!(!format!("{c:?}").contains("ts-secret"));
857    }
858}