usage

type ACPExtension struct {
	ServiceID           string
	AgentType           string
	Operation           string
	ThreadID            string
	SessionID           string
	PermissionRequestID string
	FreshSession        *bool
	EventCounts         map[string]int
	UsageJSON           string
	ResultStatus        string
}

type ACPSummary struct {
	RequestCount int64 `json:"request_count"`
	TurnCount    int64 `json:"turn_count"`
	SuccessCount int64 `json:"success_count"`
	FailureCount int64 `json:"failure_count"`
	AvgLatencyMS int64 `json:"avg_latency_ms"`
}

type ACPUsageEvent struct {
	InteractionEvent
	ServiceID           string
	AgentType           string
	Operation           string
	ThreadID            string
	SessionID           string
	PermissionRequestID string
	FreshSession        *bool
	EventCounts         map[string]int
	UsageJSON           string
	ResultStatus        string
}

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

type AgentAttributor interface {
	ResolveAgentID(routeID, serviceID, sessionID string) (string, bool)
}

type AttributionFilter struct {
	AgentID  string
	RouteIDs []string
}

type BreakdownOptions struct {
	From        string
	To          string
	GroupBy     string
	OrderBy     string
	Limit       int
	Filters     map[string]string
	Attribution *AttributionFilter
}

type BreakdownResponse struct {
	GroupBy string           `json:"group_by,omitempty"`
	Items   []map[string]any `json:"items"`
	Limit   int              `json:"limit"`
}

type BuiltinExtension struct {
	Operation           string
	SessionID           string
	RunID               string
	PermissionRequestID string
	LinkTraceID         string
	LinkSpanID          string
	TopologyKind        string
	ModelSteps          *int
	ToolSteps           *int
	EventCounts         map[string]int
	ResultStatus        string
}

type BuiltinSummary struct {
	RequestCount int64 `json:"request_count"`
	TurnCount    int64 `json:"turn_count"`
	SuccessCount int64 `json:"success_count"`
	FailureCount int64 `json:"failure_count"`
	AvgLatencyMS int64 `json:"avg_latency_ms"`
}

type BuiltinUsageEvent struct {
	InteractionEvent
	Operation string
	SessionID string
	// RunID is retained as the typed builtin extension field while the embedded
	// common event carries the same value for cross-runtime consumers.
	RunID               string
	PermissionRequestID string
	// LinkTraceID/LinkSpanID identify the earlier asynchronous segment of the
	// same run. The OTLP adapter reconstructs them as an OpenTelemetry Span
	// Link instead of pretending a resumed HITL turn is a synchronous child.
	LinkTraceID  string
	LinkSpanID   string
	TopologyKind string
	// ModelSteps counts assistant model outputs and ToolSteps counts tool
	// executions observed during the turn.
	ModelSteps   int
	ToolSteps    int
	EventCounts  map[string]int
	ResultStatus string
}

type CommonExtension struct {
	AgentID     string
	RuntimeType string
	RunID       string
}

type Config struct {
	RetentionDays int        `json:"retention_days,omitempty"`
	MaxAgentDepth int        `json:"max_agent_depth,omitempty"`
	OTLP          OTLPConfig `json:"otlp,omitzero"`
}

type EventListOptions struct {
	From        string
	To          string
	Limit       int
	Filters     map[string]string
	Success     *bool
	Attribution *AttributionFilter
}

type EventListResponse struct {
	Items []map[string]any `json:"items"`
	Limit int              `json:"limit"`
}

type EventSink interface {
	Enqueue(any) bool
}

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

type InMemorySink struct {
	Dropped atomic.Uint64
	Events  []any
}

type InteractionDimensions struct {
	TraceID       string
	SpanID        string
	ParentSpanID  string
	AgentDepth    int
	RouteID       string
	RouteKind     string
	RouteProtocol string
	VirtualKeyID  string
	// AgentID, when set by the caller, is stamped verbatim. When empty the
	// observer attempts attribution from RouteID via the wired AgentAttributor.
	AgentID string
	// RuntimeType selects the Agent backend while RunID identifies one logical
	// execution across transport/HITL resume segments.
	RuntimeType string
	RunID       string
}

