Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

19.1 KB
Raw Blame
//! Calling the `tinydocs` module over the bus.
//!
//! Each function here is the host half of one method on
//! `ai.tinyhumans.tinydocs.Documents`. These wrappers keep document tools from
//! needing to know about streams, held outputs, or wire error names — a caller
//! gets a typed result or a reason.
//!
//! # The shape of a call
//!
//! Inbound payloads ride a `TinyBus` stream opened alongside the call, so a
//! `.pdf` or a set of slide images is never squeezed through a 16 MiB JSON
//! frame. Outbound payloads cannot use a stream — a served object has no way to
//! open one back to its caller — so a produced document is held by the module
//! and pulled here with `ReadOutput`, then released.
//!
//! The release is in a `defer`-shaped position on purpose: the module bounds what
//! it holds and expires it, but leaving a document to time out costs its budget
//! in the meantime, and the next caller sees a full store rather than a slot.
//!
//! # Deadlines belong to the caller
//!
//! Nothing here imposes one. The document tools already wrap their calls in a
//! `tokio::time::timeout` chosen for what the tool is doing, and a second
//! deadline underneath would make the effective limit the smaller of two numbers
//! nobody picked together.

use crate::tools::implementations::document::format::spec::{DocumentSpec, WirePresentationSpec};
use base64::engine::general_purpose::STANDARD as BASE64;
use base64::Engine as _;
use tinybus::stream::StreamRef;
use tinydocs_bus::names::methods;
use tinydocs_bus::OutputRef;

use super::{ops, registry};
use crate::config::Config;

/// Registry id of the module these calls go to.
const MODULE_ID: &str = "tinydocs";

/// User-facing reason for the temporary host-side spreadsheet import stop.
const SPREADSHEET_IMPORT_UNAVAILABLE: &str = "spreadsheet imports are temporarily unavailable";

/// How much of a held document to pull per `ReadOutput`.
///
/// Below the module's own per-chunk cap with room for the base64 expansion and
/// the JSON envelope around it.
const READ_CHUNK: u64 = 1024 * 1024;

/// Largest document this host will assemble from a module.
///
/// Matches the module's own per-output cap, and is enforced here anyway. A
/// declared length is a number a module sent us: trusting it for a
/// `Vec::with_capacity` turns a wrong or hostile value into an allocation
/// failure, which aborts the process rather than returning an error. The rest of
/// `read_all` already treats the declared length as possibly wrong; this applies
/// the same distrust to the allocation.
const MAX_DOCUMENT_BYTES: u64 = 64 * 1024 * 1024;

/// Why a document call did not produce bytes.
///
/// Three variants rather than one string because the three tools that call this
/// map them onto three different agent-facing shapes: a spec the model can fix,
/// a failure it cannot, and a capability that is not present at all.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DocumentCallError {
    /// The module is not loaded and cannot be: unsupported host, downloads off,
    /// disabled in config, or a load that already failed in this process.
    Unavailable(String),
    /// The spec was rejected. A model can act on this.
    InvalidInput(String),
    /// Synthesis, extraction, or the transfer itself failed.
    Failed(String),
}

impl std::fmt::Display for DocumentCallError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Unavailable(message) | Self::InvalidInput(message) | Self::Failed(message) => {
                f.write_str(message)
            }
        }
    }
}

/// Generate a `.docx` from `spec`.
///
/// # Errors
///
/// [`DocumentCallError`] describing whether the spec, the module, or the
/// synthesis was at fault.
pub async fn generate_docx(
    config: &Config,
    spec: &DocumentSpec,
) -> Result<Vec<u8>, DocumentCallError> {
    let (runtime, record) = ready(config).await?;
    let proxy = proxy(runtime, record)?;
    let handle: OutputRef = proxy
        .call(methods::GENERATE_DOCX, (spec,))
        .await
        .map_err(|error| classify(&error))?;
    collect(&proxy, handle).await
}

/// Generate a `.pptx` from `deck`, streaming `images` alongside the call.
///
/// `images` is every slide image concatenated in slide order; the `byte_len` on
/// each entry in `deck` says where one ends and the next begins.
///
/// # Errors
///
/// [`DocumentCallError`], including an `InvalidInput` if `images` does not add
/// up to the lengths `deck` declares.
pub async fn generate_pptx(
    config: &Config,
    deck: &WirePresentationSpec,
    images: &[u8],
) -> Result<Vec<u8>, DocumentCallError> {
    let (runtime, record) = ready(config).await?;
    let proxy = proxy(runtime, record)?;

    let handle: OutputRef = if images.is_empty() {
        // A text-only deck opens no stream: there is nothing to send, and an
        // empty stream is a round trip for nothing.
        proxy
            .call(methods::GENERATE_PPTX, (deck, Option::<StreamRef>::None))
            .await
            .map_err(|error| classify(&error))?
    } else {
        let (destination, path, interface) = address(record)?;
        runtime
            .connection()
            .call_with_stream(
                destination,
                path,
                interface,
                member(methods::GENERATE_PPTX)?,
                |stream| serde_json::json!([deck, stream]),
                images,
            )
            .await
            .map_err(|error| classify(&error))?
    };
    collect(&proxy, handle).await
}

