llm

package
v1.26.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 22, 2026 License: Apache-2.0 Imports: 18 Imported by: 3

Documentation

Overview

Package llm defines the unified abstraction layer over different LLM providers.

It provides core interfaces, message types, and content blocks used across all providers:

  • LLM and StreamingLLM are the provider interfaces.
  • Message carries content to and from an LLM.
  • Content blocks represent text, images, documents, tool calls, and other message components.
  • Option functions configure LLM requests (model, temperature, tools, etc.).
  • Tool describes a callable tool at the LLM level.

Most users interact with this package indirectly through github.com/deepnoodle-ai/dive.Agent. Direct usage is needed when building custom providers or working with the LLM layer directly.

Index

Constants

View Source 
const (
	CacheTTL5m = "5m"
	CacheTTL1h = "1h"
)

Cache TTL values accepted by providers that support an extended cache duration. The default (empty) TTL is the provider's standard 5-minute cache; CacheTTL1h requests the 1-hour extended cache where supported.

View Source 
const (
	CostSourceListPriceEstimate = "list_price_estimate"
	CostSourceProviderReported  = "provider_reported"
	CostSourceMixed             = "mixed"
	CostModelMixed              = "mixed"
)

Variables

View Source 
var ToolChoiceAny = &ToolChoice{Type: ToolChoiceTypeAny}

ToolChoiceAny is a ToolChoice with type "any".

View Source 
var ToolChoiceAuto = &ToolChoice{Type: ToolChoiceTypeAuto}

ToolChoiceAuto is a ToolChoice with type "auto".

View Source 
var ToolChoiceNone = &ToolChoice{Type: ToolChoiceTypeNone}

ToolChoiceNone is a ToolChoice with type "none".

Functions

func ContextWithLogger added in v0.0.12 

func ContextWithLogger(ctx context.Context, logger Logger) context.Context

ContextWithLogger returns a new context with the given logger.

func DecodeToolResultContent added in v1.5.0 

func DecodeToolResultContent[T any](c *ToolResultContent) (T, error)

DecodeToolResultContent decodes a ToolResultContent into a value of type T. Generic wrapper around (*ToolResultContent).DecodeContent for call sites that prefer a return value over an out-parameter.

func Fatal added in v0.0.12 

func Fatal(args ...any)

Fatal wraps the standard library log.Fatal function.

func FormatReminder added in v1.14.0 

func FormatReminder(c *ReminderContent) string

FormatReminder renders the provider-wire representation of a reminder.

func PopulateCost added in v1.9.0 

func PopulateCost(model string, fast bool, u *Usage)

PopulateCost sets u.Cost from the resolved pricing for the model, when a resolver is installed and pricing is known. It is a no-op (leaving u.Cost nil — i.e. "unknown") when there is no resolver, no pricing, or no usage. It also preserves a provider-computed cost or an explicit unavailable marker. fast selects fast-mode pricing where a provider distinguishes it.

func SetCostResolver added in v1.9.0 

func SetCostResolver(r CostResolver)

SetCostResolver installs the global pricing resolver. The providers package wires this up in init() so that PopulateCost — and therefore the streaming accumulator — can attach cost to usage automatically. Passing nil clears it.

func SetDefaultLogLevel added in v0.0.12 

func SetDefaultLogLevel(level Level)

SetDefaultLogLevel sets the default log level for Dive.

func ValidReminderName added in v1.14.0 

func ValidReminderName(name string) bool

ValidReminderName reports whether name is safe for a reminder tag attribute.

Types

type AppliedContextEdit added in v0.0.12 

type AppliedContextEdit struct {
	// Type is the strategy type identifier (e.g., "clear_tool_uses_20250919").
	Type string `json:"type"`

	// ClearedToolUses is the number of tool use/result pairs that were cleared.
	// Populated for "clear_tool_uses_20250919" strategy.
	ClearedToolUses int `json:"cleared_tool_uses,omitempty"`

	// ClearedThinkingTurns is the number of thinking turns that were cleared.
	// Populated for "clear_thinking_20251015" strategy.
	ClearedThinkingTurns int `json:"cleared_thinking_turns,omitempty"`

	// ClearedInputTokens is the number of input tokens that were removed from the context.
	ClearedInputTokens int `json:"cleared_input_tokens,omitempty"`
}

AppliedContextEdit describes a context edit that was performed.

type BashCodeExecutionFile added in v0.0.12 

type BashCodeExecutionFile struct {
	FileID string `json:"file_id"`
}

BashCodeExecutionFile represents a file created during bash execution.

type BashCodeExecutionResult added in v0.0.12 

type BashCodeExecutionResult struct {
	Type       string `json:"type"` // "bash_code_execution_result" or "bash_code_execution_tool_result_error"
	Stdout     string `json:"stdout,omitempty"`
	Stderr     string `json:"stderr,omitempty"`
	ReturnCode int    `json:"return_code,omitempty"`
	ErrorCode  string `json:"error_code,omitempty"` // For error responses
	// Content may contain file references when files are created
	Content []BashCodeExecutionFile `json:"content,omitempty"`
}

BashCodeExecutionResult contains the result of a bash command execution.

type BashCodeExecutionToolResultContent added in v0.0.12 

type BashCodeExecutionToolResultContent struct {
	ToolUseID string                  `json:"tool_use_id"`
	Content   BashCodeExecutionResult `json:"content"`
}

BashCodeExecutionToolResultContent represents the result of a bash code execution.

func (*BashCodeExecutionToolResultContent) IsError added in v0.0.12 

func (c *BashCodeExecutionToolResultContent) IsError() bool

IsError returns true if this result represents an error.

func (*BashCodeExecutionToolResultContent) MarshalJSON added in v0.0.12 

func (c *BashCodeExecutionToolResultContent) MarshalJSON() ([]byte, error)

func (*BashCodeExecutionToolResultContent) Type added in v0.0.12 

func (c *BashCodeExecutionToolResultContent) Type() ContentType

type CacheControl 

type CacheControl struct {
	Type CacheControlType `json:"type"`
	// TTL selects the cache lifetime when the provider supports an extended
	// cache duration. Empty means the provider default (5 minutes); "1h"
	// requests the extended 1-hour cache. See CacheTTL5m / CacheTTL1h.
	TTL string `json:"ttl,omitempty"`
}

CacheControl is used to control caching of content blocks.

type CacheControlSetter 

type CacheControlSetter interface {
	SetCacheControl(cacheControl *CacheControl)
}

CacheControlSetter is an interface that allows setting the cache control for a content block.

type CacheControlType 

type CacheControlType string

CacheControlType is used to control how the LLM caches responses. 

const (
	CacheControlTypeEphemeral CacheControlType = "ephemeral"
)

func (CacheControlType) String 

func (c CacheControlType) String() string

type CharLocation 

type CharLocation struct {
	Type           string `json:"type"` // "char_location"
	CitedText      string `json:"cited_text,omitempty"`
	DocumentIndex  int    `json:"document_index,omitempty"`
	DocumentTitle  string `json:"document_title,omitempty"`
	StartCharIndex int    `json:"start_char_index,omitempty"`
	EndCharIndex   int    `json:"end_char_index,omitempty"`
}

CharLocation is a citation to a specific part of a document.

func (*CharLocation) IsCitation 

func (c *CharLocation) IsCitation() bool

type Citation 

type Citation interface {
	IsCitation() bool
}

Citation is a reference to source material attached to generated text.

type CitationSettings 

type CitationSettings struct {
	Enabled bool `json:"enabled"`
}

CitationSettings contains settings for citations in a message.

type CitationType 

type CitationType string

CitationType identifies the kind of citation attached to a text content block. 

const (
	CitationTypeCharLocation            CitationType = "char_location"
	CitationTypeWebSearchResultLocation CitationType = "web_search_result_location"
	CitationTypeURLCitation             CitationType = "url_citation"
)

type CodeExecutionResult 

type CodeExecutionResult struct {
	Type       string `json:"type"`
	Stdout     string `json:"stdout"`
	Stderr     string `json:"stderr"`
	ReturnCode int    `json:"return_code"`
}

CodeExecutionResult contains stdout, stderr, and return code from code execution.

type CodeExecutionToolResultContent 

type CodeExecutionToolResultContent struct {
	ToolUseID string              `json:"tool_use_id"`
	Content   CodeExecutionResult `json:"content"`
}

CodeExecutionToolResultContent carries the result of a server-side code execution tool call.

func (*CodeExecutionToolResultContent) MarshalJSON 

func (c *CodeExecutionToolResultContent) MarshalJSON() ([]byte, error)

func (*CodeExecutionToolResultContent) Type 

func (c *CodeExecutionToolResultContent) Type() ContentType

type Config 

