typesafeai-sdk 0.3.7

Rust SDK for TypeSafe AI — typed judgments from System One models like Jev
Documentation
//! Blocking (synchronous) client for the TypeSafe AI API.
//!
//! Enabled with the `blocking` feature flag. Wraps the async
//! [`TypeSafeClient`] with a current-thread Tokio
//! runtime so you can call the API without `async`/`await`.
//!
//! ## Quickstart
//!
//! ```no_run
//! use typesafeai_sdk::blocking::BlockingClient;
//! use typesafeai_sdk::noul;
//! use std::collections::HashMap;
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let client = BlockingClient::from_env()?;
//!
//!     let mut questions = HashMap::new();
//!     questions.insert("billing".to_string(), noul("Is this about billing?").into());
//!
//!     let response = client.system_one("I was charged twice.", questions)?;
//!
//!     if let Some(answer) = response.noul("billing") {
//!         println!("Billing probability: {}", answer.noul);
//!     }
//!     Ok(())
//! }
//! ```

use std::collections::HashMap;
use std::fmt;

use serde_json::Value;

use crate::client::{ClientConfig, SystemOneOpts, TypeSafeClient};
use crate::error::{ErrorKind, Result, TypeSafeError};
use crate::questions::Question;
use crate::types::{ListModelsResponse, SystemOneResponse};

/// A blocking (synchronous) client for the TypeSafe AI API.
///
/// Wraps an async [`TypeSafeClient`] with a dedicated current-thread Tokio
/// runtime. Each method call blocks the calling thread until the response
/// is received.
///
/// Construct with [`BlockingClient::new`], [`BlockingClient::from_env`], or
/// [`BlockingClient::from_config`].
///
/// # Async-context safety
///
/// The constructors and API methods are safe to call from inside a Tokio
/// async context (including `spawn_blocking` threads). When a Tokio runtime
/// is detected on the current thread, `block_on` is executed on a dedicated
/// helper thread to avoid the "cannot start a runtime from within a runtime"
/// panic. Dropping a `BlockingClient` inside an async context is also safe
/// because the runtime is shut down in the background.
#[non_exhaustive]
pub struct BlockingClient {
    inner: TypeSafeClient,
    runtime: Option<tokio::runtime::Runtime>,
}

impl fmt::Debug for BlockingClient {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("BlockingClient")
            .field("inner", &self.inner)
            .finish_non_exhaustive()
    }
}

impl BlockingClient {
    /// Run a future to completion, blocking the calling thread.
    ///
    /// If the current thread is inside a Tokio runtime, `block_on` is
    /// executed on a dedicated helper thread to avoid the "cannot start a
    /// runtime from within a runtime" panic. This makes the blocking client
    /// usable from `spawn_blocking` and other async-adjacent contexts.
    fn block_on<F>(&self, future: F) -> F::Output
    where
        F: std::future::Future + Send,
        F::Output: Send,
    {
        let runtime = self.runtime.as_ref().expect("runtime missing");
        if tokio::runtime::Handle::try_current().is_ok() {
            // We're inside a Tokio runtime. Running `block_on` directly
            // would panic, so spawn a helper thread, run the future there,
            // and wait for the result.
            let handle = runtime.handle().clone();
            let (tx, rx) = std::sync::mpsc::channel();
            std::thread::scope(|scope| {
                scope.spawn(move || {
                    let result = handle.block_on(future);
                    let _ = tx.send(result);
                });
                rx.recv().expect("helper thread panicked")
            })
        } else {
            runtime.block_on(future)
        }
    }

    /// Build a multi-threaded Tokio runtime, returning a `Runtime` error on
    /// failure. A multi-threaded runtime is used so that `Handle::block_on`
    /// can drive the event loop from a helper thread when the blocking
    /// client is used inside an async context.
    fn build_runtime() -> Result<tokio::runtime::Runtime> {
        tokio::runtime::Builder::new_multi_thread()
            .worker_threads(1)
            .enable_all()
            .build()
            .map_err(|e| {
                TypeSafeError::new(ErrorKind::Runtime(format!(
                    "Failed to create Tokio runtime for blocking client: {e}"
                )))
            })
    }