/// Extract the text layer of the `.pdf` in `document`.
///
/// # Errors
///
/// [`DocumentCallError`]. A document that parses but carries no text layer — a
/// scan — is not an error: it yields an empty string.
pub async fn extract_text(config: &Config, document: &[u8]) -> Result<String, DocumentCallError> {
    let (runtime, record) = ready(config).await?;
    let proxy = proxy(runtime, record)?;
    let (destination, path, interface) = address(record)?;

    let handle: OutputRef = runtime
        .connection()
        .call_with_stream(
            destination,
            path,
            interface,
            member(methods::EXTRACT_TEXT)?,
            |stream| serde_json::json!([stream]),
            document,
        )
        .await
        .map_err(|error| classify(&error))?;

    let bytes = collect(&proxy, handle).await?;
    String::from_utf8(bytes)
        .map_err(|_| DocumentCallError::Failed("extracted text was not valid UTF-8".to_string()))
}

/// Load the document module if it is not already serving.
///
/// Callers do not have to invoke this — every operation below does it — but a
/// caller that wraps its work in a deadline should, *outside* that deadline.
/// A first use may download and verify an artifact, and charging that against a
/// generation timeout means the first document a user ever asks for is the one
/// that fails. Every later call finds it cached and returns immediately.
///
/// # Errors
///
/// The same [`DocumentCallError::Unavailable`] the operations return.
pub async fn ensure_ready(config: &Config) -> Result<(), DocumentCallError> {
    ops::ensure_loaded(config, MODULE_ID)
        .await
        .map_err(DocumentCallError::Unavailable)
}

/// Ensure the module is serving and hand back what a call needs.
async fn ready(
    config: &Config,
) -> Result<
    (
        &'static tinybus::module::ModuleRuntime,
        &'static super::ModuleRecord,
    ),
    DocumentCallError,
> {
    ops::ensure_loaded(config, MODULE_ID)
        .await
        .map_err(DocumentCallError::Unavailable)?;
    let record = registry::find(MODULE_ID)
        .ok_or_else(|| DocumentCallError::Unavailable(format!("unknown module '{MODULE_ID}'")))?;
    let runtime = super::runtime::runtime()
        .await
        .map_err(|_| DocumentCallError::Unavailable("the module bus is not running".to_string()))?;
    Ok((runtime, record))
}

/// A proxy for the module's object.
fn proxy(
    runtime: &'static tinybus::module::ModuleRuntime,
    record: &super::ModuleRecord,
) -> Result<tinybus::Proxy, DocumentCallError> {
    runtime
        .proxy(record.bus_name, record.object_path)
        .map_err(|error| DocumentCallError::Failed(error.to_string()))
}

/// The destination triple a streaming call needs.
fn address(
    record: &super::ModuleRecord,
) -> Result<
    (
        tinybus::BusName,
        tinybus::ObjectPath,
        tinybus::InterfaceName,
    ),
    DocumentCallError,
> {
    let bad = |error: tinybus::Error| DocumentCallError::Failed(error.to_string());
    Ok((
        tinybus::BusName::new(record.bus_name).map_err(bad)?,
        tinybus::ObjectPath::new(record.object_path).map_err(bad)?,
        tinybus::InterfaceName::new(record.bus_name).map_err(bad)?,
    ))
}

/// A member name, which is a constant in every caller here.
fn member(name: &str) -> Result<tinybus::MemberName, DocumentCallError> {
    tinybus::MemberName::new(name).map_err(|error| DocumentCallError::Failed(error.to_string()))
}

/// Releases held outputs even when a caller drops a timed-out future.
struct OutputReleaseGuard {
    proxy: tinybus::Proxy,
    ids: Vec<String>,
}
impl Drop for OutputReleaseGuard {
    fn drop(&mut self) {
        if self.ids.is_empty() {
            return;
        }
        let Ok(runtime) = tokio::runtime::Handle::try_current() else {
            return;
        };
        let proxy = self.proxy.clone();
        let ids = std::mem::take(&mut self.ids);
        runtime.spawn(async move {
            for id in ids {
                let _ = tokio::time::timeout(
                    std::time::Duration::from_secs(5),
                    proxy.call::<()>(methods::RELEASE_OUTPUT, (id,)),
                )
                .await;
            }
        });
    }
}

