simon

README

simon-go

Go port of "Simon SDK," a lightweight AI agent framework originally written in Python. There is no separate migration-plan document — design rationale for hard-to-port Python idioms (reflection-based tool schemas, contextvars, dual sync/async APIs, dual-inheritance exceptions, pickle/numpy knowledge index) lives inline in package doc comments, and is indexed in docs/.

Quick start

cp .env.example .env   # add an API key, or point OLLAMA_HOST at a local server
go build ./...
go run ./cmd/simon chat

See docs/configuration.md for every environment variable, and docs/examples.md for ~15 runnable programs demonstrating individual features.

SDK

Simon is a reusable Go module (github.com/LuisKeys/simon) as well as a runnable CLI: a host application embeds the public simon/model/tool/ memory/knowledge/pkg/simonerr packages without ever importing anything under internal/.

Installation

go get github.com/LuisKeys/simon@latest

Minimal example

package main

import (
	"context"
	"fmt"
	"log"

	simon "github.com/LuisKeys/simon"
	"github.com/LuisKeys/simon/model"
)

func main() {
	runtime, err := simon.New(
		simon.WithModel(model.EchoModel{}),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer runtime.Close()

	session, err := runtime.NewSession(
		"example",
		simon.WithSystemPrompt("You are a local personal assistant."),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer session.Close()

	response, err := session.Run(
		context.Background(),
		"Hello Simon",
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(response.Text)
}

Public packages

Package	Purpose
simon	Runtime, sessions, events, approvals and configuration
model	Model-provider contract
tool	Typed and runtime-defined tools
memory	Conversation persistence contracts and implementations
knowledge	Retrieval and embedding contracts
simonerr	Public error hierarchy

See docs/public-sdk.md for the full facade reference, and examples/public_* for ten runnable programs covering tools, tool approval, memory, knowledge, events, streaming, structured output, custom models, and parallel sessions.

Development from another local repository

To iterate on Simon and a consumer repository together, use a go.work workspace so changes are picked up without publishing a release:

mkdir simon-workspace
cd simon-workspace

git clone git@github.com:LuisKeys/simon.git
git clone <consumer-repository>

go work init ./simon ./<consumer-directory>

Alternatively, a consumer-only replace directive works without a workspace:

replace github.com/LuisKeys/simon => ../simon

A local replace directive like this must stay in the consumer's go.mod only — it must never be published in Simon's own root go.mod.

Documentation

• docs/architecture.md — layer map and cross-cutting design decisions (start here)
• docs/agent-core.md — the ReAct loop, model providers, tools, memory, multi-agent patterns
• docs/knowledge-base.md — document ingestion, embeddings, the SIDX binary index format
• docs/activity-pipeline.md — sensors, events, privacy, semantic classification, habit mining
• docs/surface.md — the CLI, TUI, planner, and MCP client
• docs/public-sdk.md — the embeddable simon/model/tool/knowledge/memory facade for host applications
• docs/examples.md — what each program under examples/ demonstrates and how to run it
• docs/configuration.md — every environment variable, with defaults

Commands

• Build: go build ./...
• Test all: go test ./...
• Single test: go test -run TestName ./internal/pkg/...
• Race-sensitive pipeline test: go test -race ./internal/pipeline/...
• Vet: go vet ./... (no golangci-lint or other configured linter; no Makefile, no CI workflow)
• Run the CLI: go run ./cmd/simon chat|ask|index|plan|knowledge

Status

Phase 0 (foundation) in progress: pkg/simonerr, internal/config, internal/reliability, internal/router, internal/agent/response.

Phase 1 (core execution) complete: internal/model (+ openai/anthropic/ollama providers), internal/tool (registration + ToolRunner), internal/memory, internal/agent (ReAct loop + structured output), internal/multi (Group/Pool/Triage).

Phase 2 (knowledge) complete: internal/knowledge/embed (OpenAI/Ollama/Voyage embedding providers), internal/knowledge/index (from-scratch SIDX binary format replacing Python's pickle+numpy), internal/knowledge/extract (pdf/docx/xlsx/pptx text extraction), internal/knowledge (chunking + KnowledgeBase), wired into internal/agent as an optional knowledge-context system message via the KnowledgeSearcher interface.

Phase 3 (surface) complete: internal/mcp (official MCP Go SDK, stdio client), internal/planner (goal decomposition + sequential execution), internal/tui (terminal chat: Markdown→ANSI rendering + /quit /clear — line-based input via bufio.Scanner rather than raw-mode tab-completion, a deliberate simplification), cmd/simon (chat/ask/index/plan CLI via the stdlib flag package). The binary builds and runs end-to-end against a real local Ollama server.

Phase 4 (activity pipeline) complete: internal/events (EventBus pub/sub + SQLite-backed Store + EventCompressor), internal/privacy (deny-by-default PermissionManager, audited via the event bus), internal/activity (ActivityStore query layer, ContextEngine, activity transition graph), internal/habits (n-gram habit mining over session history), internal/semantic (LLM-based activity classification, local Ollama only by design), internal/sensors (Sensor/Manager lifecycle — macOS sensors themselves are out of scope for this port; see package doc). internal/pipeline has an end-to-end test wiring a synthetic sensor through the full chain (sensor -> bus -> semantic -> session compression -> activity store -> graph -> habit discovery), verified clean under -race.

Knowledge Router complete: internal/knowledge/router — a second, embeddings-free agent.KnowledgeSearcher backend that routes queries through curated category/document/section YAML metadata instead of a vector index, reusing internal/knowledge/extract for source reads. Selected via KNOWLEDGE_MODE=router; exposed through simon knowledge build|validate|tree|search. The default KNOWLEDGE_MODE remains vector, so simon index and the existing internal/knowledge KnowledgeBase are unchanged. See docs/knowledge-base.md.

Public SDK facade complete: simon (Runtime/Session), model, tool, knowledge, memory — an embeddable public surface wrapping internal/agent for host applications, so a consumer never has to import anything under internal/. 10 runnable examples under examples/public_* plus matching .vscode/launch.json entries demonstrate tools, memory, knowledge, streaming, cancellation, tool approval, structured output, parallel sessions, and desktop event forwarding. See docs/public-sdk.md.

Documentation

Overview

Package simon is the public facade for embedding Simon in another Go application: a Runtime holds shared resources (settings, provider selection, tool registry, memory/knowledge attachments, event dispatch), and each Session is one independent conversation or task run against it.

Public types here (Response, Event, Usage, ...) intentionally do not alias internal/agent/response's types even where the shapes currently match: internal packages are free to change shape without that silently changing this package's contract. See internal/agent's package doc for why the agent loop itself doesn't offer an async variant — Runtime and Session follow the same rule (callers wanting concurrency use goroutines, not a parallel API).

Index

• func RunStructured[T any](ctx context.Context, s *Session, prompt string) (T, error)
• type AllowAll
  • func (AllowAll) Approve(context.Context, ApprovalRequest) (bool, error)
• type ApprovalPolicy
• type ApprovalRequest
• type Event
• type EventHandler
• type EventType
• type MemoryFactory
• type ModelRouter
• type Option
  • func WithApprovalPolicy(policy ApprovalPolicy) Option
  • func WithEnvironment() Option
  • func WithEventHandler(handler EventHandler) Option
  • func WithKnowledgeBase(kb knowledge.Searcher) Option
  • func WithLogger(logger *slog.Logger) Option
  • func WithMaxConcurrentRuns(limit int) Option
  • func WithMemoryFactory(factory MemoryFactory) Option
  • func WithModel(m model.Model) Option
  • func WithRouter(router ModelRouter) Option
  • func WithSettings(settings Settings) Option
  • func WithToolRegistry(registry *tool.Registry) Option
• type Response
• type Runtime
  • func New(opts ...Option) (*Runtime, error)
  • func (rt *Runtime) Close() error
  • func (rt *Runtime) NewSession(id string, opts ...SessionOption) (*Session, error)
  • func (rt *Runtime) RegisterTool(t tool.Tool) error
  • func (rt *Runtime) RegisterTools(tools ...tool.Tool) error
• type Session
  • func (s *Session) Cancel()
  • func (s *Session) Clear(ctx context.Context) error
  • func (s *Session) Close() error
  • func (s *Session) ID() string
  • func (s *Session) Run(ctx context.Context, prompt string) (Response, error)
  • func (s *Session) Stream(ctx context.Context, prompt string) (<-chan Event, error)
• type SessionOption
  • func WithMaxSteps(n int) SessionOption
  • func WithSessionKnowledge(kb knowledge.Searcher) SessionOption
  • func WithSystemPrompt(prompt string) SessionOption
• type Settings
• type StopReason
• type ToolCall
• type Usage

Functions

func RunStructured

func RunStructured[T any](ctx context.Context, s *Session, prompt string) (T, error)

RunStructured runs prompt like Session.Run, but parses the model's reply into T (via a JSON-schema instruction and retries on invalid JSON, matching internal/agent.RunStructured's behavior). On exhaustion, the returned error is a *simonerr.StructuredOutputError (recoverable via errors.As), carrying the raw text and attempt count.

Types

type AllowAll

type AllowAll struct{}

AllowAll is the default ApprovalPolicy: every tool call is permitted without prompting.

func (AllowAll) Approve

func (AllowAll) Approve(context.Context, ApprovalRequest) (bool, error)

Approve implements ApprovalPolicy.

type ApprovalPolicy

type ApprovalPolicy interface {
	// Approve returns true to allow the call, false (with a nil error) to
	// deny it silently, or a non-nil error to deny it and surface why.
	Approve(ctx context.Context, request ApprovalRequest) (bool, error)
}

ApprovalPolicy gates tool execution, giving desktop/interactive applications a hook to require human confirmation before a sensitive tool call runs.

type ApprovalRequest

type ApprovalRequest struct {
	SessionID string
	ToolName  string
	Arguments json.RawMessage
}

ApprovalRequest describes a tool call awaiting an approval decision.

type Event

type Event struct {
	Type      EventType
	RuntimeID string
	SessionID string
	RunID     string
	Timestamp time.Time
	Data      any
}

Event is a single point-in-time occurrence during a Session run.

type EventHandler

type EventHandler func(context.Context, Event)

EventHandler observes every Event a Runtime's sessions emit. A handler that panics or is slow must never destabilize a run: Runtime always invokes handlers through a recover-guarded call.

type EventType

type EventType string

EventType identifies a point in a run's lifecycle.

const (
	EventRunStarted     EventType = "run.started"
	EventModelSelected  EventType = "model.selected"
	EventResponseDelta  EventType = "response.delta"
	EventToolRequested  EventType = "tool.requested"
	EventToolStarted    EventType = "tool.started"
	EventToolCompleted  EventType = "tool.completed"
	EventToolFailed     EventType = "tool.failed"
	EventRetryAttempted EventType = "retry.attempted"
	EventRunCompleted   EventType = "run.completed"
	EventRunFailed      EventType = "run.failed"
	EventRunCancelled   EventType = "run.cancelled"
)

type MemoryFactory

type MemoryFactory = memory.Factory

MemoryFactory builds a Memory for a given session, letting each Session obtain independent storage.

type ModelRouter

type ModelRouter interface {
	Resolve(ctx context.Context, modelLabel, task string) (provider, modelName string)
}

ModelRouter selects a provider/model pair for a run. Implement this to customize provider selection instead of using Simon's built-in heuristics (env-configured providers + task-complexity keywords).

Routing decisions from a custom ModelRouter are resolved once per Session (at NewSession), not per prompt — Simon's own default router already resolves per-prompt when no custom Model/ModelRouter is set, so this only affects the advanced case of a caller-supplied router.

type Option

type Option func(*Runtime) error

Option configures a Runtime at construction time.

func WithApprovalPolicy

func WithApprovalPolicy(policy ApprovalPolicy) Option

WithApprovalPolicy attaches a policy every registered tool call is checked against before it executes. The default policy (AllowAll) permits every call.

func WithEnvironment

func WithEnvironment() Option

WithEnvironment loads settings from the process environment (and a ".env" file in the working directory, if present) — the same source cmd/simon uses. This is the default even with no options at all; passing it explicitly documents intent and lets it be combined with WithSettings (which takes precedence field-by-field).

func WithEventHandler

func WithEventHandler(handler EventHandler) Option

WithEventHandler attaches a handler invoked for every Event emitted by any Session this Runtime creates. Handler panics/errors are recovered and never affect the run that triggered them.

func WithKnowledgeBase

func WithKnowledgeBase(kb knowledge.Searcher) Option

WithKnowledgeBase attaches a knowledge base every Session searches by default (a Session can override it via WithSessionKnowledge).

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger attaches a structured logger. Without one, Runtime uses a silent (slog.DiscardHandler) logger — errors are still returned normally, nothing is printed.

func WithMaxConcurrentRuns

func WithMaxConcurrentRuns(limit int) Option

WithMaxConcurrentRuns caps how many Session runs may execute concurrently across the whole Runtime. Zero (the default) means unlimited.

func WithMemoryFactory

func WithMemoryFactory(factory MemoryFactory) Option

WithMemoryFactory attaches a MemoryFactory so every Session gets its own Memory instance at construction time.

func WithModel

func WithModel(m model.Model) Option

WithModel pins every session created by this Runtime to a single custom Model implementation, bypassing router-based provider selection entirely.

func WithRouter

func WithRouter(router ModelRouter) Option

WithRouter replaces Simon's default provider-selection heuristics with a custom ModelRouter.

func WithSettings

func WithSettings(settings Settings) Option

WithSettings applies explicit settings on top of whatever base settings are already loaded (environment by default). Fields left at their zero value keep the base's value, so WithSettings can be used to override just one or two fields.

func WithToolRegistry

func WithToolRegistry(registry *tool.Registry) Option

WithToolRegistry replaces the Runtime's tool registry outright, instead of registering tools one at a time via RegisterTool/RegisterTools.

type Response

type Response struct {
	Text       string
	Usage      Usage
	ToolCalls  []ToolCall
	Steps      int
	Model      string
	Provider   string
	StopReason StopReason
	Metadata   map[string]any
}

Response is the result of Session.Run/RunStructured. It is a distinct type from internal/agent/response.AgentResponse (even though the shapes currently overlap) so internal refactors can't silently change the public contract.

type Runtime

type Runtime struct {
	// contains filtered or unexported fields
}

Runtime holds resources shared across every Session it creates: settings, provider/router selection, the tool registry, the approval policy, event dispatch, and lifecycle. Safe for concurrent use.

func New

func New(opts ...Option) (*Runtime, error)

New builds a Runtime. With no options, settings are loaded from the environment (equivalent to WithEnvironment()).

func (*Runtime) Close

func (rt *Runtime) Close() error

Close cancels every active run and closes every Session this Runtime created. Idempotent: calling it more than once is a no-op after the first call.

func (*Runtime) NewSession

func (rt *Runtime) NewSession(id string, opts ...SessionOption) (*Session, error)

NewSession creates an independent Session bound to this Runtime's shared resources. Multiple Sessions may run concurrently.

func (*Runtime) RegisterTool

func (rt *Runtime) RegisterTool(t tool.Tool) error

RegisterTool adds a single tool to the Runtime's shared registry. Tools registered here are available to every Session created afterward; Sessions already created keep the tool set they were built with.

func (*Runtime) RegisterTools

func (rt *Runtime) RegisterTools(tools ...tool.Tool) error

RegisterTools registers multiple tools; see RegisterTool.

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session represents one independent conversation or task run against a Runtime's shared resources: its own history, its own active-run state, its own event stream. A Runtime may host many concurrent Sessions; within a single Session, only one Run/Stream/RunStructured may be active at a time — a second call while one is in flight returns simonerr.ErrSessionBusy.

func (*Session) Cancel

func (s *Session) Cancel()

Cancel cancels this session's active run, if any. It is a no-op if no run is active.

func (*Session) Clear

func (s *Session) Clear(ctx context.Context) error

Clear erases this session's memory, if it has any.

func (*Session) Close

func (s *Session) Close() error

Close cancels any active run, closes this session's exclusive memory (if any), and marks it closed. Idempotent.

func (*Session) ID

func (s *Session) ID() string

ID returns the session identifier passed to Runtime.NewSession.

func (*Session) Run

func (s *Session) Run(ctx context.Context, prompt string) (Response, error)

Run executes prompt through the ReAct loop and returns once it completes, fails, or is cancelled.

func (*Session) Stream

func (s *Session) Stream(ctx context.Context, prompt string) (<-chan Event, error)

Stream executes prompt like Run, but returns immediately with a read-only channel of Events instead of waiting for the final Response. The channel closes once the run completes, fails, or is cancelled; the final event is always delivered even if earlier events were dropped for buffer space.

type SessionOption

type SessionOption func(*sessionConfig)

SessionOption configures a Session at construction time.

func WithMaxSteps

func WithMaxSteps(n int) SessionOption

WithMaxSteps overrides the maximum number of ReAct tool-call steps for this session.

func WithSessionKnowledge

func WithSessionKnowledge(kb knowledge.Searcher) SessionOption

WithSessionKnowledge overrides the Runtime's default knowledge base for this session only.

func WithSystemPrompt

func WithSystemPrompt(prompt string) SessionOption

WithSystemPrompt sets the session's system prompt.

type Settings

type Settings struct {
	DefaultModel string

	OpenAIAPIKey    string
	OpenAIModel     string
	AnthropicAPIKey string
	AnthropicModel  string
	OllamaHost      string
	OllamaModel     string

	KnowledgeStorePath string
	EmbeddingProvider  string
	EmbeddingModel     string

	MaxRetries        int
	RequestTimeout    float64
	RetryBaseDelay    float64
	StructuredRetries int
}

Settings is the subset of Simon's environment-backed configuration relevant to an embedding application. It is a hand-maintained parallel of internal/config.Settings (not a type alias): CLI-only fields (activity store path, sensor poll interval, directory-enable flags) stay internal, and any internal renumbering/renaming can't silently change this public contract. Zero-value fields fall back to config.Load()'s defaults.

type StopReason

type StopReason string

StopReason describes why a run stopped producing more tool calls.

type ToolCall

type ToolCall struct {
	ID        string
	Name      string
	Arguments map[string]any
}

ToolCall is a single tool invocation the model requested during a run.

type Usage

type Usage struct {
	InputTokens  int
	OutputTokens int
	TotalTokens  int
}

Usage tracks token consumption for a Run.