transparency

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 6, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package transparency provides full visibility into LLM invocations.

This is the core of Buckley's radical transparency philosophy: - Every token is counted and attributed to its source - Every cost is tracked and displayed - Every model response is traceable - Nothing is hidden from the user

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultPricingTable added in v1.1.0 

func DefaultPricingTable() map[string]ModelPricing

DefaultPricingTable returns per-model pricing for known Claude models.

Types

type ContextAudit 

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

ContextAudit tracks all context sources and their token contributions. This allows users to see exactly what consumed their token budget.

func NewContextAudit 

func NewContextAudit() *ContextAudit

NewContextAudit creates an empty context audit.

func (*ContextAudit) Add 

func (ca *ContextAudit) Add(name string, tokens int)

Add records a context source and its token count.

func (*ContextAudit) AddTruncated 

func (ca *ContextAudit) AddTruncated(name string, tokens, originalTokens int)

AddTruncated records a context source that was truncated.

func (*ContextAudit) AddWithBytes 

func (ca *ContextAudit) AddWithBytes(name string, tokens, bytes int)

AddWithBytes records a context source with both token and byte counts.

func (*ContextAudit) HasTruncation 

func (ca *ContextAudit) HasTruncation() bool

HasTruncation returns true if any source was truncated.

func (*ContextAudit) Merge 

func (ca *ContextAudit) Merge(other *ContextAudit)

Merge combines another audit into this one.

func (*ContextAudit) Sources 

func (ca *ContextAudit) Sources() []ContextSource

Sources returns all context sources, sorted by token count descending.

func (*ContextAudit) TotalTokens 

func (ca *ContextAudit) TotalTokens() int

TotalTokens returns the total token count across all sources.

type ContextSource 

type ContextSource struct {
	// Name identifies the source (e.g., "git diff", "AGENTS.md")
	Name string `json:"name"`

	// Tokens is the number of tokens from this source
	Tokens int `json:"tokens"`

	// Bytes is the raw byte count before tokenization
	Bytes int `json:"bytes"`

	// Truncated indicates if the source was truncated to fit budget
	Truncated bool `json:"truncated,omitempty"`

	// OriginalTokens is the token count before truncation (if truncated)
	OriginalTokens int `json:"original_tokens,omitempty"`
}

ContextSource represents a single source of context tokens.

func (ContextSource) Percentage 

func (cs ContextSource) Percentage(total int) float64

Percentage returns this source's percentage of total tokens.

type CostEntry 

type CostEntry struct {
	// Timestamp when the invocation occurred
	Timestamp time.Time `json:"timestamp"`

	// Model identifier
	Model string `json:"model"`

	// Tokens consumed
	Tokens TokenUsage `json:"tokens"`

	// Cost in USD
	Cost float64 `json:"cost"`

	// Latency of the request
	Latency time.Duration `json:"latency"`

	// InvocationID links to the full trace
	InvocationID string `json:"invocation_id,omitempty"`
}

CostEntry represents the cost of a single LLM invocation.

type CostLedger 

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

CostLedger tracks costs across a session. It provides running totals and historical data for transparency.

func NewCostLedger 

func NewCostLedger() *CostLedger

NewCostLedger creates an empty cost ledger.

func (*CostLedger) Entries 

func (cl *CostLedger) Entries() []CostEntry

Entries returns all cost entries.

func (*CostLedger) InvocationCount 

func (cl *CostLedger) InvocationCount() int

InvocationCount returns the number of LLM invocations.

func (*CostLedger) Record 

func (cl *CostLedger) Record(entry CostEntry)

Record adds a cost entry to the ledger.

func (*CostLedger) SessionTokens 

func (cl *CostLedger) SessionTokens() TokenUsage

SessionTokens returns total tokens for the current session.

func (*CostLedger) SessionTotal 

func (cl *CostLedger) SessionTotal() float64