/// Pull a held document, verify it, and release it.
///
/// The release runs whether or not the read succeeded: a document left behind
/// costs the module's budget until its TTL expires, and the next caller sees a
/// full store rather than a slot.
async fn collect(proxy: &tinybus::Proxy, handle: OutputRef) -> Result<Vec<u8>, DocumentCallError> {
    let mut release = OutputReleaseGuard {
        proxy: proxy.clone(),
        ids: vec![handle.output_id.clone()],
    };
    let result = read_all(proxy, &handle).await;
    if let Err(error) = proxy
        .call::<()>(methods::RELEASE_OUTPUT, (handle.output_id.clone(),))
        .await
    {
        // Not fatal: the module expires what nobody reads. Worth a line, because
        // a pattern of these means documents are sitting in the module's budget
        // until they time out.
        log::debug!("[modules] releasing a read document failed: {error}");
    }
    release.ids.clear();
    result
}

/// Read a held document in chunks and check it against its digest.
async fn read_all(
    proxy: &tinybus::Proxy,
    handle: &OutputRef,
) -> Result<Vec<u8>, DocumentCallError> {
    if handle.total_bytes > MAX_DOCUMENT_BYTES {
        return Err(DocumentCallError::Failed(format!(
            "the module declared a {}-byte document, over the {MAX_DOCUMENT_BYTES}-byte limit",
            handle.total_bytes
        )));
    }
    // Reserve against the declared length only once it is known to be sane, and
    // still only up to one chunk beyond what has arrived — the loop grows the
    // buffer as real bytes land rather than trusting the number up front.
    let capacity = usize::try_from(handle.total_bytes).unwrap_or(0);
    let mut out = Vec::with_capacity(capacity.min(MAX_DOCUMENT_BYTES as usize));
    while (out.len() as u64) < handle.total_bytes {
        let encoded: String = proxy
            .call(
                methods::READ_OUTPUT,
                (handle.output_id.clone(), out.len() as u64, READ_CHUNK),
            )
            .await
            .map_err(|error| classify(&error))?;
        let chunk = BASE64.decode(encoded).map_err(|_| {
            DocumentCallError::Failed("a document chunk was not base64".to_string())
        })?;
        if chunk.is_empty() {
            // The module clamps a read to what is left, so an empty chunk before
            // the declared length means the two sides disagree about the size.
            // Looping would spin forever.
            return Err(DocumentCallError::Failed(
                "the document ended before its declared length".to_string(),
            ));
        }
        out.extend_from_slice(&chunk);
    }

    let digest = sha256_hex(&out);
    if digest != handle.sha256 {
        return Err(DocumentCallError::Failed(
            "the assembled document did not match its declared digest".to_string(),
        ));
    }
    Ok(out)
}

/// Lowercase hex SHA-256, matching what the module declares.
fn sha256_hex(bytes: &[u8]) -> String {
    use sha2::{Digest, Sha256};
    let digest = Sha256::digest(bytes);
    let mut out = String::with_capacity(64);
    for byte in digest {
        use std::fmt::Write as _;
        let _ = write!(out, "{byte:02x}");
    }
    out
}

/// Map a bus failure onto the shape a tool can act on.
///
/// The wire name is the contract; the message is for a human. An unrecognised
/// name is `Failed` rather than `InvalidInput`, because telling a model its input
/// was wrong when it was not sends it into a rewrite loop.
fn classify(error: &tinybus::Error) -> DocumentCallError {
    let message = error.to_string();
    match error.wire_name() {
        "ai.tinyhumans.tinydocs.Error.InvalidInput" => DocumentCallError::InvalidInput(message),
        // The module is loaded but not answering: refused, faulted, or gone.
        name if name.contains("ModuleUnavailable") => DocumentCallError::Unavailable(message),
        _ => DocumentCallError::Failed(message),
    }
}

#[cfg(test)]
#[path = "documents_tests.rs"]
mod tests;

/// Extract structured document sections using the published intake contract.
/// XLSX is recognized by the contract but temporarily refused before loading
/// the module while the published parser dependencies are being repaired.
pub async fn extract_document(
    config: &Config,
    document: &[u8],
    spec: &tinydocs_bus::ExtractDocumentSpec,
) -> Result<tinydocs_bus::ExtractedDocument, DocumentCallError> {
    reject_disabled_spreadsheet_import(spec.format)?;
    intake_available()?;
    let (runtime, record) = ready(config).await?;
    let (destination, path, interface) = address(record)?;
    runtime
        .connection()
        .call_with_stream(
            destination,
            path,
            interface,
            member(methods::EXTRACT_DOCUMENT)?,
            |stream| serde_json::json!([spec, stream]),
            document,
        )
        .await
        .map_err(|e| classify(&e))
}

