spawningpool 0.1.1

Create hyper-specific, 0-waste agents
Documentation
spawningpool-0.1.1 has been yanked.

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,
    )
    .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.