type InteractionEvent struct {
	EventID       string
	TraceID       string
	SpanID        string
	ParentSpanID  string
	AgentDepth    int
	StartedAt     time.Time
	FinishedAt    time.Time
	RouteID       string
	RouteKind     string
	RouteProtocol string
	VirtualKeyID  string
	Success       bool
	StatusCode    int
	ErrorType     string
	LatencyMS     int64
	// AgentID is the write-time attribution tag. It is empty for non-agent
	// traffic and for events whose route/service maps to zero or more than one
	// agent (stamp only when unambiguous).
	AgentID string
	// RuntimeType and RunID are common Agent-execution dimensions. They remain
	// empty for direct non-Agent protocol traffic and legacy rows.
	RuntimeType string
	RunID       string
}

type InteractionObserver interface {
	Begin(ctx context.Context, dims InteractionDimensions) (InteractionSpan, context.Context)
}

type InteractionOutcome struct {
	Success    bool
	StatusCode int
	ErrorType  string
	FinishedAt time.Time
}

type InteractionSpan interface {
	SetExtension(v any)
	AddAnnotation(key, value string)
	Finish(outcome InteractionOutcome)
	// Discard ends the span without emitting an event. Dispatch paths that
	// turn out not to handle the request (path passthrough to the next
	// handler) use it so unhandled requests do not pollute usage events.
	Discard()
}

type LLMExtension struct {
	LLMAPI                string
	APIOperation          string
	ProviderID            string
	ProviderType          string
	LogicalModel          string
	UpstreamModel         string
	CredentialSource      string
	CredentialID          string
	Stream                *bool
	Transport             string
	ResponseOutcome       string
	ResponseCommitted     *bool
	ResponseMode          string
	RelayIneligibleReason string
	MessageIDSource       string
	UsageSource           string
	Execution             string
	InputTokens           *int
	OutputTokens          *int
	TotalTokens           *int
	CachedTokens          *int
	ReasoningTokens       *int
	UsageFinalized        *bool
	RequestToolCount      *int
	RequestToolNames      []string
	ToolCallCount         *int
	ToolNames             []string
}

type LLMSummary struct {
	RequestCount    int64 `json:"request_count"`
	SuccessCount    int64 `json:"success_count"`
	FailureCount    int64 `json:"failure_count"`
	InputTokens     int64 `json:"input_tokens"`
	OutputTokens    int64 `json:"output_tokens"`
	TotalTokens     int64 `json:"total_tokens"`
	CachedTokens    int64 `json:"cached_tokens"`
	ReasoningTokens int64 `json:"reasoning_tokens"`
	AvgLatencyMS    int64 `json:"avg_latency_ms"`
}

type LLMUsageEvent struct {
	InteractionEvent
	LLMAPI                string
	APIOperation          string
	ProviderID            string
	ProviderType          string
	LogicalModel          string
	UpstreamModel         string
	CredentialSource      string
	CredentialID          string
	Stream                bool
	Transport             string
	ResponseOutcome       string
	ResponseCommitted     bool
	ResponseMode          string
	RelayIneligibleReason string
	MessageIDSource       string
	UsageSource           string
	Execution             string
	InputTokens           int
	OutputTokens          int
	TotalTokens           int
	// CachedTokens is the cache-served subset of InputTokens; ReasoningTokens
	// is the reasoning subset of OutputTokens. Zero when the upstream does not
	// report the breakdown.
	CachedTokens     int
	ReasoningTokens  int
	UsageFinalized   bool
	RequestToolCount int
	RequestToolNames []string
	ToolCallCount    int
	ToolNames        []string
}

type MCPExtension struct {
	RequestID          string
	ServiceID          string
	Method             string
	ToolName           string
	PresentedToolName  string
	ExecutedToolName   string
	ExecutionMode      string
	PolicyAction       string
	ResourceURI        string
	PromptName         string
	CompletionRefType  string
	CompletionArgument string
	ArgCount           *int
	ResultStatus       string
	Cancelled          *bool
	ToolArgsJSON       string
}

type MCPSummary struct {
	RequestCount   int64 `json:"request_count"`
	SuccessCount   int64 `json:"success_count"`
	FailureCount   int64 `json:"failure_count"`
	ToolsCallCount int64 `json:"tools_call_count"`
	AvgLatencyMS   int64 `json:"avg_latency_ms"`
}

