Skip to main content

Crate spawningpool

Crate spawningpool 

Source
Expand description

§spawningpool

crates.io docs.rs license

Create hyper-specific, 0-waste agents.

spawningpool is the core library behind the spawningpool CLI. A specialist is a saved template of (provider, model, system prompt, tools) that you instantiate with a prompt and run. This crate gives you the domain types, the on-disk registry, the provider clients (Anthropic and any OpenAI-compatible endpoint), and the agentic run loop that drives a specialist against a prompt — executing its tools and feeding results back until it settles.

If you just want the command-line tool, install spawningpool-cli instead.

§Install

cargo add spawningpool

§What’s in the box

  • domain — the entity model: Registry, ProviderDef, ModelDef, Specialist, and ToolDef, with reference resolution between them.
  • store — load and save the JSON registry on disk.
  • tools — resolve executable scripts in the tools/ folder into ToolDefs.
  • ai — the Client, provider adapters, message/streaming types, and optional JSON-Schema validation of tool calls.
  • run_specialist — the front-end-agnostic agentic loop, which reports progress through a RunEvent observer you supply rather than writing to stdout itself.

§Example

Load the registry the spawningpool CLI persists, then run a specialist and print its output as it streams:

use spawningpool::ai::Client;
use spawningpool::{run_specialist, store, tools, RunEvent};

#[tokio::main]
async fn main() -> Result<(), String> {
    // Load the registry the `spawningpool` CLI writes to disk.
    let registry = store::load()?;
    let specialist = registry
        .specialists
        .get("namer")
        .ok_or("unknown specialist")?;

    // Resolve the specialist's tools from the tools/ folder beside the registry.
    let resolved = tools::resolve_all(&store::tools_dir(), specialist.tool_names())?;

    // Build request options, sourcing the API key from the provider's env var.
    let mut opts = specialist.complete_options();
    if let Some(provider) = registry.providers.get(&specialist.provider) {
        if let Some(env) = provider.api_key_env.as_ref() {
            if let Ok(key) = std::env::var(env) {
                opts.api_key = Some(key);
            }
        }
        opts.constrained_decoding = provider.constrained_decoding;
    }

    // Drive the agentic loop, printing assistant text as it arrives.
    let client = Client::new();
    let mut observer = |event: RunEvent<'_>| {
        if let RunEvent::Text(text) | RunEvent::TextDelta(text) = event {
            print!("{text}");
        }
    };
    run_specialist(
        &client,
        &registry,
        specialist,
        "A CLI that spawns AI specialists",
        &resolved,
        &opts,
        &mut observer,
        None, // no structured logging in this minimal example
    )
    .await
}

§Forcing structured output

A Specialist with a constraint forces one call to a named tool, making the tool’s parameters a structured-output schema. By default this uses the tool-call trick: rather than relying on grammar-constrained decoding (which not every endpoint supports), the request forces a tool call whose arguments are the structured output — tool_choice on OpenAI-compatible endpoints, native forced tool choice on Anthropic — so it works on every provider.

Setting constrained_decoding (from a ProviderDef declared with --constrained-decoding) upgrades to true grammar-constrained decoding. Only the OpenAI-compatible adapter honors it; the Anthropic adapter always uses native forced tool choice.

§Documentation

§License

Licensed under the MIT license.

Re-exports§

pub use log::LogSink;
pub use log::SpecialistLog;
pub use run::run_specialist;
pub use run::RunEvent;
pub use domain::EntityKind;
pub use domain::MissingRef;
pub use domain::ModelDef;
pub use domain::ProviderDef;
pub use domain::Referrer;
pub use domain::Registry;
pub use domain::Specialist;
pub use domain::ToolDef;
pub use types::ExitCode;
pub use types::Param;
pub use types::Type;

Modules§

ai
Multi-provider LLM abstraction.
domain
The definition layer: persisted templates that compile down into the runtime crate::ai types.
log
Structured workflow logging (docs/workflow-logging.md).
run
Running a specialist: the agentic loop that drives a Specialist against a prompt, executing its tools and feeding results back until it settles.
store
Persistence for the Registry: a single JSON file on disk.
tools
The tool catalog as an ls-able folder of executable scripts.
types
The workflow DSL type system: the notation a tool header declares (in its # params: and # output: lines) and the rule for lowering it to JSON Schema.
workflow
Workflow DSL: parse, type-check, and evaluate orchestration scripts that chain tools and specialists with typed data flow.

Structs§

ScriptRun
The outcome of running a script: whether it exited successfully, its combined stdout/stderr (ready to feed back to the model as a tool result), and any structured output the script wrote to $SP_OUTPUT_PATH.
ScriptSummary
A tool script’s declared description, parameters, and output type, parsed from its header comments.

Enums§

ScriptError
Why a tool script can’t be accepted as a tool’s backing executable.

Functions§

prepare_script
Resolve a tool script to an absolute path and confirm it can actually run: it must exist and have the executable bit set. Storing the script absolute means the tool resolves no matter where it is later invoked from. This is the check spawningpool define tool (or a UI) runs before accepting a script, so an un-runnable one fails at define time with a fixable error rather than mid-run.
run_script
Run a tool script directly, passing each argument as an environment variable. Captures combined stdout/stderr; a non-zero exit is reported via ScriptRun::success, not as an Err (only a failure to launch is an Err). The script must be executable and carry a shebang.
summarize
Read a tool script’s header for its # desc: line, # params: list, and # output: type. Parameters are separated by whitespace and/or commas and may carry an optional :type suffix (no suffix means string); the # output: line declares the tool’s output type (see crate::types). The first occurrence of each directive wins; non-comment lines are ignored. A malformed type in the header is an error.