type Config struct {
	Model              string                   `json:"model,omitempty"`
	SystemPrompt       string                   `json:"system_prompt,omitempty"`
	Endpoint           string                   `json:"endpoint,omitempty"`
	APIKey             string                   `json:"api_key,omitempty"`
	Prefill            string                   `json:"prefill,omitempty"`
	PrefillClosingTag  string                   `json:"prefill_closing_tag,omitempty"`
	MaxTokens          *int                     `json:"max_tokens,omitempty"`
	Temperature        *float64                 `json:"temperature,omitempty"`
	PresencePenalty    *float64                 `json:"presence_penalty,omitempty"`
	FrequencyPenalty   *float64                 `json:"frequency_penalty,omitempty"`
	ReasoningBudget    *int                     `json:"reasoning_budget,omitempty"`
	ReasoningEffort    ReasoningEffort          `json:"reasoning_effort,omitempty"`
	ReasoningSummary   ReasoningSummary         `json:"reasoning_summary,omitempty"`
	Thinking           ThinkingType             `json:"thinking,omitempty"`
	ThinkingDisplay    ThinkingDisplay          `json:"thinking_display,omitempty"`
	Speed              Speed                    `json:"speed,omitempty"`
	ContextManagement  *ContextManagementConfig `json:"context_management,omitempty"`
	Tools              []Tool                   `json:"tools,omitempty"`
	ToolChoice         *ToolChoice              `json:"tool_choice,omitempty"`
	ParallelToolCalls  *bool                    `json:"parallel_tool_calls,omitempty"`
	Features           []string                 `json:"features,omitempty"`
	RequestHeaders     http.Header              `json:"request_headers,omitempty"`
	MCPServers         []MCPServerConfig        `json:"mcp_servers,omitempty"`
	Caching            *bool                    `json:"caching,omitempty"`
	PromptCacheKey     string                   `json:"prompt_cache_key,omitempty"`
	PreviousResponseID string                   `json:"previous_response_id,omitempty"`
	ServiceTier        string                   `json:"service_tier,omitempty"`
	ProviderOptions    map[string]interface{}   `json:"provider_options,omitempty"`
	ResponseFormat     *ResponseFormat          `json:"response_format,omitempty"`
	Messages           Messages                 `json:"messages"`
	Hooks              Hooks                    `json:"-"`
	Client             *http.Client             `json:"-"`
	Logger             Logger                   `json:"-"`
	SSECallback        ServerSentEventsCallback `json:"-"`
}

Config is used to configure LLM calls. Not all providers support all options. If a provider doesn't support a given option, it will be ignored.

func (*Config) Apply 

func (c *Config) Apply(opts ...Option)

Apply applies the given options to the config.

func (*Config) FireHooks 

func (c *Config) FireHooks(ctx context.Context, hookCtx *HookContext) error

FireHooks fires the configured hooks for the matching hook type.

func (*Config) IsFeatureEnabled 

func (c *Config) IsFeatureEnabled(feature string) bool

IsFeatureEnabled returns true if the feature is enabled.

type Content 

type Content interface {
	Type() ContentType
}

Content is a single block of content in a message. A message may contain multiple content blocks of varying types.

func UnmarshalContent 

func UnmarshalContent(data []byte) (Content, error)

UnmarshalContent unmarshals the JSON of one content block into the appropriate concrete Content type.

type ContentChunk 

type ContentChunk struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
}

ContentChunk is used within a Content block to pass chunks of content.

type ContentCloner added in v1.0.0 

type ContentCloner interface {
	CloneContent() Content
}

ContentCloner is an interface for content blocks that can produce a shallow copy with CacheControl cleared. This is used by provider convertMessages functions to avoid mutating the caller's content when applying cache control.

type ContentSource 

type ContentSource struct {
	// Type is the type of the content source ("base64", "url", "text", or "file")
	Type ContentSourceType `json:"type"`

	// MediaType is the media type of the content. E.g. "image/jpeg", "application/pdf"
	MediaType string `json:"media_type,omitempty"`

	// Data is base64 encoded data (used with ContentSourceTypeBase64)
	Data string `json:"data,omitempty"`

	// URL is the URL of the content (used with ContentSourceTypeURL)
	URL string `json:"url,omitempty"`

	// FileID is the file ID from the Files API (used with ContentSourceTypeFile)
	FileID string `json:"file_id,omitempty"`

	// Chunks of content. Only use if chunking on the client side, for use
	// within a DocumentContent block.
	Content []*ContentChunk `json:"content,omitempty"`

	// GenerationID is an ID associated with the generation of this content,
	// if any. This may be set on content returned from image generation, for
	// example. Used for OpenAI image generation results.
	GenerationID string `json:"generation_id,omitempty"`

	// GenerationStatus is the status of the generation of this content,
	// if any. This may be set on content returned from image generation, for
	// example. Used for OpenAI image generation results.
	GenerationStatus string `json:"generation_status,omitempty"`
}

ContentSource conveys information about media content in a message.

func ContentURL 

func ContentURL(url string) *ContentSource

ContentURL creates a content source with the given URL.

func EncodedData 

func EncodedData(mediaType, base64Data string) *ContentSource

EncodedData creates a content source with the given media type and base64-encoded data.

func FileID 

func FileID(id string) *ContentSource

FileID creates a content source with the given file ID.

func RawData 

func RawData(mediaType string, data []byte) *ContentSource

RawData creates a content source with the given media type and raw data. Automatically base64 encodes the provided data.

func (*ContentSource) DecodedData 

func (c *ContentSource) DecodedData() ([]byte, error)

DecodedData returns the decoded data if this content carries base64 encoded data.

type ContentSourceType 

type ContentSourceType string

ContentSourceType indicates the location of the media content. 

const (
	ContentSourceTypeBase64 ContentSourceType = "base64"
	ContentSourceTypeURL    ContentSourceType = "url"
	ContentSourceTypeText   ContentSourceType = "text"
	ContentSourceTypeFile   ContentSourceType = "file"
)

func (ContentSourceType) String 

func (c ContentSourceType) String() string

type ContentType 

type ContentType string

ContentType indicates the type of a content block in a message 

const (
	ContentTypeText                    ContentType = "text"
	ContentTypeImage                   ContentType = "image"
	ContentTypeDocument                ContentType = "document"
	ContentTypeFile                    ContentType = "file"
	ContentTypeToolUse                 ContentType = "tool_use"
	ContentTypeToolResult              ContentType = "tool_result"
	ContentTypeThinking                ContentType = "thinking"
	ContentTypeRedactedThinking        ContentType = "redacted_thinking"
	ContentTypeServerToolUse           ContentType = "server_tool_use"
	ContentTypeWebSearchToolResult     ContentType = "web_search_tool_result"
	ContentTypeMCPToolUse              ContentType = "mcp_tool_use"
	ContentTypeMCPToolResult           ContentType = "mcp_tool_result"
	ContentTypeMCPListTools            ContentType = "mcp_list_tools"
	ContentTypeMCPApprovalRequest      ContentType = "mcp_approval_request"
	ContentTypeMCPApprovalResponse     ContentType = "mcp_approval_response"
	ContentTypeCodeExecutionToolResult ContentType = "code_execution_tool_result"
	ContentTypeRefusal                 ContentType = "refusal"
	ContentTypeDynamic                 ContentType = "dynamic"
	ContentTypeSummary                 ContentType = "summary"
	ContentTypeReminder                ContentType = "reminder"

	// Code execution tool result types (code_execution_20250825)
	ContentTypeBashCodeExecutionToolResult       ContentType = "bash_code_execution_tool_result"
	ContentTypeTextEditorCodeExecutionToolResult ContentType = "text_editor_code_execution_tool_result"
)

type ContextManagementConfig added in v0.0.12 

type ContextManagementConfig struct {
	// Edits is a list of context editing strategies to apply.
	// If multiple strategies are provided, they are applied in order.
	Edits []ContextManagementEdit `json:"edits"`
}

ContextManagementConfig configures automated context management strategies. This allows the LLM provider to automatically manage conversation context, such as clearing tool results or thinking blocks, to optimize context window usage.

type ContextManagementEdit added in v0.0.12 

type ContextManagementEdit struct {
	// Type is the strategy type identifier.
	// Supported values:
	// - "clear_tool_uses_20250919": Clears tool results when context grows beyond a threshold.
	//   Oldest tool results are cleared first and replaced with placeholder text.
	// - "clear_thinking_20251015": Clears thinking blocks from previous assistant turns
	//   when extended thinking is enabled.
	Type string `json:"type"`

	// Trigger defines when the context editing strategy activates.
	// Once the prompt exceeds this threshold, clearing will begin.
	// Measuring units can be "input_tokens" or "tool_uses".
	// Only applicable for "clear_tool_uses_20250919".
	Trigger *ContextManagementTrigger `json:"trigger,omitempty"`

	// Keep defines how much content to preserve after clearing occurs.
	// For "clear_tool_uses_20250919", this is the number of recent tool use/result pairs to keep.
	// For "clear_thinking_20251015", this is the number of recent assistant turns with thinking blocks to preserve.
	Keep *ContextManagementKeep `json:"keep,omitempty"`

	// ClearAtLeast ensures a minimum number of tokens is cleared each time the strategy activates.
	// If the API can't clear at least the specified amount, the strategy will not be applied.
	// This helps determine if context clearing is worth breaking the prompt cache.
	// Only applicable for "clear_tool_uses_20250919".
	ClearAtLeast *ContextManagementTrigger `json:"clear_at_least,omitempty"`

	// ExcludeTools is a list of tool names whose tool uses and results should never be cleared.
	// Useful for preserving important context (e.g., "memory" or "web_search").
	// Only applicable for "clear_tool_uses_20250919".
	ExcludeTools []string `json:"exclude_tools,omitempty"`

	// ClearToolInputs controls whether the tool call parameters are cleared along with the tool results.
	// By default (false), only the tool results are cleared while keeping the original tool calls visible.
	// Only applicable for "clear_tool_uses_20250919".
	ClearToolInputs bool `json:"clear_tool_inputs,omitempty"`
}

ContextManagementEdit defines a specific context editing strategy.

type ContextManagementKeep added in v0.0.12 

type ContextManagementKeep struct {
	// Type specifies the unit of measurement.
	// Supported values: "tool_uses" (for clear_tool_uses strategy) or "thinking_turns" (for clear_thinking strategy).
	Type string `json:"type"`

	// Value indicates how much to keep.
	// For tool_uses, use an integer (N latest uses).
	// For thinking_turns, use an integer (N latest turns) or the string "all" (to keep all thinking blocks).
	Value any `json:"value"`
}

ContextManagementKeep defines content to preserve during context editing.

type ContextManagementResponse added in v0.0.12 

type ContextManagementResponse struct {
	// AppliedEdits is a list of edits that were applied to the context.
	AppliedEdits []AppliedContextEdit `json:"applied_edits,omitempty"`

	// OriginalInputTokens is the token count before any context editing occurred.
	// This is useful for calculating token savings.
	OriginalInputTokens int `json:"original_input_tokens,omitempty"`
}

