llmops

type APIError struct {
	StatusCode int
	Message    string
	Details    map[string]any
	Provider   string
	Err        error
}

type Annotation struct {
	ID          string         `json:"id,omitempty"`
	SpanID      string         `json:"span_id,omitempty"`  // Set for span annotations
	TraceID     string         `json:"trace_id,omitempty"` // Set for trace annotations
	Name        string         `json:"name"`               // Annotation name/type
	Score       float64        `json:"score,omitempty"`    // Numeric score (0-1)
	Label       string         `json:"label,omitempty"`    // Categorical label
	Explanation string         `json:"explanation,omitempty"`
	Source      AnnotatorKind  `json:"source,omitempty"` // Who created: human, llm, code
	Metadata    map[string]any `json:"metadata,omitempty"`
	CreatedAt   time.Time      `json:"created_at,omitempty"`
	UpdatedAt   time.Time      `json:"updated_at,omitempty"`
}

type AnnotationManager interface {
	// CreateAnnotation creates an annotation on a span or trace.
	// Either SpanID or TraceID must be set in the annotation.
	CreateAnnotation(ctx context.Context, annotation Annotation) error

	// ListAnnotations lists annotations for spans or traces.
	// Provide either spanIDs or traceIDs (not both).
	ListAnnotations(ctx context.Context, opts ListAnnotationsOptions) ([]*Annotation, error)
}

type AnnotatorKind string

type Capability string

type CapabilityChecker interface {
	// HasCapability checks if the provider supports a given capability.
	HasCapability(cap Capability) bool

	// Capabilities returns all supported capabilities.
	Capabilities() []Capability
}

type ClientOption func(*ClientOptions)

type ClientOptions struct {
	APIKey      string
	Endpoint    string
	Workspace   string
	ProjectName string
	HTTPClient  *http.Client
	Timeout     time.Duration
	Disabled    bool
	Debug       bool
}

type Dataset struct {
	ID          string         `json:"id"`
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Tags        []string       `json:"tags,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	ItemCount   int            `json:"item_count,omitempty"`
	CreatedAt   time.Time      `json:"created_at"`
	UpdatedAt   time.Time      `json:"updated_at"`
}

type DatasetItem struct {
	ID       string         `json:"id,omitempty"`
	Input    any            `json:"input,omitempty"`
	Expected any            `json:"expected,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
	Tags     []string       `json:"tags,omitempty"`

	// Optional references for items created from traces
	TraceID string `json:"trace_id,omitempty"`
	SpanID  string `json:"span_id,omitempty"`
}

type DatasetManager interface {
	// CreateDataset creates a new dataset for evaluation.
	CreateDataset(ctx context.Context, name string, opts ...DatasetOption) (*Dataset, error)

	// GetDataset retrieves a dataset by name.
	GetDataset(ctx context.Context, name string) (*Dataset, error)

	// GetDatasetByID retrieves a dataset by ID.
	GetDatasetByID(ctx context.Context, id string) (*Dataset, error)

	// AddDatasetItems adds items to a dataset.
	AddDatasetItems(ctx context.Context, datasetName string, items []DatasetItem) error

	// ListDatasets lists available datasets.
	ListDatasets(ctx context.Context, opts ...ListOption) ([]*Dataset, error)

	// DeleteDataset deletes a dataset by ID.
	DeleteDataset(ctx context.Context, datasetID string) error
}

type DatasetOption func(*DatasetOptions)

type DatasetOptions struct {
	Description string
	Tags        []string
	Metadata    map[string]any
}

type EndOption func(*EndOptions)

type EndOptions struct {
	Output   any
	Metadata map[string]any
	Error    error
}

type EvalInput struct {
	Input    any            `json:"input,omitempty"`    // User query/prompt
	Output   any            `json:"output,omitempty"`   // LLM response
	Expected any            `json:"expected,omitempty"` // Ground truth/expected output
	Context  []string       `json:"context,omitempty"`  // Retrieved context (for RAG)
	Metadata map[string]any `json:"metadata,omitempty"` // Additional metadata

	// Optional references
	TraceID string `json:"trace_id,omitempty"`
	SpanID  string `json:"span_id,omitempty"`
}

