promptkit/internal/domain/domain.go

package domain

import (
	"time"
)

// ArtifactRefType defines how an artifact is referenced.
type ArtifactRefType string

const (
	ArtifactRefInline ArtifactRefType = "inline"
	ArtifactRefFile   ArtifactRefType = "file"
)

// OutputFormat defines the desired format of the generated artifact.
type OutputFormat string

const (
	FormatText     OutputFormat = "text"
	FormatMarkdown OutputFormat = "markdown"
	FormatJSON     OutputFormat = "json"
)

// ValidationMode defines how the output should be validated.
type ValidationMode string

const (
	ValidationNone       ValidationMode = "none"
	ValidationBasic      ValidationMode = "basic"
	ValidationJSON       ValidationMode = "json"
	ValidationJSONSchema ValidationMode = "json_schema"
)

// ValidationStatus defines the result of a validation check.
type ValidationStatus string

const (
	ValidationPassed  ValidationStatus = "passed"
	ValidationFailed  ValidationStatus = "failed"
	ValidationSkipped ValidationStatus = "skipped"
)

// CacheControlType defines provider cache behavior for prompt content.
type CacheControlType string

const (
	CacheControlEphemeral CacheControlType = "ephemeral"
)

const (
	// SessionIDMaxLength is OpenRouter's documented maximum session_id length.
	SessionIDMaxLength = 256
)

// CacheControl describes provider cache metadata attached to prompt content.
type CacheControl struct {
	Type CacheControlType `yaml:"type" json:"type"`
	TTL  string           `yaml:"ttl,omitempty" json:"ttl,omitempty"`
}

// RunRequest represents a request to generate a single artifact.
type RunRequest struct {
	CaptureExchange  bool
	ContinueFrom     *Exchange
	PromptID         string
	ProfileID        string
	SessionID        string
	APIKey           string `json:"-" yaml:"-"`
	Inputs           map[string]ArtifactRef
	Vars             map[string]string
	Execution        *ExecutionTargetOverride
	Validation       *OutputContract
	AppendedMessages []RenderedMessage
	TransientRetries *int
	Observer         ExecutionObserver `json:"-"`
}

// RunResult represents the complete result of a prompt execution run.
type RunResult struct {
	Exchange             *Exchange
	ParentRunID          string
	RunID                string
	Artifact             Artifact
	RawOutput            string
	Validation           ValidationResult
	PromptID             string
	PromptHash           string
	SessionID            string
	RenderedPromptHash   string
	SelectedProfileID    string
	SelectedBackendID    string
	ModelName            string
	Endpoint             string
	EffectiveModelParams ExecutionTarget
	InputHashes          map[string]string
	Usage                TokenUsage
	StartTime            time.Time
	EndTime              time.Time
	Duration             time.Duration
}

// PreparedRun contains pre-LLM execution state from the prepare/render phase.
// It must never include resolved API key values, model output, or validation data.
type PreparedRun struct {
	ParentRunID          string
	PromptID             string
	PromptHash           string
	SelectedProfileID    string
	SelectedBackendID    string
	EffectiveModelParams ExecutionTarget
	TargetPresence       ExecutionTargetPresence
	OutputContract       OutputContract
	StructuredOutput     *StructuredOutputSpec
	InputHashes          map[string]string
	SessionID            string
	RenderedPromptHash   string
	Messages             []RenderedMessage
	StartTime            time.Time
	EndTime              time.Time
	DurationMS           int64
}

// ArtifactRef represents a reference to an input artifact.
type ArtifactRef struct {
	Type ArtifactRefType
	URI  string
	Body string // Used for inline
}

// Artifact represents the actual loaded content of a reference.
type Artifact struct {
	Name        string
	ContentType string
	Body        []byte
	URI         string
	Size        int64
	Hash        string
}

// PromptIdentity identifies one configured prompt.
type PromptIdentity struct {
	ID string
}

// PromptDefinition represents a configured prompt execution definition.
type PromptDefinition struct {
	ID             string                  `yaml:"id"`
	DefaultProfile string                  `yaml:"default_profile"`
	Description    string                  `yaml:"description"`
	SessionID      string                  `yaml:"session_id" json:"session_id,omitempty"`
	Inputs         []PromptInput           `yaml:"inputs"`
	Templates      []PromptMessageTemplate `yaml:"templates"`
	Validation     OutputContract          `yaml:"validation"`
}

// PromptInspection is lightweight metadata for prompt requirement selection.
type PromptInspection struct {
	PromptID         string
	PromptHash       string
	DefaultProfileID string
	Inputs           []PromptInput
	OutputContract   OutputContract
}

// PromptInput describes one named input expected by a prompt definition.
type PromptInput struct {
	Name        string `yaml:"name"`
	Required    bool   `yaml:"required"`
	ContentType string `yaml:"content_type"`
	Description string `yaml:"description"`
}

// PromptMessageTemplate defines a template for a chat message.
type PromptMessageTemplate struct {
	Role         string        `yaml:"role"`
	Content      string        `yaml:"content"`
	CacheControl *CacheControl `yaml:"cache_control,omitempty" json:"cache_control,omitempty"`
}