ContextManagementResponse contains information about applied context edits. This struct is populated if the API performed any context editing (e.g., clearing tool results).

type ContextManagementTrigger added in v0.0.12 

type ContextManagementTrigger struct {
	// Type specifies the unit of measurement.
	// Supported values: "input_tokens", "tool_uses".
	Type string `json:"type"`

	// Value is the threshold or amount.
	Value int `json:"value"`
}

ContextManagementTrigger defines a threshold or amount for context editing.

type Cost added in v1.9.0 

type Cost struct {
	Input                float64 `json:"input"`
	Output               float64 `json:"output"`
	CacheRead            float64 `json:"cache_read"`
	CacheWrite           float64 `json:"cache_write"`
	Total                float64 `json:"total"`
	Currency             string  `json:"currency,omitempty"`
	Model                string  `json:"model,omitempty"`
	Source               string  `json:"source,omitempty"`
	BreakdownUnavailable bool    `json:"breakdown_unavailable,omitempty"`
}

Cost is a monetary cost broken out by token category. Source distinguishes a provider-reported account charge from a list-price estimate. Some providers report only an authoritative Total, in which case BreakdownUnavailable is true and the category fields must not be treated as measured zeroes.

func (*Cost) Add added in v1.9.0 

func (c *Cost) Add(other *Cost)

Add accumulates another Cost into this one. It is nil-safe on the argument. Each summand was computed at its own call's prices, so summing per-call costs stays correct even across model or speed changes within a session.

type CostResolver added in v1.9.0 

type CostResolver func(model string, fast bool) (PricingInfo, bool)

CostResolver returns the pricing for a model at a given speed (fast vs. standard). ok is false when no pricing is known for the model.

type DocumentContent 

type DocumentContent struct {
	Source       *ContentSource    `json:"source"`
	Title        string            `json:"title,omitempty"`
	Context      string            `json:"context,omitempty"`
	Citations    *CitationSettings `json:"citations,omitempty"`
	CacheControl *CacheControl     `json:"cache_control,omitempty"`
}

func NewDocumentContent 

func NewDocumentContent(source *ContentSource) *DocumentContent

NewDocumentContent creates a document content block with the given content source.

func (*DocumentContent) CloneContent added in v1.0.0 

func (c *DocumentContent) CloneContent() Content

func (*DocumentContent) MarshalJSON 

func (c *DocumentContent) MarshalJSON() ([]byte, error)

func (*DocumentContent) SetCacheControl 

func (c *DocumentContent) SetCacheControl(cacheControl *CacheControl)

func (*DocumentContent) Type 

func (c *DocumentContent) Type() ContentType

type EmbeddingPricingInfo added in v0.0.10 

type EmbeddingPricingInfo struct {
	Model     string  `json:"model"`
	Price     float64 `json:"price_per_1m_tokens"` // per 1M tokens (USD)
	Currency  string  `json:"currency"`
	UpdatedAt string  `json:"updated_at"`
}

EmbeddingPricingInfo represents pricing for embedding services

type Event 

type Event struct {
	Type              EventType                  `json:"type"`
	Index             *int                       `json:"index,omitempty"`
	Message           *Response                  `json:"message,omitempty"`
	ContentBlock      *EventContentBlock         `json:"content_block,omitempty"`
	Delta             *EventDelta                `json:"delta,omitempty"`
	Usage             *Usage                     `json:"usage,omitempty"`
	ContextManagement *ContextManagementResponse `json:"context_management,omitempty"`
}

Event represents a single streaming event from the LLM. A successfully run stream will end with a final message containing the complete Response.

type EventContentBlock 

type EventContentBlock struct {
	Type      ContentType      `json:"type"`
	Text      string           `json:"text,omitempty"`
	ID        string           `json:"id,omitempty"`
	Name      string           `json:"name,omitempty"`
	Input     json.RawMessage  `json:"input,omitempty"`
	Thinking  string           `json:"thinking,omitempty"`
	Signature string           `json:"signature,omitempty"`
	Metadata  ProviderMetadata `json:"metadata,omitempty"`
}

EventContentBlock carries the start of a content block in an LLM event.

type EventDelta 

type EventDelta struct {
	Type         EventDeltaType   `json:"type,omitempty"`
	Text         string           `json:"text,omitempty"`
	Index        int              `json:"index,omitempty"`
	StopReason   string           `json:"stop_reason,omitempty"`
	StopSequence string           `json:"stop_sequence,omitempty"`
	PartialJSON  string           `json:"partial_json,omitempty"`
	Thinking     string           `json:"thinking,omitempty"`
	Signature    string           `json:"signature,omitempty"`
	Metadata     ProviderMetadata `json:"metadata,omitempty"`
}

EventDelta carries a portion of an LLM response.

type EventDeltaType 

type EventDeltaType string

EventDeltaType indicates the type of delta in an LLM event. 

const (
	EventDeltaTypeText      EventDeltaType = "text_delta"
	EventDeltaTypeInputJSON EventDeltaType = "input_json_delta"
	EventDeltaTypeThinking  EventDeltaType = "thinking_delta"
	EventDeltaTypeSignature EventDeltaType = "signature_delta"
	EventDeltaTypeMetadata  EventDeltaType = "metadata_delta"
	EventDeltaTypeCitations EventDeltaType = "citations_delta"
)

func (EventDeltaType) String 

func (e EventDeltaType) String() string

type EventType 

type EventType string

EventType represents the type of streaming event 

const (
	EventTypePing              EventType = "ping"
	EventTypeMessageStart      EventType = "message_start"
	EventTypeMessageDelta      EventType = "message_delta"
	EventTypeMessageStop       EventType = "message_stop"
	EventTypeContentBlockStart EventType = "content_block_start"
	EventTypeContentBlockDelta EventType = "content_block_delta"
	EventTypeContentBlockStop  EventType = "content_block_stop"
)

func (EventType) String 

func (e EventType) String() string

type Hook 

type Hook struct {
	Type HookType
	Func HookFunc
}

Hook is used to register callbacks for different LLM events.

type HookContext 

type HookContext struct {
	Type     HookType             `json:"type"`
	Request  *HookRequestContext  `json:"request,omitempty"`
	Response *HookResponseContext `json:"response,omitempty"`
}

HookContext contains information passed to hooks.

type HookFunc 

type HookFunc func(ctx context.Context, hookCtx *HookContext) error

Hook is a function that gets called during LLM operations

type HookRequestContext 

type HookRequestContext struct {
	Messages []*Message `json:"messages"`
	Config   *Config    `json:"config,omitempty"`
	Body     []byte     `json:"-"`
}

HookRequestContext contains information about a request to an LLM.

type HookResponseContext 

type HookResponseContext struct {
	Response *Response `json:"response,omitempty"`
	Error    error     `json:"error,omitempty"`
}

HookResponseContext contains information about a response from an LLM.

type HookType 

type HookType string

Hook types for different LLM events 

const (
	BeforeGenerate HookType = "before_generate"
	AfterGenerate  HookType = "after_generate"
	OnError        HookType = "on_error"
)

type Hooks 

type Hooks []Hook

Hooks is a list of hooks.

type ImageContent 

type ImageContent struct {
	Source       *ContentSource `json:"source"`
	CacheControl *CacheControl  `json:"cache_control,omitempty"`
}

func NewImageContent added in v1.0.0 

func NewImageContent(source *ContentSource) *ImageContent

NewImageContent creates an image content block with the given content source.

func (*ImageContent) CloneContent added in v1.0.0 

func (c *ImageContent) CloneContent() Content

func (*ImageContent) Image 

func (c *ImageContent) Image() (image.Image, error)

Image returns the image content as an image.Image.

func (*ImageContent) MarshalJSON 

func (c *ImageContent) MarshalJSON() ([]byte, error)

func (*ImageContent) SetCacheControl 

func (c *ImageContent) SetCacheControl(cacheControl *CacheControl)

func (*ImageContent) Type 

func (c *ImageContent) Type() ContentType

type ImagePricingInfo added in v0.0.10 

type ImagePricingInfo struct {
	Model     string  `json:"model"`
	Price     float64 `json:"price_per_image"` // per image (USD)
	MaxSize   string  `json:"max_size"`        // e.g., "1024x1024"
	Currency  string  `json:"currency"`
	UpdatedAt string  `json:"updated_at"`
}

ImagePricingInfo represents pricing for image generation services

type ImageType 

type ImageType string

ImageType represents a supported image MIME type. 

const (
	ImageTypePNG  ImageType = "image/png"
	ImageTypeJPEG ImageType = "image/jpeg"
	ImageTypeGIF  ImageType = "image/gif"
	ImageTypeWEBP ImageType = "image/webp"
)

func DetectImageType 

func DetectImageType(imageBase64 string) (ImageType, error)

DetectImageType detects the type of an image from its base64-encoded data. Supports PNG, JPEG, GIF, and WEBP.

type LLM 

type LLM interface {
	// Name of the LLM provider
	Name() string

	// Generate a response from the LLM by passing messages.
	Generate(ctx context.Context, opts ...Option) (*Response, error)
}

LLM is the core interface for interacting with a language model provider.

type Level added in v0.0.12 

type Level int

Level represents the minimum log level 

const (
	LevelDebug Level = iota
	LevelInfo
	LevelWarn
	LevelError
)

Available log levels

func GetDefaultLogLevel added in v0.0.12 

func GetDefaultLogLevel() Level

GetDefaultLogLevel returns the default log level for Dive.

func LevelFromString added in v0.0.12 

func LevelFromString(value string) Level

LevelFromString converts a string to a LogLevel.

type Logger added in v0.0.12 

