logstore

type AsyncJob struct {
	ID           string                 `gorm:"primaryKey;type:varchar(255)" json:"id"`
	Status       schemas.AsyncJobStatus `gorm:"type:varchar(50);index:idx_async_jobs_status;not null" json:"status"`
	RequestType  schemas.RequestType    `gorm:"type:varchar(50);index:idx_async_jobs_request_type;not null" json:"request_type"`
	Response     string                 `gorm:"type:text" json:"response"`
	StatusCode   int                    `gorm:"default:0" json:"status_code,omitempty"`
	Error        string                 `gorm:"type:text" json:"error,omitempty"`
	VirtualKeyID *string                `gorm:"type:varchar(255);index:idx_async_jobs_vk_id" json:"virtual_key_id,omitempty"`
	ResultTTL    int                    `gorm:"default:3600" json:"-"` // TTL in seconds, used to calculate ExpiresAt on completion
	ExpiresAt    *time.Time             `gorm:"index:idx_async_jobs_expires_at" json:"expires_at,omitempty"`
	CreatedAt    time.Time              `gorm:"index;not null" json:"created_at"`
	CompletedAt  *time.Time             `json:"completed_at,omitempty"`
}

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

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

type AsyncOperation func(ctx *schemas.BifrostContext) (any, *schemas.BifrostError)

type CleanerConfig struct {
	RetentionDays int
}

type Config struct {
	Enabled       bool                `json:"enabled"`
	Type          LogStoreType        `json:"type"`
	RetentionDays int                 `json:"retention_days"`
	Config        any                 `json:"config"`
	ObjectStorage *objectstore.Config `json:"object_storage,omitempty"`
	// ObjectStorageExcludeFields lists payload field names (DB column names) that
	// should NOT be offloaded to object storage and instead remain in the database.
	ObjectStorageExcludeFields []string `json:"object_storage_exclude_fields,omitempty"`
}

type CostHistogramBucket struct {
	Timestamp time.Time          `json:"timestamp"`
	TotalCost float64            `json:"total_cost"`
	ByModel   map[string]float64 `json:"by_model"`
}

type CostHistogramResult struct {
	Buckets           []CostHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                 `json:"bucket_size_seconds"`
	Models            []string              `json:"models"`
}

type DimensionCostHistogramBucket struct {
	Timestamp   time.Time          `json:"timestamp"`
	TotalCost   float64            `json:"total_cost"`
	ByDimension map[string]float64 `json:"by_dimension"`
}

type DimensionCostHistogramResult struct {
	Buckets           []DimensionCostHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                          `json:"bucket_size_seconds"`
	Dimension         HistogramDimension             `json:"dimension"`
	DimensionValues   []string                       `json:"dimension_values"`
}

type DimensionLatencyHistogramBucket struct {
	Timestamp   time.Time                        `json:"timestamp"`
	ByDimension map[string]DimensionLatencyStats `json:"by_dimension"`
}

type DimensionLatencyHistogramResult struct {
	Buckets           []DimensionLatencyHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                             `json:"bucket_size_seconds"`
	Dimension         HistogramDimension                `json:"dimension"`
	DimensionValues   []string                          `json:"dimension_values"`
}

type DimensionLatencyStats struct {
	AvgLatency    float64 `json:"avg_latency"`
	P90Latency    float64 `json:"p90_latency"`
	P95Latency    float64 `json:"p95_latency"`
	P99Latency    float64 `json:"p99_latency"`
	TotalRequests int64   `json:"total_requests"`
}

type DimensionRankingEntry struct {
	ID            string  `json:"id"`
	Name          string  `json:"name,omitempty"`
	TotalRequests int64   `json:"total_requests"`
	TotalTokens   int64   `json:"total_tokens"`
	TotalCost     float64 `json:"total_cost"`
}

type DimensionRankingResult struct {
	Rankings  []DimensionRankingWithTrend `json:"rankings"`
	Dimension RankingDimension            `json:"dimension"`
	// TotalActualRequests / TotalAttributedRequests are only set for fan-out
	// dimensions (team / business unit / customer) on Postgres. Attributed
	// counts credit a request to every dimension value it touches, so their
	// sum can exceed the real request count; actual is COUNT(DISTINCT id)
	// over the same attributed population. Zero/omitted when not computed.
	TotalActualRequests     int64 `json:"total_actual_requests,omitempty"`
	TotalAttributedRequests int64 `json:"total_attributed_requests,omitempty"`
}

type DimensionRankingTrend struct {
	HasPreviousPeriod bool    `json:"has_previous_period"`
	RequestsTrend     float64 `json:"requests_trend"`
	TokensTrend       float64 `json:"tokens_trend"`
	CostTrend         float64 `json:"cost_trend"`
}

type DimensionRankingWithTrend struct {
	DimensionRankingEntry
	Trend DimensionRankingTrend `json:"trend"`
}

type DimensionTokenHistogramBucket struct {
	Timestamp   time.Time                      `json:"timestamp"`
	ByDimension map[string]DimensionTokenStats `json:"by_dimension"`
}

type DimensionTokenHistogramResult struct {
	Buckets           []DimensionTokenHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                           `json:"bucket_size_seconds"`
	Dimension         HistogramDimension              `json:"dimension"`
	DimensionValues   []string                        `json:"dimension_values"`
}

type DimensionTokenStats struct {
	PromptTokens     int64 `json:"prompt_tokens"`
	CompletionTokens int64 `json:"completion_tokens"`
	TotalTokens      int64 `json:"total_tokens"`
}

