assistants

Documentation

Overview

Package model provides core domain models for OpenBotStack.

Package agent defines the agent state machine and lifecycle for OpenBotStack.

The agent state machine manages the deterministic lifecycle of a single request, enforcing bounded reflection and explicit state transitions.

Index

• Variables
• type AgentState
• type AgentStateMachine
• type AssistantProfile
• type DefaultStateMachine
  • func NewStateMachine(maxReflections int) *DefaultStateMachine
  • func (sm *DefaultStateMachine) CanTransitionTo(next AgentState) bool
  • func (sm *DefaultStateMachine) CurrentState() AgentState
  • func (sm *DefaultStateMachine) History() []StateTransition
  • func (sm *DefaultStateMachine) MaxReflections() int
  • func (sm *DefaultStateMachine) ReflectionCount() int
  • func (sm *DefaultStateMachine) Serialize() ([]byte, error)
  • func (sm *DefaultStateMachine) TransitionTo(next AgentState, reason string) error
• type StateTransition

Variables

var (
	// ErrInvalidTransition is returned when a state transition is not allowed.
	ErrInvalidTransition = errors.New("agent: invalid state transition")

	// ErrMaxReflectionsExceeded is returned when reflection limit is reached.
	ErrMaxReflectionsExceeded = errors.New("agent: max reflections exceeded")

	// ErrSerializationFailed is returned when state serialization fails.
	ErrSerializationFailed = errors.New("agent: serialization failed")
)

Types

type AgentState

type AgentState string

AgentState represents the current phase of agent execution.

const (
	// StateIdle indicates the agent is awaiting a request.
	StateIdle AgentState = "idle"

	// StatePlanning indicates the agent is decomposing a goal into steps.
	StatePlanning AgentState = "planning"

	// StateExecuting indicates the agent is delegating to runtime.
	StateExecuting AgentState = "executing"

	// StateReflecting indicates the agent is evaluating execution results.
	StateReflecting AgentState = "reflecting"

	// StateFinalizing indicates the agent is preparing the response.
	StateFinalizing AgentState = "finalizing"

	// StateCompleted indicates execution finished successfully.
	StateCompleted AgentState = "completed"

	// StateFailed indicates an unrecoverable error occurred.
	StateFailed AgentState = "failed"
)

type AgentStateMachine

type AgentStateMachine interface {
	// CurrentState returns the current execution state.
	CurrentState() AgentState

	// CanTransitionTo returns true if the transition is valid.
	CanTransitionTo(next AgentState) bool

	// TransitionTo moves to the next state.
	// Returns error if transition is invalid.
	// Emits audit event on success.
	TransitionTo(next AgentState, reason string) error

	// ReflectionCount returns how many reflection cycles have occurred.
	ReflectionCount() int

	// MaxReflections returns the configured upper bound on reflections.
	MaxReflections() int

	// Serialize returns the full state for persistence.
	Serialize() ([]byte, error)

	// History returns the ordered list of state transitions.
	History() []StateTransition
}

AgentStateMachine manages the deterministic lifecycle of a single request.

Key invariants:

• Exactly one active state at any time
• Transitions are explicit and audited
• Reflection is bounded (max iterations)
• All state is serializable for persistence

type AssistantProfile

type AssistantProfile struct {
	// ID is a unique identifier for this assistant profile.
	ID string

	// Name is the display name of the assistant.
	Name string

	// Description explains what this assistant does.
	Description string

	// SystemPrompt is the base prompt defining assistant behavior.
	SystemPrompt string

	// EnabledSkillIDs lists skills this assistant can use.
	EnabledSkillIDs []string
}

AssistantProfile defines the identity and configuration of an AI assistant. Full definition deferred to future implementation.

type DefaultStateMachine

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

DefaultStateMachine is the default implementation of AgentStateMachine.

func NewStateMachine

func NewStateMachine(maxReflections int) *DefaultStateMachine

NewStateMachine creates a new state machine with the given max reflections.

func (*DefaultStateMachine) CanTransitionTo

func (sm *DefaultStateMachine) CanTransitionTo(next AgentState) bool

CanTransitionTo returns true if the transition is valid.

func (*DefaultStateMachine) CurrentState

func (sm *DefaultStateMachine) CurrentState() AgentState

CurrentState returns the current execution state.

func (*DefaultStateMachine) History

func (sm *DefaultStateMachine) History() []StateTransition

History returns the ordered list of state transitions.

func (*DefaultStateMachine) MaxReflections

func (sm *DefaultStateMachine) MaxReflections() int

MaxReflections returns the configured upper bound on reflections.

func (*DefaultStateMachine) ReflectionCount

func (sm *DefaultStateMachine) ReflectionCount() int

ReflectionCount returns how many reflection cycles have occurred.

func (*DefaultStateMachine) Serialize

func (sm *DefaultStateMachine) Serialize() ([]byte, error)

Serialize returns the full state for persistence.

func (*DefaultStateMachine) TransitionTo

func (sm *DefaultStateMachine) TransitionTo(next AgentState, reason string) error

TransitionTo moves to the next state.

type StateTransition

type StateTransition struct {
	From      AgentState
	To        AgentState
	Reason    string
	Timestamp time.Time
}

StateTransition records a single state change.