package structuredoutput import ( "context" "encoding/json" "time" "gitea.maximumdirect.net/eric/audita/v3/internal/framework/outcomes" "gitea.maximumdirect.net/eric/audita/v3/internal/framework/responseschema" ) // DiagnosticContext identifies the logical call without examining rendered text. type DiagnosticContext struct { StageIndex *int `json:"stage_index,omitempty"` StageID *string `json:"stage_id,omitempty"` Role string `json:"role"` ModuleKey string `json:"module_key,omitempty"` ModuleInstance string `json:"module_instance,omitempty"` SectionIndex *int `json:"section_index,omitempty"` BatchIndex *int `json:"batch_index,omitempty"` ValidatorName string `json:"validator_name,omitempty"` ProposalIndex *int `json:"proposal_index,omitempty"` RepairAttempt *int `json:"repair_attempt,omitempty"` } // Request names an embedded prompt and response schema. Profile selection and // credentials are supplied by the role-bound runtime client. type Request struct { PromptID string `json:"prompt_id"` Variables map[string]string `json:"variables"` Schema responseschema.Key `json:"schema"` Context DiagnosticContext `json:"context"` CaptureExchange bool `json:"-"` } // PromptMetadata is the execution snapshot returned by the runtime when available. type PromptMetadata struct { PromptID string `json:"prompt_id,omitempty"` DefinitionHash string `json:"definition_hash,omitempty"` RenderedHash string `json:"rendered_hash,omitempty"` ProfileID string `json:"profile_id,omitempty"` BackendID string `json:"backend_id,omitempty"` Model string `json:"model,omitempty"` } // Exchange is an opaque immutable conversation owned by the runtime adapter. type Exchange struct { State any } type Response struct { Exchange *Exchange `json:"-"` Execution outcomes.ExecutionCounts `json:"execution"` Content json.RawMessage `json:"content,omitempty"` Model string `json:"model,omitempty"` Prompt PromptMetadata `json:"prompt"` Prepared *PreparedSnapshot `json:"prepared,omitempty"` FinalContent string `json:"final_content,omitempty"` } // PreparedSnapshot is the exact rendered request snapshot. Its messages may // contain transcript and glossary content and belong only in protected diagnostics. type PreparedSnapshot struct { Messages []Message `json:"messages"` Prompt PromptMetadata `json:"prompt"` } type Message struct { Role string `json:"role"` Content string `json:"content"` CacheControl *CacheControl `json:"cache_control,omitempty"` } type CacheControl struct { Type string `json:"type"` TTL string `json:"ttl,omitempty"` } // CallRecord brackets one logical operation, including preparation. type CallRecord struct { RequestedPromptID string `json:"requested_prompt_id,omitempty"` CallID uint64 `json:"call_id"` Context DiagnosticContext `json:"context"` Prompt PromptMetadata `json:"prompt"` Started time.Time `json:"started"` Finished time.Time `json:"finished,omitempty"` Failure FailureKind `json:"failure,omitempty"` } type Client interface { CompleteStructured(ctx context.Context, req Request, out any) (Response, error) } // Turn delivers a completed correction request, or its failure. The initial // callback has no response. A failure is terminal for this coordination. type Turn struct { Response *Response Err error } // Coordinator delegates bounded conversation progression to the runtime. // Returning no request stops the branch; requesting beyond the budget exhausts it. type Coordinator interface { Coordinate(context.Context, *Exchange, int, func(context.Context, Turn) (*Request, error)) (bool, error) }