Files
audita/internal/framework/proposal_generation/generate.go
Eric Rakestraw da5b8913d1
All checks were successful
ci/woodpecker/tag/release Pipeline was successful
Migrate Audita to the v4 module path
2026-11-17 19:57:22 +00:00

184 lines
7.1 KiB
Go

// Package proposal_generation provides shared, deterministic LLM-backed
// proposal-generation helpers. It only produces candidate proposals; validation
// and application remain runner responsibilities.
package proposal_generation
import (
"context"
"fmt"
"strings"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/jsonnumber"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/contracts"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/outcomes"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/proposals"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/responseschema"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/stagename"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/structuredoutput"
)
// StructuredCorrectionProposal is one LLM response correction payload.
type StructuredCorrectionProposal struct {
SegmentReference jsonnumber.Integer `json:"id"`
OriginalText string `json:"original_text"`
CorrectedText string `json:"corrected_text"`
}
// StructuredCorrectionSet is the reusable structured LLM response model for
// candidate correction proposals.
type StructuredCorrectionSet struct {
Corrections []StructuredCorrectionProposal `json:"corrections"`
}
// Request captures reusable proposal-generation inputs for future modules.
type Request struct {
StageIndex *int `json:"stage_index,omitempty"`
StageID *string `json:"stage_id,omitempty"`
ModuleKey string `json:"module_key"`
ModuleInstance string `json:"module_instance"`
ReplacementPolicy proposals.ReplacementPolicy `json:"replacement_policy"`
WorkingTranscript *schema.Transcript `json:"-"`
Section *contracts.SectionMetadata `json:"section,omitempty"`
PromptID string `json:"prompt_id"`
Variables map[string]string `json:"variables"`
StageName string `json:"stage_name,omitempty"`
CaptureExchange bool
LLMClient contracts.StructuredLLMClient
Interactions structuredoutput.InteractionSink
}
// Result contains generated candidate proposals and optional diagnostics paths.
type Result struct {
contracts.ProposalResult
Artifacts structuredoutput.InteractionArtifacts `json:"artifacts,omitempty"`
}
// GenerateCandidates executes one structured LLM call and deterministically maps
// its correction-set response into framework proposal types.
func GenerateCandidates(ctx context.Context, req Request) (Result, error) {
if strings.TrimSpace(req.ModuleKey) == "" {
return Result{}, fmt.Errorf("module key must not be empty")
}
if strings.TrimSpace(req.ModuleInstance) == "" {
return Result{}, fmt.Errorf("module instance must not be empty")
}
if req.LLMClient == nil {
return Result{}, fmt.Errorf("structured LLM client is required")
}
if strings.TrimSpace(req.PromptID) == "" {
return Result{}, fmt.Errorf("prompt ID must not be empty")
}
stage := strings.TrimSpace(req.StageName)
if stage == "" {
stage = stagename.ProposalGeneration(req.ModuleInstance, sectionIndexPtr(req.Section))
}
var (
response StructuredCorrectionSet
completion contracts.StructuredCompletionResponse
callErr error
artifacts structuredoutput.InteractionArtifacts
)
coordinates := structuredoutput.DiagnosticContext{StageIndex: req.StageIndex, StageID: req.StageID, Role: "proposal", ModuleKey: req.ModuleKey, ModuleInstance: req.ModuleInstance, SectionIndex: sectionIndexPtr(req.Section)}
completion, callErr = req.LLMClient.CompleteStructured(ctx, contracts.StructuredCompletionRequest{
CaptureExchange: req.CaptureExchange,
CaptureDiagnostics: req.Interactions != nil,
PromptID: req.PromptID,
Variables: req.Variables, Schema: responseschema.CorrectionSetKey,
Context: coordinates,
}, &response)
sectionIndex := 0
if req.Section != nil {
sectionIndex = req.Section.Index
}
operation := outcomes.Operation{
Reference: outcomes.Reference{
StageIndex: req.StageIndex, StageID: req.StageID,
ModuleKey: req.ModuleKey, ModuleInstance: req.ModuleInstance,
SectionIndex: sectionIndex, Kind: outcomes.OperationProposal,
},
Counts: completion.Execution,
}
if req.Interactions != nil {
requestMetadata := map[string]any{
"stage_index": req.StageIndex, "stage_id": req.StageID,
"module_key": req.ModuleKey,
"module_instance": req.ModuleInstance,
"replacement_policy": req.ReplacementPolicy,
"section": req.Section,
"start_index": 0, // Position of the first item within this response.
"segment_ids": segmentIDs(req.WorkingTranscript),
"prompt": completion.Prompt,
}
requestMetadata["response_schema"] = responseschema.MustLookup(responseschema.CorrectionSetKey).DiagnosticsMap()
artifacts, _ = req.Interactions.WriteInteraction(structuredoutput.Interaction{
Name: stage, Context: coordinates, RequestMetadata: requestMetadata, RequestPayload: completion.Prepared,
ResponsePayload: map[string]any{"decoded": response, "final_content": completion.FinalContent, "model": completion.Model},
ErrorPayload: errPayload(callErr),
})
}
if callErr != nil {
structuredoutput.RecordFailure(&operation, callErr)
result := Result{ProposalResult: contracts.ProposalResult{Operations: []outcomes.Operation{operation}}, Artifacts: artifacts}
if operation.FailureClass == outcomes.FailureRecoverable {
return result, nil
}
return result, fmt.Errorf("proposal generation completion failed: %w", callErr)
}
operation.Succeeded = true
operation.RecoveryReasons = outcomes.ExecutionRecoveries(completion.Execution)
references := make([]int, 0, len(response.Corrections))
corrections := make([]proposals.CorrectionProposal, 0, len(response.Corrections))
for _, raw := range response.Corrections {
ref := int(raw.SegmentReference)
references = append(references, ref)
// Unknown references remain invalid candidates for the existing domain validators.
corrections = append(corrections, proposals.CorrectionProposal{
TargetSegmentID: proposals.SegmentIDAtReference(req.WorkingTranscript, ref),
OriginalText: raw.OriginalText,
CorrectedText: raw.CorrectedText,
})
}
return Result{
ProposalResult: contracts.ProposalResult{
Proposals: corrections,
SegmentReferences: references,
Exchange: completion.Exchange,
Operations: []outcomes.Operation{operation},
},
Artifacts: artifacts,
}, nil
}
func errPayload(err error) any {
if err == nil {
return nil
}
return map[string]any{"error": err.Error()}
}
func sectionIndexPtr(section *contracts.SectionMetadata) *int {
if section == nil {
return nil
}
index := section.Index
return &index
}
// segmentIDs records the request-local reference mapping in debug metadata.
func segmentIDs(transcript *schema.Transcript) []int {
if transcript == nil {
return nil
}
ids := make([]int, len(transcript.Segments))
for i, segment := range transcript.Segments {
ids[i] = segment.ID
}
return ids
}