observation

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Jun 11, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package observation defines host-facing runtime observation DTOs.

Runtime events are presentation-neutral facts, and those facts may still be too low-level for a host UI or API response. Package observation projects selected events and narrow observation DTOs into stable, UI-neutral status records that a host can render without parsing assistant text, exposing prompt-cache storage records, or depending on internal inspection types.

Observation values are not raw debug records. They intentionally omit provider payloads, model deltas, reasoning, tool arguments, tool results, and local paths. Hosts that need raw local inspection should build that capability as an explicit privileged surface behind its own product boundary.

Index

Constants

View Source 
const (
	EventTypeProviderUsage    = "provider_usage"
	EventTypeContextCompact   = "context_compact"
	CompactionPhaseStart      = "start"
	CompactionPhaseComplete   = "complete"
	CompactionPhaseFailed     = "failed"
	CompactionStatusRunning   = "running"
	CompactionStatusCompacted = "compacted"
	CompactionStatusFailed    = "failed"
)
View Source 
const (
	ContextPhaseProjectedRequest = "projected_request"
	ContextPhaseProviderUsage    = "provider_usage"

	ContextStatusStable        = "stable"
	ContextStatusNearThreshold = "near_threshold"
	ContextStatusWillCompact   = "will_compact"
	ContextStatusHardLimit     = "hard_limit"
	ContextStatusEstimated     = "estimated"

	ProviderUsagePhaseStreamUsage        = "stream_usage"
	ProviderUsagePhaseFinalContextStatus = "final_context_status"
)

Variables

This section is empty.

Functions

func ContextPressureDisplayStatus added in v0.3.0 

func ContextPressureDisplayStatus(pressure config.ContextPressure) string

func ContextPressureThresholdRatio added in v0.3.0 

func ContextPressureThresholdRatio(pressure config.ContextPressure) float64

func ContextPressureUsedRatio added in v0.3.0 

func ContextPressureUsedRatio(pressure config.ContextPressure) float64

func RequestID 

func RequestID(runID string, step int) string

func SortContextStatuses 

func SortContextStatuses(statuses []ContextStatus)

Types

type CompactionEvent 

type CompactionEvent struct {
	RunID                   string                 `json:"run_id,omitempty"`
	ThreadID                string                 `json:"thread_id,omitempty"`
	TurnID                  string                 `json:"turn_id,omitempty"`
	Step                    int                    `json:"step,omitempty"`
	Phase                   string                 `json:"phase"`
	Status                  string                 `json:"status"`
	Trigger                 string                 `json:"trigger,omitempty"`
	Reason                  string                 `json:"reason,omitempty"`
	CompactionID            string                 `json:"compaction_id,omitempty"`
	CompactionGeneration    int                    `json:"compaction_generation,omitempty"`
	CompactionWindowID      string                 `json:"compaction_window_id,omitempty"`
	CompactedThroughEntryID string                 `json:"compacted_through_entry_id,omitempty"`
	TokensBefore            int64                  `json:"tokens_before,omitempty"`
	TokensAfterEstimate     int64                  `json:"tokens_after_estimate,omitempty"`
	BeforePressure          config.ContextPressure `json:"before_pressure,omitempty"`
	ContextBefore           config.ContextUsage    `json:"context_before,omitempty"`
	ContextAfter            config.ContextUsage    `json:"context_after,omitempty"`
	Error                   string                 `json:"error,omitempty"`
	ObservedAt              time.Time              `json:"observed_at"`
}

func CompactionEventFromEvent added in v0.3.0 

func CompactionEventFromEvent(ev Event) (CompactionEvent, bool)

func CompactionEventsFromEvents added in v0.3.0 

func CompactionEventsFromEvents(events []Event) []CompactionEvent

type ContextStatus 

type ContextStatus struct {
	RunID                string                 `json:"run_id,omitempty"`
	ThreadID             string                 `json:"thread_id,omitempty"`
	TurnID               string                 `json:"turn_id,omitempty"`
	Step                 int                    `json:"step,omitempty"`
	RequestID            string                 `json:"request_id,omitempty"`
	LogicalRequestID     string                 `json:"logical_request_id,omitempty"`
	Attempt              int                    `json:"attempt,omitempty"`
	Phase                string                 `json:"phase"`
	Provider             string                 `json:"provider,omitempty"`
	Model                string                 `json:"model,omitempty"`
	ObservedAt           time.Time              `json:"observed_at"`
	Usage                ProviderUsage          `json:"usage,omitempty"`
	RequestEstimate      config.RequestEstimate `json:"request_estimate,omitempty"`
	ContextPressure      config.ContextPressure `json:"context_pressure,omitempty"`
	UsedRatio            float64                `json:"used_ratio,omitempty"`
	ThresholdRatio       float64                `json:"threshold_ratio,omitempty"`
	Status               string                 `json:"status"`
	CompactionGeneration int                    `json:"compaction_generation,omitempty"`
	CompactionWindowID   string                 `json:"compaction_window_id,omitempty"`
}