SessionTotal returns the total cost for the current session.

func (*CostLedger) Summary 

func (cl *CostLedger) Summary() CostSummary

Summary returns aggregated cost data.

func (*CostLedger) TodayTotal 

func (cl *CostLedger) TodayTotal() float64

TodayTotal returns total cost for today (UTC).

type CostSummary 

type CostSummary struct {
	SessionCost     float64    `json:"session_cost"`
	TodayCost       float64    `json:"today_cost"`
	SessionTokens   TokenUsage `json:"session_tokens"`
	InvocationCount int        `json:"invocation_count"`
}

Summary returns a human-readable cost summary.

type MessageTrace 

type MessageTrace struct {
	Role    string `json:"role"`
	Content string `json:"content"`
	// Truncated length for display
	ContentLength int `json:"content_length"`
}

MessageTrace is a simplified message for tracing.

type ModelPricing 

type ModelPricing struct {
	// InputPerMillion is the cost per million input tokens
	InputPerMillion float64

	// OutputPerMillion is the cost per million output tokens
	OutputPerMillion float64

	// ReasoningPerMillion is the cost per million reasoning tokens (if separate)
	ReasoningPerMillion float64

	// CachedInputPerMillion is the cost for cached input tokens
	CachedInputPerMillion float64
}

ModelPricing contains per-model pricing information.

func (ModelPricing) Calculate 

func (mp ModelPricing) Calculate(usage TokenUsage) float64

Calculate computes the cost for given token usage.

type NoToolCallError 

type NoToolCallError struct {
	Expected string
	Got      string
}

NoToolCallError indicates the model didn't make an expected tool call.

func (*NoToolCallError) Error 

func (e *NoToolCallError) Error() string

type RequestTrace 

type RequestTrace struct {
	// Messages sent to the model
	Messages []MessageTrace `json:"messages"`

	// Tools provided to the model
	Tools []string `json:"tools,omitempty"`

	// Temperature setting
	Temperature float64 `json:"temperature"`

	// MaxTokens limit
	MaxTokens int `json:"max_tokens,omitempty"`
}

RequestTrace captures request details for debugging.

type ResponseTrace 

type ResponseTrace struct {
	// Raw response body (may be large)
	Raw json.RawMessage `json:"raw,omitempty"`

	// FinishReason from the model
	FinishReason string `json:"finish_reason"`

	// StopReason for Anthropic-style responses
	StopReason string `json:"stop_reason,omitempty"`
}

ResponseTrace captures response details for debugging.

type TokenUsage 

type TokenUsage struct {
	// Input tokens sent to the model
	Input int `json:"input"`

	// Output tokens received from the model
	Output int `json:"output"`

	// Reasoning tokens (for thinking models like kimi-k2)
	Reasoning int `json:"reasoning,omitempty"`

	// CachedInput tokens that were cache hits (reduced cost)
	CachedInput int `json:"cached_input,omitempty"`
}

TokenUsage tracks token consumption for an invocation.

func (TokenUsage) Total 

func (tu TokenUsage) Total() int

Total returns the total token count.

type Trace 

type Trace struct {
	// ID uniquely identifies this invocation
	ID string `json:"id"`

	// Timestamp when the invocation started
	Timestamp time.Time `json:"timestamp"`

	// Model used for this invocation
	Model string `json:"model"`

	// Provider (e.g., "openrouter", "anthropic")
	Provider string `json:"provider"`

	// Duration of the request
	Duration time.Duration `json:"duration"`

	// Context audit showing what was sent
	Context *ContextAudit `json:"context,omitempty"`

	// Tokens consumed
	Tokens TokenUsage `json:"tokens"`

	// Cost in USD
	Cost float64 `json:"cost"`

	// Request contains the raw request (for --trace mode)
	Request *RequestTrace `json:"request,omitempty"`

	// Response contains the raw response (for --trace mode)
	Response *ResponseTrace `json:"response,omitempty"`

	// ToolCalls made by the model
	ToolCalls []tools.ToolCall `json:"tool_calls,omitempty"`

	// Reasoning content from the model (for thinking models)
	Reasoning string `json:"reasoning,omitempty"`

	// Content is the text content (if any)
	Content string `json:"content,omitempty"`

	// Error if the invocation failed
	Error string `json:"error,omitempty"`
}

