README
¶
ore
ore are the inputs to an agentic system.
ore is a Go-native framework for building agentic applications. It provides a minimal core inference primitive, provider-agnostic LLM adapters, composable I/O conduits, and clean extension points implemented as Go interfaces.
This is a learning project and a conceptual exploration. It is inspired by pi.dev's philosophy of minimal cores and aggressive extensibility, but reimagined in Go with different architectural priorities: first-class non-interactive conduits, build-time composition via Go interfaces, and a narrower core that delegates all workflow opinions to extensions and applications.
Design Principles
- Simplicity — The core does as little as possible. Every feature that can live outside the core does.
- Composability — Components connect through narrow interfaces. A Step, an OpenAI adapter, a tool handler, and a TUI conduit compose the same way as a Step, an Anthropic adapter, an image handler, and a webhook conduit.
- I/O Agnosticism — The core does not know whether it is running in an interactive terminal or responding to a 3 AM PagerDuty alert.
- Build-time Extension — Extensions are Go packages composed at build time, not runtime plugins. This keeps deployment simple and interfaces type-safe.
- Defer Specifics — Patterns like memory, reflection, planning, reasoning strategies, multi-agent orchestration, and tool calling emerge as artifact handlers and orchestrators, not as core implementations.
- Treat Tool Calling as an Extension — Tool calling is one artifact handler among many. This ensures the architecture can absorb future LLM capabilities without core changes.
Relationship to pi.dev
[ore] is conceptually descended from pi.dev, a mature TypeScript terminal coding harness. Where ore diverges: Language (Go instead of TypeScript), I/O Conduits (all ingress/egress adapters are first-class, not just TUI), Extension Model (Go interfaces and build-time composition instead of runtime module loading), and Scope (a framework for building agents, not a specific agent implementation).
Packages
| Package | Description | Docs |
|---|---|---|
artifact |
Extensible Artifact interface and common types (Text, ToolCall, Image, Reasoning, deltas) | pkg.go.dev |
state |
Conversation history model: State interface with Turns() and Append() | pkg.go.dev |
provider |
Provider interface and InvokeOption for LLM adapter contracts | pkg.go.dev |
loop |
Single-turn execution primitive: Step with Turn(), handlers, and inference assembly transforms | pkg.go.dev |
tool |
Tool interface, registry, and sandbox contracts for LLM tool calling | pkg.go.dev |
cognitive |
Cognitive patterns (ReAct) for multi-turn looping | pkg.go.dev |
session |
Stream and Manager primitives for per-session inference orchestration | pkg.go.dev |
agent |
Multi-conduit orchestration container and application scaffold | pkg.go.dev |
Extensions (provider adapters, conduits, and tool implementations) live under x/.
Getting Started
The fastest way to understand ore is to run one of the hand-written examples. Each is a complete, compilable Go program that wires the framework together without any YAML or code generation layer.
examples/http-chat/— Stateful HTTP chat server with NDJSON streaming, SSE events, and an optional web UI.examples/tui-chat/— Interactive terminal chat with Markdown rendering and persistent thread store.examples/calculator/— Single-turn CLI demo with tool calling (add, multiply) via the ReAct cognitive pattern.examples/filesystem/— File system tool demo with path resolution and working directory constraints.examples/single-turn-cli/— Minimal single-turn CLI example with direct provider invocation.
For a more fully fledged coding agent built on ore, see
andrewhowdencom/workshop.
Note: The TUI conduit's conversation view is cached locally. If your application replaces thread state via
stream.LoadTurns(e.g. after compaction), calltui.ReloadHistory(stream.Turns())to refresh the UI. Seex/conduit/tui/README.mdfor details.
All examples read ORE_API_KEY from the environment. Set ORE_MODEL to choose
a different model (default: gpt-4o). Set STORE_DIR for persistent JSON
thread storage.
See Development / Validation for how to validate the entire codebase before submitting changes.
Development / Validation
The repository uses Taskfile for common developer commands. The root task
validate runs the full lint–test–build pipeline for all 16 workspace
modules (root, examples/, and every x/* package):
task validate
Validate a single module only (e.g. the TUI conduit):
task x-conduit-tui:validate
Running task validate from the repo root therefore guarantees that the
entire codebase stays healthy.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package agent provides multi-conduit orchestration for ore agent applications.
|
Package agent provides multi-conduit orchestration for ore agent applications. |
|
Package artifact defines the extensible Artifact interface and common concrete types used throughout ore.
|
Package artifact defines the extensible Artifact interface and common concrete types used throughout ore. |
|
cmd
|
|
|
release
command
|
|
|
Package cognitive defines cognitive patterns that drive multi-turn inference loops.
|
Package cognitive defines cognitive patterns that drive multi-turn inference loops. |
|
examples
module
|
|
|
Package loop implements the single-turn execution primitive for ore.
|
Package loop implements the single-turn execution primitive for ore. |
|
Package provider defines the Provider interface, the contract between the core loop and concrete LLM provider adapters.
|
Package provider defines the Provider interface, the contract between the core loop and concrete LLM provider adapters. |
|
Package session provides the Stream and Manager primitives that orchestrate per-session inference and session lifecycle in the ore framework.
|
Package session provides the Stream and Manager primitives that orchestrate per-session inference and session lifecycle in the ore framework. |
|
Package state defines the State interface and supporting types for ore's conversation history model.
|
Package state defines the State interface and supporting types for ore's conversation history model. |
|
Package tool defines the core tool execution framework for ore.
|
Package tool defines the core tool execution framework for ore. |
|
x
|
|
|
export
Package export renders session.Thread conversation histories into human-reviewable formats: plain text, self-contained HTML, and JSON.
|
Package export renders session.Thread conversation histories into human-reviewable formats: plain text, self-contained HTML, and JSON. |
|
guardrails
Package guardrails provides a loop.Transform that injects safety and formatting constraints into the inference context without mutating the persistent conversation buffer.
|
Package guardrails provides a loop.Transform that injects safety and formatting constraints into the inference context without mutating the persistent conversation buffer. |
|
slash
Package slash provides a slash command registry for intercepting and handling user messages before they enter the LLM inference pipeline.
|
Package slash provides a slash command registry for intercepting and handling user messages before they enter the LLM inference pipeline. |
|
systemprompt
Package systemprompt provides a loop.Transform that injects a system prompt into the inference context without mutating the persistent conversation buffer.
|
Package systemprompt provides a loop.Transform that injects a system prompt into the inference context without mutating the persistent conversation buffer. |
|
systemprompt/source
Package source provides factory functions that return func() string closures compatible with systemprompt.WithContentFunc, bridging content acquisition (files, directory traversal) and the composable system prompt transform.
|
Package source provides factory functions that return func() string closures compatible with systemprompt.WithContentFunc, bridging content acquisition (files, directory traversal) and the composable system prompt transform. |
|
analytics
module
|
|
|
compaction
module
|
|
|
conduit
module
|
|
|
conduit/http
module
|
|
|
conduit/stdio
module
|
|
|
conduit/tui
module
|
|
|
llmbytes
module
|
|
|
provider/anthropic
module
|
|
|
provider/openai
module
|
|
|
provider/retry
module
|
|
|
subagent
module
|
|
|
telemetry
module
|
|
|
tool
module
|
|
|
tool/bash
module
|
|
|
tool/calculator
module
|
|
|
tool/filesystem
module
|
|
|
tool/sandbox/unsafe
module
|
|
|
tool/set_model
module
|
|
|
tool/set_title
module
|
|
|
tool/settitle
module
|
|
|
tool/skills
module
|
|
|
tool/truncate
module
|
|
|
usage
module
|
|
|
verifier
module
|
|
|
wire/anthropic
module
|
|
|
wire/openai
module
|