token

Documentation

Overview

Package token is the Stage-1 namespace for token-related types and functions in package engine. See ../REFACTOR_PLAN.md.

New code in hawk should import this package instead of reaching into engine for token symbols. Implementation will move here in Stage 2.

Index

• func ClassifyTaskComplexity(task string) string
• func CompressForContext(text string, budget int) (string, int)
• func CountTokens(text string) int
• func CountTokensFast(text string) int
• func DynamicMaxTokens(messages []types.EyrieMessage, contextSize int, taskType string) int
• func EstimateMessageTokens(m types.EyrieMessage) int
• func EstimateTokens(msgs []types.EyrieMessage) int
• func FormatPrediction(pred *Prediction, model string) string
• func WarnIfExpensive(pred *Prediction, budgetUSD float64) string
• type BudgetAlert
• type Prediction
• type PredictionRecord
• type TokenEntry
• type TokenPredictor
  • func NewTokenPredictor() *TokenPredictor
  • func (tp *TokenPredictor) Calibrate()
  • func (tp *TokenPredictor) EstimateCost(tokens int, model string) float64
  • func (tp *TokenPredictor) GetAccuracy(model string) float64
  • func (tp *TokenPredictor) Predict(task string, contextSize int, model string) *Prediction
  • func (tp *TokenPredictor) RecordActual(taskType string, predicted, actual int, model string)
• type TokenReporter
  • func NewTokenReporter(sessionBudget int) *TokenReporter
  • func (tr *TokenReporter) CheckBudget() *BudgetAlert
  • func (tr *TokenReporter) FormatAlert(alert *BudgetAlert) string
  • func (tr *TokenReporter) GetHistory(last int) []TokenEntry
  • func (tr *TokenReporter) GetRemaining() int
  • func (tr *TokenReporter) GetUsageRate() float64
  • func (tr *TokenReporter) ProjectCompletion() time.Duration
  • func (tr *TokenReporter) Record(input, output int, model, tool string, cost float64)
  • func (tr *TokenReporter) RenderBreakdown() string
  • func (tr *TokenReporter) RenderLive() string
  • func (tr *TokenReporter) Reset()

Functions

func ClassifyTaskComplexity

func ClassifyTaskComplexity(task string) string

ClassifyTaskComplexity categorizes a task description into a complexity tier.

func CompressForContext

func CompressForContext(text string, budget int) (string, int)

CompressForContext compresses text to fit within a token budget, returning the compressed text and the final token count.

func CountTokens

func CountTokens(text string) int

CountTokens returns a precise BPE-based token count for the given text.

func CountTokensFast

func CountTokensFast(text string) int

CountTokensFast returns a fast heuristic token estimate for the given text.

func DynamicMaxTokens

func DynamicMaxTokens(messages []types.EyrieMessage, contextSize int, taskType string) int

DynamicMaxTokens calculates the optimal max_tokens for a request based on: - Whether the last few turns were tool-call-heavy (reduce to 4096) - Whether the user asked a question expecting text (8192) - Whether this is a code generation task (16384) - The remaining context budget (don't exceed model's limit)

Research basis: Output tokens are 3-5x more expensive than input tokens. Most tool-call turns only need 200-2000 tokens of output.

func EstimateMessageTokens

func EstimateMessageTokens(m types.EyrieMessage) int

func EstimateTokens

func EstimateTokens(msgs []types.EyrieMessage) int

func FormatPrediction

func FormatPrediction(pred *Prediction, model string) string

FormatPrediction returns a human-readable summary of a token prediction.

func WarnIfExpensive

func WarnIfExpensive(pred *Prediction, budgetUSD float64) string

WarnIfExpensive returns a warning string if the predicted cost exceeds 10% of the remaining budget. Returns empty string if within budget.

Types

type BudgetAlert

type BudgetAlert struct {
	Level      string // "info", "warning", "critical"
	Message    string
	Triggered  time.Time
	Percentage float64
}

BudgetAlert represents a budget threshold notification.

type Prediction

type Prediction struct {
	InputTokens   int
	OutputTokens  int
	TotalTokens   int
	EstimatedCost float64
	Confidence    float64
	Reasoning     string
}

Prediction holds a token usage estimate for a task.

type PredictionRecord

