hooks

type CacheHook struct {

	// TTL is how long cached responses remain valid. Default: 5 minutes.
	TTL time.Duration
	// MaxEntries caps the cache size. When exceeded, the least-recently-used
	// entry is evicted. 0 means unlimited.
	MaxEntries int
	// Hits and Misses track cache statistics.
	Hits   int
	Misses int
	// contains filtered or unexported fields
}

type CallMetric struct {
	Type             EventType     `json:"type"`
	Name             string        `json:"name"`
	StartedAt        time.Time     `json:"started_at"`
	Duration         time.Duration `json:"duration"`
	PromptTokens     int           `json:"prompt_tokens,omitempty"`
	CompletionTokens int           `json:"completion_tokens,omitempty"`
	Error            bool          `json:"error,omitempty"`
}

type Chain []Hook

type CostReport struct {
	PromptTokens     int     `json:"prompt_tokens"`
	CompletionTokens int     `json:"completion_tokens"`
	TotalTokens      int     `json:"total_tokens"`
	TotalCost        float64 `json:"total_cost"`
	Currency         string  `json:"currency"`
}

type CostTracker struct {

	// Budget is the maximum total spend (in currency units) before calls are
	// blocked. 0 means unlimited.
	Budget float64
	// RejectUnknownModels controls handling of models absent from the price
	// table. When true, After returns an error for such models instead of
	// silently costing $0; when false (default) their token usage is still
	// tracked and the event is flagged, but cost is not accrued.
	RejectUnknownModels bool
	// contains filtered or unexported fields
}

type Event struct {
	Type     EventType      `json:"type"`
	Name     string         `json:"name"` // tool name, model name, or node ID
	Input    any            `json:"input,omitempty"`
	Output   any            `json:"output,omitempty"`
	Error    error          `json:"-"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type EventType string

type Hook interface {
	// Before is called before the event executes. Return an error to abort.
	Before(ctx context.Context, evt *Event) error
	// After is called after the event executes.
	After(ctx context.Context, evt *Event) error
}

type LoggingHook struct {
	Events []Event
}

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

type MetricsSink interface {
	RecordToolCall(tenant, tool string, d time.Duration, isErr bool)
	RecordModelCall(tenant, provider string, d time.Duration, promptTokens, completionTokens int64, isErr bool)
}

type MetricsSummary struct {
	TotalModelCalls   int           `json:"total_model_calls"`
	TotalToolCalls    int           `json:"total_tool_calls"`
	TotalErrors       int           `json:"total_errors"`
	TotalPromptTokens int           `json:"total_prompt_tokens"`
	TotalCompTokens   int           `json:"total_completion_tokens"`
	AvgModelLatency   time.Duration `json:"avg_model_latency"`
	AvgToolLatency    time.Duration `json:"avg_tool_latency"`
	MaxModelLatency   time.Duration `json:"max_model_latency"`
	MaxToolLatency    time.Duration `json:"max_tool_latency"`
}

type ModelPrice struct {
	PromptPricePerToken     float64 // cost per prompt token (e.g. $0.000003)
	CompletionPricePerToken float64 // cost per completion token
}

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

type RateLimitHook struct {
	// RequestsPerMinute caps the number of model calls per minute. 0 = unlimited.
	RequestsPerMinute int
	// TokensPerMinute caps the estimated prompt tokens per minute. 0 = unlimited.
	TokensPerMinute int
	// WaitOnLimit controls whether the hook blocks until capacity is available
	// (true) or returns an error immediately (false). Default: true.
	WaitOnLimit bool
	// contains filtered or unexported fields
}

type RetryHook struct {
	MaxRetries int
	BaseDelay  time.Duration
	MaxDelay   time.Duration

	// RetryableError optionally classifies errors. If nil, all errors trigger retry.
	RetryableError func(err error) bool

	// OnRetry is called when a retry is about to be attempted. It receives the
	// attempt number (1-based) and the delay that will be applied.
	OnRetry func(attempt int, delay time.Duration)

	// Retries tracks the total number of retries performed (for observability).
	// Access it concurrently via RetriesCount / addRetries, which guard it with
	// mu; the exported field remains for backward-compatible reads after a hook
	// has finished executing.
	Retries int

	// SleepFn is the function used to sleep between retries.
	// Defaults to time.Sleep. Override in tests for instant execution.
	SleepFn func(time.Duration)
	// contains filtered or unexported fields
}