annotations

type Annotation struct {
	// ID is a unique identifier for this annotation.
	ID string `json:"id"`

	// Type identifies the kind of annotation.
	Type AnnotationType `json:"type"`

	// SessionID is the session this annotation belongs to.
	SessionID string `json:"session_id"`

	// Target specifies what this annotation targets.
	Target Target `json:"target"`

	// Key is the annotation key (e.g., "quality", "category", "safety").
	Key string `json:"key"`

	// Value holds the annotation value (type depends on annotation type).
	Value AnnotationValue `json:"value"`

	// Metadata contains additional structured data.
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// CreatedAt is when this annotation was created.
	CreatedAt time.Time `json:"created_at"`

	// CreatedBy identifies who created this annotation.
	CreatedBy string `json:"created_by,omitempty"`

	// Version is the annotation version (for corrections/updates).
	Version int `json:"version"`

	// PreviousID references the previous version if this is an update.
	PreviousID string `json:"previous_id,omitempty"`
}

type AnnotationType string

type AnnotationValue struct {
	// Score is the numeric value (for TypeScore, TypeMetric).
	Score *float64 `json:"score,omitempty"`

	// Label is the categorical value (for TypeLabel, TypeGroundTruth).
	Label string `json:"label,omitempty"`

	// Labels is a list of categorical values (for multi-label scenarios).
	Labels []string `json:"labels,omitempty"`

	// Text is the textual value (for TypeComment).
	Text string `json:"text,omitempty"`

	// Flag is the boolean value (for TypeFlag).
	Flag *bool `json:"flag,omitempty"`

	// Passed indicates assertion result (for TypeAssertion).
	Passed *bool `json:"passed,omitempty"`

	// Message is an optional message (for TypeAssertion, TypeComment).
	Message string `json:"message,omitempty"`

	// Unit is the unit of measurement (for TypeMetric).
	Unit string `json:"unit,omitempty"`
}

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

type Filter struct {
	// SessionID filters by session.
	SessionID string

	// Types filters by annotation type.
	Types []AnnotationType

	// Keys filters by annotation key.
	Keys []string

	// TargetTypes filters by target type.
	TargetTypes []TargetType

	// EventID filters by target event ID.
	EventID string

	// TurnIndex filters by target turn index.
	TurnIndex *int

	// CreatedBy filters by creator.
	CreatedBy string

	// Since filters by creation time (inclusive).
	Since time.Time

	// Until filters by creation time (exclusive).
	Until time.Time

	// IncludeDeleted includes deleted annotations.
	IncludeDeleted bool

	// LatestVersionOnly returns only the latest version of each annotation.
	LatestVersionOnly bool

	// Limit limits the number of results.
	Limit int
}

type Store interface {
	// Add creates a new annotation.
	Add(ctx context.Context, ann *Annotation) error

	// Update creates a new version of an existing annotation.
	// The new annotation will reference the previous version.
	Update(ctx context.Context, previousID string, ann *Annotation) error

	// Get retrieves an annotation by ID.
	Get(ctx context.Context, id string) (*Annotation, error)

	// Query returns annotations matching the filter.
	Query(ctx context.Context, filter *Filter) ([]*Annotation, error)

	// Delete removes an annotation by ID.
	// Note: This is a soft delete - the annotation is marked as deleted but preserved.
	Delete(ctx context.Context, id string) error

	// Close releases resources held by the store.
	Close() error
}

type Target struct {
	// Type identifies the target type.
	Type TargetType `json:"type"`

	// EventID is the target event ID (for TargetEvent).
	EventID string `json:"event_id,omitempty"`

	// EventSequence is the target event sequence number (alternative to EventID).
	EventSequence int64 `json:"event_sequence,omitempty"`

	// TurnIndex is the target turn index (for TargetTurn).
	TurnIndex int `json:"turn_index,omitempty"`

	// MessageIndex is the target message index (for TargetMessage).
	MessageIndex int `json:"message_index,omitempty"`

	// StartTime is the start of the time range (for TargetTimeRange).
	StartTime time.Time `json:"start_time,omitempty"`

	// EndTime is the end of the time range (for TargetTimeRange).
	EndTime time.Time `json:"end_time,omitempty"`
}

type TargetType string