type MCPUsageEvent struct {
	InteractionEvent
	RequestID          string
	ServiceID          string
	Method             string
	ToolName           string
	PresentedToolName  string
	ExecutedToolName   string
	ExecutionMode      string
	PolicyAction       string
	ResourceURI        string
	PromptName         string
	CompletionRefType  string
	CompletionArgument string
	ArgCount           int
	ResultStatus       string
	Cancelled          bool
	ToolArgsJSON       string
}

type NoopObserver struct{}

type NoopSpan struct{}

type OTLPConfig struct {
	// Endpoint is the collector address as host:port, or a full URL
	// (scheme://host:port). Empty disables export.
	Endpoint string `json:"endpoint,omitempty"`
	// Protocol selects the OTLP transport: "grpc" (default) or "http"
	// (OTLP/HTTP protobuf).
	Protocol string `json:"protocol,omitempty"`
	// Insecure disables transport TLS. Ignored when Endpoint is a full URL,
	// where the scheme decides.
	Insecure bool `json:"insecure,omitempty"`
	// Headers are sent with every export request (e.g. auth tokens).
	Headers map[string]string `json:"headers,omitempty"`
	// ServiceName sets the OTel resource service.name. Default "agent-gateway".
	ServiceName string `json:"service_name,omitempty"`
	// TimeoutSeconds bounds one export batch. Default 10.
	TimeoutSeconds int `json:"timeout_seconds,omitempty"`
	// Components additionally exports one span per eino chat-model component
	// call (via the process-global callbacks tap), nested under the
	// interaction span. Off by default: it multiplies span volume.
	Components bool `json:"components,omitempty"`
}

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

type Pipeline interface {
	EventSink
	Start()
	Close() error
	DroppedEvents() uint64
	WriteFailures() uint64
}

type PrometheusLabels struct {
	RouteKind   string
	RuntimeType string
}

type PrometheusProvider interface {
	PrometheusSnapshot() PrometheusSnapshot
}

type PrometheusSnapshot struct {
	Requests map[PrometheusLabels]int64
	Failures map[PrometheusLabels]int64
	Tokens   map[PrometheusLabels]int64
}

type QueryService interface {
	Summary() (Summary, error)
	ListEvents(kind string, opts EventListOptions) (EventListResponse, error)
	ListInteractions(opts EventListOptions) (EventListResponse, error)
	LLMTimeseries(opts TimeseriesOptions) (SeriesResponse, error)
	LLMBreakdown(opts BreakdownOptions) (BreakdownResponse, error)
	MCPTimeseries(opts TimeseriesOptions) (SeriesResponse, error)
	MCPBreakdown(opts BreakdownOptions) (BreakdownResponse, error)
	MCPToolsSummary(opts SummaryOptions) (BreakdownResponse, error)
	ACPTimeseries(opts TimeseriesOptions) (SeriesResponse, error)
	ACPBreakdown(opts BreakdownOptions) (BreakdownResponse, error)
	ACPSummary(opts BreakdownOptions) (BreakdownResponse, error)
	InteractionsSummary(opts BreakdownOptions) (BreakdownResponse, error)
}

type RuntimeStats interface {
	DroppedEvents() uint64
	WriteFailures() uint64
}

type SQLDBProvider interface {
	UsageDB() *gorm.DB
}

type SeriesResponse struct {
	Bucket  string           `json:"bucket"`
	GroupBy string           `json:"group_by,omitempty"`
	Items   []map[string]any `json:"items"`
}

type Summary struct {
	LLM     LLMSummary     `json:"llm"`
	MCP     MCPSummary     `json:"mcp"`
	ACP     ACPSummary     `json:"acp"`
	Builtin BuiltinSummary `json:"builtin"`
}

type SummaryOptions struct {
	From        string
	To          string
	Limit       int
	Filters     map[string]string
	Attribution *AttributionFilter
}

type TimeseriesOptions struct {
	From        string
	To          string
	Bucket      string
	GroupBy     string
	Filters     map[string]string
	Attribution *AttributionFilter
}

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