langfuse

type AgentUsageStats struct {
	// AgentName is the trace name (i.e. the agent identifier) in Langfuse.
	AgentName string `json:"agent_name"`
	// TotalCost is the total cost in USD for all observations belonging to
	// this agent's traces within the queried time window.
	TotalCost float64 `json:"total_cost"`
	// InputTokens is the sum of input tokens consumed across all observations.
	InputTokens float64 `json:"input_tokens"`
	// OutputTokens is the sum of output tokens produced across all observations.
	OutputTokens float64 `json:"output_tokens"`
	// TotalTokens is the sum of all tokens consumed across all observations.
	TotalTokens float64 `json:"total_tokens"`
	// Count is the total number of observations for this agent.
	Count float64 `json:"count"`
}

type AnalyzeTracesRequest struct {
	// UserID filters traces to a specific user. Optional.
	UserID string

	// SessionID filters traces to a specific session. Optional.
	SessionID string

	// AgentName filters traces by agent (trace name). Optional.
	AgentName string

	// Duration is the lookback window from now. Required when using Analyze().
	Duration time.Duration

	// Tags filters traces to those matching these tags. Optional.
	Tags []string

	// Limit caps the number of traces fetched. Defaults to 100.
	Limit int
}

type Client interface {
	// GetPrompt returns the prompt template by name, or the default if not found/disabled.
	GetPrompt(ctx context.Context, name, defaultPrompt string) string

	// GetAgentStats returns aggregated token usage and cost statistics per
	// agent (trace name) for the duration specified in the request. Without
	// this method, consumers would need to call the Langfuse metrics API
	// directly, duplicating auth and parsing logic.
	GetAgentStats(ctx context.Context, req GetAgentStatsRequest) ([]AgentUsageStats, error)
}

type Config struct {
	PublicKey     string `json:"public_key" toml:"public_key,omitempty" yaml:"public_key,omitempty"`
	SecretKey     string `json:"secret_key" toml:"secret_key,omitempty" yaml:"secret_key,omitempty"`
	Host          string `json:"host" toml:"host,omitempty" yaml:"host,omitempty"`
	EnablePrompts bool   `json:"enable_prompts" toml:"enable_prompts,omitempty" yaml:"enable_prompts,omitempty"`
}

type GetAgentStatsRequest struct {
	// Duration is the lookback period from now (e.g. 24h, 7*24h).
	Duration time.Duration
	// AgentName optionally restricts the query to a single agent.
	// When empty, stats for all agents are returned.
	AgentName string
}

type GetObservationsRequest struct {
	TraceID string

	// Page is the 1-based page number. Defaults to 1 when zero.
	Page int

	// Limit caps the number of observations per page.
	// Defaults to 100 when zero. Langfuse enforces a server-side max of 100.
	Limit int
}

type GetTraceRequest struct {
	TraceID string
}

type ObsUsage struct {
	Input  int     `json:"input"`
	Output int     `json:"output"`
	Total  int     `json:"total"`
	Unit   string  `json:"unit,omitempty"`
	Cost   float64 `json:"totalCost,omitempty"`
}

type Observation struct {
	ID                  string         `json:"id"`
	TraceID             string         `json:"traceId"`
	ParentObservationID *string        `json:"parentObservationId"`
	Type                string         `json:"type"` // "GENERATION", "SPAN", "EVENT", "TOOL", "AGENT", "CHAIN"
	Name                string         `json:"name"`
	StartTime           time.Time      `json:"startTime"`
	EndTime             *time.Time     `json:"endTime,omitempty"`
	CompletionStartTime *time.Time     `json:"completionStartTime,omitempty"`
	Model               string         `json:"model,omitempty"`
	ModelParameters     map[string]any `json:"modelParameters,omitempty"`
	Input               any            `json:"input,omitempty"`
	Output              any            `json:"output,omitempty"`
	Metadata            any            `json:"metadata,omitempty"`
	Level               string         `json:"level,omitempty"`
	StatusMessage       string         `json:"statusMessage,omitempty"`
	Version             string         `json:"version,omitempty"`
	Environment         string         `json:"environment,omitempty"`
	Usage               *ObsUsage      `json:"usage,omitempty"`
	PromptName          *string        `json:"promptName,omitempty"`
	PromptVersion       *int           `json:"promptVersion,omitempty"`

	CalculatedTotalCost  float64 `json:"calculatedTotalCost,omitempty"`
	CalculatedInputCost  float64 `json:"calculatedInputCost,omitempty"`
	CalculatedOutputCost float64 `json:"calculatedOutputCost,omitempty"`

	TimeToFirstToken *float64       `json:"timeToFirstToken,omitempty"`
	Latency          float64        `json:"latency,omitempty"`
	UsageDetails     map[string]any `json:"usageDetails,omitempty"`
	CostDetails      map[string]any `json:"costDetails,omitempty"`
}

