Move embedded prompts to PromptKit definitions

internal/framework/contracts/contracts.go

@@ -2,22 +2,18 @@ package contracts
 
 import (
 	"context"
-	"encoding/json"
 	"fmt"
 
 	"gitea.maximumdirect.net/eric/audita/internal/core/chunking"
 	"gitea.maximumdirect.net/eric/audita/internal/core/config"
 	"gitea.maximumdirect.net/eric/audita/internal/core/schema"
 	"gitea.maximumdirect.net/eric/audita/internal/framework/proposals"
-	"gitea.maximumdirect.net/eric/audita/internal/framework/responseschema"
+	"gitea.maximumdirect.net/eric/audita/internal/framework/structuredoutput"
 	"gitea.maximumdirect.net/eric/audita/internal/framework/validators"
 	stagewarnings "gitea.maximumdirect.net/eric/audita/internal/framework/warnings"
 )
 
-// StructuredLLMClient provides provider-agnostic structured completion.
-type StructuredLLMClient interface {
-	CompleteStructured(ctx context.Context, req StructuredCompletionRequest, out any) (StructuredCompletionResponse, error)
-}
+type StructuredLLMClient = structuredoutput.Client
 
 // LLMScheduler provides bounded execution for LLM call sites.
 type LLMScheduler interface {
@@ -38,29 +34,8 @@ type Validator interface {
 	Validate(ctx context.Context, req ValidationRequest) (validators.Result, error)
 }
 
-// StructuredCompletionRequest is a transport-neutral structured completion request.
-type StructuredCompletionRequest struct {
-	StageName      string                 `json:"stage_name"`
-	Messages       []LLMMessage           `json:"messages"`
-	Model          string                 `json:"model,omitempty"`
-	ResponseSchema *responseschema.Schema `json:"response_schema,omitempty"`
-}
-
-// StructuredCompletionResponse is a transport-neutral structured completion response payload.
-type StructuredCompletionResponse struct {
-	Content          json.RawMessage `json:"content"`
-	Provider         string          `json:"provider,omitempty"`
-	Model            string          `json:"model,omitempty"`
-	PromptTokens     int             `json:"prompt_tokens,omitempty"`
-	CompletionTokens int             `json:"completion_tokens,omitempty"`
-	TotalTokens      int             `json:"total_tokens,omitempty"`
-}
-
-// LLMMessage is a minimal chat message shape for LLM prompts.
-type LLMMessage struct {
-	Role    string `json:"role"`
-	Content string `json:"content"`
-}
+type StructuredCompletionRequest = structuredoutput.Request
+type StructuredCompletionResponse = structuredoutput.Response
 
 // ModuleRunSpec identifies one resolved module instance in a pipeline.
 type ModuleRunSpec struct {

internal/framework/responseschema/registry.go

@@ -6,6 +6,7 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
+	"io/fs"
 	"sort"
 	"strings"
 )
@@ -16,6 +17,7 @@ type Key string
 const (
 	CorrectionSetKey          Key = "correction_set"
 	ValidatorDecisionSetKey   Key = "validator_decision_set"
+	AssetRoot                     = "assets"
 	correctionSetSchemaID         = "audita.correction_set"
 	validatorDecisionSchemaID     = "audita.validator_decision_set"
 	schemaVersionV1               = "v1"
@@ -24,6 +26,20 @@ const (
 //go:embed assets/*.json
 var schemaAssets embed.FS
 
+// Filesystem exposes the canonical embedded schemas to PromptKit.
+func Filesystem() fs.FS { return schemaAssets }
+
+func AssetPath(key Key) (string, bool) {
+	switch key {
+	case CorrectionSetKey:
+		return "correction_set.v1.json", true
+	case ValidatorDecisionSetKey:
+		return "validator_decision_set.v1.json", true
+	default:
+		return "", false
+	}
+}
+
 // Schema describes one registered structured response schema.
 type Schema struct {
 	ID         string          `json:"id"`

internal/framework/responseschema/registry_test.go

@@ -5,9 +5,31 @@ import (
 	"crypto/sha256"
 	"encoding/hex"
 	"encoding/json"
+	"io"
 	"testing"
 )
 
+func TestPromptKitSchemaPathsUseCanonicalAssets(t *testing.T) {
+	for _, key := range []Key{CorrectionSetKey, ValidatorDecisionSetKey} {
+		path, ok := AssetPath(key)
+		if !ok {
+			t.Fatalf("missing path for %q", key)
+		}
+		file, err := Filesystem().Open(AssetRoot + "/" + path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		data, err := io.ReadAll(file)
+		file.Close()
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !bytes.Equal(data, MustLookup(key).JSONSchema) {
+			t.Fatalf("PromptKit schema differs for %q", key)
+		}
+	}
+}
+
 const (
 	expectedCorrectionSetSHA256        = "b86a2dde38d7f440d26470fa8830167512bb0aa1b35e5fee5547057be583c388"
 	expectedValidatorDecisionSetSHA256 = "2fe90d450e2595b57885aba91c8cc5cedf783dd36758ab430309e3eace401f54"

internal/framework/structuredoutput/call.go

@@ -0,0 +1,53 @@
+package structuredoutput
+
+import (
+	"context"
+	"encoding/json"
+
+	"gitea.maximumdirect.net/eric/audita/internal/framework/responseschema"
+)
+
+// DiagnosticContext identifies the logical call without examining rendered text.
+type DiagnosticContext struct {
+	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"`
+}
+
+// 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"`
+	PromptVersion string             `json:"prompt_version"`
+	Variables     map[string]string  `json:"variables"`
+	Schema        responseschema.Key `json:"schema"`
+	Context       DiagnosticContext  `json:"context"`
+}
+
+// PromptMetadata is the execution snapshot returned by the runtime when available.
+type PromptMetadata struct {
+	PromptID       string `json:"prompt_id,omitempty"`
+	PromptVersion  string `json:"prompt_version,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"`
+}
+
+type Response struct {
+	Content          json.RawMessage `json:"content,omitempty"`
+	Provider         string          `json:"provider,omitempty"`
+	Model            string          `json:"model,omitempty"`
+	PromptTokens     int             `json:"prompt_tokens,omitempty"`
+	CompletionTokens int             `json:"completion_tokens,omitempty"`
+	TotalTokens      int             `json:"total_tokens,omitempty"`
+	Prompt           PromptMetadata  `json:"prompt"`
+}
+
+type Client interface {
+	CompleteStructured(ctx context.Context, req Request, out any) (Response, error)
+}

internal/framework/validators/llm_models.go

@@ -1,10 +1,8 @@
 package validators
 
 import (
-	"context"
-
 	"gitea.maximumdirect.net/eric/audita/internal/core/schema"
-	"gitea.maximumdirect.net/eric/audita/internal/framework/responseschema"
+	"gitea.maximumdirect.net/eric/audita/internal/framework/structuredoutput"
 )
 
 type LLMValidatorType string
@@ -17,27 +15,9 @@ const (
 	LLMValidatorTypeSpokenWordReview       LLMValidatorType = "spoken_word_review"
 )
 
-type LLMMessage struct {
-	Role    string `json:"role"`
-	Content string `json:"content"`
-}
-
-type StructuredCompletionRequest struct {
-	StageName      string                 `json:"stage_name"`
-	Messages       []LLMMessage           `json:"messages"`
-	Model          string                 `json:"model,omitempty"`
-	ResponseSchema *responseschema.Schema `json:"response_schema,omitempty"`
-}
-
-type StructuredCompletionResponse struct {
-	PromptTokens     int `json:"prompt_tokens,omitempty"`
-	CompletionTokens int `json:"completion_tokens,omitempty"`
-	TotalTokens      int `json:"total_tokens,omitempty"`
-}
-
-type StructuredLLMClient interface {
-	CompleteStructured(ctx context.Context, req StructuredCompletionRequest, out any) (StructuredCompletionResponse, error)
-}
+type StructuredCompletionRequest = structuredoutput.Request
+type StructuredCompletionResponse = structuredoutput.Response
+type StructuredLLMClient = structuredoutput.Client
 
 // LLMValidationItem is one candidate correction payload passed to LLM validators.
 type LLMValidationItem struct {