load

type ArrivalPattern string

type Executor func(context.Context, Request) Observation

type Metrics struct {
	Completed          uint64  `json:"completed"`
	Succeeded          uint64  `json:"succeeded"`
	Failed             uint64  `json:"failed"`
	TimedOut           uint64  `json:"timed_out"`
	SuccessRatePercent float64 `json:"success_rate_percent"`
	// OfferedQPS is the scheduler demand (launched plus locally rejected)
	// divided by the send window. LaunchedQPS is the demand admitted by the
	// client. SuccessfulRequestQPS is aligned with AIPerf request throughput:
	// only valid responses divided by the full benchmark window.
	OfferedQPS           float64 `json:"offered_qps,omitempty"`
	LaunchedQPS          float64 `json:"launched_qps,omitempty"`
	CompletedQPS         float64 `json:"completed_qps,omitempty"`
	SuccessfulRequestQPS float64 `json:"successful_request_qps,omitempty"`
	// RequestQPS is the all-outcomes completion rate over the full window.
	RequestQPS                float64 `json:"request_qps"`
	RPM                       float64 `json:"rpm"`
	InputTPM                  float64 `json:"input_tpm"`
	OutputTPM                 float64 `json:"output_tpm"`
	TotalTPM                  float64 `json:"total_tpm"`
	GenerationTPS             float64 `json:"generation_tps"`
	TTFTSamples               uint64  `json:"ttft_samples"`
	TTFTP50                   float64 `json:"ttft_p50_ms"`
	TTFTP90                   float64 `json:"ttft_p90_ms"`
	TTFTP95                   float64 `json:"ttft_p95_ms"`
	TTFTP99                   float64 `json:"ttft_p99_ms"`
	TTFTAverage               float64 `json:"ttft_average_ms"`
	TTFBSamples               uint64  `json:"ttfb_samples"`
	TTFBP50                   float64 `json:"ttfb_p50_ms"`
	TTFBP95                   float64 `json:"ttfb_p95_ms"`
	TTFBP99                   float64 `json:"ttfb_p99_ms"`
	TTFBAverage               float64 `json:"ttfb_average_ms"`
	TTFTAnySamples            uint64  `json:"ttft_any_samples"`
	TTFTAnyP50                float64 `json:"ttft_any_p50_ms"`
	TTFTAnyP95                float64 `json:"ttft_any_p95_ms"`
	TTFTAnyP99                float64 `json:"ttft_any_p99_ms"`
	TTFTAnyAverage            float64 `json:"ttft_any_average_ms"`
	TTFTVisibleSamples        uint64  `json:"ttft_visible_samples"`
	TTFTVisibleP50            float64 `json:"ttft_visible_p50_ms"`
	TTFTVisibleP95            float64 `json:"ttft_visible_p95_ms"`
	TTFTVisibleP99            float64 `json:"ttft_visible_p99_ms"`
	TTFTVisibleAverage        float64 `json:"ttft_visible_average_ms"`
	TTSTSamples               uint64  `json:"ttst_samples"`
	TTSTP50                   float64 `json:"ttst_p50_ms"`
	TTSTP95                   float64 `json:"ttst_p95_ms"`
	TTSTP99                   float64 `json:"ttst_p99_ms"`
	TTSTAverage               float64 `json:"ttst_average_ms"`
	ObservedICLSamples        uint64  `json:"observed_icl_samples"`
	ObservedICLP50            float64 `json:"observed_icl_p50_ms"`
	ObservedICLP95            float64 `json:"observed_icl_p95_ms"`
	ObservedICLP99            float64 `json:"observed_icl_p99_ms"`
	ObservedICLAverage        float64 `json:"observed_icl_average_ms"`
	SemanticChunkCountSamples uint64  `json:"semantic_chunk_count_samples"`
	SemanticChunkCountP50     float64 `json:"semantic_chunk_count_p50"`
	SemanticChunkCountP95     float64 `json:"semantic_chunk_count_p95"`
	SemanticChunkCountP99     float64 `json:"semantic_chunk_count_p99"`
	SemanticChunkCountAverage float64 `json:"semantic_chunk_count_average"`
	TPOTP50                   float64 `json:"tpot_p50_ms"`
	TPOTP90                   float64 `json:"tpot_p90_ms"`
	TPOTP95                   float64 `json:"tpot_p95_ms"`
	TPOTP99                   float64 `json:"tpot_p99_ms"`
	TPOTAverage               float64 `json:"tpot_average_ms"`
	E2EP50                    float64 `json:"e2e_p50_ms"`
	E2EP90                    float64 `json:"e2e_p90_ms"`
	E2EP95                    float64 `json:"e2e_p95_ms"`
	E2EP99                    float64 `json:"e2e_p99_ms"`
	E2EAverage                float64 `json:"e2e_average_ms"`
	ScheduleLagP50            float64 `json:"schedule_lag_p50_ms"`
	ScheduleLagP90            float64 `json:"schedule_lag_p90_ms,omitempty"`
	ScheduleLagP95            float64 `json:"schedule_lag_p95_ms"`
	ScheduleLagP99            float64 `json:"schedule_lag_p99_ms,omitempty"`
	ScheduleLagAverage        float64 `json:"schedule_lag_average_ms"`
	PromptTokens              uint64  `json:"prompt_tokens"`
	CompletionTokens          uint64  `json:"completion_tokens"`
	CachedTokens              uint64  `json:"cached_tokens"`
	CacheRatePercent          float64 `json:"cache_rate_percent"`
}

