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: 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 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 .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
628fn 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
660async 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
689fn 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
729pub 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 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}