type Logger interface {
	// Debug logs a message at debug level with optional key-value pairs
	Debug(msg string, args ...any)

	// Info logs a message at info level with optional key-value pairs
	Info(msg string, args ...any)

	// Warn logs a message at warn level with optional key-value pairs
	Warn(msg string, args ...any)

	// Error logs a message at error level with optional key-value pairs
	Error(msg string, args ...any)

	// With returns a Logger that includes the given attributes in each output operation
	With(args ...any) Logger
}

Logger defines the interface for logging within Dive. This interface is designed to be compatible with slog and other structured logging libraries.

func LoggerFromContext added in v0.0.12 

func LoggerFromContext(ctx context.Context) Logger

LoggerFromContext returns the logger from the given context. If no logger is set, it returns a NullLogger.

type MCPApprovalRequestContent 

type MCPApprovalRequestContent struct {
	ID          string `json:"id"`
	Arguments   string `json:"arguments"`
	Name        string `json:"name"`
	ServerLabel string `json:"server_label"`
}

func (*MCPApprovalRequestContent) MarshalJSON 

func (c *MCPApprovalRequestContent) MarshalJSON() ([]byte, error)

func (*MCPApprovalRequestContent) Type 

func (c *MCPApprovalRequestContent) Type() ContentType

type MCPApprovalResponseContent 

type MCPApprovalResponseContent struct {
	ApprovalRequestID string `json:"approval_request_id"`
	Approve           bool   `json:"approve"`
	Reason            string `json:"reason,omitempty"`
}

func (*MCPApprovalResponseContent) MarshalJSON 

func (c *MCPApprovalResponseContent) MarshalJSON() ([]byte, error)

func (*MCPApprovalResponseContent) Type 

func (c *MCPApprovalResponseContent) Type() ContentType

type MCPListToolsContent 

type MCPListToolsContent struct {
	ServerLabel string               `json:"server_label"`
	Tools       []*MCPToolDefinition `json:"tools"`
}

MCPListToolsContent lists the tools available on an MCP server.

func (*MCPListToolsContent) MarshalJSON 

func (c *MCPListToolsContent) MarshalJSON() ([]byte, error)

func (*MCPListToolsContent) Type 

func (c *MCPListToolsContent) Type() ContentType

type MCPOAuthConfig 

type MCPOAuthConfig struct {
	ClientID     string            `json:"client_id"`
	ClientSecret string            `json:"client_secret,omitempty"`
	RedirectURI  string            `json:"redirect_uri"`
	Scopes       []string          `json:"scopes,omitempty"`
	PKCEEnabled  bool              `json:"pkce_enabled,omitempty"`
	TokenStore   *MCPTokenStore    `json:"token_store,omitempty"`
	ExtraParams  map[string]string `json:"extra_params,omitempty"`
}

MCPOAuthConfig represents OAuth 2.0 configuration for MCP servers

type MCPServerConfig 

type MCPServerConfig struct {
	Type               string                `json:"type"`
	Command            string                `json:"command,omitempty"`
	URL                string                `json:"url,omitempty"`
	Name               string                `json:"name,omitempty"`
	AuthorizationToken string                `json:"authorization_token,omitempty"`
	OAuth              *MCPOAuthConfig       `json:"oauth,omitempty"`
	ToolConfiguration  *MCPToolConfiguration `json:"tool_configuration,omitempty"`
	Headers            map[string]string     `json:"headers,omitempty"`
}

MCPServerConfig is used to configure an MCP server. Corresponds to this Anthropic feature: https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector#using-the-mcp-connector-in-the-messages-api And OpenAI's Remote MCP feature: https://platform.openai.com/docs/guides/tools-remote-mcp#page-top

type MCPTokenStore 

type MCPTokenStore struct {
	Type string `json:"type"`           // "memory", "file", "keychain"
	Path string `json:"path,omitempty"` // For file storage
}

MCPTokenStore represents token storage configuration

type MCPToolApprovalFilter 

type MCPToolApprovalFilter struct {
	Always []string `json:"always,omitempty"`
	Never  []string `json:"never,omitempty"`
}

MCPToolApprovalFilter is used to configure the approval filter for MCP tools. The Always and Never fields should contain the names of tools whose calls should have customized approvals.

type MCPToolConfiguration 

type MCPToolConfiguration struct {
	Enabled      bool     `json:"enabled"`
	AllowedTools []string `json:"allowed_tools,omitempty"`

	// OpenAI MCP server only, for the Responses API
	ApprovalMode   string                 `json:"approval_mode,omitempty"`
	ApprovalFilter *MCPToolApprovalFilter `json:"approval_filter,omitempty"`
}

MCPToolConfiguration represents the configuration for MCP tools. Generally corresponds to Anthropic's tool_configuration field: https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector#mcp-server-configuration OpenAI Remote MCP uses approval mode/filter: https://platform.openai.com/docs/guides/tools-remote-mcp

type MCPToolDefinition 

type MCPToolDefinition struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description,omitempty"`
	InputSchema map[string]interface{} `json:"input_schema,omitempty"`
}

MCPToolDefinition describes a tool provided by an MCP server.

type MCPToolResultContent 

type MCPToolResultContent struct {
	ToolUseID string          `json:"tool_use_id"`
	IsError   bool            `json:"is_error,omitempty"`
	Content   []*ContentChunk `json:"content,omitempty"`
}

func (*MCPToolResultContent) MarshalJSON 

func (c *MCPToolResultContent) MarshalJSON() ([]byte, error)

func (*MCPToolResultContent) Type 

func (c *MCPToolResultContent) Type() ContentType

type MCPToolUseContent 

type MCPToolUseContent struct {
	ID         string          `json:"id"`
	Name       string          `json:"name"`
	ServerName string          `json:"server_name"`
	Input      json.RawMessage `json:"input"`
}

func (*MCPToolUseContent) MarshalJSON 

func (c *MCPToolUseContent) MarshalJSON() ([]byte, error)

func (*MCPToolUseContent) Type 

func (c *MCPToolUseContent) Type() ContentType

type Message 

type Message struct {
	ID      string    `json:"id,omitempty"`
	Role    Role      `json:"role"`
	Content []Content `json:"content"`
}

Message containing content passed to or from an LLM.

func NewAssistantMessage 

func NewAssistantMessage(content ...Content) *Message

NewAssistantMessage creates an assistant message with the given content.

func NewAssistantTextMessage 

func NewAssistantTextMessage(text string) *Message

NewAssistantTextMessage creates an assistant message with a single text content block.

func NewMessage 

func NewMessage(role Role, content []Content) *Message

NewMessage creates a message with the given role and content blocks.

func NewSystemMessage 

func NewSystemMessage(text string) *Message

NewSystemMessage creates a system message with a single text content block.

func NewToolResultMessage 

func NewToolResultMessage(outputs ...*ToolResultContent) *Message

NewToolResultMessage creates a message with the user role and a list of tool outputs. Used to pass the results of tool calls back to an LLM.

func NewUserMessage 

func NewUserMessage(content ...Content) *Message

NewUserMessage creates a user message with the given content blocks.

func NewUserTextMessage 

func NewUserTextMessage(text string) *Message

NewUserTextMessage creates a user message with a single text content block.

func RenderReminders added in v1.14.0 

func RenderReminders(messages []*Message, resolve ReminderAuthorityResolver) ([]*Message, error)

RenderReminders converts typed reminder blocks to provider-wire text without mutating caller-owned messages. Only messages containing ReminderContent are normalized; raw system/developer messages retain their existing behavior.

Operator reminders render with the strongest role the resolver reports as legal for their position, falling back to a tagged user message everywhere else. A nil resolver means native operator authority is unavailable.

func (*Message) Copy added in v0.0.12 

func (m *Message) Copy() *Message

Copy creates a deep copy of the message.

This method uses JSON marshaling/unmarshaling to create a fully independent copy of the message including all content blocks. The copied message can be modified without affecting the original.

This is primarily used by ThreadRepository.ForkThread to ensure that forked conversation threads have independent message histories.

If marshaling fails (which should be rare), falls back to a shallow copy of the content slice.

func (*Message) DecodeInto 

func (m *Message) DecodeInto(v any) error

DecodeInto decodes the last text content in the message as JSON into a given Go object. This pairs with the WithResponseFormat request option.

func (*Message) ImageContent 

func (m *Message) ImageContent() (*ImageContent, bool)

ImageContent returns the first image content in the message, if any.

func (*Message) LastText 

func (m *Message) LastText() string

LastText returns the last text content in the message.

func (*Message) MarshalJSON 

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

MarshalJSON implements custom marshaling for Message to properly handle the polymorphic Content field.

func (*Message) Text 

func (m *Message) Text() string

Text returns a concatenated text from all message content. If there were multiple text contents, they are separated by two newlines.

func (*Message) ThinkingContent 

func (m *Message) ThinkingContent() (*ThinkingContent, bool)

ThinkingContent returns the first thinking content in the message, if any.

func (*Message) UnmarshalJSON 

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

UnmarshalJSON implements custom unmarshaling for Message to properly handle the polymorphic Content field.

func (*Message) WithContent 

func (m *Message) WithContent(content ...Content) *Message

WithContent appends content block(s) to the message.

func (*Message) WithText 

func (m *Message) WithText(text ...string) *Message

WithText appends text content block(s) to the message.

type Messages 

type Messages []*Message

Messages is shorthand for a slice of messages.

type ModalityTokenUsage added in v1.21.0 

type ModalityTokenUsage struct {
	InputTokens              int `json:"input_tokens,omitempty"`
	OutputTokens             int `json:"output_tokens,omitempty"`
	CacheCreationInputTokens int `json:"cache_creation_input_tokens,omitempty"`
	CacheReadInputTokens     int `json:"cache_read_input_tokens,omitempty"`
}

