model

Documentation

Overview

Package model — extension types for the 98-feature implementation. These types are used by feature packages (budget, trends, analytics, etc.) and are independent of Devin CLI's schema.

Package model defines the normalized data structures used across devinmonitor.

These types are independent of Devin CLI's internal SQLite schema so that the reader layer can adapt to schema changes without touching reports/UI.

Index

• func DayStart(t time.Time) time.Time
• func EstimateCost(p Pricing, input, output, cacheRead, cacheWrite int64) float64
• func Percentile(xs []float64, p float64) float64
• type AlertItem
• type Budget
• type BurnRate
• type CacheStats
• type CompactionEvent
• type ContextAnalysis
• type ContributionDay
• type CostBreakdown
• type CostProjection
• type EfficiencyScore
• type FilterOptions
• type HeatmapCell
• type Message
• type Metrics
• type ModelCompareRow
• type ModelComparison
• type ModelStats
• type Notification
• type OneShotRate
• type PeriodComparison
• type Pricing
  • func AllPricing() []Pricing
  • func LookupPricing(model string) Pricing
• type ProjectDetail
• type PromptHistoryEntry
• type RenderedCommit
• type SearchResult
• type Session
• type SessionListItem
• type SubAgentCall
• type TaskCategory
• type TimeBucket
• type ToolAttribution
• type ToolCall
• type ToolCallStateEntry
• type TrendPoint
• type WasteFinding

Functions

func DayStart

func DayStart(t time.Time) time.Time

DayStart returns t truncated to midnight local.

func EstimateCost

func EstimateCost(p Pricing, input, output, cacheRead, cacheWrite int64) float64

EstimateCost computes an estimated USD cost from token counts. Only meaningful when Devin's credit/ACU is zero (free models).

func Percentile

func Percentile(xs []float64, p float64) float64

Percentile returns the p-th percentile (0-100) of xs. Returns 0 if empty.

Types

type AlertItem

type AlertItem struct {
	Kind     string `json:"kind"`     // low_context, idle, ghost, budget
	Severity string `json:"severity"` // info, warning, critical
	Message  string `json:"message"`
}

AlertItem is a single alert for `alerts --json`.

type Budget

type Budget struct {
	Daily   float64 // USD
	Weekly  float64
	Monthly float64
}

Budget holds user-configured spending limits.

type BurnRate

type BurnRate struct {
	PerHour  float64 // USD/hr based on recent activity
	PerDay   float64 // USD/day extrapolated
	PerWeek  float64
	PerMonth float64
}

BurnRate computes real-time spending velocity.

type CacheStats

type CacheStats struct {
	CacheRead   int64
	CacheWrite  int64
	InputTokens int64
	HitRatio    float64 // cache_read / (cache_read + input_tokens)
	Leverage    float64 // cache_read / total_input
	SavingsUSD  float64 // estimated cost saved by caching
}

CacheStats holds cache efficiency metrics.

type CompactionEvent

type CompactionEvent struct {
	SessionID    string
	Timestamp    time.Time
	BeforeTokens int
	AfterTokens  int
}

CompactionEvent marks a context window compaction.

type ContextAnalysis

type ContextAnalysis struct {
	SessionID   string
	TotalTokens int64
	ByTool      map[string]int64 // tool name → estimated token contribution
	ByCategory  map[string]int64 // message type → token contribution
}

ContextAnalysis breaks down what fills a session's context window.

type ContributionDay

type ContributionDay struct {
	Date  time.Time
	Count int
	Cost  float64
	Level int // 0-4 intensity level
}

ContributionDay is one day in a GitHub-style contribution calendar.

type CostBreakdown

type CostBreakdown struct {
	PerRequest float64
	PerSession float64
	PerToken   float64
	PerDay     float64
}

CostBreakdown holds per-unit cost metrics.

type CostProjection

type CostProjection struct {
	PredictedMonthEnd float64 // predicted total spend by end of current month
	RemainingBudget   float64 // remaining budget (if configured)
	DaysToExhaust     int     // days until budget exhausted (0 = already over)
	Confidence        float64 // 0-1, based on data volume

}

CostProjection predicts future spending based on historical patterns.

type EfficiencyScore

type EfficiencyScore struct {
	TokensPerDollar  float64
	TokensPerRequest float64
	OutputVerbosity  float64 // output_tokens / request
	CacheSavingsPct  float64
}

