or

README

Choose the path from intent to action.

English | 简体中文

About

or is a modular Go toolkit for building applications with language models and higher-level agents. A provider-neutral LLM package keeps conversations, tools, reasoning, and streaming events stable while models and wire protocols change underneath, and an agent package builds the tool-call loop, state, and streaming events on top. The repository also includes Or, a coding agent built with these packages.

Why or

• Use one conversation model across OpenAI-compatible and Anthropic-compatible providers.
• Stream text, reasoning, tool calls, usage, and errors through typed events.
• Define tools from Go structs and validate model-generated arguments.
• Preserve provider metadata needed for multi-turn reasoning and tool use.
• Switch models between requests without rebuilding conversation history.
• Add custom model protocols without expanding the shared request API.
• Run autonomous multi-step tool loops with streaming events, mid-run steering, and per-step model switching.
• Layer transcript persistence, context compaction, per-step system prompts, and skills on top with the harness.

Packages

Package	Status	Description
or/llm	Available	Unified model access, streaming, tools, reasoning, images, and conversation history
or/agent	Available	Stateful agent loop with tools, streaming events, steering, follow-ups, and abort
or/harness	Available	Orchestration over the agent: transcript persistence, context compaction, per-step system prompt, and skills
Or	Product	Coding agent service, React client, and Electron desktop application

Future packages can build higher-level orchestration on the same foundations without turning the root package into a single large API.

Catalog

The project maintains a curated catalog of Agent Skills, recommended MCP servers, and useful CLI tools. These are source and recommendation collections rather than runtime configuration; review each entry and follow its collection-specific setup before use.

Requirements

• Go 1.25 or later
• An API key for the selected hosted provider, or a compatible local endpoint

Install

Install the LLM package:

go get github.com/ktsoator/or/llm@latest

Set the API key expected by the selected provider. For example:

export DEEPSEEK_API_KEY=your-deepseek-api-key

See Providers and models for supported provider IDs, environment variables, catalog discovery, and custom endpoints.

Quick start

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/ktsoator/or/llm"
	_ "github.com/ktsoator/or/llm/openai" // registers the OpenAI-compatible protocol (DeepSeek, Groq, xAI, ...)
)

func main() {
	model := llm.GetModel("deepseek", "deepseek-v4-flash")
	response, err := llm.Complete(
		context.Background(),
		model,
		llm.Prompt("Explain Go channels briefly."),
		llm.StreamOptions{},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(response.Text())
}

Each protocol lives in a provider package that registers itself on import. Pull in the protocols you use — and only their vendor SDKs — by importing the matching provider package for its side effects (llm/openai, llm/anthropic), or import llm/all for every built-in protocol at once.

Use llm.Stream instead of llm.Complete to consume deltas while the model is generating:

events, err := llm.Stream(ctx, model, input, llm.StreamOptions{})
if err != nil {
	log.Fatal(err)
}
for event := range events {
	switch event.Type {
	case llm.EventTextDelta:
		fmt.Print(event.Delta)
	case llm.EventError:
		log.Fatal(event.Err)
	}
}

Documentation

Guides for the SDK packages live at ktsoator.github.io/or.

API reference: or/llm · or/agent · or/harness

Releases

The Go SDK and Or share a version. Pushing a vX.Y.Z tag creates the GitHub Release and attaches the macOS builds. See RELEASING.md.

Supported protocols

The built-in adapters implement:

• OpenAI Responses
• OpenAI-compatible Chat Completions
• Anthropic-compatible Messages

The model catalog includes explicit compatibility metadata for DeepSeek, MiniMax, Xiaomi MiMo, Z.AI, Moonshot AI, Kimi, Anthropic, OpenCode, and other compatible providers. Catalog presence is not a guarantee that every model has been live-tested; all built-in wire adapters are covered by automated mock-server tests.

Project status

v0.6.0 is the first public release of Or. It also moves or/harness, the stateful orchestration layer for or/agent, to a top-level package. The project remains pre-1.0, so APIs may continue to evolve between minor versions. Breaking changes will be called out in release notes.

Acknowledgements

This project is inspired by and partially adapted from earendil-works/pi, created by Mario Zechner.

License

Released under the MIT License.