// 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/v3/internal/core/jsonnumber" "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" ) // 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 }