llm

type AfterCompleteHook ¶

type AfterCompleteHook func(ctx context.Context, req AfterCompleteRequest) error

AfterCompleteHook fires when the recursive convergence loop terminates (no more pending tool calls).

type AfterCompleteRequest ¶

type AfterCompleteRequest struct {
	SessionID    string
	FinalMessage Message
	ToolHistory  []ToolExecutionRecord
}

AfterCompleteRequest carries context for the AfterComplete hook.

type AfterToolHook ¶

type AfterToolHook func(ctx context.Context, req AfterToolRequest) error

AfterToolHook fires after each tool execution, regardless of success or failure.

type AfterToolRequest ¶

type AfterToolRequest struct {
	SessionID string
	ToolCall  ToolRequestPart
	Result    ToolResultPart
	Duration  time.Duration
	Error     error // non-nil if the tool execution itself failed
}

AfterToolRequest carries context for the AfterTool hook.

type BeforeGenerateHook ¶

type BeforeGenerateHook func(ctx context.Context, req *BeforeGenerateRequest) error

BeforeGenerateHook fires before each LLM call (including recursive turns). Hooks execute serially and may mutate CurrentMessages. req is passed by pointer so mutations are visible to subsequent hooks.

type BeforeGenerateRequest ¶

type BeforeGenerateRequest struct {
	SessionID       string
	CurrentMessages []Message // accumulated from prior hooks
}

BeforeGenerateRequest carries context for the BeforeGenerate hook. Hooks are executed serially in registration order. Each hook may read, append, reorder, or filter CurrentMessages.

type BeforeStartHook ¶

type BeforeStartHook func(ctx context.Context, req BeforeStartRequest) error

BeforeStartHook fires once per Stream() call, before any LLM interaction.

type BeforeStartRequest ¶

type BeforeStartRequest struct {
	SessionID  string
	InitialMsg Message
}

BeforeStartRequest carries context for the BeforeStart hook.

type BeforeToolHook ¶

type BeforeToolHook func(ctx context.Context, req BeforeToolRequest) error

BeforeToolHook fires before each tool execution. Returning an error blocks the tool; the engine converts the error into a synthetic ToolResultPart{IsError:true} and feeds it back to the LLM.

func NewHITLHook(handler HITLHandler, requiresSupervision map[string]interface{}, unsafeAllTools bool) BeforeToolHook

type BeforeToolRequest ¶

type BeforeToolRequest struct {
	SessionID string
	ToolCall  ToolRequestPart
	CallIndex int // 0-based index of this tool call within the current session
}

BeforeToolRequest carries context for the BeforeTool hook.

type Engine ¶

type Engine interface {
	// Stream spins up internal resources and returns an unbuffered channel that yields
	// intermediate states or final Messages. The Engine is responsible for closing the channel.
	Stream(ctx context.Context, inputMessage Message) (<-chan Message, error)
}

Engine represents the core LLM execution block (which wraps internal agentic tool convergence) The engine handles its own back-and-forth reasoning inside its implementation.

type HITLHandler ¶

type HITLHandler interface {
	ApproveTool(ctx context.Context, req ToolRequestPart) (bool, error)
}

HITLHandler defines how the system explicitly requests human confirmation to execute a tool.

type History ¶

type History interface {
	// Append adds a new message to the session history.
	Append(ctx context.Context, sessionID string, msg Message) error

	// Read retrieves the full message history for a given session.
	Read(ctx context.Context, sessionID string) ([]Message, error)
}

History defines the minimal interface for persisting and retrieving conversational state within an agentic session.

type Identity ¶

type Identity struct {
	Role string // e.g., "user", "assistant", "system", "tool"
	Name string // The name of the specific tool or agent interacting
}

Identity represents the exact source and nature of a message.

type ImagePart ¶

type ImagePart struct {
	MIMEType string
	Data     []byte
	URL      string
}

ImagePart represents image data for multimodal LLMs.

func (i ImagePart) Type() PartType

type Message ¶

type Message struct {
	ID         string
	SessionID  string
	Identity   Identity
	Parts      []Part // Flexible payload list instead of a rigid string
	Attributes map[string]string
	Volatility Volatility
}

Message is the upgraded payload structure representing a completely isolated event.

func (m Message) MarshalJSON() ([]byte, error)

func (m Message) Text() string

func (m *Message) UnmarshalJSON(data []byte) error

type Part ¶

type Part interface {
	Type() PartType
}

Part defines an abstract section of an LLM generation. The Type() method allows downstream adapters (like Slack) to branch UI logic based on the part's intent, decoupled from how the part physically marshals itself.

type PartType ¶

type PartType string

PartType identifies the structural intent of a Message Part.