ModalityTokenUsage is a disjoint token breakdown for one provider modality. Its input buckets follow the same convention as Usage; OutputTokens includes any reasoning tokens when the provider attributes them to the modality.

type NullLogger added in v0.0.12 

type NullLogger struct{}

NullLogger implements the Logger interface but does nothing. This is useful for testing or when you want to disable logging.

func (*NullLogger) Debug added in v0.0.12 

func (l *NullLogger) Debug(msg string, args ...any)

func (*NullLogger) Error added in v0.0.12 

func (l *NullLogger) Error(msg string, args ...any)

func (*NullLogger) Info added in v0.0.12 

func (l *NullLogger) Info(msg string, args ...any)

func (*NullLogger) Warn added in v0.0.12 

func (l *NullLogger) Warn(msg string, args ...any)

func (*NullLogger) With added in v0.0.12 

func (l *NullLogger) With(args ...any) Logger

type Option 

type Option func(*Config)

Option is a function that is used to adjust LLM configuration.

func WithAPIKey 

func WithAPIKey(apiKey string) Option

WithAPIKey sets the API key.

func WithAdaptiveThinking added in v1.6.0 

func WithAdaptiveThinking() Option

WithAdaptiveThinking enables adaptive thinking, where the model decides when and how much to think. Equivalent to WithThinking(ThinkingTypeAdaptive).

func WithCaching added in v1.0.0 

func WithCaching(enabled bool) Option

WithCaching controls provider-level caching. When true (default), providers that support caching will automatically apply cache control to messages. Set to false to disable automatic caching.

func WithContextManagement added in v0.0.12 

func WithContextManagement(config *ContextManagementConfig) Option

WithContextManagement sets the context management configuration for the interaction.

func WithEndpoint 

func WithEndpoint(endpoint string) Option

WithEndpoint sets the endpoint.

func WithFeatures 

func WithFeatures(features ...string) Option

WithFeatures sets the features for the interaction.

func WithFrequencyPenalty 

func WithFrequencyPenalty(frequencyPenalty float64) Option

WithFrequencyPenalty sets the frequency penalty for the interaction.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets the HTTP client.

func WithHook 

func WithHook(hookType HookType, hookFunc HookFunc) Option

WithHook adds a callback for the specified hook type

func WithHooks 

func WithHooks(hooks Hooks) Option

WithHooks sets the hooks for the interaction.

func WithLogger 

func WithLogger(l Logger) Option

WithLogger sets the logger.

func WithMCPServers 

func WithMCPServers(servers ...MCPServerConfig) Option

WithMCPServers sets the remote MCP servers for the interaction. Used to configure MCP servers that the LLM provider itself is going to call. Corresponds to the Anthropic "MCP connector" feature: https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector

func WithMaxTokens 

func WithMaxTokens(maxTokens int) Option

WithMaxTokens sets the max tokens.

func WithMessages 

func WithMessages(messages ...*Message) Option

WithMessages sets the messages for the interaction.

func WithModel 

func WithModel(model string) Option

WithModel sets the LLM model for the generation.

func WithParallelToolCalls 

func WithParallelToolCalls(parallelToolCalls bool) Option

WithParallelToolCalls sets whether to allow parallel tool calls.

func WithPrefill 

func WithPrefill(prefill, closingTag string) Option

WithPrefill sets the prefilled assistant response for the interaction.

func WithPresencePenalty 

func WithPresencePenalty(presencePenalty float64) Option

WithPresencePenalty sets the presence penalty for the interaction.

func WithPreviousResponseID 

func WithPreviousResponseID(previousResponseID string) Option

WithPreviousResponseID sets the previous response ID for the interaction. OpenAI only. https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#openai-apis-for-conversation-state

func WithPromptCacheKey added in v1.21.0 

func WithPromptCacheKey(promptCacheKey string) Option

WithPromptCacheKey sets a stable routing key for provider prompt caches.

func WithReasoningBudget 

func WithReasoningBudget(reasoningBudget int) Option

WithReasoningBudget sets the reasoning budget for the interaction.

func WithReasoningEffort 

func WithReasoningEffort(reasoningEffort ReasoningEffort) Option

WithReasoningEffort sets the reasoning effort for the interaction.

func WithReasoningSummary 

func WithReasoningSummary(reasoningSummary ReasoningSummary) Option

WithReasoningSummary sets the reasoning summary for the interaction.

func WithRequestHeaders 

func WithRequestHeaders(headers http.Header) Option

WithRequestHeaders sets the request headers for the interaction.

func WithResponseFormat 

func WithResponseFormat(responseFormat *ResponseFormat) Option

WithResponseFormat sets the response format for the interaction.

func WithServerSentEventsCallback 

func WithServerSentEventsCallback(callback ServerSentEventsCallback) Option

WithServerSentEventsCallback sets the callback for the server-sent events stream.

func WithServiceTier 

func WithServiceTier(serviceTier string) Option

WithServiceTier sets the service tier for the interaction. OpenAI only. https://platform.openai.com/docs/api-reference/responses/create#responses-create-service_tier

func WithSpeed added in v1.6.0 

func WithSpeed(speed Speed) Option

WithSpeed sets the inference speed for the interaction.

func WithSystemPrompt 

func WithSystemPrompt(systemPrompt string) Option

WithSystemPrompt sets the system prompt.

func WithTemperature 

func WithTemperature(temperature float64) Option

WithTemperature sets the temperature.

func WithThinking added in v1.6.0 

func WithThinking(thinking ThinkingType) Option

WithThinking sets the extended thinking mode for the interaction.

func WithThinkingDisplay added in v1.6.0 

func WithThinkingDisplay(display ThinkingDisplay) Option

WithThinkingDisplay controls how thinking content is returned in responses.

func WithToolChoice 

func WithToolChoice(toolChoice *ToolChoice) Option

WithToolChoice sets the tool choice for the interaction.

func WithTools 

func WithTools(tools ...Tool) Option

WithTools sets the tools for the interaction.

func WithUserTextMessage 

func WithUserTextMessage(text string) Option

WithUserTextMessage sets a single user text message for the interaction.

type PricingInfo added in v0.0.10 

type PricingInfo struct {
	Model       string  `json:"model"`
	InputPrice  float64 `json:"input_price_per_1m_tokens"`  // per 1M input tokens (USD)
	OutputPrice float64 `json:"output_price_per_1m_tokens"` // per 1M output tokens (USD)
	// Per-modality prices override the corresponding base price only for the
	// provider-reported tokens in that modality. Missing modalities retain the
	// base price. This is required for providers such as Gemini that price audio
	// input differently from text, image, and video input.
	InputPriceByModality     map[string]float64 `json:"input_price_per_1m_tokens_by_modality,omitempty"`
	OutputPriceByModality    map[string]float64 `json:"output_price_per_1m_tokens_by_modality,omitempty"`
	CacheReadPriceByModality map[string]float64 `json:"cache_read_price_per_1m_tokens_by_modality,omitempty"`
	// LongContextThreshold selects the long-context input, cache-read, and
	// output prices when the request's full input size is at least this many
	// tokens. Zero means the model has no unified long-context pricing tier.
	LongContextThreshold      int     `json:"long_context_threshold_tokens,omitempty"`
	LongContextInputPrice     float64 `json:"long_context_input_price_per_1m_tokens,omitempty"`
	LongContextCacheReadPrice float64 `json:"long_context_cache_read_price_per_1m_tokens,omitempty"`
	LongContextOutputPrice    float64 `json:"long_context_output_price_per_1m_tokens,omitempty"`
	// CacheReadPrice is the price per 1M tokens read from the prompt cache (a
	// cache hit). Zero means the provider does not bill cache reads separately.
	CacheReadPrice float64 `json:"cache_read_price_per_1m_tokens,omitempty"`
	// CacheReadPriceAboveThreshold replaces CacheReadPrice when the request's
	// full input size exceeds CacheReadPriceThreshold tokens. Both fields are
	// zero for models without tiered cache-read pricing.
	CacheReadPriceAboveThreshold float64 `json:"cache_read_price_above_threshold_per_1m_tokens,omitempty"`
	CacheReadPriceThreshold      int     `json:"cache_read_price_threshold_tokens,omitempty"`
	// CacheWritePrice is the price per 1M tokens written to the prompt cache (a
	// cache miss). For providers with multiple cache TTLs this is the default
	// (shortest) TTL rate. Zero means the provider does not surcharge writes.
	CacheWritePrice float64 `json:"cache_write_price_per_1m_tokens,omitempty"`
	// NonGlobalPriceMultiplier is applied by providers whose list price differs
	// between global and regional endpoints. CostOf itself remains location-free.
	NonGlobalPriceMultiplier float64 `json:"non_global_price_multiplier,omitempty"`
	Currency                 string  `json:"currency"`
	UpdatedAt                string  `json:"updated_at"` // YYYY-MM-DD format
}

PricingInfo represents pricing information for a specific service

func (PricingInfo) CostOf added in v1.9.0 

func (p PricingInfo) CostOf(u *Usage) Cost

CostOf computes the estimated cost of the given usage at these prices. A nil usage yields a zero cost (still tagged with currency and model).

func (PricingInfo) Scaled added in v1.21.0 

func (p PricingInfo) Scaled(factor float64) PricingInfo

Scaled returns a deep copy with every token price multiplied by factor. Thresholds and descriptive metadata are preserved. The regional multiplier is cleared because the returned prices already include the adjustment.

type ProviderMetadata added in v1.10.1 

type ProviderMetadata map[string]string

ProviderMetadata carries opaque, provider-specific data attached to a content block that must round-trip through the conversation unchanged for a later request to the same provider. Keys are namespaced by provider to avoid collisions (for example "google.thought_signature"). Values are strings; binary payloads are base64-encoded by the provider that owns them. The core library never interprets these values — only the originating provider reads them back.

