typesafe_ai/lib.rs
1#![warn(missing_docs)]
2#![forbid(unsafe_code)]
3
4//! Blocking and asynchronous clients for TypeSafe's System One API.
5//!
6//! Requests contain shared [`Request::state`] and one or more typed [`Question`]s. The
7//! service evaluates those questions independently and returns an [`Answer`] under each
8//! caller-selected question ID.
9//!
10//! The default `reqwest` feature provides the asynchronous `ReqwestClient`. Enable the
11//! `ureq` feature for the blocking `UreqClient`. The `rustls-tls` feature enables rustls
12//! on each selected backend. With no backend feature, the data types and client traits
13//! remain available without an HTTP implementation.
14//!
15//! # Request example
16//!
17//! The same request can be passed to either backend:
18//!
19//! ```
20//! use std::collections::BTreeMap;
21//!
22//! use serde_json::json;
23//! use typesafe_ai::{Question, Request};
24//!
25//! let request = Request::new("Help! My payouts have been failing for three days.")
26//! .with_question(
27//! "is_urgent",
28//! Question::noul("Does the customer convey urgency?"),
29//! )
30//! .with_question(
31//! "department",
32//! Question::choice(
33//! "Which team should handle this?",
34//! BTreeMap::from([
35//! ("billing".into(), json!("Payments and invoices")),
36//! ("technical".into(), json!("Bugs and outages")),
37//! ]),
38//! ),
39//! )
40//! .with_question(
41//! "frustration",
42//! Question::score(
43//! "How frustrated is the customer?",
44//! vec![json!("Calm"), json!("Frustrated"), json!("Very angry")],
45//! ),
46//! );
47//!
48//! assert_eq!(request.model, "jev-latest");
49//! assert_eq!(request.questions.len(), 3);
50//! ```
51
52mod config;
53mod error;
54mod events;
55mod request;
56#[cfg(feature = "reqwest")]
57mod reqwest_client;
58mod response;
59#[cfg(any(feature = "reqwest", feature = "ureq"))]
60mod transport;
61#[cfg(feature = "ureq")]
62mod ureq_client;
63
64pub use config::ClientConfig;
65pub use error::Error;
66pub use events::{EvaluationEvent, EvaluationFailure};
67pub use futures_core::Stream;
68pub use request::{NoulCriteria, Question, Request};
69#[cfg(feature = "reqwest")]
70pub use reqwest_client::{ReqwestClient, ReqwestError};
71pub use response::{Answer, Response, Usage};
72#[cfg(feature = "ureq")]
73pub use ureq_client::{UreqClient, UreqError};
74
75use std::future::Future;
76
77/// A backend-neutral asynchronous TypeSafe client.
78///
79/// Use this trait when code must be generic over asynchronous backends. Concrete clients
80/// also provide an inherent `evaluate` method.
81pub trait AsyncClient {
82 /// The concrete transport error produced by this implementation.
83 type TransportError: std::error::Error + Send + Sync + 'static;
84
85 /// Creates a lazy stream of attempt failures and the final evaluation result.
86 ///
87 /// Polling drives validation, HTTP work, and retry delays. Yield retryable failures
88 /// before waiting, and end after success or a failure with no scheduled retry.
89 /// Dropping the stream cancels local pending work, not necessarily server processing.
90 fn evaluate_events<'a>(
91 &'a self,
92 request: &'a Request,
93 ) -> impl Stream<Item = EvaluationEvent<Self::TransportError>> + Send + 'a;
94
95 /// Drives the event stream to its terminal result.
96 fn evaluate<'a>(
97 &'a self,
98 request: &'a Request,
99 ) -> impl Future<Output = Result<Response, Error<Self::TransportError>>> + Send + 'a {
100 let events = self.evaluate_events(request);
101 async move {
102 let mut events = std::pin::pin!(events);
103 while let Some(event) =
104 std::future::poll_fn(|context| events.as_mut().poll_next(context)).await
105 {
106 if let Some(result) = event.into_result() {
107 return result;
108 }
109 }
110 Err(Error::IncompleteEvaluation)
111 }
112 }
113}
114
115/// A backend-neutral blocking TypeSafe client.
116///
117/// Use this trait when code must be generic over blocking backends. Concrete clients also
118/// provide an inherent `evaluate` method.
119pub trait SyncClient {
120 /// The concrete transport error produced by this implementation.
121 type TransportError: std::error::Error + Send + Sync + 'static;
122
123 /// Creates a lazy iterator of attempt failures and the final evaluation result.
124 ///
125 /// Each `next()` drives validation, retry waiting, and at most one HTTP attempt.
126 /// Dropping between calls stops further work; it cannot interrupt a running `next()`.
127 fn evaluate_events(
128 &self,
129 request: &Request,
130 ) -> impl Iterator<Item = EvaluationEvent<Self::TransportError>>;
131
132 /// Drives the event iterator to its terminal result.
133 fn evaluate(&self, request: &Request) -> Result<Response, Error<Self::TransportError>> {
134 for event in self.evaluate_events(request) {
135 if let Some(result) = event.into_result() {
136 return result;
137 }
138 }
139 Err(Error::IncompleteEvaluation)
140 }
141}