Documentation
¶
Index ¶
- func ClassifyTask(prompt string, response string) string
- func DetectMidTaskCompaction(toolsBefore, toolsAfter []string) bool
- func ExportInsightsHTML(report *InsightsReport) string
- func FormatOptimizationReport(r *OptimizationReport) string
- func FormatStats(s *SessionStats) string
- func LogEvent(name, sessionID string, properties map[string]interface{})
- func SaveInsightsReport(report *InsightsReport) (string, error)
- func SaveTrace(t *SessionTrace) error
- func SuggestModel(taskType string, currentModel string) string
- func Summary() string
- type ActivityTracker
- func (a *ActivityTracker) EndExecution()
- func (a *ActivityTracker) EndUserInput()
- func (a *ActivityTracker) ExecTime() time.Duration
- func (a *ActivityTracker) StartExecution()
- func (a *ActivityTracker) StartUserInput()
- func (a *ActivityTracker) Summary() string
- func (a *ActivityTracker) UserTime() time.Duration
- type CommandContext
- type CommandTracker
- type CostEntry
- type DateRange
- type Event
- type InsightsFacet
- type InsightsReport
- type ModelSpend
- type ModelStats
- type OneShotTracker
- type OptimizationReport
- type Recommendation
- type SessionHealth
- type SessionStats
- type SessionTrace
- type TaskSpend
- type TurnCategory
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClassifyTask ¶
ClassifyTask determines the task type from a prompt/response pair. Returns one of: "simple", "generation", "debug", "refactor", "review", "chat".
func DetectMidTaskCompaction ¶
DetectMidTaskCompaction returns true if any tool name appears in both windows, indicating compaction interrupted active work.
func ExportInsightsHTML ¶
func ExportInsightsHTML(report *InsightsReport) string
ExportInsightsHTML generates an HTML report from insights.
func FormatOptimizationReport ¶
func FormatOptimizationReport(r *OptimizationReport) string
FormatOptimizationReport produces a human-readable optimization report.
func FormatStats ¶
func FormatStats(s *SessionStats) string
FormatStats produces a human-readable stats report.
func SaveInsightsReport ¶
func SaveInsightsReport(report *InsightsReport) (string, error)
SaveInsightsReport saves an HTML report to disk.
func SuggestModel ¶
SuggestModel recommends the cheapest adequate model for a task type. If currentModel is empty, it returns the recommended model for the task type.
Types ¶
type ActivityTracker ¶
type ActivityTracker struct {
// contains filtered or unexported fields
}
ActivityTracker tracks user typing vs CLI/agent execution time to provide a ratio of how much time the user spends vs how much the agent works.
func NewActivityTracker ¶
func NewActivityTracker() *ActivityTracker
NewActivityTracker creates a new ActivityTracker.
func (*ActivityTracker) EndExecution ¶
func (a *ActivityTracker) EndExecution()
EndExecution marks the end of an agent/tool execution period.
func (*ActivityTracker) EndUserInput ¶
func (a *ActivityTracker) EndUserInput()
EndUserInput marks the end of user input time.
func (*ActivityTracker) ExecTime ¶
func (a *ActivityTracker) ExecTime() time.Duration
ExecTime returns the accumulated execution duration.
func (*ActivityTracker) StartExecution ¶
func (a *ActivityTracker) StartExecution()
StartExecution marks the beginning of an agent/tool execution period.
func (*ActivityTracker) StartUserInput ¶
func (a *ActivityTracker) StartUserInput()
StartUserInput marks the beginning of user input time.
func (*ActivityTracker) Summary ¶
func (a *ActivityTracker) Summary() string
Summary returns a formatted summary: "User: 5m30s | Agent: 12m15s | Ratio: 2.2x"
func (*ActivityTracker) UserTime ¶
func (a *ActivityTracker) UserTime() time.Duration
UserTime returns the accumulated user input duration.
type CommandContext ¶
type CommandContext struct {
Command string `json:"command"`
ExitCode int `json:"exit_code"`
Duration time.Duration `json:"duration"`
CWD string `json:"cwd"`
}
CommandContext captures metadata about a shell command execution.
type CommandTracker ¶
type CommandTracker struct {
// contains filtered or unexported fields
}
CommandTracker records shell command executions for analytics.
func (*CommandTracker) AvgDuration ¶
func (t *CommandTracker) AvgDuration() time.Duration
AvgDuration returns the average duration across all recorded commands.
func (*CommandTracker) FailureRate ¶
func (t *CommandTracker) FailureRate() float64
FailureRate returns the fraction of commands with non-zero exit codes.
func (*CommandTracker) MostUsed ¶
func (t *CommandTracker) MostUsed(n int) []string
MostUsed returns the top n most frequently used commands.
type CostEntry ¶
type CostEntry struct {
SessionID string `json:"session_id"`
Model string `json:"model"`
TaskType string `json:"task_type"` // "simple", "generation", "debug", "refactor", "review", "chat"
InputTokens int `json:"input_tokens"`
OutputTokens int `json:"output_tokens"`
CostUSD float64 `json:"cost_usd"`
Duration time.Duration `json:"duration"`
Kept bool `json:"kept"` // was the output used/kept?
Timestamp time.Time `json:"timestamp"`
}
CostEntry represents a single LLM API call with cost metadata.
type Event ¶
type Event struct {
Name string `json:"name"`
Timestamp time.Time `json:"timestamp"`
SessionID string `json:"session_id,omitempty"`
Properties map[string]interface{} `json:"properties,omitempty"`
}
Event represents an analytics event.
type InsightsFacet ¶
type InsightsFacet struct {
Category string `json:"category"` // goals, outcomes, friction, success
Items []string `json:"items"`
}
InsightsFacet represents an extracted insight category.
type InsightsReport ¶
type InsightsReport struct {
GeneratedAt time.Time `json:"generated_at"`
SessionsScanned int `json:"sessions_scanned"`
DateRange DateRange `json:"date_range"`
Facets []InsightsFacet `json:"facets"`
TopPatterns []string `json:"top_patterns"`
Recommendations []string `json:"recommendations"`
Stats *SessionStats `json:"stats,omitempty"`
}
InsightsReport holds a complete cross-session analysis.
func GenerateInsights ¶
func GenerateInsights(days int, analysisFn func(content string) ([]InsightsFacet, error)) (*InsightsReport, error)
GenerateInsights analyzes session transcripts to extract patterns and recommendations.
type ModelSpend ¶
type ModelSpend struct {
Model string `json:"model"`
TotalCost float64 `json:"total_cost"`
Calls int `json:"calls"`
AvgTokens int `json:"avg_tokens"`
}
ModelSpend aggregates cost data for a specific model.
type ModelStats ¶
type ModelStats struct {
Model string `json:"model"`
Tokens int64 `json:"tokens"`
Requests int `json:"requests"`
AvgLatency float64 `json:"avg_latency_ms"`
Cost float64 `json:"cost"`
}
ModelStats tracks usage per model.
type OneShotTracker ¶
type OneShotTracker struct {
// contains filtered or unexported fields
}
OneShotTracker tracks the percentage of edit turns that succeed without retries.
func (*OneShotTracker) Rate ¶
func (t *OneShotTracker) Rate() float64
Rate returns the one-shot success rate as a percentage (0-100).
func (*OneShotTracker) RecordTurn ¶
func (t *OneShotTracker) RecordTurn(toolNames []string)
RecordTurn records a turn's tool usage for one-shot rate calculation. An edit turn immediately followed by another edit turn = retry.
func (*OneShotTracker) Stats ¶
func (t *OneShotTracker) Stats() (total, firstTry int)
Stats returns total edits and first-try successes.
type OptimizationReport ¶
type OptimizationReport struct {
TotalSpend float64 `json:"total_spend"`
WastedSpend float64 `json:"wasted_spend"` // spend on simple tasks with expensive models
AbandonedSpend float64 `json:"abandoned_spend"` // spend on outputs that were discarded
ProductiveSpend float64 `json:"productive_spend"` // spend on outputs that were kept
YieldRate float64 `json:"yield_rate"` // productive / total
Recommendations []Recommendation `json:"recommendations"`
ByModel map[string]*ModelSpend `json:"by_model"`
ByTaskType map[string]*TaskSpend `json:"by_task_type"`
}
OptimizationReport contains spend analysis and recommendations.
func Analyze ¶
func Analyze(entries []CostEntry) *OptimizationReport
Analyze examines cost entries and produces optimization recommendations.
type Recommendation ¶
type Recommendation struct {
Type string `json:"type"` // "downgrade", "batch", "cache"
Description string `json:"description"`
Savings float64 `json:"savings"` // estimated USD savings
}
Recommendation represents a cost optimization suggestion.
type SessionHealth ¶
type SessionHealth struct {
Score int `json:"score"`
Grade string `json:"grade"`
Signals map[string]int `json:"signals"`
}
SessionHealth represents the computed health of a session.
func ComputeSessionHealth ¶
func ComputeSessionHealth(toolCalls, toolErrors, editRetries, compactions, midTaskCompactions int, outcome string) SessionHealth
ComputeSessionHealth scores a session from 0-100 based on penalty signals.
type SessionStats ¶
type SessionStats struct {
TotalSessions int `json:"total_sessions"`
TotalMessages int `json:"total_messages"`
TotalDuration time.Duration `json:"total_duration"`
TotalTokens int64 `json:"total_tokens"`
TotalCost float64 `json:"total_cost"`
ToolUsage map[string]int `json:"tool_usage"`
ModelUsage map[string]ModelStats `json:"model_usage"`
LanguageStats map[string]int `json:"language_stats"`
GitCommits int `json:"git_commits"`
ActivityHeatmap [7][24]int `json:"activity_heatmap"` // [weekday][hour]
PeakDay time.Weekday `json:"peak_day"`
PeakHour int `json:"peak_hour"`
DateRange DateRange `json:"date_range"`
}
SessionStats holds aggregated statistics for a user's sessions.
func ComputeStats ¶
func ComputeStats(days int) (*SessionStats, error)
ComputeStats aggregates statistics from session event logs.
type SessionTrace ¶
type SessionTrace struct {
SessionID string `json:"session_id"`
StartTime time.Time `json:"start_time"`
EndTime time.Time `json:"end_time,omitempty"`
Provider string `json:"provider"`
Model string `json:"model"`
MessageCount int `json:"message_count"`
ToolCalls int `json:"tool_calls"`
CostUSD float64 `json:"cost_usd"`
}
SessionTrace tracks session lifecycle events.
type TaskSpend ¶
type TaskSpend struct {
TaskType string `json:"task_type"`
TotalCost float64 `json:"total_cost"`
Calls int `json:"calls"`
SuggestedModel string `json:"suggested_model"` // cheaper model that would suffice
}
TaskSpend aggregates cost data for a specific task type.
type TurnCategory ¶
type TurnCategory string
TurnCategory classifies what a conversation turn was about.
const ( CategoryCoding TurnCategory = "coding" CategoryDebugging TurnCategory = "debugging" CategoryTesting TurnCategory = "testing" CategoryExploration TurnCategory = "exploration" CategoryPlanning TurnCategory = "planning" CategoryGitOps TurnCategory = "git_ops" CategoryRefactoring TurnCategory = "refactoring" CategoryConversation TurnCategory = "conversation" )
func ClassifyTurn ¶
func ClassifyTurn(toolNames []string, userMessage string) TurnCategory
ClassifyTurn determines the category of a turn from tool names and user message. Deterministic — no LLM calls.