func (ProviderMetadata) Clone added in v1.10.1 

func (m ProviderMetadata) Clone() ProviderMetadata

Clone returns a deep copy of the metadata, or nil if the receiver is nil.

type ReasoningEffort 

type ReasoningEffort string

ReasoningEffort defines the effort level for reasoning aka extended thinking. It controls how eagerly the model spends tokens on a response, including thinking, tool calls, and text. Not all providers support all levels: ReasoningEffortMax is supported by OpenAI GPT-5.6 and newer Anthropic models. 

const (
	// ReasoningEffortNone requests no model-side reasoning. Supported on newer
	// OpenAI GPT-5.4+ models; other providers may ignore or reject it.
	ReasoningEffortNone ReasoningEffort = "none"
	// ReasoningEffortMinimal requests the smallest amount of reasoning the
	// model supports. Useful for tasks where latency matters more than
	// step-by-step deliberation. Supported on OpenAI gpt-5 family; other
	// providers may map it to their lowest available level or ignore it.
	ReasoningEffortMinimal ReasoningEffort = "minimal"
	ReasoningEffortLow     ReasoningEffort = "low"
	ReasoningEffortMedium  ReasoningEffort = "medium"
	ReasoningEffortHigh    ReasoningEffort = "high"
	// ReasoningEffortXHigh requests extended capability for long-horizon work.
	// Supported on newer OpenAI GPT-5.4+ models and Claude Opus 4.7/4.8.
	ReasoningEffortXHigh ReasoningEffort = "xhigh"
	// ReasoningEffortMax requests the absolute maximum capability with no
	// constraints on token spend. Supported on OpenAI GPT-5.6, Claude Opus
	// 4.6, 4.7, 4.8, and Sonnet 4.6.
	ReasoningEffortMax ReasoningEffort = "max"
)

func ClampReasoningEffort added in v1.20.0 

func ClampReasoningEffort(requested ReasoningEffort, supported []ReasoningEffort) (ReasoningEffort, bool)

ClampReasoningEffort maps a requested effort onto the closest level a model actually accepts, reporting whether it had to move. Providers use it so that a portable ModelSettings survives being pointed at a model with a narrower range, instead of failing the request.

The requested level is clamped down to the most eager supported level that does not exceed it — xhigh becomes high on a model that stops at high. When the request sits below everything supported, it clamps up to the least eager supported level, so minimal becomes low rather than none.

An empty supported set, an unrecognized effort, or a supported set holding no graduated levels all return the input unchanged with false; the caller owns those cases.

func (ReasoningEffort) IsValid 

func (r ReasoningEffort) IsValid() bool

IsValid returns true if the reasoning effort is a known, valid value.

type ReasoningSummary 

type ReasoningSummary string

ReasoningSummary controls whether and how reasoning content is summarized. 

const (
	ReasoningSummaryAuto     ReasoningSummary = "auto"
	ReasoningSummaryConcise  ReasoningSummary = "concise"
	ReasoningSummaryDetailed ReasoningSummary = "detailed"
)

type RedactedThinkingContent 

type RedactedThinkingContent struct {
	Data string `json:"data"`
}

RedactedThinkingContent is a content block that contains encrypted thinking, due to being flagged by the provider's safety systems. These are decrypted when passed back to the LLM, so that it can continue the thought process.

func (*RedactedThinkingContent) MarshalJSON 

func (c *RedactedThinkingContent) MarshalJSON() ([]byte, error)

func (*RedactedThinkingContent) Type 

func (c *RedactedThinkingContent) Type() ContentType

type RefusalContent 

type RefusalContent struct {
	Text         string        `json:"text"`
	CacheControl *CacheControl `json:"cache_control,omitempty"`
}

RefusalContent represents a refusal response from the model.

func (*RefusalContent) CloneContent added in v1.0.0 

func (c *RefusalContent) CloneContent() Content

func (*RefusalContent) MarshalJSON 

func (c *RefusalContent) MarshalJSON() ([]byte, error)

func (*RefusalContent) SetCacheControl 

func (c *RefusalContent) SetCacheControl(cacheControl *CacheControl)

func (*RefusalContent) Type 

func (c *RefusalContent) Type() ContentType

type ReminderAuthorityResolver added in v1.14.0 

type ReminderAuthorityResolver func(index int, messages []*Message) (Role, bool)

ReminderAuthorityResolver reports the native role and whether it is legal for the reminder message at index. A nil resolver means native operator authority is unavailable.

type ReminderContent added in v1.14.0 

type ReminderContent struct {
	Name    string       `json:"name"`
	Tier    ReminderTier `json:"tier"`
	Content string       `json:"content"`
}

ReminderContent is a typed runtime-context block. Providers render it to a recognizable <system-reminder> block at the wire boundary.

func (*ReminderContent) MarshalJSON added in v1.14.0 

func (c *ReminderContent) MarshalJSON() ([]byte, error)

func (*ReminderContent) Type added in v1.14.0 

func (c *ReminderContent) Type() ContentType

type ReminderTier added in v1.14.0 

type ReminderTier string

ReminderTier describes the authority of runtime-injected context. 

const (
	// ReminderTierContextual is user-adjacent context such as environment facts,
	// surfaced memory, or tool-produced notifications.
	ReminderTierContextual ReminderTier = "contextual"
	// ReminderTierOperator is context asserted by the application operator.
	ReminderTierOperator ReminderTier = "operator"
)

type Response 

type Response struct {
	ID                string                     `json:"id"`
	Model             string                     `json:"model"`
	Role              Role                       `json:"role"`
	Content           []Content                  `json:"content"`
	StopReason        string                     `json:"stop_reason"`
	StopSequence      *string                    `json:"stop_sequence,omitempty"`
	StopDetails       *StopDetails               `json:"stop_details,omitempty"`
	Type              string                     `json:"type"`
	Usage             Usage                      `json:"usage"`
	ContextManagement *ContextManagementResponse `json:"context_management,omitempty"`
}

Response is the generated response from an LLM. Matches the Anthropic response format documented here: https://docs.anthropic.com/en/api/messages#response-content

In Dive, all LLM provider implementations must transform their responses into this type.

func (*Response) Message 

func (r *Response) Message() *Message

Message extracts and returns the message from the response.

func (*Response) ToolCalls 

func (r *Response) ToolCalls() []*ToolUseContent

ToolCalls extracts and returns all tool calls from the response.

func (*Response) UnmarshalJSON 

func (r *Response) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom unmarshaling for Response to properly handle the polymorphic Content field.

type ResponseAccumulator 

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

ResponseAccumulator builds up a complete response from a stream of events.

func NewResponseAccumulator 

func NewResponseAccumulator() *ResponseAccumulator

NewResponseAccumulator creates a new ResponseAccumulator.

func (*ResponseAccumulator) AddEvent 

func (r *ResponseAccumulator) AddEvent(event *Event) error

AddEvent adds an event to the ResponseAccumulator.

func (*ResponseAccumulator) IsComplete 

func (r *ResponseAccumulator) IsComplete() bool

func (*ResponseAccumulator) Response 

func (r *ResponseAccumulator) Response() *Response

func (*ResponseAccumulator) Usage 

func (r *ResponseAccumulator) Usage() *Usage

type ResponseFormat 

type ResponseFormat struct {
	// Type indicates the format type ("text", "json_object", or "json_schema")
	Type ResponseFormatType `json:"type"`

	// Schema provides a JSON schema to guide the model's output
	Schema *schema.Schema `json:"schema,omitempty"`

	// Name provides a name for the output to guide the model
	Name string `json:"name,omitempty"`

	// Description provides additional context to guide the model
	Description string `json:"description,omitempty"`
}

ResponseFormat guides an LLM's response format.

type ResponseFormatType 

type ResponseFormatType string

ResponseFormatType specifies the expected format of the LLM's response. 

const (
	ResponseFormatTypeText       ResponseFormatType = "text"
	ResponseFormatTypeJSON       ResponseFormatType = "json_object"
	ResponseFormatTypeJSONSchema ResponseFormatType = "json_schema"
)

type Role 

type Role string

Role indicates the role of a message in a conversation. Either "user", "assistant", or "system". 

const (
	User      Role = "user"
	Assistant Role = "assistant"
	System    Role = "system"
	Developer Role = "developer"
)

func (Role) String 

func (r Role) String() string

type ServerSentEventsCallback 

type ServerSentEventsCallback func(line string) error

ServerSentEventsCallback is a callback that is called for each line of the server-sent events stream.

type ServerSentEventsReader 

type ServerSentEventsReader[T any] struct {
	// contains filtered or unexported fields
}

ServerSentEventsReader reads SSE events from a reader a decodes them into the parameter type T.

func NewServerSentEventsReader 

func NewServerSentEventsReader[T any](stream io.ReadCloser) *ServerSentEventsReader[T]

NewServerSentEventsReader creates a new ServerSentEventsReader.

func (*ServerSentEventsReader[T]) Err 

func (s *ServerSentEventsReader[T]) Err() error

Err returns the error that occurred while reading the SSE stream.

func (*ServerSentEventsReader[T]) Next 

func (s *ServerSentEventsReader[T]) Next() (T, bool)

Next reads the next event from the SSE stream.

func (*ServerSentEventsReader[T]) WithSSECallback 

func (s *ServerSentEventsReader[T]) WithSSECallback(callback ServerSentEventsCallback) *ServerSentEventsReader[T]

WithSSECallback sets an optional callback that is called for each line of the server-sent events stream.

type ServerToolUseContent 

type ServerToolUseContent struct {
	ID    string         `json:"id"`
	Name  string         `json:"name"`
	Input map[string]any `json:"input"`
}

func (*ServerToolUseContent) MarshalJSON 

func (c *ServerToolUseContent) MarshalJSON() ([]byte, error)

func (*ServerToolUseContent) Type 

