pig - v0.1.0

pig/agent/runtime

Sans-IO runtime interpreter for the pig agent.

The runtime is an OTP actor that:

  1. Receives prompts (Run) or control messages (Stop)
  2. Calls update.update(state, msg) — pure state machine
  3. For each effect, applies hooks then executes
  4. Produces SessionEvent values and sends to dispatcher
  5. Feeds effect results back as new AgentMsg values

The core logic (update.gleam) is pure. This module is all IO.

Types

RuntimeConfig

</>

Configuration for the runtime. Holds everything the runtime needs that the pure core doesn’t — provider function, tool registry, hooks, dispatcher, and model name.

pub type RuntimeConfig {
  RuntimeConfig(
    provider: fn(
      List(message.Message),
      List(tool_definition.ToolDefinition),
    ) -> Result(provider.InferenceResult, error.AiError),
    tools: tool.ToolRegistry,
    hooks: List(hooks.Hooks),
    dispatcher: process.Subject(dispatcher.DispatcherMessage),
    model: String,
    max_iterations: Int,
  )
}

Constructors

RuntimeMsg

</>

Messages the runtime actor can receive.

pub type RuntimeMsg {
  Run(
    prompt: String,
    reply_to: process.Subject(
      Result(message.Message, error.AiError),
    ),
  )
  Continue(
    reply_to: process.Subject(
      Result(message.Message, error.AiError),
    ),
  )
  GetHistory(reply_to: process.Subject(List(message.Message)))
  Stop
}

Constructors

RuntimeState

</>

Internal state held by the runtime actor.

pub type RuntimeState {
  RuntimeState(
    agent_state: state.AgentState,
    config: RuntimeConfig,
  )
}

Constructors

Values

history

</> 
pub fn history(
  subject: process.Subject(RuntimeMsg),
  timeout: Int,
) -> List(message.Message)

Get the agent’s current message history.

run

</> 
pub fn run(
  subject: process.Subject(RuntimeMsg),
  prompt: String,
  timeout: Int,
) -> Result(message.Message, error.AiError)

Send a prompt to the runtime and wait for a response.

run_continue

</> 
pub fn run_continue(
  subject: process.Subject(RuntimeMsg),
  timeout: Int,
) -> Result(message.Message, error.AiError)

Resume the agent loop from its current history.

Looks at the last message in history to determine the entry point:

  • User/Tool message → call the provider
  • Assistant with stop_reason=ToolUse → execute pending tool calls
  • Assistant with stop_reason=Stop → return immediately
  • Assistant with stop_reason=Length/Error → re-call provider

start

</> 
pub fn start(
  config: RuntimeConfig,
) -> Result(process.Subject(RuntimeMsg), actor.StartError)

Start the runtime actor with the given configuration.

start_with_state

</> 
pub fn start_with_state(
  config: RuntimeConfig,
  initial_state: RuntimeState,
) -> Result(process.Subject(RuntimeMsg), actor.StartError)

Start the runtime actor with a pre-built state. Used by pig.gleam when session replay needs to happen before start.

stop

</> 
pub fn stop(subject: process.Subject(RuntimeMsg)) -> Nil

Send a stop message to the runtime actor.

supervised

</> 
pub fn supervised(
  agent_config: state.AgentConfig,
  dispatcher_name: process.Name(dispatcher.DispatcherMessage),
  name: process.Name(RuntimeMsg),
) -> supervision.ChildSpecification(Nil)

Create a ChildSpecification for use with static_supervisor.

Starts a named actor so the Subject can be recovered after supervisor start via process.named_subject(name).

try_run

</> 
pub fn try_run(
  subject: process.Subject(RuntimeMsg),
  prompt: String,
  timeout: Int,
) -> Result(Result(message.Message, error.AiError), Nil)

Send a prompt to the runtime and wait for a response. Returns Error(Nil) if the call times out or the runtime crashes.

✨ Search Document