agentobs

type AgentEvent struct {
	// Type identifies the kind of event.
	Type EventType `json:"type"`

	// Timestamp is when the event occurred.
	Timestamp time.Time `json:"timestamp"`

	// SessionID identifies the agent session this event belongs to.
	SessionID string `json:"session_id,omitempty"`

	// TraceID is the Opik trace ID for correlation.
	TraceID string `json:"trace_id,omitempty"`

	// SpanID is the Opik span ID for this specific event.
	SpanID string `json:"span_id,omitempty"`

	// ParentSpanID is the parent span ID for nested operations.
	ParentSpanID string `json:"parent_span_id,omitempty"`

	// Data contains event-specific payload.
	// The structure depends on the event type.
	Data map[string]any `json:"data,omitempty"`
}

type AgentObserver interface {
	// OnEvent processes an agent event.
	// The implementation should translate the event to the appropriate
	// backend-specific operations (e.g., creating traces, spans, etc.)
	OnEvent(ctx context.Context, event AgentEvent) error

	// Flush ensures all pending events are sent to the backend.
	Flush(ctx context.Context) error

	// Close releases resources and stops the observer.
	Close() error
}

type EventFilter func(event AgentEvent) bool

type EventType string

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

type MediaRef struct {
	// Type is the media type (image, audio, video, document, etc.)
	Type string `json:"type"`

	// MimeType is the MIME type of the media.
	MimeType string `json:"mime_type,omitempty"`

	// Source indicates where the media came from (url, file, data, markdown).
	Source string `json:"source"`

	// URL is the media URL if applicable.
	URL string `json:"url,omitempty"`

	// Data contains inline data (e.g., base64-decoded bytes).
	Data []byte `json:"data,omitempty"`

	// Alt is the alt text or description if available.
	Alt string `json:"alt,omitempty"`

	// Original is the original reference string as found in content.
	Original string `json:"original,omitempty"`
}

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

type NoOpObserver struct{}

type SanitizeConfig struct {
	// RemoveInternalMarkers removes framework-specific internal markers.
	RemoveInternalMarkers bool

	// RemoveMetadataBlocks removes metadata blocks like <system-reminder>.
	RemoveMetadataBlocks bool

	// RemoveSecrets removes patterns that look like secrets or API keys.
	RemoveSecrets bool

	// RemoveAnsiCodes removes ANSI escape codes from terminal output.
	RemoveAnsiCodes bool

	// MaxLength truncates content exceeding this length (0 = no limit).
	MaxLength int

	// CustomPatterns are additional regex patterns to remove.
	CustomPatterns []*regexp.Regexp
}

type Span interface {
	// ID returns the span ID.
	ID() string

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

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

	// End ends the span with optional output.
	End(ctx context.Context, output any, err error) error

	// CreateChildSpan creates a child span.
	CreateChildSpan(ctx context.Context, name string, spanType string, input any) (Span, error)
}

type Trace interface {
	// ID returns the trace ID.
	ID() string

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

	// End ends the trace with optional output.
	End(ctx context.Context, output any) error

	// Update updates the trace metadata.
	Update(ctx context.Context, metadata map[string]any) error

	// CreateSpan creates a new span within this trace.
	CreateSpan(ctx context.Context, name string, spanType string, input any) (Span, error)
}

type TraceClient interface {
	// CreateTrace creates a new trace.
	CreateTrace(ctx context.Context, name string, input any, tags []string) (Trace, error)

	// IsTracingEnabled returns whether tracing is active.
	IsTracingEnabled() bool
}

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

type TraceManagerConfig struct {
	// StaleTimeout is how long a trace can be inactive before being closed.
	// Default: 5 minutes.
	StaleTimeout time.Duration

	// SweepInterval is how often to check for stale traces.
	// Default: 1 minute.
	SweepInterval time.Duration

	// DefaultTags are applied to all traces.
	DefaultTags []string

	// ProjectName is the default Opik project name.
	ProjectName string

	// SanitizeContent enables content sanitization.
	// Default: true.
	SanitizeContent bool

	// SanitizeConfig is the sanitization configuration.
	// Used when SanitizeContent is true.
	SanitizeConfig SanitizeConfig

	// ExtractMedia enables media extraction from content.
	// Default: true.
	ExtractMedia bool

	// TraceNamePrefix is prepended to trace names.
	// Default: "agent.session."
	TraceNamePrefix string
}

type TraceManagerOption func(*TraceManagerConfig)

type TraceState struct {
	Trace        Trace
	SessionID    string
	LastActivity time.Time
	OpenSpans    map[string]Span // spanID -> Span
	SpanStack    []string        // Stack of span IDs for nesting
	// contains filtered or unexported fields
}