type PredictionRecord struct {
	TaskType  string
	Predicted int
	Actual    int
	Model     string
	Timestamp time.Time
	Accuracy  float64
}

PredictionRecord stores one prediction-vs-actual pair for calibration.

type TokenEntry

type TokenEntry struct {
	Timestamp    time.Time
	InputTokens  int
	OutputTokens int
	Model        string
	ToolName     string
	CostUSD      float64
	Cumulative   int
}

TokenEntry records a single token usage event.

type TokenPredictor

type TokenPredictor struct {
	History      []PredictionRecord
	ModelFactors map[string]float64
	// contains filtered or unexported fields
}

TokenPredictor estimates how many tokens a task will consume before execution. It maintains a history of predictions vs actuals to calibrate future estimates.

func NewTokenPredictor

func NewTokenPredictor() *TokenPredictor

NewTokenPredictor creates a TokenPredictor with default model factors.

func (*TokenPredictor) Calibrate

func (tp *TokenPredictor) Calibrate()

Calibrate adjusts ModelFactors based on prediction accuracy history. If predictions consistently under-predict for a model, increase its factor. If predictions consistently over-predict, decrease its factor.

func (*TokenPredictor) EstimateCost

func (tp *TokenPredictor) EstimateCost(tokens int, model string) float64

EstimateCost calculates the USD cost for a given token count and model. It splits tokens roughly 60/40 input/output for a blended rate.

func (*TokenPredictor) GetAccuracy

func (tp *TokenPredictor) GetAccuracy(model string) float64

GetAccuracy returns the mean absolute percentage error (MAPE) for predictions of the given model. Lower is better. Returns 0 if no history exists.

func (*TokenPredictor) Predict

func (tp *TokenPredictor) Predict(task string, contextSize int, model string) *Prediction

Predict estimates token usage for a task given its description, context size, and model.

func (*TokenPredictor) RecordActual

func (tp *TokenPredictor) RecordActual(taskType string, predicted, actual int, model string)

RecordActual records the actual token usage after task completion for calibration.

type TokenReporter

type TokenReporter struct {
	Entries       []TokenEntry
	SessionBudget int
	SessionSpent  int
	Alerts        []BudgetAlert
	// contains filtered or unexported fields
}

TokenReporter provides real-time visibility into token spending and projections throughout a session.

func NewTokenReporter

func NewTokenReporter(sessionBudget int) *TokenReporter

NewTokenReporter creates a TokenReporter with the given session budget.

func (*TokenReporter) CheckBudget

func (tr *TokenReporter) CheckBudget() *BudgetAlert

CheckBudget evaluates current spending against the session budget and returns an alert if a threshold has been newly crossed.

func (*TokenReporter) FormatAlert

func (tr *TokenReporter) FormatAlert(alert *BudgetAlert) string

FormatAlert returns a formatted string representation of a BudgetAlert.

func (*TokenReporter) GetHistory

func (tr *TokenReporter) GetHistory(last int) []TokenEntry

GetHistory returns the last n token entries. If last exceeds the number of entries, all entries are returned.

func (*TokenReporter) GetRemaining

func (tr *TokenReporter) GetRemaining() int

GetRemaining returns the number of tokens remaining in the session budget.

func (*TokenReporter) GetUsageRate

func (tr *TokenReporter) GetUsageRate() float64

GetUsageRate returns the token usage rate in tokens per minute over the session duration.

func (*TokenReporter) ProjectCompletion

func (tr *TokenReporter) ProjectCompletion() time.Duration

ProjectCompletion estimates the remaining time until the budget is exhausted at the current usage rate.

func (*TokenReporter) Record

func (tr *TokenReporter) Record(input, output int, model, tool string, cost float64)

Record logs a token usage event, updates cumulative totals, and checks budget thresholds.

func (*TokenReporter) RenderBreakdown

func (tr *TokenReporter) RenderBreakdown() string

RenderBreakdown returns a detailed breakdown of token usage by input/output, model, and tool.

func (*TokenReporter) RenderLive

func (tr *TokenReporter) RenderLive() string

RenderLive returns a compact single-block status display showing current token usage, rate, ETA, and last tool usage.

func (*TokenReporter) Reset

func (tr *TokenReporter) Reset()

Reset clears all recorded entries, spent tokens, and alerts, keeping the session budget intact.