// Backend describes reusable OpenAI-compatible connection defaults and optional
// diagnostic metadata.
type Backend struct {
	ID               string
	Endpoint         string
	APIKeyEnv        string
	ExtraParams      map[string]any
	SmokeTests       *BackendSmokeTestConfig
	ConcurrencyLimit int
	QueueCapacity    int
}

// BackendCapacityPolicy describes normalized run and generation capacity for
// one limited backend.
type BackendCapacityPolicy struct {
	ConcurrencyLimit int
	QueueCapacity    int
}

// ExecutionProfile holds a captured configuration target for execution.
type ExecutionProfile struct {
	ID             string
	ResolvedTarget *ExecutionTarget
	TargetPresence ExecutionTargetPresence
}

// ExecutionTargetOverride represents per-request runtime setting overrides.
type ExecutionTargetOverride struct {
	Endpoint        string         `json:"endpoint,omitempty"`
	Model           string         `json:"model,omitempty"`
	Temperature     *float64       `json:"temperature,omitempty"`
	MaxTokens       *int           `json:"max_tokens,omitempty"`
	TopP            *float64       `json:"top_p,omitempty"`
	TimeoutSeconds  *int           `json:"timeout_seconds,omitempty"`
	ServiceTier     string         `json:"service_tier,omitempty"`
	ReasoningEffort *string        `json:"reasoning_effort,omitempty"`
	APIKeyEnv       string         `json:"api_key_env,omitempty"`
	ExtraParams     map[string]any `json:"extra_params,omitempty"`
}

// ExecutionTargetPresence tracks effective numeric values that must be sent
// even when they are zero. Values may come from configuration or a request
// override; explicit configuration null suppresses the corresponding bit.
type ExecutionTargetPresence struct {
	Temperature    bool
	MaxTokens      bool
	TopP           bool
	TimeoutSeconds bool
}

// ExecutionTarget represents effective model runtime settings for a run.
type ExecutionTarget struct {
	BackendID       string         `yaml:"backend" json:"backend_id,omitempty"`
	Endpoint        string         `yaml:"endpoint" json:"endpoint"`
	Model           string         `yaml:"model" json:"model"`
	Temperature     float64        `yaml:"temperature" json:"temperature"`
	MaxTokens       int            `yaml:"max_tokens" json:"max_tokens"`
	TopP            float64        `yaml:"top_p" json:"top_p"`
	TimeoutSeconds  int            `yaml:"timeout_seconds" json:"timeout_seconds"`
	ServiceTier     string         `yaml:"service_tier" json:"service_tier"`
	ReasoningEffort string         `yaml:"reasoning_effort" json:"reasoning_effort"`
	APIKeyEnv       string         `yaml:"api_key_env" json:"api_key_env"`
	APIKey          string         `yaml:"-" json:"-"`
	APIKeyRequired  bool           `yaml:"-" json:"-"`
	ExtraParams     map[string]any `yaml:"extra_params" json:"extra_params"`
}

// OutputContract defines the requirements for the output artifact.
type OutputContract struct {
	Format         OutputFormat   `yaml:"format"`
	ValidationMode ValidationMode `yaml:"validation_mode"`
	SchemaPath     string         `yaml:"schema_path"`
	RepairAttempts int            `yaml:"repair_attempts"`
}

// RenderedPrompt represents the prompt after template application.
type RenderedPrompt struct {
	SessionID string            `json:"session_id,omitempty"`
	Messages  []RenderedMessage `json:"messages"`
}

// RenderedMessage is a single message in a rendered prompt.
type RenderedMessage struct {
	Role         string        `json:"role"`
	Content      string        `json:"content"`
	CacheControl *CacheControl `json:"cache_control,omitempty"`
}

// GenerateRequest is the internal request passed to the LLM client.
type GenerateRequest struct {
	Prompt           RenderedPrompt
	Target           ExecutionTarget
	TargetPresence   ExecutionTargetPresence
	StructuredOutput *StructuredOutputSpec
	TransientRetries uint64
	Generation       uint64
}

// StructuredOutputType indicates which provider-level output mode is requested.
type StructuredOutputType string

const (
	StructuredOutputJSONSchema StructuredOutputType = "json_schema"
)

// StructuredOutputSpec describes provider-level structured output requirements.
type StructuredOutputSpec struct {
	Type       StructuredOutputType      `json:"type"`
	JSONSchema *StructuredOutputJSONSpec `json:"json_schema,omitempty"`
}

// StructuredOutputJSONSpec contains json_schema output constraints.
type StructuredOutputJSONSpec struct {
	Name   string `json:"name"`
	Strict bool   `json:"strict"`
	Schema any    `json:"schema"`
}

// GenerateResponse is the response received from the LLM client.
type GenerateResponse struct {
	Content       string
	Usage         TokenUsage
	UsagePresence *TokenUsagePresence
}

// TokenUsagePresence records which token fields a provider reported.
type TokenUsagePresence struct {
	PromptTokens     bool
	CompletionTokens bool
	TotalTokens      bool
	CachedTokens     bool
	CacheWriteTokens bool
}

// TokenUsage tracks token consumption.
type TokenUsage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
	CachedTokens     int
	CacheWriteTokens int
}

// ValidationResult represents the outcome of an output validation.
type ValidationResult struct {
	Status         ValidationStatus
	Mode           ValidationMode
	Errors         []string
	SchemaPath     string
	RepairAttempts int
	IsValid        bool
}