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

Agent

opaque </>

Opaque handle to a running agent actor.

pub opaque type Agent

CancelReason

</>

Typed reason for cancelling active work.

pub type CancelReason =
  run_error.CancelReason

PigConfig

opaque </>

Opaque configuration builder. Construct with new, customize with with_* functions, then start to spawn an agent actor.

pub opaque type PigConfig

Run

</>

Opaque handle for one accepted agent run.

pub type Run =
  run.Run

RunEvent

</>

Transient events emitted to a caller-owned run stream.

pub type RunEvent =
  run.RunEvent

RunStartError

</>

Errors that prevent a run from being accepted.

pub type RunStartError =
  run_error.RunStartError

StartError

</>

Errors that can prevent an agent from starting.

pub type StartError {
  InvalidConfiguration(message: String)
  ActorStart(error: actor.StartError)
  SessionLoad(error: session_store.SessionError)
  ConsumerRegistration(error: dispatcher.RegistrationError)
}

Constructors

```
InvalidConfiguration(message: String)
```
The configuration combines options that cannot be used together.
```
ActorStart(error: actor.StartError)
```
An OTP actor or configured consumer failed to start.
```
SessionLoad(error: session_store.SessionError)
```
The configured durable session could not be loaded.
```
ConsumerRegistration(error: dispatcher.RegistrationError)
```
A configured consumer could not be registered with the dispatcher.

Values

add_consumer

</>

pub fn add_consumer(
  config: PigConfig,
  spec: consumer_spec.ConsumerSpec,
) -> PigConfig

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.

agent_config

</>

pub fn agent_config(config: PigConfig) -> state.AgentConfig

Get the underlying AgentConfig. Useful for testing and inspection.

build_agent_config

</>

pub fn build_agent_config(config: PigConfig) -> state.AgentConfig

Build 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.

cancel

</>

pub fn cancel(
  run: run.Run,
  reason: run_error.CancelReason,
) -> Nil

Cancel an accepted run. Repeated calls are harmless.

collect

</>

pub fn collect(
  run: run.Run,
  sink: process.Subject(run.RunEvent),
  timeout_ms: Int,
) -> Result(message.Message, run_error.RunError)

Collect a run stream into its final assistant message.

history

</>

pub fn history(agent: Agent) -> List(message.Message)

Get the agent’s current conversation history (all messages).

new

</>

pub fn new(provider: provider.Provider) -> PigConfig

Create 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.

reset_inference_settings

</>

pub fn reset_inference_settings(
  agent: Agent,
) -> Result(Nil, run_error.RunError)

Reset the running agent to the provider’s default thinking behavior.

run

</>

pub fn run(
  agent: Agent,
  prompt: String,
) -> Result(message.Message, run_error.RunError)

Run a prompt against the agent with a 120-second default timeout.

run_continue

</>

pub fn run_continue(
  agent: Agent,
) -> Result(message.Message, run_error.RunError)

Resume the agent loop with a 120-second default timeout.

run_continue_with_timeout

</>

pub fn run_continue_with_timeout(
  agent: Agent,
  timeout_ms: Int,
) -> Result(message.Message, run_error.RunError)

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.

run_with_timeout

</>

pub fn run_with_timeout(
  agent: Agent,
  prompt: String,
  timeout_ms: Int,
) -> Result(message.Message, run_error.RunError)

Run a prompt against the agent with an explicit timeout in milliseconds.

set_inference_settings

</>

pub fn set_inference_settings(
  agent: Agent,
  settings: provider.InferenceSettings,
) -> Result(Nil, run_error.RunError)

Set inference settings on a running agent.

With a durable session store this waits for the settings-only commit to be accepted before returning. A failed ambiguous commit leaves the setting unchanged and can be retried by repeating the same call.

set_inference_settings_with_timeout

</>

pub fn set_inference_settings_with_timeout(
  agent: Agent,
  settings: provider.InferenceSettings,
  timeout_ms: Int,
) -> Result(Nil, run_error.RunError)

Set inference settings on a running agent with an explicit timeout.

set_thinking_level

</>

pub fn set_thinking_level(
  agent: Agent,
  level: thinking.ThinkingLevel,
) -> Result(Nil, run_error.RunError)

Set the thinking level on a running agent.

start

</>

