pig
Top-level public API for the pig library.
Builder pattern: new(provider) |> with_tool(t) |> with_skill(s) |> start
Then: run(agent, prompt) or run_with_timeout(agent, prompt, ms)
Thin public surface. All logic in agent/update (pure core) + agent/runtime (impure interpreter).
Types
Values
pub fn add_consumer(
config: PigConfig,
spec: consumer_spec.ConsumerSpec,
) -> PigConfigRegister a custom consumer specification.
Appends to the list of consumer specs. Consumers receive pig’s
SessionEvent stream — useful for bridging events into an external
store (e.g. a host runtime’s observability table keyed by run_id).
This is the seam host runtimes use to capture pig’s agent-internal events (token usage, tool calls, inference timing) without pig ever depending on them.
pub fn agent_config(config: PigConfig) -> state.AgentConfigGet the underlying AgentConfig. Useful for testing and inspection.
pub fn build_agent_config(config: PigConfig) -> state.AgentConfigBuild the final AgentConfig from a PigConfig.
Registers librarian tool if skills are present and composes
system prompt from skill descriptions and tool info. Used by
start and pig/supervisor.start_supervised.
pub fn history(agent: Agent) -> List(message.Message)Get the agent’s current conversation history (all messages).
pub fn new(
provider: fn(
List(message.Message),
List(tool_definition.ToolDefinition),
) -> Result(provider.InferenceResult, error.AiError),
) -> PigConfigCreate a new PigConfig with a provider and sensible defaults.
Defaults: empty tool registry, no system prompt, no skills, no persistence, model “unknown”, max iterations 50, no consumers.
pub fn run(
agent: Agent,
prompt: String,
) -> Result(message.Message, error.AiError)Run a prompt against the agent with a 120-second default timeout.
pub fn run_continue(
agent: Agent,
) -> Result(message.Message, error.AiError)Resume the agent loop with a 120-second default timeout.
pub fn run_continue_with_timeout(
agent: Agent,
timeout_ms: Int,
) -> Result(message.Message, error.AiError)Resume the agent loop from its current history.
Used for the durability pattern: an external system checkpoints messages,
and on retry, rebuilds the agent’s history from those checkpoints via
with_initial_history. This function continues the loop from where
the history left off, without adding a new user prompt.
Returns the final assistant message when the loop completes, or an error.
pub fn run_with_timeout(
agent: Agent,
prompt: String,
timeout_ms: Int,
) -> Result(message.Message, error.AiError)Run a prompt against the agent with an explicit timeout in milliseconds.
pub fn start(
config: PigConfig,
) -> Result(Agent, actor.StartError)Start an agent actor from the config.
Builds the final AgentConfig: registers the librarian tool if
skills are present, composes system prompt from skill descriptions.
Also creates a dispatcher actor and registers all configured consumers.
Returns an Agent handle for sending prompts.
pub fn test_harness() -> PigConfigReturn a PigConfig with a deterministic mock provider.
The mock provider always returns
Assistant("mock response", [], None, None).
Useful for testing code that uses pig without hitting a real API.
pub fn try_run_with_timeout(
agent: Agent,
prompt: String,
timeout_ms: Int,
) -> Result(Result(message.Message, error.AiError), Nil)Run a prompt against the agent with an explicit timeout in milliseconds.
Returns Error(Nil) if the call times out or the agent crashes,
instead of panicking. Use this when you need resilience over panic-on-timeout.
pub fn with_agent_description(
config: PigConfig,
description: String,
) -> PigConfigSet the agent description.
pub fn with_agent_version(
config: PigConfig,
version: String,
) -> PigConfigSet the agent version.
pub fn with_consumer_specs(
config: PigConfig,
specs: List(consumer_spec.ConsumerSpec),
) -> PigConfigReplace the list of consumer specifications.
Overwrites any previously registered consumers (including those added
by with_session_writer / with_terminal_output / add_consumer).
Pass an empty list to clear all consumers.
pub fn with_hooks(config: PigConfig, h: hooks.Hooks) -> PigConfigRegister a hooks set for lifecycle mediation.
pub fn with_initial_history(
config: PigConfig,
messages: List(message.Message),
) -> PigConfigSeed the conversation with initial messages.
Messages are appended to the agent’s history after session replay
(if any) when the agent starts via start(). This allows resuming
a previous conversation or providing context before the first prompt.
The provider will see these messages on the first run() call,
along with any messages accumulated from session replay and the
new user prompt.
pub fn with_model(config: PigConfig, model: String) -> PigConfigSet the model name for telemetry and logging.
pub fn with_session_writer(
config: PigConfig,
path: String,
) -> PigConfigRegister a session writer consumer that writes JSONL to the given path. Also sets session_path on agent config for replay on init.
pub fn with_skill(config: PigConfig, s: skill.Skill) -> PigConfigAdd a skill and register the librarian tool.
Skills are accumulated. On start, a single librarian tool is
created from all skills, and skill descriptions are injected
into the system prompt.
pub fn with_terminal_output(config: PigConfig) -> PigConfigRegister a terminal output consumer that prints formatted events to stdout.