analytics

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: May 15, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ClassifyTask 

func ClassifyTask(prompt string, response string) string

ClassifyTask determines the task type from a prompt/response pair. Returns one of: "simple", "generation", "debug", "refactor", "review", "chat".

func DetectMidTaskCompaction 

func DetectMidTaskCompaction(toolsBefore, toolsAfter []string) bool

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 LogEvent 

func LogEvent(name, sessionID string, properties map[string]interface{})

LogEvent logs an analytics event.

func SaveInsightsReport 

func SaveInsightsReport(report *InsightsReport) (string, error)

SaveInsightsReport saves an HTML report to disk.

func SaveTrace 

func SaveTrace(t *SessionTrace) error

SaveTrace saves a session trace.

func SuggestModel 

func SuggestModel(taskType string, currentModel string) string

SuggestModel recommends the cheapest adequate model for a task type. If currentModel is empty, it returns the recommended model for the task type.

func Summary 

func Summary() string

Summary returns a formatted analytics summary.

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 BudgetViolation added in v0.2.0 

type BudgetViolation struct {
	SLO       string
	Expected  float64
	Actual    float64
	Timestamp time.Time
	Duration  time.Duration
}

BudgetViolation records when an SLO was violated.

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.

func (*CommandTracker) Record 

func (t *CommandTracker) Record(cmd string, exitCode int, duration time.Duration, cwd string)

Record adds a command execution to the tracker.

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 DashModelStats added in v0.2.0 

type DashModelStats struct {
	Requests     int     `json:"requests"`
	Tokens       int     `json:"tokens"`
	CostUSD      float64 `json:"cost_usd"`
	AvgLatencyMs int     `json:"avg_latency_ms"`
	ErrorRate    float64 `json:"error_rate"`
}

DashModelStats tracks usage and performance per model for the dashboard.

type Dashboard added in v0.2.0 

type Dashboard struct {
	Sessions     []SessionSummary          `json:"sessions"`
	DailyStats   []DayStat                 `json:"daily_stats"`
	ModelUsage   map[string]DashModelStats `json:"model_usage"`
	ToolUsage    map[string]int            `json:"tool_usage"`
	TotalCostUSD float64                   `json:"total_cost_usd"`
	TotalTokens  int                       `json:"total_tokens"`
	ActiveDays   int                       `json:"active_days"`
}

Dashboard provides a local telemetry dashboard for hawk showing usage analytics, performance metrics, and session history in a terminal-friendly format.

func NewDashboard added in v0.2.0 

func NewDashboard() *Dashboard

NewDashboard creates an initialized empty Dashboard.

func (*Dashboard) Export added in v0.2.0 

func (d *Dashboard) Export() ([]byte, error)

Export serializes the dashboard data to JSON.

func (*Dashboard) Import added in v0.2.0 

func (d *Dashboard) Import(data []byte) error

Import deserializes JSON data into the dashboard.

func (*Dashboard) RecordSession added in v0.2.0 

func (d *Dashboard) RecordSession(summary SessionSummary)

RecordSession adds a session summary to the dashboard and updates aggregates.

func (*Dashboard) RenderCostChart added in v0.2.0 

func (d *Dashboard) RenderCostChart(days int) string

RenderCostChart renders an ASCII bar chart of daily costs for the given number of days.

func (*Dashboard) RenderModelBreakdown added in v0.2.0 

func (d *Dashboard) RenderModelBreakdown() string

RenderModelBreakdown renders a pie-chart-like breakdown with percentages for each model.

func (*Dashboard) RenderOverview added in v0.2.0 

func (d *Dashboard) RenderOverview() string

RenderOverview produces a terminal-friendly overview of usage analytics.

func (*Dashboard) RenderRecentSessions added in v0.2.0 

func (d *Dashboard) RenderRecentSessions(n int) string

RenderRecentSessions renders a table of the last n sessions.

func (*Dashboard) RenderTokenChart added in v0.2.0 

func (d *Dashboard) RenderTokenChart(days int) string

RenderTokenChart renders an ASCII bar chart of daily token usage for the given number of days.

type DateRange 

type DateRange struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

DateRange represents the time span of statistics.

type DayStat added in v0.2.0 

type DayStat struct {
	Date        time.Time     `json:"date"`
	Sessions    int           `json:"sessions"`
	Tokens      int           `json:"tokens"`
	CostUSD     float64       `json:"cost_usd"`
	AvgDuration time.Duration `json:"avg_duration"`
}

DayStat aggregates metrics for a single day.

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 PerfBudget added in v0.2.0 

type PerfBudget struct {
	SLOs       map[string]*SLO
	Violations []BudgetViolation
	// contains filtered or unexported fields
}

PerfBudget tracks agent performance against defined SLOs.

func NewPerfBudget added in v0.2.0 

func NewPerfBudget() *PerfBudget

NewPerfBudget creates a PerfBudget with default SLOs.

func (*PerfBudget) AddSLO added in v0.2.0 