type Option func(*TraceAnalyzer)

type SubAgentDetail struct {
	Name      string `json:"name"`
	Input     string `json:"input,omitempty"`
	Output    string `json:"output,omitempty"`
	LLMCalls  int    `json:"llm_calls"`
	ToolCalls int    `json:"tool_calls"`
}

type ToolCallDetail struct {
	Name   string `json:"name"`
	Input  string `json:"input,omitempty"`
	Output string `json:"output,omitempty"`
	// ParentName is the name of the parent span/agent that made this call.
	ParentName string `json:"parent_name,omitempty"`
}

type Trace struct {
	ID        string    `json:"id"`
	Timestamp time.Time `json:"timestamp"`
	Name      string    `json:"name"`
	UserID    string    `json:"userId"`
	SessionID *string   `json:"sessionId"`
	Input     any       `json:"input"`
	Output    any       `json:"output"`
	Tags      []string  `json:"tags"`
	Version   string    `json:"version,omitempty"`
}

type TraceAnalysisResult struct {
	// TracesAnalyzed is the total number of traces processed.
	TracesAnalyzed int `json:"traces_analyzed"`

	// TraceDetails contains the per-trace execution breakdown.
	TraceDetails TraceDetails `json:"trace_details"`

	// Aggregated totals across all traces.
	TotalToolCalls      int `json:"total_tool_calls"`
	TotalLLMCalls       int `json:"total_llm_calls"`
	TotalSubAgents      int `json:"total_sub_agents"`
	TotalVectorStoreOps int `json:"total_vector_store_ops"`
	TotalInputTokens    int `json:"total_input_tokens"`
	TotalOutputTokens   int `json:"total_output_tokens"`
}

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

type TraceClient interface {
	GetTrace(ctx context.Context, req GetTraceRequest) (*Trace, error)
	GetObservations(ctx context.Context, req GetObservationsRequest) ([]Observation, error)
}

type TraceDetail struct {
	// TraceID is the Langfuse trace ID.
	TraceID string `json:"trace_id"`

	// AgentName is the top-level agent (trace name).
	AgentName string `json:"agent_name"`

	// UserID is who made the request.
	UserID string `json:"user_id"`

	// SessionID is the conversation session.
	SessionID string `json:"session_id,omitempty"`

	// Timestamp is when the request was made.
	Timestamp time.Time `json:"timestamp"`

	// Input is the user's original request.
	Input string `json:"input"`

	// Output is the agent's final response (nil if no output).
	Output *string `json:"output"`

	// ToolCalls lists every top-level tool invocation in this trace.
	// Tool calls made within sub-agents (i.e., spans that are descendants of a sub-agent)
	// are not included here.
	ToolCalls []ToolCallDetail `json:"tool_calls"`

	// SubAgents lists every sub-agent that was created.
	SubAgents []SubAgentDetail `json:"sub_agents"`

	// LLMCalls is the total number of LLM generation calls.
	LLMCalls int `json:"llm_calls"`

	// VectorStoreOps is the number of vector store add operations.
	VectorStoreOps int `json:"vector_store_ops"`

	// InputTokens is the sum of input tokens across all generations.
	InputTokens int `json:"input_tokens"`

	// OutputTokens is the sum of output tokens across all generations.
	OutputTokens int `json:"output_tokens"`

	// TotalCost is the estimated total cost (USD).
	TotalCost float64 `json:"total_cost"`

	// Duration is the total trace duration (first observation to last).
	Duration time.Duration `json:"duration"`
}

type TraceDetails []TraceDetail