type EvalResult struct {
	Scores   []MetricScore  `json:"scores"`
	Metadata map[string]any `json:"metadata,omitempty"`
	Duration time.Duration  `json:"duration,omitempty"`
}

type Evaluator interface {
	// Evaluate runs evaluation metrics on the given input.
	Evaluate(ctx context.Context, input EvalInput, metrics ...Metric) (*EvalResult, error)

	// AddFeedbackScore adds a feedback score to a trace or span.
	AddFeedbackScore(ctx context.Context, opts FeedbackScoreOpts) error
}

type Experiment struct {
	ID          string         `json:"id"`
	Name        string         `json:"name"`
	DatasetID   string         `json:"dataset_id,omitempty"`
	DatasetName string         `json:"dataset_name,omitempty"`
	Status      string         `json:"status,omitempty"` // running, completed, cancelled
	Metadata    map[string]any `json:"metadata,omitempty"`
	CreatedAt   time.Time      `json:"created_at"`
	UpdatedAt   time.Time      `json:"updated_at"`
}

type ExperimentItem struct {
	ID            string         `json:"id,omitempty"`
	ExperimentID  string         `json:"experiment_id"`
	DatasetItemID string         `json:"dataset_item_id,omitempty"`
	Input         any            `json:"input,omitempty"`
	Output        any            `json:"output,omitempty"`
	Expected      any            `json:"expected,omitempty"`
	Scores        []MetricScore  `json:"scores,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
	TraceID       string         `json:"trace_id,omitempty"`
}

type FeedbackOption func(*FeedbackOptions)

type FeedbackOptions struct {
	Reason   string
	Category string
	Source   string
}

type FeedbackScore struct {
	Name     string  `json:"name"`
	Score    float64 `json:"score"`
	Reason   string  `json:"reason,omitempty"`
	Category string  `json:"category,omitempty"`
	Source   string  `json:"source,omitempty"` // e.g., "user", "llm", "heuristic"
}

type FeedbackScoreOpts struct {
	TraceID  string  `json:"trace_id,omitempty"`
	SpanID   string  `json:"span_id,omitempty"`
	Name     string  `json:"name"`
	Score    float64 `json:"score"`
	Reason   string  `json:"reason,omitempty"`
	Category string  `json:"category,omitempty"`
	Source   string  `json:"source,omitempty"`
}

type ListAnnotationsOptions struct {
	SpanIDs  []string // List annotations for these span IDs
	TraceIDs []string // List annotations for these trace IDs
}

type ListOption func(*ListOptions)

type ListOptions struct {
	Limit   int
	Offset  int
	OrderBy string
	Filter  map[string]any
}

type Metric interface {
	// Name returns the metric name.
	Name() string

	// Evaluate computes the metric score for the given input.
	Evaluate(input EvalInput) (MetricScore, error)
}

type MetricScore struct {
	Name     string  `json:"name"`
	Score    float64 `json:"score"`
	Reason   string  `json:"reason,omitempty"`
	Metadata any     `json:"metadata,omitempty"`
	Error    string  `json:"error,omitempty"`
}

type Project struct {
	ID          string         `json:"id"`
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	CreatedAt   time.Time      `json:"created_at"`
	UpdatedAt   time.Time      `json:"updated_at"`
}

type ProjectManager interface {
	// CreateProject creates a new project.
	CreateProject(ctx context.Context, name string, opts ...ProjectOption) (*Project, error)

	// GetProject retrieves a project by name.
	GetProject(ctx context.Context, name string) (*Project, error)

	// ListProjects lists available projects.
	ListProjects(ctx context.Context, opts ...ListOption) ([]*Project, error)

	// SetProject sets the current project for subsequent operations.
	SetProject(ctx context.Context, name string) error
}

type ProjectOption func(*ProjectOptions)

type ProjectOptions struct {
	Description string
	Metadata    map[string]any
}

type Prompt struct {
	ID            string         `json:"id"`
	Name          string         `json:"name"`
	Template      string         `json:"template"`
	Description   string         `json:"description,omitempty"`
	Version       string         `json:"version,omitempty"`
	Tags          []string       `json:"tags,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
	ModelName     string         `json:"model_name,omitempty"`     // LLM model name
	ModelProvider string         `json:"model_provider,omitempty"` // LLM provider
	CreatedAt     time.Time      `json:"created_at"`
	UpdatedAt     time.Time      `json:"updated_at"`
}