func (pb *PerfBudget) AddSLO(slo SLO)

AddSLO adds or updates an SLO.

func (*PerfBudget) Check added in v0.2.0 

func (pb *PerfBudget) Check() map[string]string

Check evaluates all SLOs and returns status per SLO.

func (*PerfBudget) FormatDashboard added in v0.2.0 

func (pb *PerfBudget) FormatDashboard() string

FormatDashboard returns a formatted string representing the performance budget dashboard.

func (*PerfBudget) GetViolations added in v0.2.0 

func (pb *PerfBudget) GetViolations(since time.Time) []BudgetViolation

GetViolations returns violations that occurred since the given time.

func (*PerfBudget) ProjectTrend added in v0.2.0 

func (pb *PerfBudget) ProjectTrend(metric string) string

ProjectTrend analyzes measurements for a metric and returns the trend direction.

func (*PerfBudget) Record added in v0.2.0 

func (pb *PerfBudget) Record(metric string, value float64)

Record adds a measurement for the given metric.

func (*PerfBudget) Reset added in v0.2.0 

func (pb *PerfBudget) Reset()

Reset clears all measurements and violations.

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 SLO added in v0.2.0 

type SLO struct {
	Name         string
	Metric       string
	Target       float64
	Window       time.Duration
	Current      float64
	Measurements []float64
	Status       string // "met", "at_risk", "violated"
}

SLO defines a Service Level Objective for a performance metric.

type SessionAnalytics added in v0.2.0 

type SessionAnalytics struct {
	Sessions []SessionData
	// contains filtered or unexported fields
}

SessionAnalytics tracks and reports on agent behavior patterns over time.

func NewSessionAnalytics added in v0.2.0 

func NewSessionAnalytics() *SessionAnalytics

NewSessionAnalytics creates a new SessionAnalytics instance.

func (*SessionAnalytics) CostProjection added in v0.2.0 

func (sa *SessionAnalytics) CostProjection(daysAhead int) float64

CostProjection estimates cost for the given number of days ahead based on historical average daily spending.

func (*SessionAnalytics) DailyReport added in v0.2.0 

func (sa *SessionAnalytics) DailyReport(date time.Time) string

DailyReport generates a formatted report for the given date.

func (*SessionAnalytics) Export added in v0.2.0 

func (sa *SessionAnalytics) Export(format string) string

Export exports session data in the specified format ("csv" or "json").

func (*SessionAnalytics) FormatOverview added in v0.2.0 

func (sa *SessionAnalytics) FormatOverview() string

FormatOverview returns a comprehensive overview string combining key metrics.

func (*SessionAnalytics) ModelComparison added in v0.2.0 

func (sa *SessionAnalytics) ModelComparison() string

ModelComparison compares success rate, speed, and cost across models used.

func (*SessionAnalytics) ProductivityScore added in v0.2.0 

func (sa *SessionAnalytics) ProductivityScore() float64

ProductivityScore returns a composite score (0-100) based on success rate, efficiency (tokens per file modified), and speed.

func (*SessionAnalytics) Record added in v0.2.0 

func (sa *SessionAnalytics) Record(data SessionData)

Record adds a session data entry to the analytics store.

func (*SessionAnalytics) UsagePatterns added in v0.2.0 

func (sa *SessionAnalytics) UsagePatterns() []string

UsagePatterns returns human-readable insights about usage behavior.

func (*SessionAnalytics) WeeklyTrend added in v0.2.0 

func (sa *SessionAnalytics) WeeklyTrend() string

WeeklyTrend shows daily stats for the last 7 days with a sparkline.

type SessionData added in v0.2.0 

type SessionData struct {
	ID            string        `json:"id"`
	StartTime     time.Time     `json:"start_time"`
	Duration      time.Duration `json:"duration"`
	Model         string        `json:"model"`
	Provider      string        `json:"provider"`
	TokensIn      int           `json:"tokens_in"`
	TokensOut     int           `json:"tokens_out"`
	CostUSD       float64       `json:"cost_usd"`
	ToolCalls     int           `json:"tool_calls"`
	FilesModified int           `json:"files_modified"`
	TestsPassed   bool          `json:"tests_passed"`
	Success       bool          `json:"success"`
	TaskType      string        `json:"task_type"`
}

SessionData holds metrics for a single agent session.

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 SessionSummary added in v0.2.0 

type SessionSummary struct {
	ID            string        `json:"id"`
	Date          time.Time     `json:"date"`
	Duration      time.Duration `json:"duration"`
	Model         string        `json:"model"`
	Provider      string        `json:"provider"`
	TokensUsed    int           `json:"tokens_used"`
	CostUSD       float64       `json:"cost_usd"`
	ToolCalls     int           `json:"tool_calls"`
	FilesModified int           `json:"files_modified"`
	Success       bool          `json:"success"`
}

SessionSummary captures key metrics for a single session.

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.

func GetTraces 

func GetTraces() ([]*SessionTrace, error)

GetTraces returns all session traces.

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.

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.