Documentation
¶
Overview ¶
Package report builds DeveloperPeriodReport (schema omnidevx.developer-period/v1) from canonical events.
Aggregation is two-stage: BuildDaily reduces one day's events into a DailySummary; Rollup combines summaries covering a period into a report. Build is the one-call convenience that buckets events by day and runs both stages. The two-stage split matters because not every metric sums correctly across a day boundary — a session spanning midnight must be deduplicated by ID at rollup time, not double-counted per day — and because reprocessing with a changed formula should replay from stored daily summaries, never require recollection from raw session files.
Only additive, per-day event types are summarized here: ai.* session activity, devx.change.committed, and devx.contribution.recorded. Period-total events (devx.profile.snapshot, devx.contribution.snapshot) already describe an entire period rather than one day, so they are not decomposed into daily buckets; Rollup surfaces their presence as a DataQuality warning until a provider-specific merge rule is defined.
Metrics are split into combined and bySource views per source ("some metrics combine safely — sessions, cost, tokens with model retained; others do not — acceptance rate only with matching definitions"); every metric carries a Measurement recording whether it was observed or estimated, and from what confidence.
Index ¶
- Constants
- func AllPricing() map[string]ModelPricing
- func EstimateCost(p ModelPricing, input, output, cacheRead, cacheCreation int64) float64
- func PricingSource() string
- func PricingVersion() string
- type DailySummary
- type DataQuality
- type DeveloperPeriodReport
- type Measurement
- type Metric
- type MetricSet
- type ModelPricing
- type PricingData
- type SourceCoverage
- type Subject
Constants ¶
const ( KindObserved = "observed" KindEstimated = "estimated" )
Measurement kinds.
const SchemaVersion = "omnidevx.developer-period/v1"
SchemaVersion is the schema this package's DeveloperPeriodReport implements.
Variables ¶
This section is empty.
Functions ¶
func AllPricing ¶ added in v0.3.0
func AllPricing() map[string]ModelPricing
AllPricing returns a copy of the full pricing table.
func EstimateCost ¶ added in v0.3.0
func EstimateCost(p ModelPricing, input, output, cacheRead, cacheCreation int64) float64
EstimateCost computes the USD cost from token counts using model pricing.
func PricingSource ¶ added in v0.3.0
func PricingSource() string
PricingSource returns the source URL from embedded pricing.json.
func PricingVersion ¶ added in v0.3.0
func PricingVersion() string
PricingVersion returns the version string from embedded pricing.json (e.g., "2026-07").
Types ¶
type DailySummary ¶
type DailySummary struct {
Date time.Time
Combined map[string]float64
BySource map[string]map[string]float64
ByModel map[string]map[string]float64 // model name → metric → value
Snapshots int // period-total events seen but not summarized (see package doc)
// contains filtered or unexported fields
}
DailySummary is one day's reduction of canonical events: additive metric counts plus enough per-source bookkeeping for Rollup to merge many days into a period report without re-reading raw events.
func BuildDaily ¶
func BuildDaily(events []omnidevx.Event, day time.Time) *DailySummary
BuildDaily reduces one day's events into a DailySummary. day identifies the UTC calendar day being summarized; events outside [day, day+24h) are ignored so callers can pass a pre-bucketed slice or the full event set interchangeably.
type DataQuality ¶
type DataQuality struct {
CoverageScore float64 `json:"coverageScore"`
Warnings []string `json:"warnings,omitempty"`
}
DataQuality reports how complete a report's coverage is.
type DeveloperPeriodReport ¶
type DeveloperPeriodReport struct {
SchemaVersion string `json:"schemaVersion"`
Subject Subject `json:"subject"`
Period omnidevx.Period `json:"period"`
Sources []SourceCoverage `json:"sources"`
Metrics MetricSet `json:"metrics"`
Quality DataQuality `json:"quality"`
}
DeveloperPeriodReport is the analytical source of truth for one person's activity over one period, combining every source that observed them. It is a presentation-agnostic artifact: DevFolio's contributor profile summarizes and links to this, never recomputes it.
func Build ¶
Build reduces events into a DeveloperPeriodReport for one subject and period. It buckets events by UTC calendar day, reduces each day with BuildDaily, and rolls the summaries up with Rollup — the same path a caller replaying cached DailySummary artifacts would take, so reprocessing with a changed formula never requires recollection.
func Rollup ¶
func Rollup(dailies []*DailySummary, subject Subject, period omnidevx.Period) *DeveloperPeriodReport
Rollup combines DailySummary values into one DeveloperPeriodReport. Summaries outside period are ignored so callers can pass a cached superset without re-filtering first.
type Measurement ¶
type Measurement struct {
Kind string `json:"kind"`
Method string `json:"method,omitempty"`
Confidence float64 `json:"confidence"`
}
Measurement records how a metric value was derived. Every metric in this package is a direct sum of observed event attributes, so Kind is always KindObserved; estimated metrics (e.g. inferred AI contribution ratios) belong to a future analytics layer built on top of these reports.
type Metric ¶
type Metric struct {
Value float64 `json:"value"`
Unit string `json:"unit,omitempty"`
Measurement Measurement `json:"measurement"`
}
Metric is one named value with the provenance behind it.
type MetricSet ¶
type MetricSet struct {
Combined map[string]Metric `json:"combined"`
BySource map[string]map[string]Metric `json:"bySource"`
ByModel map[string]map[string]Metric `json:"byModel,omitempty"`
}
MetricSet holds the cross-source combined view alongside the per-source and per-model breakdowns. A metric that does not combine safely across sources (see package doc) appears in BySource only.
type ModelPricing ¶ added in v0.3.0
type ModelPricing struct {
InputPerMillion float64 `json:"inputPerMillion"`
OutputPerMillion float64 `json:"outputPerMillion"`
CacheReadPerMillion float64 `json:"cacheReadPerMillion"`
CacheCreationPerMillion float64 `json:"cacheCreationPerMillion"`
}
ModelPricing holds per-million-token prices (USD) for one model.
func LookupPricing ¶ added in v0.3.0
func LookupPricing(model string) (ModelPricing, bool)
LookupPricing returns pricing for a model name. It tries exact match first, then longest-prefix match with boundary validation (so "claude-opus-4-8[1m]" matches "claude-opus-4-8" but "claude-opus-4-80" does not).
Valid suffixes after a prefix: [1m], -YYYYMMDD, or end of string. Returns false if no matching pricing is found.
type PricingData ¶ added in v0.3.0
type PricingData struct {
Version string `json:"version"`
Source string `json:"source"`
Note string `json:"note"`
Models map[string]ModelPricing `json:"models"`
}
PricingData is the top-level structure of pricing.json.
type SourceCoverage ¶
type SourceCoverage struct {
Source omnidevx.Source `json:"source"`
EventCount int `json:"eventCount"`
CollectionModes []omnidevx.CollectionMode `json:"collectionModes"`
MinConfidence float64 `json:"minConfidence"`
}
SourceCoverage summarizes what one source contributed to a report.
Source Files