EfficiencyScore is a composite token efficiency metric.

type FilterOptions

type FilterOptions struct {
	Model      string
	Project    string
	Mode       string // normal/plan/bypass
	FromDate   time.Time
	ToDate     time.Time
	SearchText string
	SortBy     string // cost, tokens, context, duration, recent
	SortDesc   bool
}

FilterOptions controls session filtering.

type HeatmapCell

type HeatmapCell struct {
	Weekday int // 0=Sunday
	Hour    int // 0-23
	Count   int // activity count
	Cost    float64
}

HeatmapCell is one cell in an activity heatmap (weekday × hour).

type Message

type Message struct {
	NodeID     int
	Role       string // system / user / assistant / tool
	Content    string
	CreatedAt  time.Time
	ToolCallID string // for role=tool messages: the tool_call_id this result belongs to
	// Assistant-only fields (zero for other roles).
	Metrics            *Metrics
	FinishReason       string
	GenerationModel    string
	RequestID          string
	ToolCalls          []ToolCall
	NumTokensPreceding int // context size at this point (if available)
}

Message is a single chat message node.

type Metrics

type Metrics struct {
	TTFTMs           float64 // time to first token
	TotalTimeMs      float64
	InputTokens      int64
	OutputTokens     int64
	CacheReadTokens  int64
	CacheWriteTokens int64
	TokensPerSec     float64
}

Metrics holds per-request performance/usage data from assistant messages.

type ModelCompareRow

type ModelCompareRow struct {
	Name         string
	Requests     int
	InputTokens  int64
	OutputTokens int64
	Cost         float64
	AvgLatency   float64
	TokensPerSec float64
	CacheHitPct  float64
}

ModelCompareRow is one row in a model comparison.

type ModelComparison

type ModelComparison struct {
	Models []ModelCompareRow
}

ModelComparison compares two or more models side by side.

type ModelStats

type ModelStats struct {
	Name         string
	Requests     int
	InputTokens  int64
	OutputTokens int64
	CacheRead    int64
	CacheWrite   int64
	CreditCost   float64
	ACUCost      float64
	// Latency distribution (ms).
	TTFTs        []float64
	TotalTimes   []float64
	TokensPerSec []float64
	// Finish reason counts.
	FinishReasons map[string]int
}

ModelStats aggregates usage for a single model across sessions.

type Notification

type Notification struct {
	Title string
	Body  string
	Level string // info, warning, critical
}

Notification is a desktop or webhook notification payload.

type OneShotRate

type OneShotRate struct {
	TotalEdits  int
	Retries     int
	OneShotPct  float64        // % of edits that succeeded first try
	FileRetries map[string]int // file_path → retry count
}

OneShotRate measures edit success without retries.

type PeriodComparison

type PeriodComparison struct {
	Current  TimeBucket
	Previous TimeBucket
	DeltaPct map[string]float64 // metric name → % change
}

PeriodComparison compares two time periods side by side.

type Pricing

type Pricing struct {
	Model          string
	InputPerM      float64 // USD per 1M input tokens
	OutputPerM     float64 // USD per 1M output tokens
	CacheReadPerM  float64
	CacheWritePerM float64
	Free           bool
}

Pricing is the per-model token price table (USD per million tokens). Used as an estimate when Devin's own credit/ACU fields are zero (e.g. free models). Credit/ACU from sessions.metadata is authoritative when non-zero; this is only a fallback.

func AllPricing

func AllPricing() []Pricing

AllPricing returns the built-in pricing table (for display/export).

func LookupPricing

func LookupPricing(model string) Pricing

LookupPricing returns pricing for a model name, with a fuzzy match fallback. Unknown models return a zero-value Pricing (caller treats as free/unknown).

type ProjectDetail

type ProjectDetail struct {
	Name           string
	Path           string
	Sessions       int
	Cost           float64
	Tokens         int64
	DailyBreakdown []TrendPoint
	ModelBreakdown map[string]*ModelStats
	ToolBreakdown  map[string]int
}

ProjectDetail holds drill-down data for a single project.

type PromptHistoryEntry

type PromptHistoryEntry struct {
	ID        int
	Content   string
	Timestamp time.Time
	SessionID string
	IsShell   bool
}

