Skip to main content

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}