observations

package
v0.9.28 Latest Latest
Warning

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

Go to latest
Published: May 1, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package observations tracks per-(provider,model) speed samples for use by routing strategies.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultStorePath

func DefaultStorePath() string

DefaultStorePath returns the path for the observations file, respecting XDG. If the DDX_OBSERVATIONS_FILE environment variable is set, it takes precedence.

func PopulateFromLogs

func PopulateFromLogs(store *Store, logDir string) error

PopulateFromLogs reads all JSONL session files in logDir and adds speed observations to the store for successful sessions.

Types

type Key

type Key struct {
	ProviderSystem string `yaml:"provider_system"`
	Model          string `yaml:"model"`
}

Key identifies a provider+model combination for observation tracking.

type Ring

type Ring struct {
	Capacity int      `yaml:"capacity"`
	Samples  []Sample `yaml:"samples"`
	// contains filtered or unexported fields
}

Ring is a fixed-capacity circular buffer of Samples.

func NewRing

func NewRing(capacity int) *Ring

NewRing creates a new Ring with the given capacity.

func (*Ring) Add

func (r *Ring) Add(sample Sample)

Add appends a sample to the ring, overwriting the oldest entry when full.

func (*Ring) Mean

func (r *Ring) Mean() (outputTokensPerSec float64, ok bool)

Mean returns the mean output tokens/sec of all non-zero samples. ok is false when the ring is empty.

type Sample

type Sample struct {
	OutputTokensPerSec float64   `yaml:"output_tokens_per_sec"`
	DurationMs         int64     `yaml:"duration_ms"`
	RecordedAt         time.Time `yaml:"recorded_at"`
}

Sample is one speed observation.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store holds one Ring per Key. Internally uses a flat "providerSystem:model" string key for simplicity.

func LoadStore

func LoadStore(path string) (*Store, error)

LoadStore reads a Store from path. Returns an empty store on not-found. If the DDX_OBSERVATIONS_FILE env var is set and path is DefaultStorePath(), the env var value takes precedence (handled by DefaultStorePath).

func NewStore

func NewStore() *Store

NewStore returns an empty Store.

func (*Store) Add

func (s *Store) Add(key Key, sample Sample)

Add records a sample for the given key, auto-creating a Ring(cap=200) if needed.

func (*Store) AllKeys

func (s *Store) AllKeys() []Key

AllKeys returns all provider+model keys present in the store.

func (*Store) MarshalYAML

func (s *Store) MarshalYAML() (interface{}, error)

MarshalYAML serializes the store as a sequence of entries.

func (*Store) MeanSpeed

func (s *Store) MeanSpeed(key Key) (float64, bool)

MeanSpeed returns the mean output tokens/sec for the given key.

func (*Store) RingFor

func (s *Store) RingFor(key Key) *Ring

RingFor returns the Ring for the given key, or nil if not present.

func (*Store) Save

func (s *Store) Save(path string) error

Save writes the store to path atomically (write temp file, rename).

func (*Store) UnmarshalYAML

func (s *Store) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML deserializes the store from a sequence of entries.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL