Add public run API with injectable LLM

types.go

@@ -1,6 +1,9 @@
 package scriptorium
 
-import "time"
+import (
+	"context"
+	"time"
+)
 
 // ArtifactRefType defines how an artifact is referenced.
 type ArtifactRefType string
@@ -52,7 +55,7 @@ const (
 	StructuredOutputJSONSchema StructuredOutputType = "json_schema"
 )
 
-// RunRequest represents a request to prepare a single prompt.
+// RunRequest represents a request to prepare or run a single prompt.
 type RunRequest struct {
 	PromptID      string
 	PromptVersion string
@@ -84,6 +87,27 @@ type PreparedRun struct {
 	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
@@ -148,21 +172,27 @@ type OutputContract struct {
 
 // ValidationResult represents output validation state.
 type ValidationResult struct {
-	Status         ValidationStatus
-	Mode           ValidationMode
-	Errors         []string
-	SchemaPath     string
-	RepairAttempts int
-	IsValid        bool
+	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
-	CompletionTokens int
-	TotalTokens      int
-	CachedTokens     int
-	CacheWriteTokens int
+	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.
@@ -191,6 +221,25 @@ type StructuredOutputJSONSpec struct {
 	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"`
+}
+
+// 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}