Documentation
¶
Overview ¶
Package overview provides execution lifecycle tracking for AI client sessions. It collects token usage, tool call statistics, cost breakdowns, and the full request/response history produced during a single execution run. The central type is Overview; use OverviewFromContext to obtain or create an instance bound to a context.Context, and Overview.CostSummary to retrieve a detailed cost breakdown after execution completes.
Index ¶
- type Overview
- func (overview *Overview) AddRequest(request *ai.ChatRequest)
- func (overview *Overview) AddResponse(response *ai.ChatResponse)
- func (overview *Overview) AddToolCalls(tools []ai.ToolCall)
- func (overview *Overview) AddToolExecutionCost(toolName string, toolMetrics *cost.ToolMetrics)
- func (overview *Overview) CostSummary() cost.CostSummary
- func (overview *Overview) EndExecution()
- func (overview *Overview) ExecutionDuration() time.Duration
- func (overview *Overview) IncludeUsage(usage *ai.Usage)
- func (overview *Overview) SetComputeCost(computeCost *cost.ComputeCost)
- func (overview *Overview) SetModelCost(modelCost *cost.ModelCost)
- func (overview *Overview) StartExecution()
- func (overview *Overview) ToContext(ctx context.Context) context.Context
- func (overview *Overview) TotalCost() float64
- type StructuredOverview
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Overview ¶
type Overview struct {
LastResponse *ai.ChatResponse `json:"last_response,omitempty"`
Requests []*ai.ChatRequest `json:"requests"`
Responses []*ai.ChatResponse `json:"responses"`
TotalUsage ai.Usage `json:"total_usage"`
ToolCallStats map[string]int `json:"tool_calls,omitempty"`
// ToolCosts tracks the accumulated cost per tool
ToolCosts map[string]float64 `json:"tool_costs,omitempty"`
// ModelCost is the pricing configuration for the model (optional)
ModelCost *cost.ModelCost `json:"model_cost,omitempty"`
// ExecutionStartTime marks when the execution started
ExecutionStartTime time.Time `json:"execution_start_time,omitempty"`
// ExecutionEndTime marks when the execution ended
ExecutionEndTime time.Time `json:"execution_end_time,omitempty"`
// ComputeCost is the infrastructure/compute pricing configuration (optional)
// Examples: AWS Lambda, VM cost, container runtime cost
ComputeCost *cost.ComputeCost `json:"compute_cost,omitempty"`
}
Overview aggregates execution statistics, token usage, cost tracking, and request/response history for a single execution lifecycle. It is the primary carrier of observability data produced by the AI client and is stored in a context.Context via Overview.ToContext so that all layers of a call-stack can contribute to the same shared instance. Use OverviewFromContext to retrieve or lazily create an Overview from a context.
func OverviewFromContext ¶
OverviewFromContext retrieves the Overview from the context, creating one if it does not already exist. The context pointer is updated in-place when a new Overview is created so callers see the enriched context.
func (*Overview) AddRequest ¶
func (overview *Overview) AddRequest(request *ai.ChatRequest)
AddRequest appends a chat request to the overview's request history.
func (*Overview) AddResponse ¶
func (overview *Overview) AddResponse(response *ai.ChatResponse)
AddResponse appends a chat response to the overview's response history and updates the last response reference.
func (*Overview) AddToolCalls ¶
AddToolCalls records tool call invocations in the overview statistics.
func (*Overview) AddToolExecutionCost ¶
func (overview *Overview) AddToolExecutionCost(toolName string, toolMetrics *cost.ToolMetrics)
AddToolExecutionCost records the cost of a tool execution.
func (*Overview) CostSummary ¶
func (overview *Overview) CostSummary() cost.CostSummary
CostSummary returns a detailed breakdown of all costs accumulated during the execution. The returned cost.CostSummary contains per-tool execution costs and invocation counts, model input/output/cached/reasoning costs derived from token usage and the configured cost.ModelCost, and compute/infrastructure costs derived from the measured execution duration and the configured cost.ComputeCost. Currency is always "USD". Call Overview.TotalCost when only the scalar total is needed.
func (*Overview) EndExecution ¶
func (overview *Overview) EndExecution()
EndExecution marks the end of execution for compute cost tracking.
func (*Overview) ExecutionDuration ¶
ExecutionDuration returns the total execution duration. Returns 0 if execution hasn't started or ended.
func (*Overview) IncludeUsage ¶
IncludeUsage accumulates token usage from an AI response into the overview totals.
func (*Overview) SetComputeCost ¶
func (overview *Overview) SetComputeCost(computeCost *cost.ComputeCost)
SetComputeCost attaches an infrastructure pricing configuration so that Overview.CostSummary can calculate the cost of the execution environment (e.g. AWS Lambda, VM, or container runtime) proportional to the duration measured between Overview.StartExecution and Overview.EndExecution. Calling this is optional; omitting it leaves compute costs as zero.
func (*Overview) SetModelCost ¶
SetModelCost attaches a model pricing configuration so that Overview.CostSummary and Overview.TotalCost can calculate per-token input, output, cached, and reasoning costs. Calling this is optional; omitting it leaves all model cost fields in the returned cost.CostSummary as zero.
func (*Overview) StartExecution ¶
func (overview *Overview) StartExecution()
StartExecution marks the start of execution for compute cost tracking.
func (*Overview) ToContext ¶
ToContext stores the Overview in the given context under a private key and returns the enriched context. The private key prevents collisions with other packages that also use context values. Callers should retrieve the stored value via OverviewFromContext rather than accessing the context directly, so that nil-context and type-assertion edge cases are handled uniformly. If ctx is nil, context.Background() is used as the base.
type StructuredOverview ¶
type StructuredOverview[T any] struct { Overview // Data holds the strongly-typed value parsed from the final AI response. // It is populated by structured execution patterns (e.g. StructuredPattern[T]) // and is nil when the response could not be parsed into T. Data *T `json:"data,omitempty"` }
StructuredOverview extends Overview with parsed structured data from the final response. This is used by structured patterns (e.g., StructuredPattern[T]) to provide both execution statistics and the parsed final result.
Source Files