type GovernanceStore interface {
	GetVirtualKey(ctx context.Context, vkValue string) (*configstoreTables.TableVirtualKey, bool)
}

type HistogramBucket struct {
	Timestamp time.Time `json:"timestamp"`
	Count     int64     `json:"count"`
	Success   int64     `json:"success"`
	Error     int64     `json:"error"`
}

type HistogramDimension string

type HistogramResult struct {
	Buckets           []HistogramBucket `json:"buckets"`
	BucketSizeSeconds int64             `json:"bucket_size_seconds"`
}

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

type KeyPairResult struct {
	ID   string `gorm:"column:id"`
	Name string `gorm:"column:name"`
}

type LatencyHistogramBucket struct {
	Timestamp     time.Time `json:"timestamp"`
	AvgLatency    float64   `json:"avg_latency"`
	P90Latency    float64   `json:"p90_latency"`
	P95Latency    float64   `json:"p95_latency"`
	P99Latency    float64   `json:"p99_latency"`
	TotalRequests int64     `json:"total_requests"`
}

type LatencyHistogramResult struct {
	Buckets           []LatencyHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                    `json:"bucket_size_seconds"`
}

type Log struct {
	ID                      string    `gorm:"primaryKey;type:varchar(255)" json:"id"`
	IncNumber               *int64    `gorm:"column:inc_number" json:"inc_number,omitempty"`
	ParentRequestID         *string   `gorm:"type:varchar(255);index" json:"parent_request_id"`
	Timestamp               time.Time `gorm:"index;index:idx_logs_ts_provider_status,priority:1;not null" json:"timestamp"`
	Object                  string    `gorm:"type:varchar(255);index;not null;column:object_type" json:"object"` // text.completion, chat.completion, or embedding
	Provider                string    `gorm:"type:varchar(255);index;index:idx_logs_ts_provider_status,priority:2;not null" json:"provider"`
	Model                   string    `gorm:"type:varchar(255);index;not null" json:"model"`
	Alias                   *string   `gorm:"type:varchar(255);index" json:"alias,omitempty"` // Set when model was resolved via alias mapping; the original name the caller used
	NumberOfRetries         int       `gorm:"default:0" json:"number_of_retries"`
	FallbackIndex           int       `gorm:"default:0" json:"fallback_index"`
	SelectedKeyID           string    `gorm:"type:varchar(255);index:idx_logs_selected_key_id" json:"selected_key_id"`
	SelectedKeyName         string    `gorm:"type:varchar(255)" json:"selected_key_name"`
	AttemptTrail            string    `gorm:"type:text" json:"-"` // JSON serialized []schemas.KeyAttemptRecord
	VirtualKeyID            *string   `gorm:"type:varchar(255);index:idx_logs_virtual_key_id" json:"virtual_key_id"`
	VirtualKeyName          *string   `gorm:"type:varchar(255)" json:"virtual_key_name"`
	RoutingEnginesUsedStr   *string   `gorm:"type:varchar(255);column:routing_engines_used" json:"-"` // Comma-separated routing engines
	RoutingRuleID           *string   `gorm:"type:varchar(255);index:idx_logs_routing_rule_id" json:"routing_rule_id"`
	RoutingRuleName         *string   `gorm:"type:varchar(255)" json:"routing_rule_name"`
	SelectedPromptName      *string   `gorm:"type:varchar(255)" json:"selected_prompt_name"`
	SelectedPromptVersion   *string   `gorm:"type:varchar(64)" json:"selected_prompt_version"`
	SelectedPromptID        *string   `gorm:"type:varchar(36)" json:"selected_prompt_id"`
	UserID                  *string   `gorm:"type:varchar(255);index:idx_logs_user_id" json:"user_id"`
	UserName                *string   `gorm:"type:varchar(255)" json:"user_name"`
	TeamID                  *string   `gorm:"type:varchar(255);index:idx_logs_team_id" json:"team_id"`
	TeamName                *string   `gorm:"type:varchar(255)" json:"team_name"`
	CustomerID              *string   `gorm:"type:varchar(255);index:idx_logs_customer_id" json:"customer_id"`
	CustomerName            *string   `gorm:"type:varchar(255)" json:"customer_name"`
	BusinessUnitID          *string   `gorm:"type:varchar(255);index:idx_logs_business_unit_id" json:"business_unit_id"`
	BusinessUnitName        *string   `gorm:"type:varchar(255)" json:"business_unit_name"`
	TeamIDs                 *string   `gorm:"type:text" json:"-"`
	TeamNames               *string   `gorm:"type:text" json:"-"`
	CustomerIDs             *string   `gorm:"type:text" json:"-"`
	CustomerNames           *string   `gorm:"type:text" json:"-"`
	BusinessUnitIDs         *string   `gorm:"type:text" json:"-"`
	BusinessUnitNames       *string   `gorm:"type:text" json:"-"`
	InputHistory            string    `gorm:"type:text" json:"-"` // JSON serialized []schemas.ChatMessage
	ResponsesInputHistory   string    `gorm:"type:text" json:"-"` // JSON serialized []schemas.ResponsesMessage
	OutputMessage           string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.ChatMessage
	ResponsesOutput         string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.ResponsesMessage
	EmbeddingOutput         string    `gorm:"type:text" json:"-"` // JSON serialized [][]float32
	RerankOutput            string    `gorm:"type:text" json:"-"` // JSON serialized []schemas.RerankResult
	OCROutput               string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostOCRResponse
	Params                  string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.ModelParameters
	Tools                   string    `gorm:"type:text" json:"-"` // JSON serialized []schemas.Tool
	ToolCalls               string    `gorm:"type:text" json:"-"` // JSON serialized []schemas.ToolCall (For backward compatibility, tool calls are now in the content)
	SpeechInput             string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.SpeechInput
	TranscriptionInput      string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.TranscriptionInput
	OCRInput                string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.OCRDocument
	ImageGenerationInput    string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.ImageGenerationInput
	ImageEditInput          string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.ImageEditInput
	ImageVariationInput     string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.ImageVariationInput
	VideoGenerationInput    string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.VideoGenerationInput
	SpeechOutput            string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostSpeech
	TranscriptionOutput     string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostTranscribe
	ImageGenerationOutput   string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostImageGenerationResponse
	ListModelsOutput        string    `gorm:"type:text" json:"-"` // JSON serialized []schemas.Model
	VideoGenerationOutput   string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostVideoGenerationResponse
	VideoRetrieveOutput     string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostVideoRetrieveResponse
	VideoDownloadOutput     string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostVideoDownloadResponse
	VideoListOutput         string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostVideoListResponse
	VideoDeleteOutput       string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostVideoDeleteResponse
	CacheDebug              string    `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostCacheDebug
	Latency                 *float64  `gorm:"index:idx_logs_latency" json:"latency,omitempty"`
	TokenUsage              string    `gorm:"type:text" json:"-"`                                                                         // JSON serialized *schemas.LLMUsage
	Cost                    *float64  `gorm:"index" json:"cost,omitempty"`                                                                // Cost in dollars (total cost of the request - includes cache lookup cost)
	Status                  string    `gorm:"type:varchar(50);index;index:idx_logs_ts_provider_status,priority:3;not null" json:"status"` // "processing", "success", or "error"
	StopReason              *string   `gorm:"type:varchar(50);index:idx_logs_stop_reason" json:"stop_reason,omitempty"`                   // Why the model stopped: "stop", "length", "content_filter", "tool_calls", etc.
	ErrorDetails            string    `gorm:"type:text" json:"-"`                                                                         // JSON serialized *schemas.BifrostError
	Stream                  bool      `gorm:"default:false" json:"stream"`                                                                // true if this was a streaming response
	ContentSummary          string    `gorm:"type:text" json:"-"`
	RawRequest              string    `gorm:"type:text" json:"raw_request"`                         // Populated when `send-back-raw-request` is on
	RawResponse             string    `gorm:"type:text" json:"raw_response"`                        // Populated when `send-back-raw-response` is on
	PassthroughRequestBody  string    `gorm:"type:text" json:"passthrough_request_body,omitempty"`  // Raw body for passthrough requests (UTF-8)
	PassthroughResponseBody string    `gorm:"type:text" json:"passthrough_response_body,omitempty"` // Raw body for passthrough responses (UTF-8)
	RoutingEngineLogs       string    `gorm:"type:text" json:"routing_engine_logs,omitempty"`       // Formatted routing engine decision logs
	PluginLogs              string    `gorm:"type:text" json:"plugin_logs,omitempty"`               // JSON serialized plugin log entries grouped by plugin name
	Metadata                *string   `gorm:"type:text" json:"-"`                                   // JSON serialized map[string]interface{}
	IsLargePayloadRequest   bool      `gorm:"default:false" json:"is_large_payload_request"`
	IsLargePayloadResponse  bool      `gorm:"default:false" json:"is_large_payload_response"`
	HasObject               bool      `gorm:"default:false" json:"-"` // True when payload is stored in object storage

	// Cluster governance fields - attached by the logging plugin when running in a cluster
	// so that leaders can recover disconnected node usage from the logs table.
	ClusterNodeID *string `gorm:"type:varchar(255)" json:"cluster_node_id,omitempty"`
	BudgetIDs     *string `gorm:"type:text" json:"-"` // JSON serialized []string of budget IDs applicable to this request
	RateLimitIDs  *string `gorm:"type:text" json:"-"` // JSON serialized []string of rate limit IDs applicable to this request

	// Denormalized token fields for easier querying
	PromptTokens     int `gorm:"default:0" json:"-"`
	CompletionTokens int `gorm:"default:0" json:"-"`
	TotalTokens      int `gorm:"index:idx_logs_total_tokens;default:0" json:"-"`
	CachedReadTokens int `gorm:"default:0" json:"-"`

	CreatedAt time.Time `gorm:"index;not null" json:"created_at"`

	// Virtual fields for JSON output - these will be populated when needed
	RoutingEnginesUsed          []string                                `gorm:"-" json:"routing_engines_used,omitempty"` // Virtual field deserialized from JSON
	InputHistoryParsed          []schemas.ChatMessage                   `gorm:"-" json:"input_history,omitempty"`
	ResponsesInputHistoryParsed []schemas.ResponsesMessage              `gorm:"-" json:"responses_input_history,omitempty"`
	OutputMessageParsed         *schemas.ChatMessage                    `gorm:"-" json:"output_message,omitempty"`
	ResponsesOutputParsed       []schemas.ResponsesMessage              `gorm:"-" json:"responses_output,omitempty"`
	EmbeddingOutputParsed       []schemas.EmbeddingData                 `gorm:"-" json:"embedding_output,omitempty"`
	RerankOutputParsed          []schemas.RerankResult                  `gorm:"-" json:"rerank_output,omitempty"`
	OCROutputParsed             *schemas.BifrostOCRResponse             `gorm:"-" json:"ocr_output,omitempty"`
	ParamsParsed                interface{}                             `gorm:"-" json:"params,omitempty"`
	ToolsParsed                 []schemas.ChatTool                      `gorm:"-" json:"tools,omitempty"`
	ToolCallsParsed             []schemas.ChatAssistantMessageToolCall  `gorm:"-" json:"tool_calls,omitempty"` // For backward compatibility, tool calls are now in the content
	TokenUsageParsed            *schemas.BifrostLLMUsage                `gorm:"-" json:"token_usage,omitempty"`
	ErrorDetailsParsed          *schemas.BifrostError                   `gorm:"-" json:"error_details,omitempty"`
	SpeechInputParsed           *schemas.SpeechInput                    `gorm:"-" json:"speech_input,omitempty"`
	TranscriptionInputParsed    *schemas.TranscriptionInput             `gorm:"-" json:"transcription_input,omitempty"`
	OCRInputParsed              *schemas.OCRDocument                    `gorm:"-" json:"ocr_input,omitempty"`
	ImageGenerationInputParsed  *schemas.ImageGenerationInput           `gorm:"-" json:"image_generation_input,omitempty"`
	ImageEditInputParsed        *schemas.ImageEditInput                 `gorm:"-" json:"image_edit_input,omitempty"`
	ImageVariationInputParsed   *schemas.ImageVariationInput            `gorm:"-" json:"image_variation_input,omitempty"`
	SpeechOutputParsed          *schemas.BifrostSpeechResponse          `gorm:"-" json:"speech_output,omitempty"`
	TranscriptionOutputParsed   *schemas.BifrostTranscriptionResponse   `gorm:"-" json:"transcription_output,omitempty"`
	ImageGenerationOutputParsed *schemas.BifrostImageGenerationResponse `gorm:"-" json:"image_generation_output,omitempty"`
	CacheDebugParsed            *schemas.BifrostCacheDebug              `gorm:"-" json:"cache_debug,omitempty"`
	ListModelsOutputParsed      []schemas.Model                         `gorm:"-" json:"list_models_output,omitempty"`
	MetadataParsed              map[string]interface{}                  `gorm:"-" json:"metadata,omitempty"`
	VideoGenerationInputParsed  *schemas.VideoGenerationInput           `gorm:"-" json:"video_generation_input,omitempty"`
	VideoGenerationOutputParsed *schemas.BifrostVideoGenerationResponse `gorm:"-" json:"video_generation_output,omitempty"`
	VideoRetrieveOutputParsed   *schemas.BifrostVideoGenerationResponse `gorm:"-" json:"video_retrieve_output,omitempty"`
	VideoDownloadOutputParsed   *schemas.BifrostVideoDownloadResponse   `gorm:"-" json:"video_download_output,omitempty"`
	VideoListOutputParsed       *schemas.BifrostVideoListResponse       `gorm:"-" json:"video_list_output,omitempty"`
	VideoDeleteOutputParsed     *schemas.BifrostVideoDeleteResponse     `gorm:"-" json:"video_delete_output,omitempty"`
	AttemptTrailParsed          []schemas.KeyAttemptRecord              `gorm:"-" json:"attempt_trail,omitempty"`
	BudgetIDsParsed             []string                                `gorm:"-" json:"budget_ids,omitempty"`
	RateLimitIDsParsed          []string                                `gorm:"-" json:"rate_limit_ids,omitempty"`
	TeamIDsParsed               []string                                `gorm:"-" json:"team_ids,omitempty"`
	TeamNamesParsed             []string                                `gorm:"-" json:"team_names,omitempty"`
	CustomerIDsParsed           []string                                `gorm:"-" json:"customer_ids,omitempty"`
	CustomerNamesParsed         []string                                `gorm:"-" json:"customer_names,omitempty"`
	BusinessUnitIDsParsed       []string                                `gorm:"-" json:"business_unit_ids,omitempty"`
	BusinessUnitNamesParsed     []string                                `gorm:"-" json:"business_unit_names,omitempty"`

	// Populated in handlers after find using the virtual key id and key id
	VirtualKey  *tables.TableVirtualKey  `gorm:"-" json:"virtual_key,omitempty"`  // redacted
	SelectedKey *schemas.Key             `gorm:"-" json:"selected_key,omitempty"` // redacted
	RoutingRule *tables.TableRoutingRule `gorm:"-" json:"routing_rule,omitempty"` // redacted
}

type LogRetentionManager interface {
	DeleteLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)
}

type LogStore interface {
	Ping(ctx context.Context) error
	Create(ctx context.Context, entry *Log) error
	CreateIfNotExists(ctx context.Context, entry *Log) error
	BatchCreateIfNotExists(ctx context.Context, entries []*Log) error
	FindByID(ctx context.Context, id string) (*Log, error)
	IsLogEntryPresent(ctx context.Context, id string) (bool, error)
	FindFirst(ctx context.Context, query any, fields ...string) (*Log, error)
	FindAll(ctx context.Context, query any, fields ...string) ([]*Log, error)
	FindAllDistinct(ctx context.Context, query any, fields ...string) ([]*Log, error)
	HasLogs(ctx context.Context) (bool, error)
	SearchLogs(ctx context.Context, filters SearchFilters, pagination PaginationOptions) (*SearchResult, error)
	GetSessionLogs(ctx context.Context, sessionID string, pagination PaginationOptions) (*SessionDetailResult, error)
	GetSessionSummary(ctx context.Context, sessionID string) (*SessionSummaryResult, error)
	GetStats(ctx context.Context, filters SearchFilters) (*SearchStats, error)
	GetHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*HistogramResult, error)
	GetTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*TokenHistogramResult, error)
	GetCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*CostHistogramResult, error)
	GetModelHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ModelHistogramResult, error)
	GetLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*LatencyHistogramResult, error)
	GetProviderCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderCostHistogramResult, error)
	GetProviderTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderTokenHistogramResult, error)
	GetProviderLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderLatencyHistogramResult, error)
	GetModelRankings(ctx context.Context, filters SearchFilters) (*ModelRankingResult, error)
	GetUserRankings(ctx context.Context, filters SearchFilters) (*UserRankingResult, error)
	GetDimensionRankings(ctx context.Context, filters SearchFilters, dimension RankingDimension) (*DimensionRankingResult, error)
	// GetDimensionCostHistogram returns time-bucketed cost data grouped by the specified dimension (e.g., team_id, customer_id).
	GetDimensionCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionCostHistogramResult, error)
	// GetDimensionTokenHistogram returns time-bucketed token usage grouped by the specified dimension.
	GetDimensionTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionTokenHistogramResult, error)
	// GetDimensionLatencyHistogram returns time-bucketed latency percentiles grouped by the specified dimension.
	GetDimensionLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionLatencyHistogramResult, error)
	// GetNodeUsageAfter returns cumulative usage for rows after the provided stable
	// cursor. When the cursor has both timestamp and log ID, rows with the same
	// timestamp but greater log ID are included to avoid skipping same-timestamp rows.
	GetNodeUsageAfter(ctx context.Context, nodeID string, cursor NodeUsageCursor) (*NodeUsageAggregate, error)
	Update(ctx context.Context, id string, entry any) error
	BulkUpdateCost(ctx context.Context, updates map[string]float64) error
	Flush(ctx context.Context, since time.Time) error
	Close(ctx context.Context) error
	DeleteLog(ctx context.Context, id string) error
	DeleteLogs(ctx context.Context, ids []string) error
	DeleteLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)

	// Distinct value methods for filter data
	GetDistinctModels(ctx context.Context, limit int, query string) ([]string, error)
	GetDistinctAliases(ctx context.Context, limit int, query string) ([]string, error)
	GetDistinctKeyPairs(ctx context.Context, idCol, nameCol string, limit int, query string) ([]KeyPairResult, error)
	GetDistinctRoutingEngines(ctx context.Context, limit int, query string) ([]string, error)
	GetDistinctStopReasons(ctx context.Context, limit int, query string) ([]string, error)
	GetDistinctMetadataKeys(ctx context.Context, limit int, query string) (map[string][]string, error)

	// MCP Tool Log histogram methods
	GetMCPHistogram(ctx context.Context, filters MCPToolLogSearchFilters, bucketSizeSeconds int64) (*MCPHistogramResult, error)
	GetMCPCostHistogram(ctx context.Context, filters MCPToolLogSearchFilters, bucketSizeSeconds int64) (*MCPCostHistogramResult, error)
	GetMCPTopTools(ctx context.Context, filters MCPToolLogSearchFilters, limit int) (*MCPTopToolsResult, error)

	// MCP Tool Log methods
	CreateMCPToolLog(ctx context.Context, entry *MCPToolLog) error
	BatchCreateMCPToolLogsIfNotExists(ctx context.Context, entries []*MCPToolLog) error
	FindMCPToolLog(ctx context.Context, id string) (*MCPToolLog, error)
	UpdateMCPToolLog(ctx context.Context, id string, entry any) error
	SearchMCPToolLogs(ctx context.Context, filters MCPToolLogSearchFilters, pagination PaginationOptions) (*MCPToolLogSearchResult, error)
	GetMCPToolLogStats(ctx context.Context, filters MCPToolLogSearchFilters) (*MCPToolLogStats, error)
	HasMCPToolLogs(ctx context.Context) (bool, error)
	DeleteMCPToolLogs(ctx context.Context, ids []string) error
	FlushMCPToolLogs(ctx context.Context, since time.Time) error
	GetAvailableToolNames(ctx context.Context, limit int, query string) ([]string, error)
	GetAvailableServerLabels(ctx context.Context, limit int, query string) ([]string, error)
	GetAvailableMCPVirtualKeys(ctx context.Context, limit int, query string) ([]MCPToolLog, error)

	// Async Job methods
	CreateAsyncJob(ctx context.Context, job *AsyncJob) error
	FindAsyncJobByID(ctx context.Context, id string) (*AsyncJob, error)
	UpdateAsyncJob(ctx context.Context, id string, updates map[string]interface{}) error
	DeleteExpiredAsyncJobs(ctx context.Context) (int64, error)
	DeleteStaleAsyncJobs(ctx context.Context, staleSince time.Time) (int64, error)
}

type LogStoreType string

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

type MCPCostHistogramBucket struct {
	Timestamp time.Time `json:"timestamp"`
	TotalCost float64   `json:"total_cost"`
}

type MCPCostHistogramResult struct {
	Buckets           []MCPCostHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                    `json:"bucket_size_seconds"`
}

type MCPHistogramBucket struct {
	Timestamp time.Time `json:"timestamp"`
	Count     int64     `json:"count"`
	Success   int64     `json:"success"`
	Error     int64     `json:"error"`
}

type MCPHistogramResult struct {
	Buckets           []MCPHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                `json:"bucket_size_seconds"`
}

type MCPToolLog struct {
	ID             string    `gorm:"primaryKey;type:varchar(255)" json:"id"`
	RequestID      string    `gorm:"type:varchar(255);column:request_id;index:idx_mcp_logs_request_id" json:"request_id,omitempty"`             // The original request ID from context
	LLMRequestID   *string   `gorm:"type:varchar(255);column:llm_request_id;index:idx_mcp_logs_llm_request_id" json:"llm_request_id,omitempty"` // Links to the LLM request that triggered this tool call
	Timestamp      time.Time `gorm:"index;not null" json:"timestamp"`
	ToolName       string    `gorm:"type:varchar(255);index:idx_mcp_logs_tool_name;not null" json:"tool_name"`
	ServerLabel    string    `gorm:"type:varchar(255);index:idx_mcp_logs_server_label" json:"server_label,omitempty"` // MCP server that provided the tool
	VirtualKeyID   *string   `gorm:"type:varchar(255);index:idx_mcp_logs_virtual_key_id" json:"virtual_key_id"`
	VirtualKeyName *string   `gorm:"type:varchar(255)" json:"virtual_key_name"`
	UserID         *string   `gorm:"type:varchar(255);index:idx_mcp_logs_user_id" json:"user_id"`
	TeamID         *string   `gorm:"type:varchar(255);index:idx_mcp_logs_team_id" json:"team_id"`
	CustomerID     *string   `gorm:"type:varchar(255);index:idx_mcp_logs_customer_id" json:"customer_id"`
	BusinessUnitID *string   `gorm:"type:varchar(255);index:idx_mcp_logs_business_unit_id" json:"business_unit_id"`
	Arguments      string    `gorm:"type:text" json:"-"`                                                // JSON serialized tool arguments
	Result         string    `gorm:"type:text" json:"-"`                                                // JSON serialized tool result
	ErrorDetails   string    `gorm:"type:text" json:"-"`                                                // JSON serialized *schemas.BifrostError
	Latency        *float64  `gorm:"index:idx_mcp_logs_latency" json:"latency,omitempty"`               // Execution time in milliseconds
	Cost           *float64  `gorm:"index:idx_mcp_logs_cost" json:"cost,omitempty"`                     // Cost in dollars (per execution cost)
	Status         string    `gorm:"type:varchar(50);index:idx_mcp_logs_status;not null" json:"status"` // "processing", "success", or "error"
	Metadata       string    `gorm:"type:text" json:"-"`                                                // JSON serialized map[string]interface{}
	HasObject      bool      `gorm:"default:false" json:"-"`                                            // True when payload is stored in object storage
	CreatedAt      time.Time `gorm:"index;not null" json:"created_at"`

	// Virtual fields for JSON output - populated when needed
	ArgumentsParsed    interface{}             `gorm:"-" json:"arguments,omitempty"`
	ResultParsed       interface{}             `gorm:"-" json:"result,omitempty"`
	ErrorDetailsParsed *schemas.BifrostError   `gorm:"-" json:"error_details,omitempty"`
	MetadataParsed     map[string]interface{}  `gorm:"-" json:"metadata,omitempty"`
	VirtualKey         *tables.TableVirtualKey `gorm:"-" json:"virtual_key,omitempty"`
}

type MCPToolLogSearchFilters struct {
	ToolNames     []string   `json:"tool_names,omitempty"`
	ServerLabels  []string   `json:"server_labels,omitempty"`
	Status        []string   `json:"status,omitempty"`
	VirtualKeyIDs []string   `json:"virtual_key_ids,omitempty"`
	LLMRequestIDs []string   `json:"llm_request_ids,omitempty"`
	StartTime     *time.Time `json:"start_time,omitempty"`
	EndTime       *time.Time `json:"end_time,omitempty"`
	MinLatency    *float64   `json:"min_latency,omitempty"`
	MaxLatency    *float64   `json:"max_latency,omitempty"`
	ContentSearch string     `json:"content_search,omitempty"`
}

type MCPToolLogSearchResult struct {
	Logs       []MCPToolLog      `json:"logs"`
	Pagination PaginationOptions `json:"pagination"`
	HasLogs    bool              `json:"has_logs"`
}

type MCPToolLogStats struct {
	TotalExecutions int64   `json:"total_executions"`
	SuccessRate     float64 `json:"success_rate"`
	AverageLatency  float64 `json:"average_latency"`
	TotalCost       float64 `json:"total_cost"` // Total cost in dollars
}

type MCPTopToolResult struct {
	ToolName string  `json:"tool_name"`
	Count    int64   `json:"count"`
	Cost     float64 `json:"cost"`
}

type MCPTopToolsResult struct {
	Tools []MCPTopToolResult `json:"tools"`
}

type ModelHistogramBucket struct {
	Timestamp time.Time                  `json:"timestamp"`
	ByModel   map[string]ModelUsageStats `json:"by_model"`
}

type ModelHistogramResult struct {
	Buckets           []ModelHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                  `json:"bucket_size_seconds"`
	Models            []string               `json:"models"`
}

type ModelRankingEntry struct {
	Model         string  `json:"model"`
	Provider      string  `json:"provider"`
	TotalRequests int64   `json:"total_requests"`
	SuccessCount  int64   `json:"success_count"`
	SuccessRate   float64 `json:"success_rate"`
	TotalTokens   int64   `json:"total_tokens"`
	TotalCost     float64 `json:"total_cost"`
	AvgLatency    float64 `json:"avg_latency"`
}

type ModelRankingResult struct {
	Rankings []ModelRankingWithTrend `json:"rankings"`
}

type ModelRankingTrend struct {
	HasPreviousPeriod bool    `json:"has_previous_period"`
	RequestsTrend     float64 `json:"requests_trend"`
	TokensTrend       float64 `json:"tokens_trend"`
	CostTrend         float64 `json:"cost_trend"`
	LatencyTrend      float64 `json:"latency_trend"`
}

type ModelRankingWithTrend struct {
	ModelRankingEntry
	Trend ModelRankingTrend `json:"trend"`
}

type ModelUsageStats struct {
	Total   int64 `json:"total"`
	Success int64 `json:"success"`
	Error   int64 `json:"error"`
}

type NodeUsageAggregate struct {
	BudgetCosts       map[string]float64 `json:"budget_costs"`        // budget_id -> cumulative cost
	RateLimitRequests map[string]int64   `json:"rate_limit_requests"` // rate_limit_id -> successful request count
	RateLimitTokens   map[string]int64   `json:"rate_limit_tokens"`   // rate_limit_id -> total tokens
	RowCount          int                `json:"row_count"`           // number of log rows included in the aggregate
	MaxTimestamp      time.Time          `json:"max_timestamp"`       // highest log timestamp included in the aggregate
	MaxLogID          string             `json:"max_log_id"`          // log ID tiebreaker for MaxTimestamp
	NextCursor        NodeUsageCursor    `json:"next_cursor"`         // stable cursor for the next incremental query
}

type NodeUsageCursor struct {
	Timestamp time.Time `json:"timestamp"`
	LogID     string    `json:"log_id"`
	IncNumber *int64    `json:"inc_number,omitempty"`
}

type PaginationOptions struct {
	Limit      int    `json:"limit"`
	Offset     int    `json:"offset"`
	SortBy     string `json:"sort_by"`     // "timestamp", "latency", "tokens", "cost"
	Order      string `json:"order"`       // "asc", "desc"
	TotalCount int64  `json:"total_count"` // Total number of items matching the query
}

type PostgresConfig struct {
	Host         *schemas.EnvVar `json:"host"`
	Port         *schemas.EnvVar `json:"port"`
	User         *schemas.EnvVar `json:"user"`
	Password     *schemas.EnvVar `json:"password"`
	DBName       *schemas.EnvVar `json:"db_name"`
	SSLMode      *schemas.EnvVar `json:"ssl_mode"`
	MaxIdleConns int             `json:"max_idle_conns"`
	MaxOpenConns int             `json:"max_open_conns"`
	// MatViewRefreshInterval controls how often the materialized views backing
	// /api/logs/stats and the dashboard histograms are refreshed. Accepts any
	// Go duration string ("30s", "5m", "1h"). Empty / unset uses the default
	// (defaultMatViewRefreshInterval). Raise this when refresh CPU cost is
	// material on the database instance — the matview path already has
	// activity-gated short-circuiting (see matViewRefreshGate), so the longer
	// interval mostly affects how quickly idle clusters notice the rolling
	// 30-day filter window has aged.
	MatViewRefreshInterval string `json:"matview_refresh_interval,omitempty"`
}

type ProviderCostHistogramBucket struct {
	Timestamp  time.Time          `json:"timestamp"`
	TotalCost  float64            `json:"total_cost"`
	ByProvider map[string]float64 `json:"by_provider"`
}

type ProviderCostHistogramResult struct {
	Buckets           []ProviderCostHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                         `json:"bucket_size_seconds"`
	Providers         []string                      `json:"providers"`
}

type ProviderLatencyHistogramBucket struct {
	Timestamp  time.Time                       `json:"timestamp"`
	ByProvider map[string]ProviderLatencyStats `json:"by_provider"`
}

type ProviderLatencyHistogramResult struct {
	Buckets           []ProviderLatencyHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                            `json:"bucket_size_seconds"`
	Providers         []string                         `json:"providers"`
}

type ProviderLatencyStats struct {
	AvgLatency    float64 `json:"avg_latency"`
	P90Latency    float64 `json:"p90_latency"`
	P95Latency    float64 `json:"p95_latency"`
	P99Latency    float64 `json:"p99_latency"`
	TotalRequests int64   `json:"total_requests"`
}

type ProviderTokenHistogramBucket struct {
	Timestamp  time.Time                     `json:"timestamp"`
	ByProvider map[string]ProviderTokenStats `json:"by_provider"`
}

type ProviderTokenHistogramResult struct {
	Buckets           []ProviderTokenHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                          `json:"bucket_size_seconds"`
	Providers         []string                       `json:"providers"`
}

type ProviderTokenStats struct {
	PromptTokens     int64 `json:"prompt_tokens"`
	CompletionTokens int64 `json:"completion_tokens"`
	TotalTokens      int64 `json:"total_tokens"`
}

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

type RankingDimension string

type SQLiteConfig struct {
	Path string `json:"path"`
}

type SearchFilters struct {
	Providers         []string          `json:"providers,omitempty"`
	Models            []string          `json:"models,omitempty"`
	Aliases           []string          `json:"aliases,omitempty"`
	Status            []string          `json:"status,omitempty"`
	StopReasons       []string          `json:"stop_reasons,omitempty"` // For filtering by stop reason (stop, length, content_filter, refusal, tool_calls, etc.)
	Objects           []string          `json:"objects,omitempty"`      // For filtering by request type (chat.completion, text.completion, embedding)
	ParentRequestID   string            `json:"parent_request_id,omitempty"`
	SelectedKeyIDs    []string          `json:"selected_key_ids,omitempty"`
	VirtualKeyIDs     []string          `json:"virtual_key_ids,omitempty"`
	RoutingRuleIDs    []string          `json:"routing_rule_ids,omitempty"`
	TeamIDs           []string          `json:"team_ids,omitempty"`
	CustomerIDs       []string          `json:"customer_ids,omitempty"`
	UserIDs           []string          `json:"user_ids,omitempty"`
	BusinessUnitIDs   []string          `json:"business_unit_ids,omitempty"`
	RoutingEngineUsed []string          `json:"routing_engine_used,omitempty"` // For filtering by routing engine (routing-rule, governance, loadbalancing)
	StartTime         *time.Time        `json:"start_time,omitempty"`
	EndTime           *time.Time        `json:"end_time,omitempty"`
	MinLatency        *float64          `json:"min_latency,omitempty"`
	MaxLatency        *float64          `json:"max_latency,omitempty"`
	MinTokens         *int              `json:"min_tokens,omitempty"`
	MaxTokens         *int              `json:"max_tokens,omitempty"`
	MinCost           *float64          `json:"min_cost,omitempty"`
	MaxCost           *float64          `json:"max_cost,omitempty"`
	MissingCostOnly   bool              `json:"missing_cost_only,omitempty"`
	CacheHitTypes     []string          `json:"cache_hit_types,omitempty"` // For filtering by local-cache hit type ("direct", "semantic")
	ContentSearch     string            `json:"content_search,omitempty"`
	MetadataFilters   map[string]string `json:"metadata_filters,omitempty"` // key=metadataKey, value=metadataValue for filtering by metadata
}

type SearchResult struct {
	Logs       []Log             `json:"logs"`
	Pagination PaginationOptions `json:"pagination"`
	Stats      SearchStats       `json:"stats"`
	HasLogs    bool              `json:"has_logs"`
}

type SearchStats struct {
	TotalRequests             int64   `json:"total_requests"`
	SuccessRate               float64 `json:"success_rate"`                            // Percentage of individual attempts that succeeded
	UserFacingSuccessRate     float64 `json:"user_facing_success_rate"`                // Percentage of user requests that ultimately succeeded (fallback chains counted as one request)
	UserFacingTotalRequests   int64   `json:"user_facing_total_requests"`              // Count of root requests (fallback_index = 0) used as denominator for UserFacingSuccessRate
	AverageLatency            float64 `json:"average_latency"`                         // Average latency in milliseconds
	TotalTokens               int64   `json:"total_tokens"`                            // Total tokens used
	TotalCost                 float64 `json:"total_cost"`                              // Total cost in dollars
	CacheHitRateTotalRequests *int64  `json:"cache_hit_rate_total_requests,omitempty"` // Completed requests used as local-cache hit-rate denominator
	DirectCacheHits           *int64  `json:"direct_cache_hits,omitempty"`             // Number of direct (exact) semantic cache hits
	SemanticCacheHits         *int64  `json:"semantic_cache_hits,omitempty"`           // Number of semantic (fuzzy) cache hits
}

type SessionDetailResult struct {
	SessionID     string            `json:"session_id"`
	Logs          []Log             `json:"logs"`
	Pagination    PaginationOptions `json:"pagination"`
	Count         int64             `json:"count"`
	ReturnedCount int               `json:"returned_count"`
	HasMore       bool              `json:"has_more"`
}

type SessionSummaryResult struct {
	SessionID   string  `json:"session_id"`
	Count       int64   `json:"count"`
	TotalCost   float64 `json:"total_cost"`
	TotalTokens int64   `json:"total_tokens"`
	StartedAt   string  `json:"started_at,omitempty"`
	LatestAt    string  `json:"latest_at,omitempty"`
	DurationMs  int64   `json:"duration_ms"`
}

type SortBy string

type SortOrder string

type TokenHistogramBucket struct {
	Timestamp        time.Time `json:"timestamp"`
	PromptTokens     int64     `json:"prompt_tokens"`
	CompletionTokens int64     `json:"completion_tokens"`
	TotalTokens      int64     `json:"total_tokens"`
	CachedReadTokens int64     `json:"cached_read_tokens"`
}

type TokenHistogramResult struct {
	Buckets           []TokenHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                  `json:"bucket_size_seconds"`
}

type UserRankingEntry struct {
	UserID        string  `json:"user_id"`
	TotalRequests int64   `json:"total_requests"`
	TotalTokens   int64   `json:"total_tokens"`
	TotalCost     float64 `json:"total_cost"`
}

type UserRankingResult struct {
	Rankings []UserRankingWithTrend `json:"rankings"`
}

type UserRankingTrend struct {
	HasPreviousPeriod bool    `json:"has_previous_period"`
	RequestsTrend     float64 `json:"requests_trend"`
	TokensTrend       float64 `json:"tokens_trend"`
	CostTrend         float64 `json:"cost_trend"`
}

type UserRankingWithTrend struct {
	UserRankingEntry
	Trend UserRankingTrend `json:"trend"`
}