type PromptManager interface {
	// CreatePrompt creates a new prompt template.
	CreatePrompt(ctx context.Context, name string, template string, opts ...PromptOption) (*Prompt, error)

	// GetPrompt retrieves a prompt by name, optionally at a specific version or tag.
	// The version parameter can be:
	//   - Empty/omitted: returns the latest version
	//   - A tag name (e.g., "production", "staging"): returns the version with that tag
	//   - A version ID: returns that specific version (if provider supports)
	//
	// Tag-based versioning allows deployment patterns like:
	//   prompt, _ := provider.GetPrompt(ctx, "my-prompt", "production")
	GetPrompt(ctx context.Context, name string, version ...string) (*Prompt, error)

	// ListPrompts lists available prompts.
	ListPrompts(ctx context.Context, opts ...ListOption) ([]*Prompt, error)
}

type PromptOption func(*PromptOptions)

type PromptOptions struct {
	Description   string
	Tags          []string
	Metadata      map[string]any
	ModelName     string // LLM model name (e.g., "gpt-4", "claude-3")
	ModelProvider string // LLM provider (e.g., "openai", "anthropic")
}

type Provider interface {
	Tracer
	Evaluator
	PromptManager
	DatasetManager
	ProjectManager
	AnnotationManager
	io.Closer

	// Name returns the provider name (e.g., "opik", "langfuse", "phoenix")
	Name() string
}

type ProviderFactory func(opts ...ClientOption) (Provider, error)

type ProviderInfo struct {
	Name         string
	Description  string
	Website      string
	OpenSource   bool
	SelfHosted   bool
	Capabilities []Capability
}

type Span interface {
	// ID returns the unique identifier for this span.
	ID() string

	// TraceID returns the parent trace ID.
	TraceID() string

	// ParentSpanID returns the parent span ID, if this is a nested span.
	ParentSpanID() string

	// Name returns the span name.
	Name() string

	// Type returns the span type (general, llm, tool, guardrail).
	Type() SpanType

	// StartSpan creates a child span within this span.
	StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span, error)

	// SetInput sets the span input data.
	SetInput(input any) error

	// SetOutput sets the span output data.
	SetOutput(output any) error

	// SetMetadata sets additional metadata on the span.
	SetMetadata(metadata map[string]any) error

	// SetModel sets the LLM model name (e.g., "gpt-4", "claude-3-opus").
	SetModel(model string) error

	// SetProvider sets the LLM provider name (e.g., "openai", "anthropic").
	SetProvider(provider string) error

	// SetUsage sets token usage information.
	SetUsage(usage TokenUsage) error

	// AddTag adds a tag to the span.
	AddTag(tag string) error

	// AddFeedbackScore adds a feedback score to this span.
	AddFeedbackScore(ctx context.Context, name string, score float64, opts ...FeedbackOption) error

	// End completes the span with optional final output and metadata.
	End(opts ...EndOption) error

	// EndTime returns when the span ended, if it has ended.
	EndTime() *time.Time

	// Duration returns the span duration, or time since start if not ended.
	Duration() time.Duration
}

type SpanInfo struct {
	ID           string          `json:"id"`
	TraceID      string          `json:"trace_id"`
	ParentSpanID string          `json:"parent_span_id,omitempty"`
	Name         string          `json:"name"`
	Type         SpanType        `json:"type"`
	StartTime    time.Time       `json:"start_time"`
	EndTime      *time.Time      `json:"end_time,omitempty"`
	Input        any             `json:"input,omitempty"`
	Output       any             `json:"output,omitempty"`
	Metadata     map[string]any  `json:"metadata,omitempty"`
	Model        string          `json:"model,omitempty"`
	Provider     string          `json:"provider,omitempty"`
	Usage        *TokenUsage     `json:"usage,omitempty"`
	Tags         []string        `json:"tags,omitempty"`
	Feedback     []FeedbackScore `json:"feedback,omitempty"`
}

