1use 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
35pub const DEFAULT_BASE_URL: &str = "https://api.typesafe.ai";
37pub const DEFAULT_MODEL: &str = "jev-latest";
39pub const PROVIDER: &str = "typesafe";
41
42pub const MAX_BODY_BYTES: usize = 32 * 1024 * 1024;
44pub const MAX_NESTING: usize = 64;
46pub const MAX_CHOICE_OPTIONS: usize = 255;
48pub const MAX_SCORE_LEVELS: usize = 10;
50pub const MAX_REFERENCE_BYTES: usize = 1024;
52pub 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#[derive(Clone)]
61pub struct SystemOneConfig {
62 pub base_url: String,
63 pub api_key: Option<String>,
65 pub credentials: Option<Arc<dyn CredentialSource>>,
67 pub timeout: Duration,
69 pub max_request_bytes: usize,
71 pub max_response_bytes: usize,
73 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 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#[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#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
139#[serde(tag = "type", rename_all = "lowercase")]
140#[non_exhaustive]
141pub enum Question {
142 Choice {
144 #[serde(default, skip_serializing_if = "Option::is_none")]
145 instructions: Option<Json>,
146 criteria: IndexMap<String, Json>,
147 },
148 Score {
150 #[serde(default, skip_serializing_if = "Option::is_none")]
151 instructions: Option<Json>,
152 criteria: Vec<Json>,
153 },
154 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 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 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#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
202pub struct ImageAsset {
203 #[serde(rename = "type")]
204 pub kind: String,
205 pub format: String,
207 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 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
233pub 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#[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 #[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 pub fn needs_images_header(&self) -> bool {
274 !self.assets.is_empty() || self.questions.values().any(|q| matches!(q, Question::Box { .. }))
275 }
276
277 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 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#[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#[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 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 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#[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 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#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
470pub struct SystemOneResponse {
471 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#[derive(Clone)]
485pub struct SystemOneClient {
486 config: SystemOneConfig,
487 client: crate::http::LazyClient,
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::LazyClient::new(Duration::from_secs(10));
502 Ok(Self { config, client })
503 }
504
505 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 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 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 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 let endpoint = crate::http::resolve_endpoint(&self.config.base_url, credential.base_url.as_deref())?;
571 let mut builder = self
572 .client
573 .get()?
574 .post(Self::endpoint(&endpoint.base_url))
575 .timeout(self.config.timeout)
576 .bearer_auth(&credential.secret)
577 .header(reqwest::header::CONTENT_TYPE, "application/json")
578 .body(body.to_vec());
579 if endpoint.send_static {
580 for (name, value) in &self.config.headers {
581 builder = builder.header(name.as_str(), value.as_str());
582 }
583 }
584 for (name, value) in &credential.headers {
585 builder = builder.header(name.as_str(), value.as_str());
586 }
587 if request.needs_images_header() {
588 builder = builder.header(IMAGES_HEADER, "true");
589 }
590 if request.long_context {
591 builder = builder.header(LONG_CONTEXT_HEADER, "true");
592 }
593 let response = builder.send().await.map_err(network_error)?;
594 let status = response.status().as_u16();
595 let retry_after = retry_after_ms(response.headers());
596 if (300..400).contains(&status) {
597 return Err(LlmError::BadRequest(format!(
598 "TypeSafe endpoint answered with a redirect (HTTP {status}); redirects are not followed"
599 )));
600 }
601 if !(200..300).contains(&status) {
602 let body = match read_capped(response, MAX_ERROR_BODY_BYTES).await {
603 Ok(bytes) => String::from_utf8_lossy(&bytes).into_owned(),
604 Err(e) => format!("(error body unreadable: {e})"),
605 };
606 return Err(error_for_status(status, &body, retry_after));
607 }
608 let bytes = read_capped(response, self.config.max_response_bytes).await?;
609 if bytes.len() > self.config.max_response_bytes {
610 return Err(LlmError::Decode(format!(
611 "response exceeds the {}-byte limit",
612 self.config.max_response_bytes
613 )));
614 }
615 let parsed: SystemOneResponse = serde_json::from_slice(&bytes)
616 .map_err(|e| LlmError::Decode(format!("unexpected System One response: {e}")))?;
617 if let Some(missing) = request.questions.keys().find(|name| !parsed.answers.contains_key(*name)) {
618 return Err(LlmError::Decode(format!("response has no answer for question `{missing}`")));
619 }
620 for (name, question) in &request.questions {
621 if let Some(answer) = parsed.answers.get(name) {
622 check_answer(name, question, answer)?;
623 }
624 }
625 Ok(parsed)
626 }
627}
628
629fn check_answer(name: &str, question: &Question, answer: &Answer) -> Result<(), LlmError> {
632 let bad = |msg: String| Err(LlmError::Decode(format!("answer to `{name}`: {msg}")));
633 match (question, answer) {
634 (Question::Choice { criteria, .. }, Answer::Choice { choice, probabilities, .. }) => {
635 if !criteria.contains_key(choice) {
636 return bad(format!("chose `{choice}`, which is not one of the options"));
637 }
638 if !probabilities.contains_key(choice) {
639 return bad(format!("no probability for the chosen option `{choice}`"));
640 }
641 Ok(())
642 }
643 (Question::Score { .. }, Answer::Score { probabilities, .. }) => {
644 if probabilities.is_empty() {
645 return bad("score answer without probabilities".into());
646 }
647 Ok(())
648 }
649 (Question::Noul { .. }, Answer::Noul { .. }) | (Question::Box { .. }, Answer::Box { .. }) => Ok(()),
650 (q, _) => bad(format!("answer type does not match the `{}` question", q.kind())),
651 }
652}
653
654fn network_error(e: reqwest::Error) -> LlmError {
655 if e.is_timeout() {
656 return LlmError::Network("request timed out".into());
657 }
658 LlmError::Network(e.without_url().to_string())
659}
660
661async fn read_capped(response: reqwest::Response, limit: usize) -> Result<Vec<u8>, LlmError> {
663 let mut bytes = Vec::new();
664 let mut stream = response.bytes_stream();
665 while let Some(chunk) = stream.next().await {
666 let chunk = chunk.map_err(network_error)?;
667 let room = limit.saturating_add(1).saturating_sub(bytes.len());
668 bytes.extend(chunk.iter().take(room));
669 if bytes.len() > limit {
670 break;
671 }
672 }
673 Ok(bytes)
674}
675
676fn retry_after_ms(headers: &reqwest::header::HeaderMap) -> Option<u64> {
677 if let Some(ms) = headers.get("retry-after-ms").and_then(|v| v.to_str().ok()) {
678 return ms.trim().parse::<u64>().ok();
679 }
680 let text = headers.get(reqwest::header::RETRY_AFTER)?.to_str().ok()?.trim();
681 let seconds: f64 = text.parse().ok()?;
682 if seconds.is_finite() && seconds >= 0.0 {
683 #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
684 Some((seconds * 1000.0) as u64)
685 } else {
686 None
687 }
688}
689
690fn summarize(body: &str) -> String {
692 const MAX: usize = 1000;
693 let text = match serde_json::from_str::<Json>(body) {
694 Ok(json) => match json.get("detail") {
695 Some(Json::String(s)) => s.clone(),
696 Some(Json::Array(items)) => items
697 .iter()
698 .map(|item| {
699 let loc = item
700 .get("loc")
701 .and_then(Json::as_array)
702 .map(|l| {
703 l.iter()
704 .map(|p| p.as_str().map(str::to_owned).unwrap_or_else(|| p.to_string()))
705 .collect::<Vec<_>>()
706 .join(".")
707 })
708 .unwrap_or_default();
709 let msg = item.get("msg").and_then(Json::as_str).unwrap_or("invalid");
710 if loc.is_empty() { msg.to_owned() } else { format!("{loc}: {msg}") }
711 })
712 .collect::<Vec<_>>()
713 .join("; "),
714 Some(other) => {
715 other.get("message").and_then(Json::as_str).map(str::to_owned).unwrap_or_else(|| other.to_string())
716 }
717 None => body.trim().to_owned(),
718 },
719 Err(_) => body.trim().to_owned(),
720 };
721 if text.chars().count() > MAX {
722 let mut cut: String = text.chars().take(MAX).collect();
723 cut.push('…');
724 cut
725 } else {
726 text
727 }
728}
729
730pub fn error_for_status(status: u16, body: &str, retry_after_ms: Option<u64>) -> LlmError {
732 let message = summarize(body);
733 match status {
734 401 | 403 => LlmError::Auth(message),
735 429 => LlmError::RateLimit { message, retry_after_ms },
736 408 => LlmError::Network(message),
737 400 if body.contains("max_tokens_exceeded") => LlmError::ContextLength(message),
738 413 => LlmError::BadRequest(format!("request body too large: {message}")),
739 s if s >= 500 => {
740 if s == 529 && retry_after_ms.is_some() {
741 LlmError::RateLimit { message: format!("overloaded: {message}"), retry_after_ms }
743 } else {
744 LlmError::Server { status: s, message }
745 }
746 }
747 _ => LlmError::BadRequest(message),
748 }
749}
750
751#[cfg(test)]
752mod tests {
753 use super::*;
754
755 fn tone_request() -> SystemOneRequest {
756 let mut criteria = IndexMap::new();
757 criteria.insert("angry".to_owned(), Json::from("An upset or hostile message"));
758 criteria.insert("calm".to_owned(), Json::from("A neutral or polite message"));
759 criteria.insert("excited".to_owned(), Json::from("An enthusiastic or eager message"));
760 SystemOneRequest::new(
761 DEFAULT_MODEL,
762 Json::from("I was charged twice for my subscription this month. Please refund the extra charge."),
763 )
764 .question("tone", Question::choice("What is the tone of this message?", criteria))
765 }
766
767 #[test]
768 fn serializes_like_the_documented_example() {
769 let body = tone_request().validate(MAX_BODY_BYTES).unwrap();
770 let json: Json = serde_json::from_slice(&body).unwrap();
771 assert_eq!(
772 json,
773 serde_json::json!({
774 "model": "jev-latest",
775 "state": "I was charged twice for my subscription this month. Please refund the extra charge.",
776 "questions": {"tone": {"type": "choice", "instructions": "What is the tone of this message?",
777 "criteria": {"angry": "An upset or hostile message", "calm": "A neutral or polite message",
778 "excited": "An enthusiastic or eager message"}}}
779 })
780 );
781 }
782
783 #[test]
784 fn parses_documented_answers() {
785 let raw = r#"{"model":"jev-latest","answers":{
786 "billing":{"type":"noul","noul":0.98},
787 "tone":{"type":"choice","choice":"calm","confidence":0.7,"probabilities":{"angry":0.15,"calm":0.8,"excited":0.05}},
788 "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}},
789 "red_rectangle":{"type":"box","box":{"top":0.2,"bottom":0.66,"left":0.19,"right":0.68},"confidence":null}},
790 "usage":{"input_tokens":120,"output_tokens":12}}"#;
791 let r: SystemOneResponse = serde_json::from_str(raw).unwrap();
792 assert_eq!(r.answer("billing"), Some(&Answer::Noul { noul: 0.98 }));
793 assert_eq!(r.answer("tone").and_then(Answer::choice_probability), Some(0.8));
794 assert_eq!(r.answer("tone").and_then(Answer::confidence), Some(0.7));
795 assert!(matches!(r.answer("red_rectangle"), Some(Answer::Box { confidence: None, .. })));
796 assert_eq!(r.usage.to_usage().total_tokens, 132);
797 }
798
799 #[test]
800 fn validation_rules() {
801 let empty = SystemOneRequest::new(DEFAULT_MODEL, Json::from("x"));
802 assert!(empty.validate(MAX_BODY_BYTES).is_err());
803
804 let too_many: IndexMap<String, Json> = (0..256).map(|i| (format!("o{i}"), Json::Null)).collect();
805 let r = SystemOneRequest::new(DEFAULT_MODEL, Json::from("x")).question("c", Question::choice("?", too_many));
806 assert!(r.validate(MAX_BODY_BYTES).unwrap_err().to_string().contains("255"));
807
808 let levels: Vec<Json> = (0..11).map(|i| Json::from(i.to_string())).collect();
809 let r = SystemOneRequest::new(DEFAULT_MODEL, Json::from("x")).question("s", Question::score("?", levels));
810 assert!(r.validate(MAX_BODY_BYTES).is_err());
811
812 let mut deep = Json::from("leaf");
813 for _ in 0..70 {
814 deep = Json::Array(vec![deep]);
815 }
816 let r = SystemOneRequest::new(DEFAULT_MODEL, deep).question("n", Question::noul("?"));
817 assert!(r.validate(MAX_BODY_BYTES).unwrap_err().to_string().contains("nested"));
818
819 let asset = ImageAsset::new("image/png", b"\x89PNG").unwrap();
820 let r = SystemOneRequest::new(DEFAULT_MODEL, Json::from("no reference"))
821 .question("n", Question::noul("?"))
822 .asset("ref-1234", asset.clone());
823 assert!(r.validate(MAX_BODY_BYTES).unwrap_err().to_string().contains("not referenced"));
824 let r = SystemOneRequest::new(DEFAULT_MODEL, serde_json::json!({"photo": "ref-1234"}))
825 .question("n", Question::noul("?"))
826 .asset("ref-1234", asset);
827 assert!(r.validate(MAX_BODY_BYTES).is_ok());
828 assert!(r.needs_images_header());
829
830 assert!(tone_request().validate(10).unwrap_err().to_string().contains("limit"));
831 assert!(ImageAsset::new("gif", b"x").is_err());
832 }
833
834 #[test]
835 fn status_mapping() {
836 assert!(matches!(error_for_status(401, "{\"detail\":\"bad key\"}", None), LlmError::Auth(m) if m == "bad key"));
837 let rl = error_for_status(429, "{}", Some(1500));
838 assert_eq!(rl, LlmError::RateLimit { message: "{}".into(), retry_after_ms: Some(1500) });
839 let v = error_for_status(
840 422,
841 r#"{"detail":[{"loc":["body","state"],"msg":"Field required","type":"missing"}]}"#,
842 None,
843 );
844 assert!(matches!(&v, LlmError::BadRequest(m) if m == "body.state: Field required"), "{v:?}");
845 assert!(!v.is_retryable());
846 assert!(matches!(
847 error_for_status(400, "{\"detail\":\"max_tokens_exceeded\"}", None),
848 LlmError::ContextLength(_)
849 ));
850 assert!(error_for_status(529, "overloaded", None).is_retryable());
851 assert!(error_for_status(529, "overloaded", Some(10)).is_retryable());
852 }
853
854 #[test]
855 fn debug_redacts_key() {
856 let c = SystemOneConfig::with_api_key("ts-secret");
857 assert!(!format!("{c:?}").contains("ts-secret"));
858 }
859}