pub fn start(config: PigConfig) -> Result(Agent, 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.

stop

</>

pub fn stop(agent: Agent) -> Nil

Stop the agent actor and all unsupervised children owned by it.

stream

</>

pub fn stream(
  agent: Agent,
  prompt: String,
  sink: process.Subject(run.RunEvent),
) -> Result(run.Run, run_error.RunStartError)

Start one run and return as soon as it is accepted.

stream_continue

</>

pub fn stream_continue(
  agent: Agent,
  sink: process.Subject(run.RunEvent),
) -> Result(run.Run, run_error.RunStartError)

Resume the current history as one streamed run.

stream_continue_owned

</>

pub fn stream_continue_owned(
  agent: Agent,
  sink: process.Subject(run.RunEvent),
  owner: process.Pid,
) -> Result(run.Run, run_error.RunStartError)

Resume history while explicitly watching the client owner.

stream_owned

</>

pub fn stream_owned(
  agent: Agent,
  prompt: String,
  sink: process.Subject(run.RunEvent),
  owner: process.Pid,
) -> Result(run.Run, run_error.RunStartError)

Start one run and explicitly watch the client owner for disconnection.

test_harness

</>

pub fn test_harness() -> PigConfig

Return 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.

try_run_continue_with_timeout

</>

pub fn try_run_continue_with_timeout(
  agent: Agent,
  timeout_ms: Int,
) -> Result(Result(message.Message, run_error.RunError), Nil)

Resume the agent loop from its current history with an explicit timeout.

Returns Error(Nil) if the call times out or the agent crashes, instead of panicking. The inner result preserves the agent’s response or RunError.

A timeout actively cancels in-flight provider or tool work before returning.

try_run_with_timeout

</>

pub fn try_run_with_timeout(
  agent: Agent,
  prompt: String,
  timeout_ms: Int,
) -> Result(Result(message.Message, run_error.RunError), 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.

watch_client

</>

pub fn watch_client(run: run.Run, owner: process.Pid) -> Nil

Replace the client process watched for disconnect cancellation.

with_agent_description

</>

pub fn with_agent_description(
  config: PigConfig,
  description: String,
) -> PigConfig

Set the agent description.

with_agent_id

</>

pub fn with_agent_id(config: PigConfig, id: String) -> PigConfig

Set the agent ID.

with_agent_name

</>

pub fn with_agent_name(
  config: PigConfig,
  name: String,
) -> PigConfig

Set the agent name.

with_agent_version

</>

pub fn with_agent_version(
  config: PigConfig,
  version: String,
) -> PigConfig

Set the agent version.

with_consumer_specs

</>

pub fn with_consumer_specs(
  config: PigConfig,
  specs: List(consumer_spec.ConsumerSpec),
) -> PigConfig

Replace 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.

with_hooks

</>

pub fn with_hooks(config: PigConfig, h: hooks.Hooks) -> PigConfig

with_inference_settings

</>

pub fn with_inference_settings(
  config: PigConfig,
  settings: provider.InferenceSettings,
) -> PigConfig

Set the initial inference settings for this agent.

with_initial_history

</>

pub fn with_initial_history(
  config: PigConfig,
  messages: List(message.Message),
) -> PigConfig

Seed 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.

A non-empty initial history cannot be combined with with_session_store: a configured durable store is authoritative, so start rejects that configuration. Persist the history in the store instead.

The provider will see these messages on the first run() call, along with any messages accumulated from session replay and the new user prompt.

with_model

</>

pub fn with_model(config: PigConfig, model: String) -> PigConfig

Set the model name for telemetry and logging.

with_provider_name

</>

pub fn with_provider_name(
  config: PigConfig,
  name: String,
) -> PigConfig

Set the provider name.

with_session_store

</>

pub fn with_session_store(
  config: PigConfig,
  store: session_store.SessionStore,
) -> PigConfig

Configure synchronous durable storage for accepted agent transitions.

The store is loaded before the agent starts. Each newly accepted message delta is committed before Pig executes its effects or returns success.

with_session_writer

</>

pub fn with_session_writer(
  config: PigConfig,
  path: String,
) -> PigConfig

Register a session writer consumer that writes JSONL to the given path. Also sets session_path on agent config for replay on init.

with_skill

</>

pub fn with_skill(config: PigConfig, s: skill.Skill) -> PigConfig

Add 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.

with_system_prompt

</>

pub fn with_system_prompt(
  config: PigConfig,
  prompt: String,
) -> PigConfig

Set the system prompt.

with_terminal_output

</>

pub fn with_terminal_output(config: PigConfig) -> PigConfig

with_thinking_level

</>

pub fn with_thinking_level(
  config: PigConfig,
  level: thinking.ThinkingLevel,
) -> PigConfig

Set the initial thinking level for this agent.

with_tool

</>

pub fn with_tool(config: PigConfig, t: tool.Tool) -> PigConfig

with_tools

</>

pub fn with_tools(
  config: PigConfig,
  tools: List(tool.Tool),
) -> PigConfig