func (c *ServerToolUseContent) Type() ContentType

type Speed added in v1.6.0 

type Speed string

Speed controls the inference speed of the model. 

const (
	// SpeedFast requests fast mode: significantly higher output tokens per
	// second at premium pricing. Anthropic research preview; supported on
	// Claude Opus 4.6, 4.7, and 4.8 (requires fast-mode access).
	SpeedFast Speed = "fast"
	// SpeedStandard requests standard inference speed (the default).
	SpeedStandard Speed = "standard"
)

type StopDetails added in v1.6.0 

type StopDetails struct {
	// Type categorizes the stop reason (e.g. the refusal category).
	Type string `json:"type,omitempty"`
}

StopDetails provides additional structured detail about why generation stopped. It is populated alongside StopReason — most notably on refusals, where Type categorizes the kind of refusal so applications can route the user to the right next step.

type StreamIterator 

type StreamIterator interface {
	// Next advances the stream to the next event. It returns false when the stream
	// is complete or if an error occurs. The caller should check Err() after Next
	// returns false to distinguish between normal completion and errors.
	Next() bool

	// Event returns the current event in the stream. It should only be called
	// after a successful call to Next.
	Event() *Event

	// Err returns any error that occurred while reading from the stream.
	// It should be checked after Next returns false.
	Err() error

	// Close closes the stream and releases any associated resources.
	Close() error
}

StreamIterator provides an iterator-style interface for reading streaming LLM responses.

type StreamingLLM 

type StreamingLLM interface {
	LLM

	// Stream starts a streaming response from the LLM by passing messages.
	// The caller should call Close on the returned Stream when done.
	Stream(ctx context.Context, opts ...Option) (StreamIterator, error)
}

StreamingLLM extends LLM with support for streaming responses.

type SummaryContent added in v0.0.12 

type SummaryContent struct {
	Summary      string        `json:"summary"`
	CacheControl *CacheControl `json:"cache_control,omitempty"`
}

SummaryContent represents a compacted conversation summary that replaces the full message history during context compaction.

func (*SummaryContent) CloneContent added in v1.0.0 

func (c *SummaryContent) CloneContent() Content

func (*SummaryContent) MarshalJSON added in v0.0.12 

func (c *SummaryContent) MarshalJSON() ([]byte, error)

func (*SummaryContent) SetCacheControl added in v0.0.12 

func (c *SummaryContent) SetCacheControl(cacheControl *CacheControl)

func (*SummaryContent) Type added in v0.0.12 

func (c *SummaryContent) Type() ContentType

type TextContent 

type TextContent struct {
	Text         string        `json:"text"`
	CacheControl *CacheControl `json:"cache_control,omitempty"`
	Citations    []Citation    `json:"citations,omitempty"`
	// Metadata carries opaque provider-specific data (see ProviderMetadata)
	// that must remain attached to this exact text block when replayed.
	Metadata ProviderMetadata `json:"metadata,omitempty"`
}

func NewTextContent 

func NewTextContent(text string) *TextContent

NewTextContent creates a text content block with the given text.

func (*TextContent) CloneContent added in v1.0.0 

func (c *TextContent) CloneContent() Content

func (*TextContent) MarshalJSON 

func (c *TextContent) MarshalJSON() ([]byte, error)

func (*TextContent) SetCacheControl 

func (c *TextContent) SetCacheControl(cacheControl *CacheControl)

func (*TextContent) Type 

func (c *TextContent) Type() ContentType

type TextEditorCodeExecutionResult added in v0.0.12 

type TextEditorCodeExecutionResult struct {
	Type string `json:"type"` // "text_editor_code_execution_result" or "text_editor_code_execution_tool_result_error"

	// View operation fields
	FileType   string `json:"file_type,omitempty"`
	Content    string `json:"content,omitempty"`
	NumLines   int    `json:"numLines,omitempty"`
	StartLine  int    `json:"startLine,omitempty"`
	TotalLines int    `json:"totalLines,omitempty"`

	// Create operation fields
	IsFileUpdate *bool `json:"is_file_update,omitempty"`

	// Edit (str_replace) operation fields
	OldStart int      `json:"oldStart,omitempty"`
	OldLines int      `json:"oldLines,omitempty"`
	NewStart int      `json:"newStart,omitempty"`
	NewLines int      `json:"newLines,omitempty"`
	Lines    []string `json:"lines,omitempty"`

	// Error fields
	ErrorCode string `json:"error_code,omitempty"`
}

TextEditorCodeExecutionResult contains the result of a text editor operation.

type TextEditorCodeExecutionToolResultContent added in v0.0.12 

type TextEditorCodeExecutionToolResultContent struct {
	ToolUseID string                        `json:"tool_use_id"`
	Content   TextEditorCodeExecutionResult `json:"content"`
}

TextEditorCodeExecutionToolResultContent represents the result of a text editor operation.

func (*TextEditorCodeExecutionToolResultContent) IsError added in v0.0.12 

func (c *TextEditorCodeExecutionToolResultContent) IsError() bool

IsError returns true if this result represents an error.

func (*TextEditorCodeExecutionToolResultContent) MarshalJSON added in v0.0.12 

func (c *TextEditorCodeExecutionToolResultContent) MarshalJSON() ([]byte, error)

func (*TextEditorCodeExecutionToolResultContent) Type added in v0.0.12 

func (c *TextEditorCodeExecutionToolResultContent) Type() ContentType

type ThinkingContent 

type ThinkingContent struct {
	ID        string `json:"id,omitempty"`
	Thinking  string `json:"thinking"`
	Signature string `json:"signature,omitempty"`
	// Metadata carries provider-specific replay state that cannot safely use
	// Signature because its wire meaning differs between providers.
	Metadata ProviderMetadata `json:"metadata,omitempty"`
}

ThinkingContent is a content block that contains the LLM's internal thought process. The provider may use the signature to verify that the content was generated by the LLM.

Per Anthropic's documentation: It is only strictly necessary to send back thinking blocks when using tool use with extended thinking. Otherwise you can omit thinking blocks from previous turns, or let the API strip them for you if you pass them back.

func (*ThinkingContent) CloneContent added in v1.22.0 

func (c *ThinkingContent) CloneContent() Content

func (*ThinkingContent) MarshalJSON 

func (c *ThinkingContent) MarshalJSON() ([]byte, error)

func (*ThinkingContent) Type 

func (c *ThinkingContent) Type() ContentType

type ThinkingDisplay added in v1.6.0 

type ThinkingDisplay string

ThinkingDisplay controls how thinking content is returned in responses. 

const (
	// ThinkingDisplaySummarized returns a summary of the model's thinking. This
	// is the default on Claude Opus 4.6 and earlier 4.x models.
	ThinkingDisplaySummarized ThinkingDisplay = "summarized"
	// ThinkingDisplayOmitted returns thinking blocks with an empty thinking
	// field (the encrypted signature is still present for multi-turn
	// continuity). This is the default on Claude Fable 5, Mythos 5, Sonnet 5,
	// Opus 4.7, and Opus 4.8, and reduces time-to-first text token when
	// streaming.
	ThinkingDisplayOmitted ThinkingDisplay = "omitted"
)

type ThinkingType added in v1.6.0 

type ThinkingType string

ThinkingType controls the extended thinking mode used by the model. 

const (
	// ThinkingTypeAdaptive lets the model decide when and how much to think
	// based on request complexity. Recommended for Claude Opus 4.6+ and
	// Sonnet 4.6, and the only supported thinking mode on Opus 4.7 and 4.8.
	// Combine with WithReasoningEffort to guide thinking depth.
	ThinkingTypeAdaptive ThinkingType = "adaptive"
	// ThinkingTypeEnabled requests manual extended thinking with a fixed token
	// budget (see WithReasoningBudget). Not supported on Opus 4.7 and 4.8.
	ThinkingTypeEnabled ThinkingType = "enabled"
	// ThinkingTypeDisabled explicitly turns thinking off.
	ThinkingTypeDisabled ThinkingType = "disabled"
)

type Tool 

type Tool interface {
	// Name of the tool.
	Name() string

	// Description of the tool.
	Description() string

	// Schema describes the parameters used to call the tool.
	Schema() *schema.Schema
}

Tool is an interface that defines a tool that can be called by an LLM.

type ToolChoice 

type ToolChoice struct {
	Type ToolChoiceType `json:"type"`
	Name string         `json:"name,omitempty"`
}

ToolChoice influences the behavior of the LLM when choosing which tool to use.

type ToolChoiceType 

type ToolChoiceType string

ToolChoiceType is used to guide the LLM's choice of which tool to use. 

const (
	ToolChoiceTypeAuto ToolChoiceType = "auto"
	ToolChoiceTypeAny  ToolChoiceType = "any"
	ToolChoiceTypeTool ToolChoiceType = "tool"
	ToolChoiceTypeNone ToolChoiceType = "none"
)

func (ToolChoiceType) IsValid 

func (t ToolChoiceType) IsValid() bool

IsValid returns true if the ToolChoiceType is a known, valid value.

type ToolConfiguration 

type ToolConfiguration interface {

	// ToolConfiguration returns a map of configuration for the tool, when used
	// with the given provider.
	ToolConfiguration(providerName string) map[string]any
}

ToolConfiguration is an interface that may be implemented by a Tool to provide explicit JSON configuration to pass to the LLM provider.

type ToolDefinition 

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

ToolDefinition is a concrete implementation of the Tool interface. Note this does not provide a mechanism for calling the tool, but only for describing what the tool does so the LLM can understand it. You might not use this implementation if you use a full dive.Tool implementation in your app.

func NewToolDefinition 

func NewToolDefinition() *ToolDefinition

NewToolDefinition creates a new ToolDefinition.

func (*ToolDefinition) Description 

func (t *ToolDefinition) Description() string

Description returns the description of the tool, per the Tool interface.