func ContextStatusFromProviderUsage 

func ContextStatusFromProviderUsage(usage ProviderUsageObservation) (ContextStatus, bool)

func ContextStatusFromProviderUsageEvent 

func ContextStatusFromProviderUsageEvent(ev Event) (ContextStatus, bool)

func ContextStatusFromRequest 

func ContextStatusFromRequest(req RequestObservation) ContextStatus

func ContextStatusesFromObservations 

func ContextStatusesFromObservations(requests []RequestObservation, usages []ProviderUsageObservation, events []Event) []ContextStatus

func ContextStatusesFromRequests 

func ContextStatusesFromRequests(requests []RequestObservation, events []Event) []ContextStatus

func (ContextStatus) PhaseOrder 

func (s ContextStatus) PhaseOrder() int

type Event added in v0.3.0 

type Event struct {
	Type       string         `json:"type"`
	RunID      string         `json:"run_id,omitempty"`
	ThreadID   string         `json:"thread_id,omitempty"`
	TurnID     string         `json:"turn_id,omitempty"`
	Step       int            `json:"step,omitempty"`
	Provider   string         `json:"provider,omitempty"`
	Model      string         `json:"model,omitempty"`
	Result     string         `json:"result,omitempty"`
	Error      string         `json:"error,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
	ObservedAt time.Time      `json:"observed_at"`
}

type ProviderUsage added in v0.3.0 

type ProviderUsage struct {
	InputTokens       int64   `json:"input_tokens,omitempty"`
	OutputTokens      int64   `json:"output_tokens,omitempty"`
	ReasoningTokens   int64   `json:"reasoning_tokens,omitempty"`
	CacheReadTokens   int64   `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens  int64   `json:"cache_write_tokens,omitempty"`
	TotalTokens       int64   `json:"total_tokens,omitempty"`
	WindowInputTokens int64   `json:"window_input_tokens,omitempty"`
	CostUSD           float64 `json:"cost_usd,omitempty"`
	Source            string  `json:"source,omitempty"`
	Available         bool    `json:"available,omitempty"`
}

func (ProviderUsage) Normalized added in v0.3.0 

func (u ProviderUsage) Normalized() ProviderUsage

type ProviderUsageObservation 

type ProviderUsageObservation struct {
	RunID                string                 `json:"run_id,omitempty"`
	ThreadID             string                 `json:"thread_id,omitempty"`
	TurnID               string                 `json:"turn_id,omitempty"`
	Step                 int                    `json:"step,omitempty"`
	RequestID            string                 `json:"request_id,omitempty"`
	LogicalRequestID     string                 `json:"logical_request_id,omitempty"`
	Attempt              int                    `json:"attempt,omitempty"`
	Provider             string                 `json:"provider,omitempty"`
	Model                string                 `json:"model,omitempty"`
	ObservedAt           time.Time              `json:"observed_at"`
	Usage                ProviderUsage          `json:"usage,omitempty"`
	RequestEstimate      config.RequestEstimate `json:"request_estimate,omitempty"`
	ContextPressure      config.ContextPressure `json:"context_pressure,omitempty"`
	CompactionGeneration int                    `json:"compaction_generation,omitempty"`
	CompactionWindowID   string                 `json:"compaction_window_id,omitempty"`
}

type RequestObservation 

type RequestObservation struct {
	RunID                string                 `json:"run_id,omitempty"`
	ThreadID             string                 `json:"thread_id,omitempty"`
	TurnID               string                 `json:"turn_id,omitempty"`
	Step                 int                    `json:"step"`
	RequestID            string                 `json:"request_id,omitempty"`
	LogicalRequestID     string                 `json:"logical_request_id,omitempty"`
	Attempt              int                    `json:"attempt,omitempty"`
	Provider             string                 `json:"provider"`
	Model                string                 `json:"model"`
	ObservedAt           time.Time              `json:"observed_at"`
	RequestEstimate      config.RequestEstimate `json:"request_estimate,omitempty"`
	ProjectedPressure    config.ContextPressure `json:"projected_context_pressure,omitempty"`
	CompactionGeneration int                    `json:"compaction_generation,omitempty"`
	CompactionWindowID   string                 `json:"compaction_window_id,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.