assist

Documentation

Overview

Package assist is the model-agnostic harness: a natural-language task is routed by ANY chat model (local Ollama, Anthropic, OpenAI) to prism's deterministic code-graph operations. The discipline that steering files can only request is enforced here structurally: the model never receives or re-emits operation payloads (the harness renders them), and no text-search escape hatch exists inside the loop — the two measured failure modes of steered agents (relay loss, re-derivation) are impossible by construction.

Index

• func DetectDefaultModel() (string, error)
• func Run(task string, provider Provider, invoke Invoker, opts Options) (string, error)
• type Invoker
• type Msg
• type Options
• type Provider
  • func NewProvider(spec string) (Provider, error)
• type ToolCall
• type ToolDef

Functions

func DetectDefaultModel

func DetectDefaultModel() (string, error)

DetectDefaultModel picks a provider when --model is not given: a blessed local Ollama model if one is installed (free, private), else Anthropic's small tier, else OpenAI. The blessed list is the measured set — models verified to sit on the engine ceiling at task altitude.

func Run

func Run(task string, provider Provider, invoke Invoker, opts Options) (string, error)

Run executes one assist session. Returns the model's final summary.

Types

type Invoker

type Invoker func(tool string, args map[string]any) (any, error)

Invoker runs one prism operation and returns its result map — satisfied by (*mcp.Handler).Invoke, injected to avoid an import cycle and to make the loop testable with a fake.

type Msg

type Msg struct {
	Role    string     // "system" | "user" | "assistant" | "tool"
	Content string     // text content (or tool result payload for Role=="tool")
	Calls   []ToolCall // tool calls the assistant issued (Role=="assistant")
	CallID  string     // for Role=="tool": which call this result answers
	Name    string     // for Role=="tool": the tool name
}

Msg is one chat message in the provider-neutral shape.

type Options

type Options struct {
	Model          string // provider spec, e.g. "ollama:qwen2.5-coder:14b", "claude:claude-haiku-4-5-20251001"
	Apply          bool   // apply rename_plan confirmed edits to the working tree
	ApplyAmbiguous bool   // ALSO apply Ambiguous edits (verify is the safety net)
	Verify         string // shell command to run after apply (build/tests); "" = skip
	Root           string // project root (edits are applied relative to it)
	MaxTurns       int
	Out            *os.File // rendering destination (default os.Stdout)
}

Options configures one assist session.

type Provider

type Provider interface {
	// Chat sends the conversation and returns the assistant's reply.
	// forceTools requests that the model MUST call a tool this turn (the
	// invocation wall for small local models); providers that cannot express
	// it may ignore it.
	Chat(msgs []Msg, tools []ToolDef, forceTools bool) (Msg, error)
	Name() string
}

Provider abstracts one chat turn against any model backend.

func NewProvider

func NewProvider(spec string) (Provider, error)

NewProvider resolves a model spec to a provider:

ollama:<model>     local Ollama (default http://localhost:11434)
claude:<model>     Anthropic API (ANTHROPIC_API_KEY)
openai:<model>     OpenAI API (OPENAI_API_KEY)

A bare spec with no prefix is treated as an Ollama model name.

type ToolCall

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

ToolCall is a provider-neutral tool invocation.

type ToolDef

type ToolDef struct {
	Name        string
	Description string
	Parameters  map[string]any
}

ToolDef is a provider-neutral tool definition (JSON-schema parameters).