Expand description
§spawningpool
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, andToolDef, with reference resolution between them.store— load and save the JSON registry on disk.tools— resolve executable scripts in thetools/folder intoToolDefs.ai— theClient, 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 aRunEventobserver 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,
®istry,
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
- API docs: https://docs.rs/spawningpool
- Guides (quickstart, CLI reference, writing tools, configuration):
the
docs/folder
§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::aitypes. - log
- Structured workflow logging (docs/workflow-logging.md).
- run
- Running a specialist: the agentic loop that drives a
Specialistagainst 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§
- Script
Run - 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. - Script
Summary - A tool script’s declared description, parameters, and output type, parsed from its header comments.
Enums§
- Script
Error - 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 anErr(only a failure to launch is anErr). 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:typesuffix (no suffix meansstring); the# output:line declares the tool’s output type (seecrate::types). The first occurrence of each directive wins; non-comment lines are ignored. A malformed type in the header is an error.