PromptHistoryEntry is a single prompt from prompt_history table.

type RenderedCommit

type RenderedCommit struct {
	ID             int
	SessionID      string
	SequenceNumber int
	HTML           string
	CreatedAt      time.Time
}

RenderedCommit is a rendered commit HTML from rendered_commits table.

type SearchResult

type SearchResult struct {
	SessionID string
	NodeID    int
	Role      string
	Snippet   string
	Timestamp time.Time
}

SearchResult is a full-text search match.

type Session

type Session struct {
	ID             string
	WorkingDir     string
	BackendType    string
	Model          string
	AgentMode      string // normal / plan / bypass
	CreatedAt      time.Time
	LastActivityAt time.Time
	Title          string
	MainChainID    int
	Hidden         bool
	WorkspaceDirs  []string
	// Cost from Devin's own accounting (authoritative when non-zero).
	CreditCost float64
	ACUCost    float64
	// Aggregated from assistant messages.
	Messages       []Message
	InputTokens    int64
	OutputTokens   int64
	CacheRead      int64
	CacheWrite     int64
	ToolCalls      map[string]int // tool name -> count
	AssistantCount int            // number of assistant turns (= requests)
	// LatestModel is the generation_model from the most recent assistant
	// message. More accurate than the session-level Model field (which is
	// set at creation time and doesn't update when the user switches models).
	LatestModel string
	// SubAgentCalls contains all run_subagent invocations in this session.
	SubAgentCalls []SubAgentCall
	// ReadSubAgentCalls counts how many times the main agent called read_subagent
	// (explicitly waiting for a background subagent to finish).
	ReadSubAgentCalls int
}

Session is a normalized Devin CLI session.

type SessionListItem

type SessionListItem struct {
	ID       string  `json:"id"`
	Title    string  `json:"title"`
	Model    string  `json:"model"`
	Project  string  `json:"project"`
	Cost     float64 `json:"cost"`
	Tokens   int64   `json:"tokens"`
	Duration string  `json:"duration"`
	Status   string  `json:"status"`
}

SessionListItem is a compact session row for `ls --json`.

type SubAgentCall

type SubAgentCall struct {
	Title         string    // task title
	Profile       string    // subagent_explore / subagent_general / etc.
	IsBackground  bool      // whether the subagent runs in the background
	Task          string    // full task description
	AgentID       string    // agent_id from tool result (for background subagents)
	StartTime     time.Time // when the run_subagent tool call was made
	EndTime       time.Time // when completion notification arrived (zero if not found)
	HasCompletion bool      // whether a completion notification was found
	OutputLen     int       // character count of the completion notification content
}

SubAgentCall is a parsed run_subagent invocation.

type TaskCategory

type TaskCategory struct {
	Name  string // Coding, Debugging, Testing, etc.
	Count int
	Cost  float64
}

TaskCategory classifies a session's work type.

type TimeBucket

type TimeBucket struct {
	Label        string // date / week / month label
	Requests     int
	InputTokens  int64
	OutputTokens int64
	CacheRead    int64
	CreditCost   float64
	ACUCost      float64
	ByModel      map[string]*ModelStats
}

TimeBucket is a daily/weekly/monthly aggregation.

type ToolAttribution

type ToolAttribution struct {
	ToolName  string
	Calls     int
	CostShare float64 // proportional cost
	Tokens    int64
}

ToolAttribution distributes cost across tools.

type ToolCall

type ToolCall struct {
	ID   string
	Name string
	// Arguments kept as raw JSON string; readers don't parse it.
	Arguments string
}

ToolCall is a single tool invocation extracted from an assistant message.

type ToolCallStateEntry

type ToolCallStateEntry struct {
	SessionID          string
	ToolCallID         string
	ToolCallJSON       string
	ToolCallUpdateJSON string
}

ToolCallStateEntry is a tool call state record.

type TrendPoint

type TrendPoint struct {
	Label  string
	Cost   float64
	Tokens int64
}

TrendPoint is a single point in a time series chart.

type WasteFinding

type WasteFinding struct {
	Category    string // e.g. "cache_miss", "retry_loop", "subagent_fanout"
	Description string
	Impact      string // estimated cost impact
	Suggestion  string
}

WasteFinding is a single optimization recommendation.