Documentation
¶
Overview ¶
Package trace records model calls as an append-only JSONL rollout, one file per run. Each line is a self-contained record — a run header, then one record per call carrying its system prompt, tool set, messages, response, usage, and priced cost. There is no shared database, no lock, and no checkpoint step, so a run's trace is complete the instant its last call returns and survives being copied out of a container mid-flight. This is the canonical session store the other agents keep (codex, opencode, claude each write their own rollout); tomo keeps the same, which is what makes a tomo run reconstructable downstream.
Index ¶
- func ExportNative(dir, runID, output string) error
- func ExportSTS(dir, runID, output string) error
- func Wrap(base provider.Provider, opts Options) (provider.Provider, error)
- type DatasetExport
- type Filter
- type ImportCall
- type ImportResult
- type ImportRun
- type Options
- type Pricing
- type Run
- type Summary
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExportNative ¶
ExportNative resolves one normalized run into tomo's lossless JSON shape.
Types ¶
type DatasetExport ¶
DatasetExport describes a materialized Hugging Face trace dataset.
func ExportDataset ¶
func ExportDataset(dir, outputDir string, filter Filter) (DatasetExport, error)
ExportDataset materializes every matching run as STS JSONL, organized by date, provider, model, task, and run. The normalized ledger remains the only persistent copy until this explicit export is requested.
type Filter ¶
type Filter struct {
Model string
Provider string
Task string
Date string
Since time.Time
Limit int
}
Filter narrows trace queries. Date uses YYYY-MM-DD. Since is inclusive.
type ImportCall ¶
type ImportCall struct {
StartedAt time.Time
Duration time.Duration
Request provider.Request
Response *provider.Response
Error string
}
ImportCall is one historical model call reconstructed by a migration tool.
type ImportResult ¶
ImportResult reports whether a historical run was added or already complete.
func ImportHistoricalRun ¶
ImportHistoricalRun appends a reconstructed session to the rollout store. Call sequences already present in the run's file are skipped, which makes the operation safe to resume after interruption.
type ImportRun ¶
type ImportRun struct {
ID string
StartedAt time.Time
Provider string
Pricing *Pricing
Calls []ImportCall
}
ImportRun is one historical session. ID should be deterministic so a migration can resume safely without creating duplicate runs.
type Options ¶
type Options struct {
Dir string
Provider string
Pricing *Pricing
PricingByModel map[string]Pricing
OnError func(error)
}
Options identifies the trace store and upstream provider.
type Pricing ¶
type Pricing struct {
InputUSDPerMillion float64 `json:"input_usd_per_million"`
CachedUSDPerMillion float64 `json:"cached_input_usd_per_million"`
CacheWriteUSDPerMillion float64 `json:"cache_write_usd_per_million"`
OutputUSDPerMillion float64 `json:"output_usd_per_million"`
}
Pricing is a list-price snapshot in USD per one million tokens. Supplying a zero-valued Pricing marks a free or locally hosted model as priced at zero.
type Run ¶
type Run struct {
ID string `json:"id"`
Date string `json:"date"`
StartedAt string `json:"started_at"`
EndedAt string `json:"ended_at"`
Provider string `json:"provider"`
Model string `json:"model"`
TaskID string `json:"task_id"`
TaskLabel string `json:"task_label"`
Status string `json:"status"`
Calls int `json:"calls"`
FailedCalls int `json:"failed_calls"`
InputTokens int `json:"input_tokens"`
CachedInputTokens int `json:"cached_input_tokens"`
CacheWriteInputTokens int `json:"cache_write_input_tokens"`
OutputTokens int `json:"output_tokens"`
ReasoningTokens int `json:"reasoning_tokens"`
TotalTokens int `json:"total_tokens"`
PricedCalls int `json:"priced_calls"`
UnpricedCalls int `json:"unpriced_calls"`
InputCostNanos int64 `json:"input_cost_nanos"`
CachedCostNanos int64 `json:"cached_input_cost_nanos"`
CacheWriteCostNanos int64 `json:"cache_write_cost_nanos"`
OutputCostNanos int64 `json:"output_cost_nanos"`
CostNanos int64 `json:"cost_nanos"`
CostUSD float64 `json:"cost_usd"`
DurationMS int64 `json:"duration_ms"`
}
Run is one provider instance with cumulative usage and priced cost.
type Summary ¶
type Summary struct {
Runs int `json:"runs"`
Calls int `json:"calls"`
FailedCalls int `json:"failed_calls"`
Models int `json:"models"`
Tasks int `json:"tasks"`
InputTokens int64 `json:"input_tokens"`
CachedInputTokens int64 `json:"cached_input_tokens"`
CacheWriteInputTokens int64 `json:"cache_write_input_tokens"`
OutputTokens int64 `json:"output_tokens"`
ReasoningTokens int64 `json:"reasoning_tokens"`
TotalTokens int64 `json:"total_tokens"`
PricedCalls int64 `json:"priced_calls"`
UnpricedCalls int64 `json:"unpriced_calls"`
InputCostNanos int64 `json:"input_cost_nanos"`
CachedCostNanos int64 `json:"cached_input_cost_nanos"`
CacheWriteCostNanos int64 `json:"cache_write_cost_nanos"`
OutputCostNanos int64 `json:"output_cost_nanos"`
CostNanos int64 `json:"cost_nanos"`
CostUSD float64 `json:"cost_usd"`
DurationMS int64 `json:"duration_ms"`
StoredRuns int `json:"stored_runs"`
StoredBytes int64 `json:"stored_bytes"`
}
Summary aggregates matching runs without loading prompt content.
Source Files