func (*ToolDefinition) Name 

func (t *ToolDefinition) Name() string

Name returns the name of the tool, per the Tool interface.

func (*ToolDefinition) Schema 

func (t *ToolDefinition) Schema() *schema.Schema

Schema returns the schema of the tool, per the Tool interface.

func (*ToolDefinition) WithDescription 

func (t *ToolDefinition) WithDescription(description string) *ToolDefinition

WithDescription sets the description of the tool.

func (*ToolDefinition) WithName 

func (t *ToolDefinition) WithName(name string) *ToolDefinition

WithName sets the name of the tool.

func (*ToolDefinition) WithSchema 

func (t *ToolDefinition) WithSchema(schema *schema.Schema) *ToolDefinition

WithSchema sets the schema of the tool.

type ToolResultContent 

type ToolResultContent struct {
	ToolUseID    string        `json:"tool_use_id"`
	Content      any           `json:"content"`
	IsError      bool          `json:"is_error,omitempty"`
	CacheControl *CacheControl `json:"cache_control,omitempty"`
	// contains filtered or unexported fields
}

func NewToolResultContent 

func NewToolResultContent(toolUseID string, content any, isError bool) *ToolResultContent

NewToolResultContent creates a tool result content block.

func (*ToolResultContent) CloneContent added in v1.0.0 

func (c *ToolResultContent) CloneContent() Content

func (*ToolResultContent) DecodeContent added in v1.5.0 

func (c *ToolResultContent) DecodeContent(dst any) error

DecodeContent decodes the tool result's content into dst without the type loss that reading Content directly incurs after a JSON round-trip.

When ToolResultContent was populated via json.Unmarshal — which happens transparently during Message.Copy, session persistence, and cross-process suspend/resume — reading the Content field gives the generic decoded shape (map[string]any, []any, float64). DecodeContent instead replays the original JSON bytes into dst, so integers stay integers, typed structs decode into themselves, and slices keep their element types.

When the struct was constructed in memory and never round-tripped, DecodeContent falls back to marshaling Content and decoding into dst, so call sites work the same in both cases.

Returns nil without touching dst when the content is empty.

func (*ToolResultContent) MarshalJSON 

func (c *ToolResultContent) MarshalJSON() ([]byte, error)

func (*ToolResultContent) SetCacheControl 

func (c *ToolResultContent) SetCacheControl(cacheControl *CacheControl)

func (*ToolResultContent) Type 

func (c *ToolResultContent) Type() ContentType

func (*ToolResultContent) UnmarshalJSON added in v1.5.0 

func (c *ToolResultContent) UnmarshalJSON(data []byte) error

type ToolUseContent 

type ToolUseContent struct {
	ID           string          `json:"id"`
	Name         string          `json:"name"`
	Input        json.RawMessage `json:"input"`
	CacheControl *CacheControl   `json:"cache_control,omitempty"`
	// Metadata carries opaque provider-specific data (see ProviderMetadata) that
	// must be replayed to the provider on later requests — for example a Google
	// function-call thought signature.
	Metadata ProviderMetadata `json:"metadata,omitempty"`
}

func NewToolUseContent 

func NewToolUseContent(id, name string, input json.RawMessage) *ToolUseContent

NewToolUseContent creates a tool use content block.

func (*ToolUseContent) CloneContent added in v1.9.0 

func (c *ToolUseContent) CloneContent() Content

func (*ToolUseContent) MarshalJSON 

func (c *ToolUseContent) MarshalJSON() ([]byte, error)

func (*ToolUseContent) SetCacheControl added in v1.9.0 

func (c *ToolUseContent) SetCacheControl(cacheControl *CacheControl)

func (*ToolUseContent) Type 

func (c *ToolUseContent) Type() ContentType

type Usage 

type Usage struct {
	InputTokens              int `json:"input_tokens"`
	OutputTokens             int `json:"output_tokens"`
	CacheCreationInputTokens int `json:"cache_creation_input_tokens,omitempty"`
	CacheReadInputTokens     int `json:"cache_read_input_tokens,omitempty"`
	// ToolUseInputTokens is the subset of InputTokens attributable to results
	// from provider-managed tool executions that were supplied back to the
	// model. It is not additive, just as ReasoningTokens is not additive.
	ToolUseInputTokens int `json:"tool_use_input_tokens,omitempty"`
	// ReasoningTokens is the number of output tokens spent on reasoning, when
	// the provider reports it separately (e.g. OpenAI o-series, Grok reasoning
	// models, and Anthropic extended thinking). It is a subset of OutputTokens,
	// not additive.
	ReasoningTokens int `json:"reasoning_tokens,omitempty"`
	// ModalityTokens preserves provider-reported modality detail using the same
	// disjoint buckets as the aggregate fields. Keys are lower-case provider
	// modality names such as "text", "audio", "image", and "video".
	ModalityTokens map[string]ModalityTokenUsage `json:"modality_tokens,omitempty"`
	// The incomplete flags are true when aggregate usage is exact but the
	// provider omitted detail needed to assign that category to modalities.
	InputModalityTokenDetailsIncomplete     bool `json:"input_modality_token_details_incomplete,omitempty"`
	OutputModalityTokenDetailsIncomplete    bool `json:"output_modality_token_details_incomplete,omitempty"`
	CacheReadModalityTokenDetailsIncomplete bool `json:"cache_read_modality_token_details_incomplete,omitempty"`
	// ServiceTier records the serving tier used for this request when known.
	// Aggregating requests served by different tiers produces "mixed".
	ServiceTier string `json:"service_tier,omitempty"`
	// CacheCreationInputTokensUnavailable distinguishes a measured zero from a
	// provider that exposes cache reads but no cache-creation token metric.
	CacheCreationInputTokensUnavailable bool `json:"cache_creation_input_tokens_unavailable,omitempty"`
	// CostEstimateUnavailable prevents a provider-specific unknown price from
	// being replaced by a generic model-only estimate. Cost remains nil.
	CostEstimateUnavailable bool `json:"cost_estimate_unavailable,omitempty"`
	// Speed indicates which inference speed served the request, either "fast"
	// or "standard". Populated by Anthropic when fast mode is requested.
	Speed string `json:"speed,omitempty"`
	// Cost is the monetary cost of this usage. Providers attach an authoritative
	// charge when they report one; otherwise Dive may estimate from cataloged
	// list prices. Nil means cost is unknown, distinct from a known zero.
	Cost *Cost `json:"cost,omitempty"`
}

Usage contains token usage information for an LLM response.

The input-side token buckets are mutually disjoint. InputTokens counts uncached input; CacheCreationInputTokens counts the subset reported as cache writes; and CacheReadInputTokens counts cache hits. When a provider does not expose cache writes, InputTokens contains all uncached input and CacheCreationInputTokensUnavailable is true. The full input size is their sum, exposed by TotalInputTokens. This differs deliberately from ReasoningTokens, which is a subset of OutputTokens rather than an additive bucket.

func (*Usage) Absorb added in v1.24.0 

func (u *Usage) Absorb(other *Usage)

Absorb merges a cumulative usage frame into this usage object. Streaming providers report running totals for the whole message rather than increments (Anthropic documents message_delta usage as cumulative), so a later frame supersedes an earlier one field by field. A zero token count means the frame omitted that field, so token buckets merge by max rather than wholesale replacement — message_delta frames that carry only output_tokens must not erase the input buckets seeded by message_start. Use Add for aggregating usage across separate requests.

func (*Usage) Add 

func (u *Usage) Add(other *Usage)

Add incremental usage to this usage object.

func (*Usage) Copy 

func (u *Usage) Copy() *Usage

Copy returns a deep copy of the usage data.

func (Usage) TotalInputTokens added in v1.21.0 

func (u Usage) TotalInputTokens() int

TotalInputTokens returns the full input size across the disjoint input-side token buckets.

func (*Usage) UnmarshalJSON added in v1.12.0 

func (u *Usage) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts provider-native usage shapes and maps their cache and reasoning breakdowns onto Dive's canonical token buckets.

type WebSearchResult 

type WebSearchResult struct {
	Type             string `json:"type"`
	URL              string `json:"url"`
	Title            string `json:"title"`
	EncryptedContent string `json:"encrypted_content"`
	PageAge          string `json:"page_age"`
}

WebSearchResult is a single web search result within a WebSearchToolResultContent.

type WebSearchResultLocation 

type WebSearchResultLocation struct {
	Type           string `json:"type"` // "web_search_result_location"
	URL            string `json:"url"`
	Title          string `json:"title"`
	EncryptedIndex string `json:"encrypted_index,omitempty"`
	CitedText      string `json:"cited_text,omitempty"`
}

WebSearchResultLocation is a citation to a specific part of a web page.

func (*WebSearchResultLocation) IsCitation 

func (c *WebSearchResultLocation) IsCitation() bool

type WebSearchToolResultContent 

type WebSearchToolResultContent struct {
	ToolUseID string             `json:"tool_use_id"`
	Content   []*WebSearchResult `json:"content"`
	ErrorCode string             `json:"error_code,omitempty"`
}

WebSearchToolResultContent contains the results of a server-side web search tool call.

The API returns "content" in one of two shapes: an array of web search results on success, or an error object ({"type": "web_search_tool_result_error", "error_code": "..."}) when the server-side search failed. On error, ErrorCode is populated and Content is empty.

func (*WebSearchToolResultContent) MarshalJSON 

func (c *WebSearchToolResultContent) MarshalJSON() ([]byte, error)

func (*WebSearchToolResultContent) Type 

func (c *WebSearchToolResultContent) Type() ContentType

func (*WebSearchToolResultContent) UnmarshalJSON added in v1.8.0 

func (c *WebSearchToolResultContent) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts both documented variants of the "content" field: an array of web search results, or an error object whose error_code is surfaced via ErrorCode.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.