/// Convert a streamed PDF, Word document, or presentation to complete
/// normalized Markdown. XLSX is temporarily refused before loading the module
/// while the published parser dependencies are being repaired.
///
/// Unlike [`extract_document`], this operation preserves the full text needed
/// for memory persistence and returns it through the module's bounded held
/// output store.
///
/// # Errors
///
/// Returns [`DocumentCallError`] when the module is unavailable, the document
/// is invalid, the output transfer fails, or the complete text is not UTF-8.
pub async fn convert_markdown(
    config: &Config,
    format: tinydocs_bus::DocumentFormat,
    document: &[u8],
) -> Result<String, DocumentCallError> {
    reject_disabled_spreadsheet_import(format)?;
    let (runtime, record) = ready(config).await?;
    let proxy = proxy(runtime, record)?;
    let (destination, path, interface) = address(record)?;
    let handle: OutputRef = runtime
        .connection()
        .call_with_stream(
            destination,
            path,
            interface,
            member(methods::CONVERT_MARKDOWN)?,
            |stream| serde_json::json!([format, stream]),
            document,
        )
        .await
        .map_err(|error| classify(&error))?;
    let bytes = collect(&proxy, handle).await?;
    String::from_utf8(bytes)
        .map_err(|_| DocumentCallError::Failed("converted Markdown was not valid UTF-8".into()))
}

/// Inspect bounded PNG/JPEG bytes through TinyDocs and return their verified
/// format and dimensions.
pub async fn inspect_image(
    config: &Config,
    image: &[u8],
) -> Result<tinydocs_bus::ImageFacts, DocumentCallError> {
    let max = tinydocs_bus::spec::presentation::MAX_IMAGE_BYTES;
    if image.is_empty() || image.len() > max {
        return Err(DocumentCallError::InvalidInput(format!(
            "image must contain 1 to {max} bytes"
        )));
    }
    let (runtime, record) = ready(config).await?;
    let (destination, path, interface) = address(record)?;
    runtime
        .connection()
        .call_with_stream(
            destination,
            path,
            interface,
            member(methods::INSPECT_IMAGE)?,
            |stream| serde_json::json!([stream]),
            image,
        )
        .await
        .map_err(|error| classify(&error))
}

/// Render selected PDF pages and collect/release every held PNG output.
pub async fn render_pdf(
    config: &Config,
    document: &[u8],
    spec: &tinydocs_bus::RenderPdfSpec,
) -> Result<Vec<(u32, Vec<u8>)>, DocumentCallError> {
    intake_available()?;
    let (runtime, record) = ready(config).await?;
    let proxy = proxy(runtime, record)?;
    let (destination, path, interface) = address(record)?;
    let rendered: tinydocs_bus::RenderedPdf = runtime
        .connection()
        .call_with_stream(
            destination,
            path,
            interface,
            member(methods::RENDER_PDF)?,
            |stream| serde_json::json!([spec, stream]),
            document,
        )
        .await
        .map_err(|e| classify(&e))?;
    let mut pending = OutputReleaseGuard {
        proxy: proxy.clone(),
        ids: rendered
            .pages
            .iter()
            .map(|page| page.output.output_id.clone())
            .collect(),
    };
    let mut pages = Vec::new();
    let mut error = None;
    for page in rendered.pages {
        let id = page.output.output_id.clone();
        match collect(&proxy, page.output).await {
            Ok(bytes) if error.is_none() => pages.push((page.page, bytes)),
            Ok(_) => (),
            Err(e) => {
                error.get_or_insert(e);
            }
        }
        pending.ids.retain(|pending_id| pending_id != &id);
    }
    if let Some(error) = error {
        Err(error)
    } else {
        Ok(pages)
    }
}

fn intake_available() -> Result<(), DocumentCallError> {
    let record = registry::find(MODULE_ID).ok_or_else(|| {
        DocumentCallError::Unavailable("document module is not registered".into())
    })?;
    // 0.1.20 predates the additive intake methods. Keep signed artifact admission intact.
    if record.version == "0.1.20" {
        return Err(DocumentCallError::Unavailable(
            "the pinned TinyDocs release does not expose document intake or PDF rendering".into(),
        ));
    }
    Ok(())
}

/// Refuse spreadsheet parsing before module loading or bus access.
fn reject_disabled_spreadsheet_import(
    format: tinydocs_bus::DocumentFormat,
) -> Result<(), DocumentCallError> {
    if matches!(format, tinydocs_bus::DocumentFormat::Xlsx) {
        Err(DocumentCallError::Unavailable(
            SPREADSHEET_IMPORT_UNAVAILABLE.to_string(),
        ))
    } else {
        Ok(())
    }
}