type Observation struct {
	// TTFTObserved distinguishes a measured zero from a missing first token.
	TTFTObserved       bool              `json:"ttft_observed,omitempty"`
	Index              uint64            `json:"index"`
	ScheduledOffset    time.Duration     `json:"scheduled_offset"`
	StartedOffset      time.Duration     `json:"started_offset"`
	FinishedOffset     time.Duration     `json:"finished_offset"`
	ScheduleLag        time.Duration     `json:"schedule_lag"`
	E2E                time.Duration     `json:"e2e"`
	Streaming          bool              `json:"streaming"`
	TTFB               time.Duration     `json:"ttfb"`
	TTFT               time.Duration     `json:"ttft"`
	TTFTAny            time.Duration     `json:"ttft_any"`
	TTFTVisible        time.Duration     `json:"ttft_visible"`
	TTST               time.Duration     `json:"ttst"`
	ObservedICL        time.Duration     `json:"observed_icl"`
	SemanticChunkCount uint64            `json:"semantic_chunk_count"`
	HTTPStatus         int               `json:"http_status"`
	Success            bool              `json:"success"`
	TimedOut           bool              `json:"timed_out"`
	StreamComplete     bool              `json:"stream_complete"`
	PromptTokens       uint64            `json:"prompt_tokens"`
	CompletionTokens   uint64            `json:"completion_tokens"`
	CachedTokens       uint64            `json:"cached_tokens"`
	ErrorCode          domain.ErrorCode  `json:"error_code,omitempty"`
	Dimensions         map[string]string `json:"dimensions,omitempty"`
}

type Options struct {
	// Closing StopSending prevents new work from launching while allowing
	// already-started requests to drain normally.
	StopSending <-chan struct{}
	OnProgress  func(Progress)
	// MaxOpenLoopInFlight may lower, but never raise, the process safety limit.
	// It is primarily useful for constrained hosts and deterministic tests.
	MaxOpenLoopInFlight uint64
	// ArrivalPattern selects constant-spacing or a seeded Poisson process for
	// open-loop work. RandomSeed is intentionally request-order independent.
	ArrivalPattern ArrivalPattern
	RandomSeed     uint32
	// Ramp turns a duration-bounded fixed-concurrency or open-loop run into a
	// linear staircase from its minimum load to the configured target.
	Ramp bool
	// MaxScheduledRequests may lower, but never raise, the process-wide request
	// cap. Explicit count-limited profiles above it fail; duration-only profiles
	// stop offering at the cap. Open-loop runs keep their configured send window;
	// fixed-concurrency runs drain immediately once the cap is exhausted.
	MaxScheduledRequests uint64
}

type Outcome struct {
	Progress Progress      `json:"progress"`
	Results  []Observation `json:"results"`
	Metrics  Metrics       `json:"metrics"`
}

type Phase string

type Progress struct {
	Phase         Phase         `json:"phase"`
	Planned       uint64        `json:"planned"`
	Offered       uint64        `json:"offered,omitempty"`
	Launched      uint64        `json:"launched"`
	Completed     uint64        `json:"completed"`
	InFlight      uint64        `json:"in_flight"`
	PeakInFlight  uint64        `json:"peak_in_flight"`
	Succeeded     uint64        `json:"succeeded"`
	Failed        uint64        `json:"failed"`
	Rejected      uint64        `json:"rejected"`
	Stopped       bool          `json:"stopped"`
	Capped        bool          `json:"capped,omitempty"`
	SendDuration  time.Duration `json:"send_duration"`
	DrainDuration time.Duration `json:"drain_duration"`
	TotalDuration time.Duration `json:"total_duration"`
}

type Request struct {
	Index           uint64        `json:"index"`
	ScheduledOffset time.Duration `json:"scheduled_offset"`
}