prompt

type Argument struct {
	Name        string `json:"name" example:"date"`
	Description string `json:"description" example:"The date to analyze (YYYY-MM-DD)"`
	Required    bool   `json:"required" example:"true"`
}

type ListFilter struct {
	Scope           string   // "global", "persona", "personal", or "" for all
	Personas        []string // filter by persona membership (OR match)
	OwnerEmail      string   // filter by owner
	Enabled         *bool    // filter by enabled state
	Search          string   // free-text search on name, display_name, description
	ReviewRequested *bool    // filter by pending promotion request (admin queue)
	Source          string   // include only this origin (operator, agent, system); "" for all
	ExcludeSource   string   // exclude this origin (e.g. "system" to hide ingested static prompts)
}

type Prompt struct {
	ID          string     `json:"id" example:"prompt_a1b2c3d4"`
	Name        string     `json:"name" example:"daily-sales-report"`
	DisplayName string     `json:"display_name" example:"Daily Sales Report"`
	Description string     `json:"description" example:"Generate a daily sales summary by region"`
	Content     string     `json:"content" example:"Analyze sales data for {date} grouped by region."`
	Arguments   []Argument `json:"arguments"`
	Category    string     `json:"category" example:"analysis"`
	Scope       string     `json:"scope" example:"persona"`
	Personas    []string   `json:"personas" example:"analyst,data-engineer"`
	OwnerEmail  string     `json:"owner_email" example:"admin@example.com"`
	Source      string     `json:"source" example:"database"`
	Enabled     bool       `json:"enabled" example:"true"`
	Tags        []string   `json:"tags" example:"sales,reporting"`

	// Promotion lifecycle.
	Status       string     `json:"status" example:"approved"`
	ApprovedBy   string     `json:"approved_by,omitempty" example:"admin@example.com"`
	ApprovedAt   *time.Time `json:"approved_at,omitempty"`
	DeprecatedAt *time.Time `json:"deprecated_at,omitempty"`
	SupersededBy string     `json:"superseded_by,omitempty" example:"daily-sales-report-v2"`

	// Promotion request: an owner asks to move a personal prompt into a shared
	// scope. ReviewRequested marks the prompt as pending in the admin queue;
	// RequestedScope/RequestedPersonas record the target. Cleared on approve or
	// reject (see ApplyPromotionRequest / ApprovePromotion).
	ReviewRequested   bool     `json:"review_requested" example:"false"`
	RequestedScope    string   `json:"requested_scope,omitempty" example:"persona"`
	RequestedPersonas []string `json:"requested_personas,omitempty" example:"analyst"`

	CreatedAt time.Time `json:"created_at" example:"2026-01-15T14:30:00Z"`
	UpdatedAt time.Time `json:"updated_at" example:"2026-01-15T14:30:00Z"`
}

type ScoredPrompt struct {
	Prompt Prompt  `json:"prompt"`
	Score  float64 `json:"score"`
}

type SearchQuery struct {
	Embedding  []float32 // query vector; nil selects lexical-only ranking
	QueryText  string    // raw query text for the lexical arm
	OwnerEmail string    // caller identity, for personal-scope visibility
	Persona    string    // caller persona, for persona-scope visibility
	IsAdmin    bool      // admin callers rank across all approved prompts
	Scope      string    // optional explicit scope filter ("" = all visible)
	Limit      int       // max results; see EffectiveLimit
}

type Searcher interface {
	Search(ctx context.Context, q SearchQuery) ([]ScoredPrompt, error)
}

type Store interface {
	// Create persists a new prompt.
	Create(ctx context.Context, p *Prompt) error

	// Get retrieves a non-personal (global or persona) prompt by name, which is
	// globally unique. Returns nil, nil if not found. Personal prompts are
	// per-owner and must be fetched with GetPersonal.
	Get(ctx context.Context, name string) (*Prompt, error)

	// GetPersonal retrieves a personal prompt by its owner and name. Personal
	// names are unique only within an owner, so the owner is required to
	// disambiguate. Returns nil, nil if not found.
	GetPersonal(ctx context.Context, ownerEmail, name string) (*Prompt, error)

	// GetByID retrieves a prompt by ID. Returns nil, nil if not found.
	GetByID(ctx context.Context, id string) (*Prompt, error)

	// Update modifies an existing prompt.
	Update(ctx context.Context, p *Prompt) error

	// Delete removes a prompt by name.
	Delete(ctx context.Context, name string) error

	// DeleteByID removes a prompt by ID.
	DeleteByID(ctx context.Context, id string) error

	// List returns prompts matching the filter.
	List(ctx context.Context, filter ListFilter) ([]Prompt, error)

	// Count returns the number of prompts matching the filter.
	Count(ctx context.Context, filter ListFilter) (int, error)
}