Define typed producer assessment and native execution dependencies

This commit is contained in:
2026-11-21 23:12:01 +00:00
parent b899ee32a6
commit 797320b4da
23 changed files with 657 additions and 707 deletions

View File

@@ -181,20 +181,19 @@ type InputAdapter interface {
}
type ChunkRequest struct {
Source *source.SourceDocument `json:"-"`
SourceInput LLMInputMaterial `json:"source_input,omitempty"`
SessionID string `json:"session_id,omitempty"`
References ReferenceSet `json:"references,omitempty"`
LLMProfile string `json:"llm_profile,omitempty"`
StructuredOutputRepairAttempts *int `json:"structured_output_repair_attempts,omitempty"`
Correction *SemanticCorrection `json:"-"`
Metadata map[string]any `json:"metadata,omitempty"`
Operation ProducerOperation[source.ChunkPlan] `json:"-"`
Source *source.SourceDocument `json:"-"`
SourceInput LLMInputMaterial `json:"source_input,omitempty"`
SessionID string `json:"session_id,omitempty"`
References ReferenceSet `json:"references,omitempty"`
LLMProfile string `json:"llm_profile,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
type ChunkPlanResult struct {
Plan source.ChunkPlan `json:"plan"`
Diagnostics []ProducerDiagnostic `json:"diagnostics,omitempty"`
ModelCandidate *ModelCandidate `json:"-"`
Outcome ProducerOutcome `json:"outcome"`
Plan source.ChunkPlan `json:"plan"`
Diagnostics []ProducerDiagnostic `json:"diagnostics,omitempty"`
}
type Chunker interface {

View File

@@ -278,7 +278,7 @@ func (extractor fakeExtractor) ReferenceSlots() []ReferenceSlot {
return nil
}
func (extractor fakeExtractor) Extract(ctx context.Context, req TypedExtractionRequest) (TypedExtractionResult[fakeArtifact], error) {
func (extractor fakeExtractor) Extract(ctx context.Context, req TypedExtractionRequest[fakeArtifact]) (TypedExtractionResult[fakeArtifact], error) {
value := "example"
if req.AmbientContext["mode"] == "chunked" {
value = "chunked"

View File

@@ -0,0 +1,87 @@
package contracts
import (
"context"
"go.maximumdirect.net/promptkit"
)
type ExecutionMode string
const (
ModeStrict ExecutionMode = "strict"
ModePermissive ExecutionMode = "permissive"
)
type CacheMode string
const (
CacheAuto CacheMode = "auto"
CacheBypass CacheMode = "bypass"
CacheRefresh CacheMode = "refresh"
)
// ProducerControls is resolved before execution; modules do not inherit settings.
type ProducerControls struct {
Mode ExecutionMode `json:"mode"`
MaxAdditionalTurns int `json:"max_additional_turns"`
Cache CacheMode `json:"cache"`
}
// ExecutionOptions carries native request options, not a completion protocol.
// Observer closures shared by concurrent operations must synchronize their state.
type ExecutionOptions struct {
Execution *promptkit.ExecutionTargetOverride
TransientRetries *int
Observer promptkit.ExecutionObserver `json:"-"`
OnPrepared func(context.Context, promptkit.PreparedRun) `json:"-"`
}
type AssessmentDecision string
const (
AssessmentApproved AssessmentDecision = "approved"
AssessmentRejected AssessmentDecision = "rejected"
AssessmentFailed AssessmentDecision = "failed"
AssessmentUnavailable AssessmentDecision = "unavailable"
)
// ValidatorAssessment keeps model-facing guidance in Result separate from
// diagnostic reason codes, operator prose, and operational failures.
type ValidatorAssessment struct {
ValidatorName string
Decision AssessmentDecision
Result ValidationResult
Failure error
}
// CandidateAssessment contains the complete ordered chain for one candidate.
type CandidateAssessment struct {
Validators []ValidatorAssessment
}
type CandidateAssessor[T any] func(context.Context, T) (CandidateAssessment, error)
// ProducerOperation is supplied explicitly by the runner for one operation.
// Validators receive ExecutionOptions, never a producer assessment callback.
type ProducerOperation[T any] struct {
Controls ProducerControls
Assess CandidateAssessor[T] `json:"-"`
Execution ExecutionOptions
ReuseEligible bool
}
type ProducerDisposition string
const (
ProducerAccepted ProducerDisposition = "accepted"
ProducerFallback ProducerDisposition = "fallback"
)
// ProducerOutcome qualifies a returned domain value without wrapping a native
// execution result. A zero outcome is not accepted or eligible for reuse.
type ProducerOutcome struct {
Disposition ProducerDisposition `json:"disposition"`
FallbackReason string `json:"fallback_reason,omitempty"`
ReuseEligible bool `json:"reuse_eligible"`
}

View File

@@ -33,48 +33,46 @@ type NormalizeArtifact[T any] struct {
Value T
}
type TypedExtractionRequest struct {
Source *source.SourceDocument
Chunk *source.Chunk
AmbientContext map[string]any
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
StructuredOutputRepairAttempts *int
Correction *SemanticCorrection
Metadata map[string]any
type TypedExtractionRequest[T any] struct {
Operation ProducerOperation[T]
Source *source.SourceDocument
Chunk *source.Chunk
AmbientContext map[string]any
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
Metadata map[string]any
}
type TypedExtractionResult[T any] struct {
Value T
Diagnostics []ProducerDiagnostic
ModelCandidate *ModelCandidate
Outcome ProducerOutcome
Value T
Diagnostics []ProducerDiagnostic
}
type Extractor[T any] interface {
Key() string
ReferenceSlots() []ReferenceSlot
Extract(context.Context, TypedExtractionRequest) (TypedExtractionResult[T], error)
Extract(context.Context, TypedExtractionRequest[T]) (TypedExtractionResult[T], error)
}
type TypedMergeRequest[T any] struct {
Source *source.SourceDocument
LaneID string
ExtractOutputs []ExtractArtifact[T]
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
StructuredOutputRepairAttempts *int
Correction *SemanticCorrection
Metadata map[string]any
Operation ProducerOperation[T]
Source *source.SourceDocument
LaneID string
ExtractOutputs []ExtractArtifact[T]
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
Metadata map[string]any
}
type TypedMergeResult[T any] struct {
Value T
Diagnostics []ProducerDiagnostic
ModelCandidate *ModelCandidate
Outcome ProducerOutcome
Value T
Diagnostics []ProducerDiagnostic
}
type Merger[T any] interface {
@@ -83,40 +81,21 @@ type Merger[T any] interface {
}
type TypedNormalizeRequest[T any] struct {
Source *source.SourceDocument
LaneID string
MergeOutput MergeArtifact[T]
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
StructuredOutputRepairAttempts *int
Correction *SemanticCorrection
Metadata map[string]any
Operation ProducerOperation[T]
Source *source.SourceDocument
LaneID string
MergeOutput MergeArtifact[T]
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
Metadata map[string]any
}
type TypedNormalizeResult[T any] struct {
Value T
Diagnostics []ProducerDiagnostic
Retry *NormalizeRetry
ModelCandidate *ModelCandidate
}
// Normalize retry limits bound module-provided control and diagnostic text
// before the framework consumes or records it.
const (
MaxNormalizeRetryReasonCodeBytes = 128
MaxNormalizeRetryMessageBytes = 4096
MaxNormalizeRetryCorrectionGuidanceBytes = 4096
)
// NormalizeRetry asks the framework to retry normalization while retaining a
// safe candidate for acceptance if the retry budget is exhausted.
type NormalizeRetry struct {
ReasonCode string
Message string
CorrectionGuidance string
FallbackDiagnostics []ProducerDiagnostic
Outcome ProducerOutcome
Value T
Diagnostics []ProducerDiagnostic
}
type Normalizer[T any] interface {
@@ -126,21 +105,21 @@ type Normalizer[T any] interface {
}
type TypedValidationRequest[T any] struct {
Stage string
LaneID string
ModuleKey string
Source *source.SourceDocument
SourceID string
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
StructuredOutputRepairAttempts *int
Metadata map[string]any
Chunk *source.Chunk
Chunks []source.Chunk
Ref source.SourceRef
Value T
Execution ExecutionOptions
Stage string
LaneID string
ModuleKey string
Source *source.SourceDocument
SourceID string
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
Metadata map[string]any
Chunk *source.Chunk
Chunks []source.Chunk
Ref source.SourceRef
Value T
}
type TypedValidator[T any] interface {
@@ -150,16 +129,16 @@ type TypedValidator[T any] interface {
}
type ChunkValidationRequest struct {
ModuleKey string
Source *source.SourceDocument
SourceID string
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
StructuredOutputRepairAttempts *int
Metadata map[string]any
Chunks []source.Chunk
Execution ExecutionOptions
ModuleKey string
Source *source.SourceDocument
SourceID string
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
Metadata map[string]any
Chunks []source.Chunk
}
type ChunkValidator interface {
@@ -169,22 +148,22 @@ type ChunkValidator interface {
}
type SerializedValidationRequest struct {
Stage string
LaneID string
ModuleKey string
Source *source.SourceDocument
SourceID string
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
StructuredOutputRepairAttempts *int
Metadata map[string]any
Chunk *source.Chunk
Chunks []source.Chunk
Schema ArtifactSchema
MediaType string
Content []byte
Execution ExecutionOptions
Stage string
LaneID string
ModuleKey string
Source *source.SourceDocument
SourceID string
SourceInput LLMInputMaterial
SessionID string
References ReferenceSet
LLMProfile string
Metadata map[string]any
Chunk *source.Chunk
Chunks []source.Chunk
Schema ArtifactSchema
MediaType string
Content []byte
}
type SerializedValidator interface {