engine

Documentation

Overview

Package engine is the high-level entrypoint for embedding the rakit agent: it wires the LLM client, tool registry, skills, plugins, MCP, and the agent manager behind one constructor. Hosts that need finer control can construct the underlying packages directly — the engine is a convenience, not a gate.

Index

• Variables
• type Engine
  • func New(opts Options) (*Engine, error)
  • func (e *Engine) Bus() *events.Bus
  • func (e *Engine) Compact(sessionID string) error
  • func (e *Engine) HasProvider() bool
  • func (e *Engine) Home() string
  • func (e *Engine) LLM() *llm.LLMClient
  • func (e *Engine) MCP() *mcp.Manager
  • func (e *Engine) MCPStatus() []mcp.ServerConfig
  • func (e *Engine) Manager() *agent.Manager
  • func (e *Engine) Memory() *memory.Manager
  • func (e *Engine) ModelInfo() (string, string)
  • func (e *Engine) Plugins() *plugins.Manager
  • func (e *Engine) Profiles() []llm.ProviderProfile
  • func (e *Engine) ReasoningEffort(effort string)
  • func (e *Engine) RegisterMCPTools()
  • func (e *Engine) Run(ctx context.Context, prompt string) (string, error)
  • func (e *Engine) RunIn(ctx context.Context, sessionID, prompt string, mentionedPaths ...string) (string, error)
  • func (e *Engine) SetModel(fullID string) bool
  • func (e *Engine) SkillManager() *skills.Manager
  • func (e *Engine) Skills() []skills.Skill
  • func (e *Engine) Tools() *tools.Registry
  • func (e *Engine) UsageSummary() map[string]any
  • func (e *Engine) Workspace() string
• type Options

Variables

var ErrNoProvider = errors.New("no LLM provider configured: run `rakit import`, set an API key env var (e.g. OPENAI_API_KEY), or add a profile under the home dir")

ErrNoProvider is returned by Run when no provider profile or environment API key is available.

Types

type Engine

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

Engine is a wired, ready-to-use agent runtime.

func New

func New(opts Options) (*Engine, error)

New assembles the engine. It returns an error only when the workspace or home cannot be resolved; LLM configuration problems surface on first use.

func (*Engine) Bus

func (e *Engine) Bus() *events.Bus

Bus exposes the event bus; all agent activity streams through it.

func (*Engine) Compact

func (e *Engine) Compact(sessionID string) error

Compact summarizes a session's history in place to free context window.

func (*Engine) HasProvider

func (e *Engine) HasProvider() bool

HasProvider reports whether any LLM provider is usable: an active profile with a key (or a local base URL), or any enabled profile.

func (*Engine) Home

func (e *Engine) Home() string

Home is the resolved storage root.

func (*Engine) LLM

func (e *Engine) LLM() *llm.LLMClient

LLM returns the engine's LLM client (provider profiles, active model, chat APIs).

func (*Engine) MCP

func (e *Engine) MCP() *mcp.Manager

MCP returns the engine's MCP manager (server config, connect/disconnect, connected tools).

func (*Engine) MCPStatus

func (e *Engine) MCPStatus() []mcp.ServerConfig

MCPStatus lists configured MCP servers with their connection status.

func (*Engine) Manager

func (e *Engine) Manager() *agent.Manager

Manager exposes the agent manager for full control (sessions, approvals, subagents, schedules).

func (*Engine) Memory

func (e *Engine) Memory() *memory.Manager

Memory returns the manager's memory instance.

func (*Engine) ModelInfo

func (e *Engine) ModelInfo() (string, string)

ModelInfo returns the active provider id and model name.

func (*Engine) Plugins

func (e *Engine) Plugins() *plugins.Manager

Plugins returns the engine's plugin manager.

func (*Engine) Profiles

func (e *Engine) Profiles() []llm.ProviderProfile

Profiles lists the configured provider profiles.

func (*Engine) ReasoningEffort

func (e *Engine) ReasoningEffort(effort string)

ReasoningEffort sets the thinking-effort hint sent to providers that support it ("low", "medium", "high"; "" clears it).

func (*Engine) RegisterMCPTools

func (e *Engine) RegisterMCPTools()

RegisterMCPTools connects nothing but registers whatever tools the MCP manager reports as connected into the engine's tool registry.

func (*Engine) Run

func (e *Engine) Run(ctx context.Context, prompt string) (string, error)

Run executes one headless turn in a throwaway session and returns the assistant's final text. Mutating tool calls are auto-approved only when Options.Yolo was set; otherwise they are declined so the turn can end.

func (*Engine) RunIn

func (e *Engine) RunIn(ctx context.Context, sessionID, prompt string, mentionedPaths ...string) (string, error)

RunIn executes one turn inside an existing session (REPLs, resume flows) and returns the assistant's final text. Optional mentioned paths are @-mention files whose contents get inlined for the model.

func (*Engine) SetModel

func (e *Engine) SetModel(fullID string) bool

SetModel switches the active provider/model by full id ("provider/model"). Reports whether a matching profile was found.

func (*Engine) SkillManager

func (e *Engine) SkillManager() *skills.Manager

SkillManager returns the engine's skills manager (Skills lists the discovered skills).

func (*Engine) Skills

func (e *Engine) Skills() []skills.Skill

Skills lists installed skills.

func (*Engine) Tools

func (e *Engine) Tools() *tools.Registry

Tools returns the engine's tool registry; hosts register app-specific tools and MCP tools into it.

func (*Engine) UsageSummary

func (e *Engine) UsageSummary() map[string]any

UsageSummary aggregates token usage across sessions, providers, and models.

func (*Engine) Workspace

func (e *Engine) Workspace() string

Workspace is the resolved working folder.

type Options

type Options struct {
	// Home is the engine's storage root. Empty means $RAKIT_HOME, else
	// ~/.rakit. Provider profiles, MCP servers, plugins, sessions, and skills
	// all live under it.
	Home string

	// Workspace is the folder the agent operates on. Empty means the current
	// process working directory.
	Workspace string

	// Model selects the initial model as "provider/model" (for example
	// "openai/gpt-4o"). Empty uses the client's active profile.
	Model string

	// Yolo auto-approves every tool call. Only for trusted, sandboxed use.
	Yolo bool

	// Bus lets a host supply its own event bus (subscribe before New returns
	// to catch everything). A new bus is created when nil.
	Bus *events.Bus

	// Term optionally supplies persistent shells (PTY-backed). nil makes the
	// bash tool run one-shot subprocesses.
	Term agent.ShellManager

	// ConnectMCP connects configured MCP servers at startup and registers
	// their tools. Off by default: hosts usually want lazy or custom wiring.
	ConnectMCP bool

	// Optional pre-built components. When nil (the normal case) the engine
	// constructs its own from Home; hosts that need custom construction —
	// a desktop app sharing its own tool registry or search index, a server
	// with its own LLM profile store — supply them and the engine adopts
	// them as-is. See CONTRACT.md.
	LLMClient *llm.LLMClient
	Tools     *tools.Registry
	Skills    *skills.Manager
	Plugins   *plugins.Manager
	MCP       *mcp.Manager
	Memory    *memory.Manager
}

Options configures a new Engine.