    /// Create a new blocking client with the given API key and default settings.
    ///
    /// # Errors
    /// - [`ErrorKind::Validation`] if the API key is empty.
    #[must_use = "the returned client should be used to make API calls"]
    pub fn new(api_key: impl Into<String>) -> Result<Self> {
        Self::from_config(ClientConfig {
            api_key: api_key.into(),
            ..ClientConfig::default()
        })
    }

    /// Create a new blocking client from a full [`ClientConfig`].
    ///
    /// # Errors
    /// - [`ErrorKind::Validation`] if the API key is empty, the base URL
    ///   is invalid, or the default model name is empty.
    /// - [`ErrorKind::Runtime`] if the Tokio runtime cannot be created.
    #[must_use = "the returned client should be used to make API calls"]
    pub fn from_config(config: ClientConfig) -> Result<Self> {
        let inner = TypeSafeClient::from_config(config)?;
        let runtime = Self::build_runtime()?;
        Ok(Self {
            inner,
            runtime: Some(runtime),
        })
    }

    /// Create a new blocking client, reading the API key from the
    /// `TYPESAFE_API_KEY` environment variable. Also reads
    /// `TYPESAFE_BASE_URL` and `TYPESAFE_DEFAULT_MODEL` if set.
    ///
    /// # Errors
    /// - [`ErrorKind::Validation`] if `TYPESAFE_API_KEY` is unset or empty.
    /// - [`ErrorKind::Runtime`] if the Tokio runtime cannot be created.
    #[must_use = "the returned client should be used to make API calls"]
    pub fn from_env() -> Result<Self> {
        let inner = TypeSafeClient::from_env()?;
        let runtime = Self::build_runtime()?;
        Ok(Self {
            inner,
            runtime: Some(runtime),
        })
    }

    /// Returns the base URL this client is configured to use.
    #[must_use]
    pub fn base_url(&self) -> &str {
        self.inner.base_url()
    }

    /// Returns the default model this client uses.
    #[must_use]
    pub fn default_model(&self) -> &str {
        self.inner.default_model()
    }

    /// Answer named questions about text or structured state.
    ///
    /// Blocks the calling thread until the response is received.
    ///
    /// # Errors
    /// See [`TypeSafeClient::system_one`] for the full list of error variants.
    pub fn system_one(
        &self,
        state: impl Into<Value> + Send,
        questions: HashMap<String, Question>,
    ) -> Result<SystemOneResponse> {
        self.block_on(self.inner.system_one(state, questions))
    }

    /// Like [`system_one`](Self::system_one) but with an explicit model
    /// override (`None` uses the client default).
    ///
    /// # Errors
    /// See [`TypeSafeClient::system_one_with_model`] for the full list of
    /// error variants.
    pub fn system_one_with_model(
        &self,
        state: impl Into<Value> + Send,
        questions: HashMap<String, Question>,
        model: Option<&str>,
    ) -> Result<SystemOneResponse> {
        self.block_on(self.inner.system_one_with_model(state, questions, model))
    }

    /// Like [`system_one`](Self::system_one) but with full per-call options
    /// via a [`SystemOneOpts`] builder.
    ///
    /// # Errors
    /// See [`TypeSafeClient::system_one_with_opts`] for the full list of
    /// error variants.
    pub fn system_one_with_opts(
        &self,
        questions: HashMap<String, Question>,
        opts: SystemOneOpts,
    ) -> Result<SystemOneResponse> {
        self.block_on(self.inner.system_one_with_opts(questions, opts))
    }

    /// List available models. Sends `GET /v1/models`.
    ///
    /// # Errors
    /// See [`TypeSafeClient::list_models`] for the full list of error variants.
    pub fn list_models(&self) -> Result<ListModelsResponse> {
        self.block_on(self.inner.list_models())
    }
}

impl Drop for BlockingClient {
    fn drop(&mut self) {
        // Shut down the runtime in the background so that dropping a
        // `BlockingClient` inside an async context does not panic.
        // `Runtime::drop` calls `block_on` internally to wait for tasks to
        // finish, which panics if called from within a runtime. Using
        // `shutdown_background()` avoids this by not blocking.
        if let Some(runtime) = self.runtime.take() {
            runtime.shutdown_background();
        }
    }
}