type SpanOption func(*SpanOptions)

type SpanOptions struct {
	Type         SpanType
	Input        any
	Output       any
	Metadata     map[string]any
	Tags         []string
	Model        string
	Provider     string
	Usage        *TokenUsage
	ParentSpanID string
}

type SpanType string

type StreamAccumulator struct {
	Chunks       []StreamChunk `json:"chunks"`
	TotalContent string        `json:"total_content"`
	TotalTokens  int           `json:"total_tokens"`
	ChunkCount   int           `json:"chunk_count"`
	StartTime    time.Time     `json:"start_time"`
	FirstChunkAt *time.Time    `json:"first_chunk_at,omitempty"`
	FinishReason string        `json:"finish_reason,omitempty"`
}

type StreamChunk struct {
	Content      string         `json:"content,omitempty"`
	TokenCount   int            `json:"token_count,omitempty"`
	Index        int            `json:"index,omitempty"`
	FinishReason string         `json:"finish_reason,omitempty"`
	Metadata     map[string]any `json:"metadata,omitempty"`
}

type TokenUsage struct {
	PromptTokens     int `json:"prompt_tokens,omitempty"`
	CompletionTokens int `json:"completion_tokens,omitempty"`
	TotalTokens      int `json:"total_tokens,omitempty"`

	// Cost tracking (optional, provider-dependent)
	PromptCost     float64 `json:"prompt_cost,omitempty"`
	CompletionCost float64 `json:"completion_cost,omitempty"`
	TotalCost      float64 `json:"total_cost,omitempty"`
	Currency       string  `json:"currency,omitempty"` // e.g., "USD"
}

type Trace interface {
	// ID returns the unique identifier for this trace.
	ID() string

	// Name returns the trace name.
	Name() string

	// StartSpan creates a child span within this trace.
	StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span, error)

	// SetInput sets the trace input data.
	SetInput(input any) error

	// SetOutput sets the trace output data.
	SetOutput(output any) error

	// SetMetadata sets additional metadata on the trace.
	SetMetadata(metadata map[string]any) error

	// AddTag adds a tag to the trace.
	AddTag(tag string) error

	// AddFeedbackScore adds a feedback score to this trace.
	AddFeedbackScore(ctx context.Context, name string, score float64, opts ...FeedbackOption) error

	// End completes the trace with optional final output and metadata.
	End(opts ...EndOption) error

	// EndTime returns when the trace ended, if it has ended.
	EndTime() *time.Time

	// Duration returns the trace duration, or time since start if not ended.
	Duration() time.Duration
}

type TraceInfo struct {
	ID        string          `json:"id"`
	Name      string          `json:"name"`
	ProjectID string          `json:"project_id,omitempty"`
	StartTime time.Time       `json:"start_time"`
	EndTime   *time.Time      `json:"end_time,omitempty"`
	Input     any             `json:"input,omitempty"`
	Output    any             `json:"output,omitempty"`
	Metadata  map[string]any  `json:"metadata,omitempty"`
	Tags      []string        `json:"tags,omitempty"`
	Feedback  []FeedbackScore `json:"feedback,omitempty"`
}

type TraceOption func(*TraceOptions)

type TraceOptions struct {
	ProjectName string
	Input       any
	Output      any
	Metadata    map[string]any
	Tags        []string
	ThreadID    string // For conversation threading
}

type Tracer interface {
	// StartTrace begins a new trace, optionally attaching it to the context.
	StartTrace(ctx context.Context, name string, opts ...TraceOption) (context.Context, Trace, error)

	// StartSpan begins a new span within the current trace context.
	// If no trace exists in context, implementations may create one or return an error.
	StartSpan(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span, error)

	// TraceFromContext retrieves the current trace from context, if any.
	TraceFromContext(ctx context.Context) (Trace, bool)

	// SpanFromContext retrieves the current span from context, if any.
	SpanFromContext(ctx context.Context) (Span, bool)
}