const (
	TypeText             PartType = "text"
	TypeReasoning        PartType = "reasoning"
	TypeImage            PartType = "image"
	TypeToolCall         PartType = "tool_call"
	TypeToolDefinition   PartType = "tool_definition"
	TypeToolResult       PartType = "tool_result"
	TypeTransitionSignal PartType = "transition_signal"
	TypeTelemetry        PartType = "telemetry"
)

type ReasoningPart ¶

type ReasoningPart string

ReasoningPart represents chain-of-thought or provider-supplied reasoning.

func (r ReasoningPart) MarshalText() ([]byte, error)

func (r ReasoningPart) Type() PartType

type Receiver ¶

type Receiver interface {
	Receive(ctx context.Context) (<-chan Message, error)
}

Receiver yields incoming messages over a channel. It acts as an asynchronous producer. The provided context should control the lifetime of the receiver.

type Sender ¶

type Sender interface {
	Send(ctx context.Context, msg Message) error
}

Sender writes output messages back to a transport layer.

type SessionHandler ¶

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

SessionHandler wireframes the core Input/Output loop. It enforces strict request queuing and propagates Contexts for graceful cancellation.

func NewSessionHandler(engine Engine, receiver Receiver, sender Sender) *SessionHandler

func (s *SessionHandler) ListenAndServe(ctx context.Context) error

type StaticEngine ¶

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

StaticEngine implements Engine and immediately returns a predefined slice of Message objects, completely ignoring the inputMessage. This is primarily useful for testing and providing canned responses.

func NewStaticEngine(responses ...Message) *StaticEngine

func (s *StaticEngine) Stream(ctx context.Context, inputMessage Message) (<-chan Message, error)

type TelemetryPart ¶

type TelemetryPart struct {
	InputTokens     int
	OutputTokens    int
	ReasoningTokens int
	Duration        time.Duration
}

TelemetryPart represents provider execution metrics (token usage, latency).

func (t TelemetryPart) Type() PartType

type TextPart ¶

type TextPart string

TextPart represents standard conversational text.

func (t TextPart) MarshalText() ([]byte, error)

func (t TextPart) Type() PartType

type Tool ¶

type Tool interface {
	// Name returns the specific identifier for this tool.
	Name() string
	// Definition returns the JSON Schema outlining arguments.
	Definition() ToolDefinitionPart
	// Execute performs the underlying tool logic.
	Execute(ctx context.Context, args map[string]interface{}) (interface{}, error)
}

Tool defines an atomic executable unit that the Agent can invoke.

type ToolDefinitionPart ¶

type ToolDefinitionPart struct {
	Name        string
	Description string
	Parameters  json.RawMessage // e.g. JSON Schema
}

ToolDefinitionPart implements Part, allowing tool schemas to be passed dynamically inside the Message structure as structural "specialized context".

func (t ToolDefinitionPart) Type() PartType

type ToolExecutionRecord ¶

type ToolExecutionRecord struct {
	ToolCall ToolRequestPart
	Result   ToolResultPart
	Duration time.Duration
	Error    error
}

ToolExecutionRecord captures a single tool call and its outcome for AfterComplete.

type ToolProvider ¶

type ToolProvider interface {
	Namespace() string
	// Tools returns all tools provided by this resolver.
	Tools() []Tool
	// GetTool allows the engine to resolve an execution callback when the LLM triggers a tool.
	GetTool(name string) (Tool, bool)
}

ToolProvider represents an authorized source of executable tools.

type ToolRequestPart ¶

type ToolRequestPart struct {
	ToolID string
	Name   string
	Args   map[string]interface{}
}

ToolRequestPart carries arguments that evaluate downstream.

func (t ToolRequestPart) MarshalJSON() ([]byte, error)

func (t ToolRequestPart) Type() PartType

func (t *ToolRequestPart) UnmarshalJSON(data []byte) error

type ToolResultPart ¶

type ToolResultPart struct {
	ToolID  string      // Maps back to the original request (if provider supports it)
	Name    string      // Which tool this answers
	Result  interface{} // Struct/Map that marshals cleanly to JSON
	IsError bool        // Indicates if the tool threw a business-logic error
}

ToolResultPart carries the output of a locally or remotely executed tool.

func (t ToolResultPart) Type() PartType

type TransitionSignalPart ¶

type TransitionSignalPart struct {
	TargetMode string
	Message    string
}

TransitionSignalPart represents an internal signal generated by a transition tool. It instructs the adapter Engine to break the recursive turn loop and yield to the context loop to swap the active workflow mode.

func (t TransitionSignalPart) Type() PartType

type Volatility ¶

type Volatility int8

const (
	VolatilityStatic Volatility = 0  // Never changes (e.g. System Prompt, Guardrails)
	VolatilityLow    Volatility = 3  // Rarely changes (e.g. Static agent instructions)
	VolatilityMedium Volatility = 5  // Occasional (e.g. Contextual RAG data)
	VolatilityHigh   Volatility = 10 // Turn-by-turn (e.g. Conversation History, Tool definitions)
)