289 lines
9.5 KiB
Go
289 lines
9.5 KiB
Go
package scriptorium
|
|
|
|
import (
|
|
"context"
|
|
"time"
|
|
)
|
|
|
|
// ArtifactRefType defines how an artifact is referenced.
|
|
type ArtifactRefType string
|
|
|
|
const (
|
|
ArtifactRefInline ArtifactRefType = "inline"
|
|
ArtifactRefFile ArtifactRefType = "file"
|
|
)
|
|
|
|
// OutputFormat defines the desired output format.
|
|
type OutputFormat string
|
|
|
|
const (
|
|
FormatText OutputFormat = "text"
|
|
FormatMarkdown OutputFormat = "markdown"
|
|
FormatJSON OutputFormat = "json"
|
|
)
|
|
|
|
// ValidationMode defines the output validation strategy.
|
|
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"
|
|
)
|
|
|
|
// StructuredOutputType identifies provider-level structured output modes.
|
|
type StructuredOutputType string
|
|
|
|
const (
|
|
StructuredOutputJSONSchema StructuredOutputType = "json_schema"
|
|
)
|
|
|
|
// RunRequest represents a request to prepare or run a single prompt.
|
|
type RunRequest struct {
|
|
PromptID string
|
|
PromptVersion string
|
|
ProfileID string
|
|
APIKey string `json:"-"`
|
|
Inputs map[string]ArtifactRef
|
|
Vars map[string]string
|
|
Execution *ExecutionTargetOverride
|
|
Validation *OutputContract
|
|
Metadata map[string]string
|
|
}
|
|
|
|
// PreparedRun contains prepared prompt execution state. It does not include
|
|
// resolved API key values, model output, validation results, or internal target
|
|
// presence metadata.
|
|
type PreparedRun struct {
|
|
PromptID string `json:"prompt_id"`
|
|
PromptVersion string `json:"prompt_version,omitempty"`
|
|
PromptHash string `json:"prompt_hash,omitempty"`
|
|
SelectedProfileID string `json:"selected_profile_id"`
|
|
EffectiveModelParams ExecutionTarget `json:"effective_model_params"`
|
|
OutputContract OutputContract `json:"output_contract"`
|
|
StructuredOutput *StructuredOutputSpec `json:"structured_output,omitempty"`
|
|
InputHashes map[string]string `json:"input_hashes,omitempty"`
|
|
SessionID string `json:"session_id,omitempty"`
|
|
RenderedPromptHash string `json:"rendered_prompt_hash"`
|
|
Messages []RenderedMessage `json:"messages"`
|
|
StartTime time.Time `json:"start_time,omitempty"`
|
|
EndTime time.Time `json:"end_time,omitempty"`
|
|
DurationMS int64 `json:"duration_ms,omitempty"`
|
|
}
|
|
|
|
// RunResult contains generated output, validation state, and run metadata.
|
|
type RunResult struct {
|
|
RunID string `json:"run_id"`
|
|
Artifact Artifact `json:"artifact"`
|
|
RawOutput string `json:"raw_output"`
|
|
Validation ValidationResult `json:"validation"`
|
|
PromptID string `json:"prompt_id"`
|
|
PromptVersion string `json:"prompt_version,omitempty"`
|
|
PromptHash string `json:"prompt_hash,omitempty"`
|
|
RenderedPromptHash string `json:"rendered_prompt_hash"`
|
|
SelectedProfileID string `json:"selected_profile_id"`
|
|
ModelName string `json:"model_name"`
|
|
Endpoint string `json:"endpoint"`
|
|
EffectiveModelParams ExecutionTarget `json:"effective_model_params"`
|
|
InputHashes map[string]string `json:"input_hashes,omitempty"`
|
|
Usage TokenUsage `json:"usage"`
|
|
StartTime time.Time `json:"start_time,omitempty"`
|
|
EndTime time.Time `json:"end_time,omitempty"`
|
|
Duration time.Duration `json:"duration,omitempty"`
|
|
}
|
|
|
|
// ArtifactRef represents a reference to prompt input content.
|
|
type ArtifactRef struct {
|
|
Type ArtifactRefType
|
|
URI string
|
|
Body string
|
|
}
|
|
|
|
// Artifact represents loaded artifact content.
|
|
type Artifact struct {
|
|
Name string
|
|
ContentType string
|
|
Body []byte
|
|
URI string
|
|
Size int64
|
|
Hash string
|
|
}
|
|
|
|
// ExecutionTarget represents effective model runtime settings.
|
|
type ExecutionTarget struct {
|
|
Endpoint string `json:"endpoint"`
|
|
Model string `json:"model"`
|
|
Temperature float64 `json:"temperature"`
|
|
MaxTokens int `json:"max_tokens"`
|
|
TopP float64 `json:"top_p"`
|
|
TimeoutSeconds int `json:"timeout_seconds"`
|
|
ServiceTier string `json:"service_tier"`
|
|
ReasoningEffort string `json:"reasoning_effort"`
|
|
APIKeyEnv string `json:"api_key_env"`
|
|
ExtraParams map[string]any `json:"extra_params"`
|
|
}
|
|
|
|
// ExecutionTargetOverride represents per-request runtime setting overrides.
|
|
type ExecutionTargetOverride struct {
|
|
Endpoint string
|
|
Model string
|
|
Temperature *float64
|
|
MaxTokens *int
|
|
TopP *float64
|
|
TimeoutSeconds *int
|
|
ServiceTier string
|
|
ReasoningEffort string
|
|
APIKeyEnv string
|
|
ExtraParams map[string]any
|
|
}
|
|
|
|
// Profile is an in-memory execution profile for library consumers.
|
|
type Profile struct {
|
|
ID string
|
|
Endpoint string
|
|
Model string
|
|
Temperature float64
|
|
MaxTokens int
|
|
TopP float64
|
|
TimeoutSeconds int
|
|
ServiceTier string
|
|
ReasoningEffort string
|
|
APIKeyRequired bool
|
|
ExtraParams map[string]any
|
|
}
|
|
|
|
// OpenAICompatibleProfileConfig configures an OpenAI-compatible in-memory profile.
|
|
type OpenAICompatibleProfileConfig struct {
|
|
ID string
|
|
Endpoint string
|
|
Model string
|
|
APIKeyRequired bool
|
|
Temperature float64
|
|
MaxTokens int
|
|
TopP float64
|
|
TimeoutSeconds int
|
|
ServiceTier string
|
|
ReasoningEffort string
|
|
ExtraParams map[string]any
|
|
}
|
|
|
|
// ExecutionTargetPresence tracks which numeric runtime settings were explicit
|
|
// request overrides.
|
|
type ExecutionTargetPresence struct {
|
|
Temperature bool
|
|
MaxTokens bool
|
|
TopP bool
|
|
TimeoutSeconds bool
|
|
}
|
|
|
|
// OutputContract defines output and validation requirements.
|
|
type OutputContract struct {
|
|
Format OutputFormat `json:"format"`
|
|
ValidationMode ValidationMode `json:"validation_mode"`
|
|
SchemaPath string `json:"schema_path"`
|
|
RepairAttempts int `json:"repair_attempts"`
|
|
}
|
|
|
|
// ValidationResult represents output validation state.
|
|
type ValidationResult struct {
|
|
Status ValidationStatus `json:"status"`
|
|
Mode ValidationMode `json:"mode"`
|
|
Errors []string `json:"errors,omitempty"`
|
|
SchemaPath string `json:"schema_path,omitempty"`
|
|
RepairAttempts int `json:"repair_attempts"`
|
|
IsValid bool `json:"is_valid"`
|
|
}
|
|
|
|
// TokenUsage tracks token consumption.
|
|
type TokenUsage struct {
|
|
PromptTokens int `json:"prompt_tokens"`
|
|
CompletionTokens int `json:"completion_tokens"`
|
|
TotalTokens int `json:"total_tokens"`
|
|
CachedTokens int `json:"cached_tokens"`
|
|
CacheWriteTokens int `json:"cache_write_tokens"`
|
|
}
|
|
|
|
// RenderedPrompt is the fully rendered prompt passed to an LLM client.
|
|
type RenderedPrompt struct {
|
|
SessionID string `json:"session_id,omitempty"`
|
|
Messages []RenderedMessage `json:"messages"`
|
|
}
|
|
|
|
// RenderedMessage is a rendered chat message.
|
|
type RenderedMessage struct {
|
|
Role string `json:"role"`
|
|
Content string `json:"content"`
|
|
CacheControl *CacheControl `json:"cache_control,omitempty"`
|
|
}
|
|
|
|
// CacheControl describes provider cache metadata attached to prompt content.
|
|
type CacheControl struct {
|
|
Type CacheControlType `json:"type"`
|
|
TTL string `json:"ttl,omitempty"`
|
|
}
|
|
|
|
// StructuredOutputSpec describes provider-level structured output.
|
|
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"`
|
|
}
|
|
|
|
// LLMClient executes rendered prompts for Engine.Run.
|
|
type LLMClient interface {
|
|
Generate(context.Context, GenerateRequest) (*GenerateResponse, error)
|
|
}
|
|
|
|
// GenerateRequest is passed to an injected LLM client.
|
|
type GenerateRequest struct {
|
|
Prompt RenderedPrompt `json:"prompt"`
|
|
Target ExecutionTarget `json:"target"`
|
|
TargetPresence ExecutionTargetPresence `json:"target_presence"`
|
|
StructuredOutput *StructuredOutputSpec `json:"structured_output,omitempty"`
|
|
APIKey string `json:"-"`
|
|
}
|
|
|
|
// GenerateResponse is returned by an injected LLM client.
|
|
type GenerateResponse struct {
|
|
Content string `json:"content"`
|
|
Usage TokenUsage `json:"usage"`
|
|
}
|
|
|
|
// File returns a file-backed artifact reference.
|
|
func File(path string) ArtifactRef {
|
|
return ArtifactRef{Type: ArtifactRefFile, URI: path}
|
|
}
|
|
|
|
// Inline returns an inline artifact reference.
|
|
func Inline(body string) ArtifactRef {
|
|
return ArtifactRef{Type: ArtifactRefInline, Body: body}
|
|
}
|
|
|
|
// InlineWithURI returns an inline artifact reference with URI metadata.
|
|
func InlineWithURI(uri string, body string) ArtifactRef {
|
|
return ArtifactRef{Type: ArtifactRefInline, URI: uri, Body: body}
|
|
}
|