pig_protocol

Shared, provider-neutral message types and OpenAI-compatible codecs for the pig agent ecosystem.

pig_protocol provides the protocol boundary used by pig and pig_proxy:

normalized messages, tool calls, inference metadata, stop reasons, and errors
request builders and response parsers for Chat Completions and Responses APIs
authentication helpers for standard API keys and Codex OAuth tokens
incremental Server-Sent Events parsing
transport types for integrating custom HTTP clients

Most codecs and parsers are pure. Network access is isolated behind transport functions, with a gleam_httpc implementation available when needed.

Installation

Add the package to a Gleam project:

gleam add pig_protocol

Usage

Build a Chat Completions request and parse its response:

import gleam/option.{Some}
import pig_protocol/codec/chat
import pig_protocol/message
import pig_protocol/thinking

pub fn request_body() -> String {
  chat.build_request_body_with_thinking(
    messages: [
      message.System("You are a helpful assistant."),
      message.User("What is 7 plus 3?"),
    ],
    tools: [],
    model: "gpt-5",
    thinking_level: Some(thinking.Medium),
  )
}

pub fn parse_response(body: String) {
  chat.parse_response(body)
}

The Responses API has the same pure request/response shape through pig_protocol/codec/responses.

pig providers receive one InferenceRequest containing messages, tools, and agent-owned settings. An explicit Off thinking level disables reasoning; an unset level leaves the provider default in control. Settings survive durable restoration and can be changed mid-session. They are not per-run overrides, and providers do not clamp levels or advertise model capabilities. Inference start and stop (and setting changes) are exposed through the agent event/session stream.

For direct HTTP calls, construct a pig_protocol/transport.HttpRequest and use pig_protocol/transport/httpc.transport, or provide your own function matching pig_protocol/transport.Transport.

Modules

Module	Purpose
`pig_protocol/message`	Unified conversation messages and tool calls
`pig_protocol/inference`	Provider response values and metadata
`pig_protocol/error`	Normalized provider errors
`pig_protocol/stop_reason`	Provider-neutral completion reasons
`pig_protocol/thinking`	Provider-neutral thinking levels
`pig_protocol/tool_definition`	JSON Schema-backed tool definitions
`pig_protocol/codec/chat`	Chat Completions request and response codecs
`pig_protocol/codec/responses`	Responses API and Codex codecs
`pig_protocol/sse`	Incremental SSE frame and event parsing
`pig_protocol/auth`	Standard API and Codex OAuth endpoint helpers
`pig_protocol/transport`	HTTP transport interfaces
`pig_protocol/transport/httpc`	`gleam_httpc` transport implementation

Development

From the repository root:

cd packages/pig_protocol
gleam test
gleam build --warnings-as-errors

Live integration tests are disabled by default. Run them through the repository's integration task with the required provider credentials configured:

mise run test-integration-protocol

License

Apache-2.0