Files
audita/internal/framework/contracts/contracts.go

131 lines
5.6 KiB
Go

package contracts
import (
"context"
"fmt"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/chunking"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/config"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/glossary"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/modulecatalog"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/outcomes"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/promptcontext"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/proposals"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/structuredoutput"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/validators"
)
type StructuredLLMClient = structuredoutput.Client
// TranscriptModule is the minimal contract for framework-integrated modules.
// Propose may run concurrently on an instance across sections. Request data
// is borrowed for the call. Copy it before retaining it or modifying it.
type TranscriptModule interface {
Key() string
ReplacementPolicy() proposals.ReplacementPolicy
Validators() []validators.Validator
Propose(ctx context.Context, req ProposalRequest) (ProposalResult, error)
}
type StructuredCompletionRequest = structuredoutput.Request
type StructuredCompletionResponse = structuredoutput.Response
// ModuleRunSpec identifies one resolved module instance in a pipeline.
type ModuleRunSpec struct {
ModuleKey string `json:"module_key"`
InstanceName string `json:"instance_name"`
ReplacementPolicy proposals.ReplacementPolicy `json:"replacement_policy"`
Index int `json:"-"`
ID *string `json:"-"`
Settings config.Stage `json:"-"`
Glossary []glossary.Entry `json:"-"`
ProtectedTerms []glossary.Term `json:"-"`
GlossaryView *validators.GlossaryView `json:"-"`
GlossaryVariables *promptcontext.GlossaryVariables `json:"-"`
CaptureProposalExchange bool `json:"-"`
ProposalClient StructuredLLMClient `json:"-"`
ValidationClient StructuredLLMClient `json:"-"`
RepairClient StructuredLLMClient `json:"-"`
}
// PrepareGlossary constructs the read-only views used by proposal and validation.
func (s *ModuleRunSpec) PrepareGlossary() error {
if s.GlossaryVariables == nil {
variables, err := promptcontext.PrepareGlossaryVariables(s.Glossary, s.ProtectedTerms)
if err != nil {
return err
}
s.GlossaryVariables = &variables
}
if s.GlossaryView == nil {
s.GlossaryView = validators.PrepareGlossaryView(s.Glossary, s.ProtectedTerms)
}
return nil
}
// SectionMetadata captures chunk-level metadata without embedding full segment payloads.
type SectionMetadata struct {
Index int `json:"section_index"`
StartSegmentID int `json:"start_segment_id"`
EndSegmentID int `json:"end_segment_id"`
EstimatedTokens int `json:"estimated_tokens"`
SegmentCount int `json:"segment_count"`
}
// SectionMetadataFromSection converts a chunking section into framework metadata.
func SectionMetadataFromSection(section chunking.Section) SectionMetadata {
return SectionMetadata{
Index: section.Index,
StartSegmentID: section.StartSegmentID,
EndSegmentID: section.EndSegmentID,
EstimatedTokens: section.EstimatedTokens,
SegmentCount: len(section.Segments),
}
}
// ExecutionContext carries shared execution state for proposal generation and validation.
type ExecutionContext struct {
StageIndex *int `json:"stage_index,omitempty"`
StageID *string `json:"stage_id,omitempty"`
Settings config.Stage `json:"-"`
WorkingTranscript *schema.Transcript `json:"-"`
Glossary []glossary.Entry `json:"-"`
ProtectedTerms []glossary.Term `json:"-"`
GlossaryVariables *promptcontext.GlossaryVariables `json:"-"`
Section *SectionMetadata `json:"section,omitempty"`
Interactions structuredoutput.InteractionSink `json:"-"`
}
// ProposalRequest is the input to module proposal generation.
type ProposalRequest struct {
ExecutionContext
RunSpec ModuleRunSpec `json:"run_spec"`
LLMClient StructuredLLMClient `json:"-"`
}
type ProposalResult struct {
SegmentReferences []int `json:"-"`
Exchange *structuredoutput.Exchange `json:"-"`
Proposals []proposals.CorrectionProposal `json:"proposals,omitempty"`
Operations []outcomes.Operation `json:"operations,omitempty"`
}
// ResolveModuleRunSpecs derives isolated consumer views from resolved settings.
func ResolveModuleRunSpecs(cfg *config.Config) []ModuleRunSpec {
if cfg == nil {
return nil
}
specs := make([]ModuleRunSpec, len(cfg.Pipeline.Stages))
for i, item := range cfg.Pipeline.Stages {
selected := glossary.Select(cfg.GlossaryCollections, item.Glossaries)
protected := glossary.Select(cfg.GlossaryCollections, item.ProtectedTerms)
var excluded []glossary.Entry
if item.Module == modulecatalog.KeyGlossary {
excluded = selected
}
specs[i] = ModuleRunSpec{ModuleKey: item.Module, InstanceName: fmt.Sprintf("%s_%d", item.Module, i+1), Index: i, ID: item.ID, Settings: item, Glossary: selected, ProtectedTerms: glossary.Vocabulary(protected, excluded)}
}
return specs
}