Documentation
¶
Overview ¶
Package session manages the context window for a single agent execution. It tracks token budgets, triggers summarization, and wraps LLM communication.
Index ¶
- type CompletionOptions
- type HTTPClient
- type LLMClient
- type MockConfig
- type MockLLM
- type Session
- func (s *Session) Add(ctx context.Context, msg model.Message) error
- func (s *Session) CompactLatestHidePage(ctx context.Context, summary string) (bool, error)
- func (s *Session) Messages() []model.Message
- func (s *Session) Reset()
- func (s *Session) Snapshot(metadata map[string]string) model.SessionContext
- func (s *Session) Usage() (used, remaining int)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CompletionOptions ¶
type CompletionOptions struct {
MaxTokens int
Temperature float64
// ExtraBody contains additional top-level fields merged into the API request
// body verbatim. Use for model-specific parameters such as
// chat_template_kwargs for Qwen3 thinking mode control.
ExtraBody map[string]any
// Tools is the list of tool definitions to make available to the model.
// Empty means no tool calling.
Tools []model.ToolDefinition
}
CompletionOptions carries per-call settings for a model request.
type HTTPClient ¶
type HTTPClient struct {
// contains filtered or unexported fields
}
HTTPClient implements LLMClient against any OpenAI-compatible endpoint.
func NewHTTPClient ¶
func NewHTTPClient(endpoint, apiKey string, timeout time.Duration) *HTTPClient
NewHTTPClient returns an HTTPClient targeting the given base URL. When apiKey is non-empty it is sent on every request as `Authorization: Bearer <apiKey>`. The key is never logged.
func (*HTTPClient) Complete ¶
func (c *HTTPClient) Complete(ctx context.Context, modelName string, messages []model.Message, opts CompletionOptions) (model.LLMResponse, error)
Complete sends a chat completion request to the LLM endpoint and returns the parsed response.
func (*HTTPClient) CountTokens ¶
func (c *HTTPClient) CountTokens(messages []model.Message) (int, error)
CountTokens estimates the token count for messages using a character-based heuristic (~4 chars/token). For precise counts, a dedicated tokenizer endpoint would be needed.
type LLMClient ¶
type LLMClient interface {
// Complete sends messages to the model and returns the generated response.
Complete(ctx context.Context, modelName string, messages []model.Message, opts CompletionOptions) (model.LLMResponse, error)
// CountTokens returns a token estimate for messages without making a completion call.
CountTokens(messages []model.Message) (int, error)
}
LLMClient is the interface leather uses to communicate with a model backend. Production code uses HTTPClient; tests use MockLLM.
type MockConfig ¶
type MockConfig struct {
// Response is the content returned by Complete calls. Defaults to "mock response".
Response string
// TokensPerMessage is the fixed token count returned by CountTokens per message.
// Defaults to 10.
TokensPerMessage int
// Err, if non-nil, is returned by Complete instead of a response.
Err error
// ToolCallSequence is consumed one entry per Complete call. When the current
// index has a non-nil slice, those ToolCalls are returned with FinishReason
// "tool_calls" before falling back to Response. Once the sequence is exhausted,
// the normal Response is returned.
ToolCallSequence [][]model.ToolCall
}
MockConfig configures the behavior of a MockLLM.
type MockLLM ¶
type MockLLM struct {
// contains filtered or unexported fields
}
MockLLM is a deterministic test double for LLMClient. It records all Complete calls so tests can assert on invocation counts and inputs.
func NewMockLLM ¶
func NewMockLLM(cfg MockConfig) *MockLLM
NewMockLLM returns a MockLLM with the given configuration.
func (*MockLLM) Complete ¶
func (m *MockLLM) Complete(_ context.Context, _ string, messages []model.Message, _ CompletionOptions) (model.LLMResponse, error)
Complete records the call and returns tool calls from the sequence (if available), then the fixed response or the configured error. It is safe for concurrent use.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session manages the context window for a single agent execution.
func New ¶
func New(budget model.TokenBudget, modelName string, client LLMClient) *Session
New returns a Session initialized with the given budget, model name, and LLM client.
func (*Session) Add ¶
Add appends msg to the context window, counts its tokens, and triggers summarization if usage exceeds the configured threshold.
func (*Session) CompactLatestHidePage ¶
CompactLatestHidePage removes the most recent completed hide-reflection cycle, keeping only the assistant's page summary in the session. This is used by reflection-mode paging so prior page bodies and hide_next scaffolding do not remain in context after the model has already summarized that page.
func (*Session) Reset ¶
func (s *Session) Reset()
Reset clears the context window. If the first message has role "system", it is preserved so the agent's identity is not lost.
Source Files