Documentation
¶
Index ¶
- Constants
- func APIKeyFromContext(ctx context.Context) string
- func AccessProviderFromContext(ctx context.Context) string
- func ExecutionRequestIDFromContext(ctx context.Context) string
- func GenerateEnabled(generate *bool) bool
- func GenerateFlag(generate bool) *bool
- func GenerateFromContext(ctx context.Context) bool
- func IsNativeAccessProvider(provider string) bool
- func IsNativeKeyFromContext(ctx context.Context) (bool, bool)
- func PublishRecord(ctx context.Context, record Record)
- func ReasoningEffortFromContext(ctx context.Context) string
- func RegisterNamedPlugin(name string, plugin Plugin)
- func RegisterPlugin(plugin Plugin)
- func RequestedModelAliasFromContext(ctx context.Context) string
- func ServiceTierFromContext(ctx context.Context) string
- func StartDefault(ctx context.Context)
- func StopDefault()
- func StreamDeliverySupported(ctx context.Context) bool
- func StreamDeliveryTracked(ctx context.Context) bool
- func StreamFromContext(ctx context.Context) bool
- func SupportStreamDelivery(ctx context.Context) func()
- func TraceIDFromContext(ctx context.Context) string
- func WaitStreamDelivery(ctx context.Context) (error, bool)
- func WithAPIKey(ctx context.Context, apiKey string) context.Context
- func WithAccessProvider(ctx context.Context, provider string) context.Context
- func WithExecutionRequestID(ctx context.Context, requestID string) context.Context
- func WithGenerate(ctx context.Context, generate bool) context.Context
- func WithIsNativeKey(ctx context.Context, isNative bool) context.Context
- func WithReasoningEffort(ctx context.Context, effort string) context.Context
- func WithRequestedModelAlias(ctx context.Context, alias string) context.Context
- func WithServiceTier(ctx context.Context, tier string) context.Context
- func WithStream(ctx context.Context, stream bool) context.Context
- func WithStreamDelivery(ctx context.Context) (context.Context, func(error))
- func WithTraceID(ctx context.Context, traceID string) context.Context
- func WithoutStreamDelivery(ctx context.Context) context.Context
- type Detail
- type Failure
- type Manager
- type Plugin
- type Record
- type TokenAccountingQuality
- type TokenBreakdown
- func NewIndependentTokenBreakdown(...) TokenBreakdown
- func NewPartialSubsetTokenBreakdown(inputTotal, cacheRead, cacheWrite, outputTotal, reasoning, total int64) TokenBreakdown
- func NewSeparateReasoningTokenBreakdown(inputTotal, cacheRead, cacheWrite, nonReasoningOutput, reasoning, total int64) TokenBreakdown
- func NewSubsetTokenBreakdown(inputTotal, cacheRead, cacheWrite, outputTotal, reasoning, total int64) TokenBreakdown
- func NewUnclassifiedTokenBreakdown(total int64) TokenBreakdown
- type TokenInputBreakdown
- type TokenOutputBreakdown
Constants ¶
const AutoServiceTier = "auto"
AutoServiceTier is the OpenAI request semantics when service_tier is omitted. OpenAI HTTP handlers set it explicitly, without changing other providers' historical direct-SDK default.
const DefaultServiceTier = "default"
DefaultServiceTier is retained for direct SDK and non-OpenAI usage callers.
const TokenAccountingSchemaVersion = 2
TokenAccountingSchemaVersion identifies the canonical token accounting contract.
Variables ¶
This section is empty.
Functions ¶
func APIKeyFromContext ¶ added in v8.0.24
APIKeyFromContext returns the client API key stored in ctx or gin.Context.
func AccessProviderFromContext ¶ added in v8.0.24
AccessProviderFromContext returns the client authentication provider stored in ctx.
func ExecutionRequestIDFromContext ¶
ExecutionRequestIDFromContext retrieves the execution instance request ID from the context.
func GenerateEnabled ¶
GenerateEnabled reports whether generation is enabled for the record field. A nil value defaults to true so legacy callers that omit Generate keep the historical behavior.
func GenerateFlag ¶
GenerateFlag returns a pointer suitable for Record.Generate.
func GenerateFromContext ¶
GenerateFromContext returns whether the client requested actual generation. Missing values default to true.
func IsNativeAccessProvider ¶ added in v8.0.24
IsNativeAccessProvider reports whether provider represents CPA's built-in inline key provider.
func IsNativeKeyFromContext ¶ added in v8.0.24
IsNativeKeyFromContext returns whether the client API key is native to CPA if explicitly set in ctx.
func PublishRecord ¶
PublishRecord publishes a record using the default manager.
func ReasoningEffortFromContext ¶
ReasoningEffortFromContext returns the client-requested reasoning effort stored in ctx.
func RegisterNamedPlugin ¶
RegisterNamedPlugin registers or replaces a named plugin on the default manager.
func RegisterPlugin ¶
func RegisterPlugin(plugin Plugin)
RegisterPlugin registers a plugin on the default manager.
func RequestedModelAliasFromContext ¶
RequestedModelAliasFromContext returns the client-requested model name stored in ctx.
func ServiceTierFromContext ¶
ServiceTierFromContext returns the client-requested service tier stored in ctx.
func StartDefault ¶
StartDefault starts the default manager's dispatcher.
func StreamDeliverySupported ¶ added in v8.0.14
StreamDeliverySupported reports whether an active producer understands delivery.
func StreamDeliveryTracked ¶ added in v8.0.14
StreamDeliveryTracked reports whether a consumer will acknowledge delivery.
func StreamFromContext ¶
StreamFromContext returns whether the request was executed in streaming mode. Missing values default to false.
func SupportStreamDelivery ¶ added in v8.0.14
SupportStreamDelivery opts an active producer into early terminal cancellation. The producer must reconcile cancellation with WaitStreamDelivery.
func TraceIDFromContext ¶
TraceIDFromContext retrieves the parent inbound HTTP request ID from the context.
func WaitStreamDelivery ¶ added in v8.0.14
WaitStreamDelivery waits for the consumer, not the upstream reader, to finish. Producers must close their output channel before waiting to avoid deadlocks.
func WithAPIKey ¶ added in v8.0.24
WithAPIKey stores the client API key for usage sinks.
func WithAccessProvider ¶ added in v8.0.24
WithAccessProvider stores the client authentication provider identifier for usage sinks.
func WithExecutionRequestID ¶
WithExecutionRequestID attaches a specific execution instance request ID to the context.
func WithGenerate ¶
WithGenerate stores whether the client requested actual generation for usage sinks. Missing context values default to true; only an explicit false disables generation.
func WithIsNativeKey ¶ added in v8.0.24
WithIsNativeKey stores whether the client API key is native to CPA for usage sinks.
func WithReasoningEffort ¶
WithReasoningEffort stores the client-requested reasoning effort for usage sinks.
func WithRequestedModelAlias ¶
WithRequestedModelAlias stores the client-requested model name for usage sinks.
func WithServiceTier ¶
WithServiceTier stores the client-requested service tier for usage sinks.
func WithStream ¶
WithStream stores whether the request was executed in streaming mode for usage sinks.
func WithStreamDelivery ¶ added in v8.0.14
WithStreamDelivery lets the HTTP consumer acknowledge delivery independently of request cancellation. The consumer must resolve the outcome on every exit.
func WithTraceID ¶
WithTraceID attaches the parent inbound HTTP request ID to the context.
func WithoutStreamDelivery ¶ added in v8.0.14
WithoutStreamDelivery isolates an internal execution from its caller's HTTP acknowledgment. Internal consumers retain EOF-based accounting completion; cancellation and all unrelated context values remain inherited.
Types ¶
type Detail ¶
type Detail struct {
InputTokens int64
OutputTokens int64
ReasoningTokens int64
CachedTokens int64
CacheReadTokens int64
CacheCreationTokens int64
TotalTokens int64
TokenBreakdown TokenBreakdown
ResponseServiceTier string
}
Detail holds the token usage breakdown.
func EnsureTokenBreakdown ¶
EnsureTokenBreakdown attaches a valid v2 breakdown to legacy or direct SDK usage details without guessing whether reasoning is already inside output.
func EnsureTokenBreakdownForProvider ¶
EnsureTokenBreakdownForProvider attaches a valid v2 breakdown to legacy or direct SDK usage details using the known provider's token semantics. Unknown providers remain unclassified instead of guessing how their buckets overlap.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager maintains a queue of usage records and delivers them to registered plugins.
func DefaultManager ¶
func DefaultManager() *Manager
DefaultManager returns the global usage manager instance.
func NewManager ¶
NewManager constructs a manager with a buffered queue.
func (*Manager) Publish ¶
Publish enqueues a usage record for processing. If no plugin is registered the record will be discarded downstream.
func (*Manager) RegisterNamed ¶
RegisterNamed registers or replaces a plugin by name.
type Record ¶
type Record struct {
// RequestID uniquely identifies this specific model execution instance (UUID v4).
RequestID string
// TraceID identifies the parent inbound HTTP request when available (8-character hex).
TraceID string
Provider string
// BaseURL stores the configured upstream base URL when available.
BaseURL string
// ExecutorType stores the concrete executor type that handled the request.
ExecutorType string
Model string
Alias string
APIKey string
// IsNativeKey reports whether the client API key was authenticated by CPA's native config provider.
IsNativeKey bool
// AccessProvider identifies the client request authentication provider (e.g. "config-inline" or plugin ID).
AccessProvider string
SessionID string
ParentSessionID string
AuthID string
AuthIndex string
// AccessTokenSHA256 identifies the OAuth token version without exposing the token.
AccessTokenSHA256 string
AuthType string
Source string
// ReasoningEffort stores the translated upstream thinking level for request event logs.
ReasoningEffort string
// ServiceTier stores the client-requested service tier.
ServiceTier string
// RequestServiceTier is a deprecated input-only alias retained for existing
// plugin callers. It is normalized into ServiceTier and never emitted.
RequestServiceTier string
// ResponseServiceTier stores the final tier reported by the upstream response.
ResponseServiceTier string
// ResponseModel stores the model name reported by the upstream response, empty when unknown.
ResponseModel string
// Generate reports whether the client requested actual generation.
// nil or true means generation is enabled; only an explicit false disables generation.
// Use GenerateFlag to set the value and GenerateEnabled to read it with the default.
Generate *bool
// Stream reports whether the request was executed in streaming mode.
Stream bool
RequestedAt time.Time
Latency time.Duration
TTFT time.Duration
Failed bool
Fail Failure
Detail Detail
// ResponseHeaders stores a snapshot of upstream response headers for usage sinks.
ResponseHeaders http.Header
}
Record contains the usage statistics captured for a single provider request.
type TokenAccountingQuality ¶
type TokenAccountingQuality string
TokenAccountingQuality describes how confidently a token total can be classified.
const ( TokenAccountingQualityComplete TokenAccountingQuality = "complete" TokenAccountingQualityInconsistent TokenAccountingQuality = "inconsistent" TokenAccountingQualityUnclassified TokenAccountingQuality = "unclassified" )
type TokenBreakdown ¶
type TokenBreakdown struct {
SchemaVersion int `json:"schema_version"`
Quality TokenAccountingQuality `json:"quality"`
TotalTokens int64 `json:"total_tokens"`
Input TokenInputBreakdown `json:"input"`
Output TokenOutputBreakdown `json:"output"`
UnclassifiedTokens int64 `json:"unclassified_tokens"`
}
TokenBreakdown is the canonical, non-overlapping token accounting contract.
func NewIndependentTokenBreakdown ¶
func NewIndependentTokenBreakdown(uncachedInput, cacheRead, cacheWrite, nonReasoningOutput, reasoning, total int64) TokenBreakdown
NewIndependentTokenBreakdown normalizes protocols where uncached input, cache reads, cache writes, non-reasoning output, and reasoning are separate.
func NewPartialSubsetTokenBreakdown ¶
func NewPartialSubsetTokenBreakdown(inputTotal, cacheRead, cacheWrite, outputTotal, reasoning, total int64) TokenBreakdown
NewPartialSubsetTokenBreakdown preserves known subset buckets while assigning an authoritative remainder to the unclassified bucket.
func NewSeparateReasoningTokenBreakdown ¶
func NewSeparateReasoningTokenBreakdown(inputTotal, cacheRead, cacheWrite, nonReasoningOutput, reasoning, total int64) TokenBreakdown
NewSeparateReasoningTokenBreakdown normalizes protocols where cache tokens are included in input totals while reasoning is separate from ordinary output.
func NewSubsetTokenBreakdown ¶
func NewSubsetTokenBreakdown(inputTotal, cacheRead, cacheWrite, outputTotal, reasoning, total int64) TokenBreakdown
NewSubsetTokenBreakdown normalizes protocols where cache tokens are included in input totals and reasoning tokens are included in output totals.
func NewUnclassifiedTokenBreakdown ¶
func NewUnclassifiedTokenBreakdown(total int64) TokenBreakdown
NewUnclassifiedTokenBreakdown preserves an authoritative total without guessing how an unknown protocol partitions it.
func (TokenBreakdown) Valid ¶
func (b TokenBreakdown) Valid() bool
Valid reports whether the breakdown satisfies the v2 accounting invariants.
type TokenInputBreakdown ¶
type TokenInputBreakdown struct {
TotalTokens int64 `json:"total_tokens"`
UncachedTokens int64 `json:"uncached_tokens"`
CacheReadTokens int64 `json:"cache_read_tokens"`
CacheWriteTokens int64 `json:"cache_write_tokens"`
}
TokenInputBreakdown contains mutually exclusive input token buckets.
type TokenOutputBreakdown ¶
type TokenOutputBreakdown struct {
TotalTokens int64 `json:"total_tokens"`
NonReasoningTokens int64 `json:"non_reasoning_tokens"`
ReasoningTokens int64 `json:"reasoning_tokens"`
}
TokenOutputBreakdown contains mutually exclusive output token buckets.