1. System Concepts

Agent

Model + harness executing multi-step decisions. Not a standalone entity; an agent is a model operating within a Loop with access to Tools and Memory. Owned by: orchestrate layer.

Loop

Control structure around inference. Drives retry, tool calls, validation. Four patterns: AgentLoop, SpecializedLoop, PlanExecutor, RedundantLoop. Owned by: orchestrate layer.

Task

Structured objective with intent, constraints, and expected output type. May be expressed as a SystemRequest.

Intent

What the output must accomplish. Used by semantic validation and planning to judge correctness beyond schema compliance.

Goal

Task-level target state. A plan succeeds when all steps converge toward the goal.

Mode

Execution strategy selector: chat, structured, plan, redundant. Determines which Loop pattern runs and which constraints apply.

2. System Boundary

SystemRequest

Input from adapters into the system. Contains messages, mode, execution hints, output contract, correlation ids. See Contracts.

SystemResponse

Output returned to adapters. Contains content, structured output, validation result, confidence, error, token usage. See Contracts.

SystemError

Canonical error model with error_code, category (from Failure Taxonomy), retryable flag, details map. See Contracts.

ExecutionHints

Optional knobs on SystemRequest: max_tokens, timeout, temperature, mode override. See Contracts.

OutputContract

Schema and grammar expectations attached to SystemRequest. Declares what shape the response must have. See Contracts.

3. Execution

ExecutionState

Tracks lifecycle position: current_state, timestamps, attempt counters, last_error, last_step. See Contracts.

ExecutionContext

Per-request context carrying immutable ids (request_id, session_id) plus mutable metadata (attempts, selected tools, candidates). See Contracts.

ExecutionPlan

Ordered sequence of Steps defining a multi-step pipeline. Created by a Planner or manually authored. Executed by PlanExecutor. See Orchestration.

Step

Single unit of work in an ExecutionPlan. Has a type, handler, name, and input/output shape.

StepHandler

Function with signature func(ctx context.Context, step Step) (Step, error). Registered in PlanExecutor by step type.

4. Execution IR (Intermediate Representation)

StepInput

Typed wrapper for data entering a Step. May contain messages, candidates, context, or tool results.

StepOutput

Typed wrapper for data leaving a Step. Carries results forward to next Step in plan.

CandidateIR

Canonical cross-step representation: {content, source, score, metadata}. Unifies context.Chunk and rerank.Candidate at step boundaries.

ContextIR

List of chunks or messages with provenance tracking. Built by context layer, consumed by orchestrate.

5. Retrieval and Reranking

Retriever

Interface for knowledge lookup. Returns Chunks matching a query. Owned by: context layer (L03).

Chunk

Individual piece of retrieved context with content, source, and score. Owned by: context layer (L03).

ContextProvider

Structural typing interface consumed by orchestrate. Any type with RetrieveContext(ctx, query) ([]core.Message, error) satisfies it. See Architecture.

Candidate

Item to be scored and ranked. Has content, source, score, metadata. Owned by: rerank layer (L06).

CandidateReranker

Structural typing interface consumed by orchestrate. Any type with RerankCandidates(ctx, query, candidates) ([]Candidate, error) satisfies it. See Architecture.

RelevanceScorer

Scores candidates for relevance. Owned by: rerank layer (L06).

RetrievalScore

Score assigned by a Retriever. Meaning depends on implementation (BM25, cosine, etc.). See Retrieval.

RerankScore

Normalized relevance score after reranking. See Retrieval.

6. Tools

Tool

Deterministic capability with metadata, schema, execution function, and availability check. All side effects live here. Owned by: tool layer (L04).

ToolCall

Model's request to invoke a tool. Contains tool name, arguments, and call id. Owned by: core (L00).

ToolResult

Output from executing a ToolCall. Contains content and error status. Part of execution IR.

ToolSafety

Metadata declaring side effects (none/read/write/external), idempotency, required capabilities. See Tools.

Registry

Groups tools, dispatches execution, reports availability. Owned by: tool layer (L04).

7. Constraints and Validation

Constraint

Any deterministic enforcement applied to model output. Includes grammar, schema, JSON repair, enum normalization. Owned by: constraint layer (L05).

DecoderConstraint

Constraint applied at token-generation time (GBNF grammar). Strongest guarantee. Owned by: constraint layer (L05).

Validation

Post-generation checking of output. Includes rule validation (deterministic) and semantic validation (inferential). Owned by: validate layer (L07).

ConstraintPipeline

Ordered sequence of constraint and validation stages applied to output. See Constraints.

Confidence

Optional score on SystemResponse indicating output reliability. Sources: voting (RedundantLoop), validation pass rate, retrieval coverage. See Constraints.

RetryPolicy

Controls retry behavior on validation failure. Defines max attempts and backoff. Owned by: validate layer (L07).

RepairStrategy

Attempts to fix invalid output (e.g., close truncated JSON) before retrying inference. Owned by: validate layer (L07).

8. Failure Categories

InferenceFailure

Engine error or model unavailable. Owned by: inference layer (L01). See Contracts.

ToolFailure

Tool missing, execution error, or timeout. Owned by: tool layer (L04). See Contracts.

ConstraintFailure

Grammar, schema, or JSON validity failure. Owned by: constraint layer (L05). See Contracts.

ValidationFailure

Rule failure or semantic validation failure. Owned by: validate layer (L07). See Contracts.

OrchestrationFailure

Plan step input mismatch or iteration limit exceeded. Owned by: orchestrate layer (L02). See Contracts.

ConfigurationFailure

Missing engine, missing required schema. See Contracts.

Cancellation

Timeout or context cancelled. See Contracts.

9. Memory

ConversationMemory

Persisted user/assistant message history for multi-turn loops. Owned by: memory layer (L09).

WorkingMemory

Per-execution transient artifacts: candidates, context blocks, tool results. Discarded after execution. Owned by: memory layer (L09).

SessionState

Durable key-value store carrying decisions across steps within a session. Owned by: memory layer (L09).

MemoryPolicy

Rules governing eviction, persistence, and ephemeral context handling per loop pattern.

10. Observability

TraceRecorder

Records execution traces with hierarchical spans. Owned by: observe layer (L10).

EventLog

Records discrete events during execution. Owned by: observe layer (L10).

MetricsCollector

Collects numeric metrics (latency, token counts, costs). Owned by: observe layer (L10).

Correlation Ids

Set of identifiers linking events to requests: request_id, session_id, trace_id, span_id. See Contracts.

11. Prompt

PromptProvider

Interface for prompt assembly: BuildSystemPrompt() (core.Message, error). Implementations live in the prompt layer and satisfy this without importing orchestrate. Owned by: orchestrate layer (L02).

Template

Parameterized prompt template with variable substitution. Owned by: prompt layer (L08).

ContextPolicy

Rules for placing retrieved context in prompt (position, source attribution). Owned by: prompt layer (L08).

12. Architecture

Layer

Numbered directory under layers/ forming a dependency DAG. Higher numbers may import lower, never reverse.

Adapter

Thin boundary shell mapping external I/O to SystemRequest/SystemResponse. Adapters are cli, tui, api. No orchestration logic allowed.

Structural Typing

Go pattern where orchestrate consumes interfaces without importing the implementing package. Compile-time safe, no coupling.