2026-05-12 02:25:33 +00:00
|
|
|
// 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"
|
|
|
|
|
|
2026-11-17 04:22:20 +00:00
|
|
|
"gitea.maximumdirect.net/eric/audita/v3/internal/core/jsonnumber"
|
2026-10-11 01:40:38 +00:00
|
|
|
"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema"
|
|
|
|
|
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/contracts"
|
|
|
|
|
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/outcomes"
|
|
|
|
|
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/proposals"
|
|
|
|
|
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/responseschema"
|
|
|
|
|
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/stagename"
|
|
|
|
|
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/structuredoutput"
|
2026-05-12 02:25:33 +00:00
|
|
|
)
|
|
|
|
|
|
|
|
|
|
// StructuredCorrectionProposal is one LLM response correction payload.
|
|
|
|
|
type StructuredCorrectionProposal struct {
|
2026-11-17 04:22:20 +00:00
|
|
|
SegmentReference jsonnumber.Integer `json:"id"`
|
|
|
|
|
OriginalText string `json:"original_text"`
|
|
|
|
|
CorrectedText string `json:"corrected_text"`
|
2026-05-12 02:25:33 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// 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 {
|
2026-11-16 03:43:29 +00:00
|
|
|
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
|
2026-05-12 02:25:33 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// Result contains generated candidate proposals and optional diagnostics paths.
|
|
|
|
|
type Result struct {
|
2026-11-16 14:30:57 +00:00
|
|
|
contracts.ProposalResult
|
|
|
|
|
Artifacts structuredoutput.InteractionArtifacts `json:"artifacts,omitempty"`
|
2026-05-12 02:25:33 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// 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")
|
|
|
|
|
}
|
2026-09-24 02:03:08 +00:00
|
|
|
if strings.TrimSpace(req.PromptID) == "" {
|
|
|
|
|
return Result{}, fmt.Errorf("prompt ID must not be empty")
|
2026-05-12 02:25:33 +00:00
|
|
|
}
|
|
|
|
|
|
2026-05-12 02:57:06 +00:00
|
|
|
stage := strings.TrimSpace(req.StageName)
|
|
|
|
|
if stage == "" {
|
2026-05-23 17:48:37 +00:00
|
|
|
stage = stagename.ProposalGeneration(req.ModuleInstance, sectionIndexPtr(req.Section))
|
2026-05-12 02:57:06 +00:00
|
|
|
}
|
2026-05-12 02:25:33 +00:00
|
|
|
|
|
|
|
|
var (
|
2026-09-24 02:03:08 +00:00
|
|
|
response StructuredCorrectionSet
|
|
|
|
|
completion contracts.StructuredCompletionResponse
|
|
|
|
|
callErr error
|
2026-11-16 03:43:29 +00:00
|
|
|
artifacts structuredoutput.InteractionArtifacts
|
2026-05-12 02:25:33 +00:00
|
|
|
)
|
2026-11-16 03:43:29 +00:00
|
|
|
coordinates := structuredoutput.DiagnosticContext{StageIndex: req.StageIndex, StageID: req.StageID, Role: "proposal", ModuleKey: req.ModuleKey, ModuleInstance: req.ModuleInstance, SectionIndex: sectionIndexPtr(req.Section)}
|
2026-09-24 02:18:31 +00:00
|
|
|
completion, callErr = req.LLMClient.CompleteStructured(ctx, contracts.StructuredCompletionRequest{
|
2026-11-16 15:08:02 +00:00
|
|
|
CaptureExchange: req.CaptureExchange,
|
|
|
|
|
CaptureDiagnostics: req.Interactions != nil,
|
|
|
|
|
PromptID: req.PromptID,
|
|
|
|
|
Variables: req.Variables, Schema: responseschema.CorrectionSetKey,
|
2026-11-16 03:43:29 +00:00
|
|
|
Context: coordinates,
|
2026-09-24 02:18:31 +00:00
|
|
|
}, &response)
|
2026-09-24 17:09:35 +00:00
|
|
|
sectionIndex := 0
|
|
|
|
|
if req.Section != nil {
|
|
|
|
|
sectionIndex = req.Section.Index
|
|
|
|
|
}
|
|
|
|
|
operation := outcomes.Operation{
|
|
|
|
|
Reference: outcomes.Reference{
|
2026-11-10 17:37:41 +00:00
|
|
|
StageIndex: req.StageIndex, StageID: req.StageID,
|
2026-09-24 17:09:35 +00:00
|
|
|
ModuleKey: req.ModuleKey, ModuleInstance: req.ModuleInstance,
|
|
|
|
|
SectionIndex: sectionIndex, Kind: outcomes.OperationProposal,
|
|
|
|
|
},
|
|
|
|
|
Counts: completion.Execution,
|
|
|
|
|
}
|
2026-05-12 02:25:33 +00:00
|
|
|
|
2026-11-16 03:43:29 +00:00
|
|
|
if req.Interactions != nil {
|
2026-11-10 20:48:32 +00:00
|
|
|
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,
|
2026-11-16 14:30:57 +00:00
|
|
|
"start_index": 0, // Position of the first item within this response.
|
2026-11-10 20:48:32 +00:00
|
|
|
"segment_ids": segmentIDs(req.WorkingTranscript),
|
|
|
|
|
"prompt": completion.Prompt,
|
|
|
|
|
}
|
|
|
|
|
requestMetadata["response_schema"] = responseschema.MustLookup(responseschema.CorrectionSetKey).DiagnosticsMap()
|
2026-11-16 03:43:29 +00:00
|
|
|
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),
|
|
|
|
|
})
|
2026-05-12 02:25:33 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if callErr != nil {
|
2026-11-16 14:27:54 +00:00
|
|
|
structuredoutput.RecordFailure(&operation, callErr)
|
2026-11-16 14:30:57 +00:00
|
|
|
result := Result{ProposalResult: contracts.ProposalResult{Operations: []outcomes.Operation{operation}}, Artifacts: artifacts}
|
2026-11-16 14:27:54 +00:00
|
|
|
if operation.FailureClass == outcomes.FailureRecoverable {
|
2026-09-24 17:09:35 +00:00
|
|
|
return result, nil
|
2026-05-23 10:07:06 -05:00
|
|
|
}
|
2026-09-24 17:09:35 +00:00
|
|
|
return result, fmt.Errorf("proposal generation completion failed: %w", callErr)
|
|
|
|
|
}
|
|
|
|
|
operation.Succeeded = true
|
2026-09-25 13:26:51 +00:00
|
|
|
operation.RecoveryReasons = outcomes.ExecutionRecoveries(completion.Execution)
|
2026-05-12 02:25:33 +00:00
|
|
|
|
2026-11-11 04:29:18 +00:00
|
|
|
references := make([]int, 0, len(response.Corrections))
|
2026-05-12 02:25:33 +00:00
|
|
|
corrections := make([]proposals.CorrectionProposal, 0, len(response.Corrections))
|
2026-11-16 14:30:57 +00:00
|
|
|
for _, raw := range response.Corrections {
|
2026-11-17 04:22:20 +00:00
|
|
|
ref := int(raw.SegmentReference)
|
|
|
|
|
references = append(references, ref)
|
2026-09-25 12:38:23 +00:00
|
|
|
// Unknown references remain invalid candidates for the existing domain validators.
|
2026-11-16 14:30:57 +00:00
|
|
|
corrections = append(corrections, proposals.CorrectionProposal{
|
2026-11-17 04:22:20 +00:00
|
|
|
TargetSegmentID: proposals.SegmentIDAtReference(req.WorkingTranscript, ref),
|
2026-05-12 02:25:33 +00:00
|
|
|
OriginalText: raw.OriginalText,
|
|
|
|
|
CorrectedText: raw.CorrectedText,
|
2026-11-16 14:30:57 +00:00
|
|
|
})
|
2026-05-12 02:25:33 +00:00
|
|
|
}
|
|
|
|
|
return Result{
|
2026-11-16 14:30:57 +00:00
|
|
|
ProposalResult: contracts.ProposalResult{
|
|
|
|
|
Proposals: corrections,
|
|
|
|
|
SegmentReferences: references,
|
|
|
|
|
Exchange: completion.Exchange,
|
|
|
|
|
Operations: []outcomes.Operation{operation},
|
|
|
|
|
},
|
|
|
|
|
Artifacts: artifacts,
|
2026-05-12 02:25:33 +00:00
|
|
|
}, nil
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func errPayload(err error) any {
|
|
|
|
|
if err == nil {
|
|
|
|
|
return nil
|
|
|
|
|
}
|
|
|
|
|
return map[string]any{"error": err.Error()}
|
|
|
|
|
}
|
|
|
|
|
|
2026-05-23 17:48:37 +00:00
|
|
|
func sectionIndexPtr(section *contracts.SectionMetadata) *int {
|
|
|
|
|
if section == nil {
|
|
|
|
|
return nil
|
|
|
|
|
}
|
|
|
|
|
index := section.Index
|
|
|
|
|
return &index
|
|
|
|
|
}
|
|
|
|
|
|
2026-09-25 12:38:23 +00:00
|
|
|
// 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
|
|
|
|
|
}
|