Trace captures everything about an LLM invocation. This is the core of radical transparency - nothing is hidden.

func (*Trace) FirstToolCall 

func (t *Trace) FirstToolCall() (tools.ToolCall, bool)

FirstToolCall returns the first tool call, if any.

func (*Trace) HasToolCalls 

func (t *Trace) HasToolCalls() bool

HasToolCalls returns true if the model made tool calls.

func (*Trace) UnmarshalToolCall 

func (t *Trace) UnmarshalToolCall(v any) error

UnmarshalToolCall unmarshals the first tool call into the given type.

type TraceBuilder 

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

TraceBuilder constructs a trace incrementally.

func NewTraceBuilder 

func NewTraceBuilder(id, model, provider string) *TraceBuilder

NewTraceBuilder starts building a new trace.

func (*TraceBuilder) Build 

func (tb *TraceBuilder) Build() *Trace

Build returns the trace without completing it (for error cases).

func (*TraceBuilder) Complete 

func (tb *TraceBuilder) Complete(tokens TokenUsage, cost float64) *Trace

Complete finalizes the trace with response data.

func (*TraceBuilder) WithContent 

func (tb *TraceBuilder) WithContent(content string) *TraceBuilder

WithContent adds text content.

func (*TraceBuilder) WithContext 

func (tb *TraceBuilder) WithContext(ctx *ContextAudit) *TraceBuilder

WithContext attaches context audit information.

func (*TraceBuilder) WithError 

func (tb *TraceBuilder) WithError(err error) *TraceBuilder

WithError marks the trace as failed.

func (*TraceBuilder) WithReasoning 

func (tb *TraceBuilder) WithReasoning(reasoning string) *TraceBuilder

WithReasoning adds reasoning content.

func (*TraceBuilder) WithRequest 

func (tb *TraceBuilder) WithRequest(req *RequestTrace) *TraceBuilder

WithRequest captures request details.

func (*TraceBuilder) WithToolCalls 

func (tb *TraceBuilder) WithToolCalls(calls []tools.ToolCall) *TraceBuilder

WithToolCalls adds tool calls to the trace.

type UsageSnapshot added in v1.1.0 

type UsageSnapshot struct {
	TotalInputTokens  uint64
	TotalOutputTokens uint64
	TotalCostUSD      float64
	Turns             uint32
	CostByModel       map[string]float64
}

UsageSnapshot is the cumulative state at any point.

type UsageTracker added in v1.1.0 

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

UsageTracker accumulates usage across turns with per-model pricing.

func NewUsageTracker added in v1.1.0 

func NewUsageTracker(pricingTable map[string]ModelPricing) *UsageTracker

func (*UsageTracker) BudgetUtilization added in v1.1.0 

func (u *UsageTracker) BudgetUtilization(sessionBudget float64) float64

BudgetUtilization returns session spend / session budget.

func (*UsageTracker) BuildCostFacts added in v1.1.0 

func (u *UsageTracker) BuildCostFacts(sessionBudget, dailyBudget, monthlyBudget float64) rules.CostFacts

BuildCostFacts creates CostFacts for arbiter evaluation.

func (*UsageTracker) Record added in v1.1.0 

func (u *UsageTracker) Record(modelID string, usage TokenUsage)

Record adds a turn's usage with the correct model pricing applied.

func (*UsageTracker) Snapshot added in v1.1.0 

func (u *UsageTracker) Snapshot() UsageSnapshot

Snapshot returns the current cumulative usage.

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.