contracts

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 27, 2026 License: GPL-3.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ReferenceBindingSourceConfig = "config"
	ReferenceBindingSourceCLI    = "cli"
)
View Source 
const (
	MaxValidationReasonCodeBytes         = 128
	MaxValidationCorrectionGuidanceBytes = 4 * 1024
	MaxAssistantResponseBytes            = 1 << 20
	MaxCorrectionGuidanceBytes           = 64 * 1024
	MaxCorrectionContentBytes            = MaxAssistantResponseBytes + MaxCorrectionGuidanceBytes
)
View Source 
const (
	MaxDiagnosticReasonCodeBytes = 128
	MaxDiagnosticScopeBytes      = 512
	MaxDiagnosticMessageBytes    = 4 * 1024
	MaxDiagnosticSamples         = 3
	MaxProducerDiagnosticGroups  = 64
)
View Source 
const (
	MaxNormalizeRetryReasonCodeBytes = 128
	MaxNormalizeRetryMessageBytes    = 4096
)

Normalize retry diagnostic limits bound module-provided values before the framework persists them in debug artifacts.

Variables

View Source 
var ErrInvalidStructuredOutput = errors.New("invalid structured output")

ErrInvalidStructuredOutput identifies a provider response that cannot satisfy the caller's declared structured-output contract.

View Source 
var ErrLLMCapacityExceeded = errors.New("LLM capacity exceeded")

ErrLLMCapacityExceeded identifies backend admission exhaustion before model generation begins.

View Source 
var ErrLLMGeneration = errors.New("LLM generation failed")

ErrLLMGeneration identifies a provider generation failure.

Functions

func DigestArtifactSchema added in v0.2.0 

func DigestArtifactSchema(schema ArtifactSchema) string

DigestArtifactSchema returns the SHA-256 digest of the exact JSON Schema bytes. Schema formatting is therefore part of the registered identity.

func ValidateProducerDiagnostics added in v0.5.0 

func ValidateProducerDiagnostics(diagnostics []ProducerDiagnostic) error

ValidateProducerDiagnostics validates the complete set returned by one producer or validator result.

func ValidateValidationResult added in v0.4.0 

func ValidateValidationResult(result ValidationResult) error

Types

type ArtifactCodec added in v0.2.0 

type ArtifactCodec[T any] interface {
	Kind() ArtifactKind
	Schema() ArtifactSchema
	MediaType() string
	// EncodeCandidate serializes a stage result before semantic validation. It
	// must not apply validity checks owned by typed validators; Encode remains
	// the strict final-artifact boundary used after validation succeeds.
	EncodeCandidate(T) ([]byte, error)
	Encode(T) ([]byte, error)
	Decode([]byte) (T, error)
}

ArtifactCodec owns the stable encoding for one concrete artifact type.

type ArtifactKind added in v0.2.0 

type ArtifactKind string

ArtifactKind is the stable logical identity of a domain artifact.

type ArtifactSchema added in v0.2.0 

type ArtifactSchema struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	Version    string `json:"version"`
	JSONSchema []byte `json:"-"`
}

ArtifactSchema describes the durable representation owned by an artifact codec. JSONSchema is cloned whenever framework ownership changes.

func CloneArtifactSchema added in v0.2.0 

func CloneArtifactSchema(schema ArtifactSchema) ArtifactSchema

type CandidateArtifactCodec added in v0.3.0 

type CandidateArtifactCodec[T any] interface {
	ArtifactCodec[T]
	DecodeCandidate([]byte) (T, error)
}

CandidateArtifactCodec extends an artifact codec with strict representation decoding for values that have not yet passed semantic validation.

type ChunkPlanResult added in v0.2.0 

type ChunkPlanResult struct {
	Plan           source.ChunkPlan     `json:"plan"`
	Diagnostics    []ProducerDiagnostic `json:"diagnostics,omitempty"`
	ModelCandidate *ModelCandidate      `json:"-"`
}

type ChunkRequest 

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"`
}

type ChunkValidationRequest added in v0.2.0 

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
}

type ChunkValidator added in v0.2.0 

type ChunkValidator interface {
	Name() string
	ExecutionClass() ExecutionClass
	Validate(context.Context, ChunkValidationRequest) (ValidationResult, error)
}

type Chunker 

type Chunker interface {
	Key() string
	ReferenceSlots() []ReferenceSlot
	Plan(ctx context.Context, req ChunkRequest) (ChunkPlanResult, error)
}

type CorrectionProtocol added in v0.4.0 

type CorrectionProtocol string

CorrectionProtocol identifies how a producer can represent the model output that directly controlled a candidate. 

const (
	CorrectionProtocolSingleResponseV1 CorrectionProtocol = "single_response_v1"
)

func (CorrectionProtocol) Validate added in v0.4.0 

func (protocol CorrectionProtocol) Validate() error

type DebugSemanticCorrection added in v0.4.0 

type DebugSemanticCorrection struct {
	AssistantResponseBytes  int    `json:"assistant_response_bytes"`
	AssistantResponseDigest string `json:"assistant_response_digest"`
	UserGuidanceBytes       int    `json:"user_guidance_bytes"`
	UserGuidanceDigest      string `json:"user_guidance_digest"`
}

DebugSemanticCorrection records only safe correction metadata. It never exposes the assistant response or user guidance text.

type DebugStructuredCompletionRequest added in v0.4.0 

type DebugStructuredCompletionRequest struct {
	StageName                      string                   `json:"stage_name,omitempty"`
	PromptID                       string                   `json:"prompt_id,omitempty"`
	PromptVersion                  string                   `json:"prompt_version,omitempty"`
	ProfileID                      string                   `json:"profile_id,omitempty"`
	SessionID                      string                   `json:"session_id,omitempty"`
	InputCount                     int                      `json:"input_count"`
	VariableCount                  int                      `json:"variable_count"`
	StructuredOutputRepairAttempts *int                     `json:"structured_output_repair_attempts,omitempty"`
	Correction                     *DebugSemanticCorrection `json:"correction,omitempty"`
}

DebugStructuredCompletionRequest is the content-safe representation of a structured completion request for ordinary diagnostics and summaries. Detailed prompt material remains available only through the explicitly requested LLM debug trace.

type DiagnosticCategory added in v0.5.0 

type DiagnosticCategory string

DiagnosticCategory gives a stable, bounded classification for a producer finding. 

const (
	DiagnosticCategoryConfiguration        DiagnosticCategory = "configuration"
	DiagnosticCategoryDegradation          DiagnosticCategory = "degradation"
	DiagnosticCategoryValidationIncomplete DiagnosticCategory = "validation_incomplete"
	DiagnosticCategoryFallback             DiagnosticCategory = "fallback"
	DiagnosticCategoryDataQuality          DiagnosticCategory = "data_quality"
	DiagnosticCategoryNormalization        DiagnosticCategory = "normalization"
)

type DiagnosticCollection added in v0.5.0 

type DiagnosticCollection struct {
	Groups                       []DiagnosticGroup `json:"groups"`
	Truncated                    bool              `json:"truncated"`
	UnrepresentedOccurrenceCount int               `json:"unrepresented_occurrence_count"`
}

DiagnosticCollection is the grouped collection supplied to later durable and presentation boundaries. Global aggregation policy is applied by the framework before it reaches those boundaries.

func CloneDiagnosticCollection added in v0.5.0 

func CloneDiagnosticCollection(collection DiagnosticCollection) DiagnosticCollection

CloneDiagnosticCollection returns independent collection ownership.

func (DiagnosticCollection) Validate added in v0.5.0 

func (collection DiagnosticCollection) Validate() error

Validate checks the collection shape without imposing later global aggregation limits.

type DiagnosticDisposition added in v0.5.0 

type DiagnosticDisposition string

DiagnosticDisposition identifies the operator significance of a producer finding. Warnings are reserved for process-level degradation or incomplete configured work. 

const (
	DiagnosticDispositionWarning     DiagnosticDisposition = "warning"
	DiagnosticDispositionAdvisory    DiagnosticDisposition = "advisory"
	DiagnosticDispositionObservation DiagnosticDisposition = "observation"
)

type DiagnosticGroup added in v0.5.0 

type DiagnosticGroup struct {
	Disposition        DiagnosticDisposition `json:"disposition"`
	Category           DiagnosticCategory    `json:"category"`
	ReasonCode         string                `json:"reason_code"`
	Origin             DiagnosticOrigin      `json:"origin"`
	OccurrenceCount    int                   `json:"occurrence_count"`
	Samples            []DiagnosticSample    `json:"samples"`
	OmittedSampleCount int                   `json:"omitted_sample_count"`
}

DiagnosticGroup is a producer diagnostic after framework origin enrichment.

func (DiagnosticGroup) Validate added in v0.5.0 

func (group DiagnosticGroup) Validate() error

Validate checks a final origin-enriched group.

type DiagnosticOrigin added in v0.5.0 

type DiagnosticOrigin struct {
	Stage        DiagnosticOriginStage `json:"stage"`
	StepID       string                `json:"step_id,omitempty"`
	LaneID       string                `json:"lane_id,omitempty"`
	ModuleKey    string                `json:"module_key,omitempty"`
	ValidatorKey string                `json:"validator_key,omitempty"`
}

DiagnosticOrigin is framework-owned context used to distinguish findings from different pipeline locations during final aggregation.

func (DiagnosticOrigin) Validate added in v0.5.0 

func (origin DiagnosticOrigin) Validate() error

Validate checks framework-owned origin fields.

type DiagnosticOriginStage added in v0.5.0 

type DiagnosticOriginStage string

DiagnosticOriginStage identifies the framework operation that promoted a diagnostic. It is framework-owned rather than producer-owned. 

const (
	DiagnosticOriginStageReferences DiagnosticOriginStage = "references"
	DiagnosticOriginStageChunk      DiagnosticOriginStage = "chunk"
	DiagnosticOriginStageExtract    DiagnosticOriginStage = "extract"
	DiagnosticOriginStageMerge      DiagnosticOriginStage = "merge"
	DiagnosticOriginStageNormalize  DiagnosticOriginStage = "normalize"
)

type DiagnosticProjection added in v0.5.0 

type DiagnosticProjection struct {
	Warnings                  []DiagnosticGroup
	Diagnostics               []DiagnosticGroup
	WarningOccurrenceCount    int
	DiagnosticOccurrenceCount int
}

DiagnosticProjection is the validated warning/non-warning view used by durable and presentation boundaries. Occurrence totals are checked before they leave the framework contract.

func ProjectDiagnosticCollection added in v0.5.0 

func ProjectDiagnosticCollection(collection DiagnosticCollection) (DiagnosticProjection, error)

ProjectDiagnosticCollection validates, partitions, and totals one finalized collection. Unrepresented occurrences belong to the non-warning projection.

type DiagnosticSample added in v0.5.0 

type DiagnosticSample struct {
	Scope      string `json:"scope"`
	Message    string `json:"message"`
	ChunkID    string `json:"chunk_id,omitempty"`
	ChunkIndex *int   `json:"chunk_index,omitempty"`
}

DiagnosticSample is a bounded, safe example of a diagnostic occurrence. Chunk identity is attached by the framework when it promotes a producer diagnostic into a final group.

type ExecutionClass added in v0.2.0 

type ExecutionClass string
const (
	ExecutionClassDeterministic ExecutionClass = "deterministic"
	ExecutionClassLLMBacked     ExecutionClass = "llm_backed"
)

type ExtractArtifact added in v0.2.0 

type ExtractArtifact[T any] struct {
	LaneID       string
	ExtractorKey string
	SourceID     string
	ChunkID      string
	ChunkIndex   int
	ChunkRef     source.SourceRef
	Value        T
}

ExtractArtifact carries a typed per-chunk value with framework provenance.

type Extractor 

type Extractor[T any] interface {
	Key() string
	ReferenceSlots() []ReferenceSlot
	Extract(context.Context, TypedExtractionRequest) (TypedExtractionResult[T], error)
}

type InputAdapter 

type InputAdapter interface {
	Key() string
	Parse(ctx context.Context, req ParseRequest) (*source.SourceDocument, error)
}

type LLMDebugMaterial added in v0.2.0 

type LLMDebugMaterial struct {
	Prompt   *LLMDebugPrompt   `json:"prompt,omitempty"`
	Response *LLMDebugResponse `json:"response,omitempty"`
}

type LLMDebugMessage added in v0.2.0 

type LLMDebugMessage struct {
	Role         string         `json:"role"`
	Content      string         `json:"content"`
	CacheControl map[string]any `json:"cache_control,omitempty"`
}

type LLMDebugPrompt added in v0.2.0 

type LLMDebugPrompt struct {
	PromptID             string            `json:"prompt_id,omitempty"`
	PromptVersion        string            `json:"prompt_version,omitempty"`
	PromptHash           string            `json:"prompt_hash,omitempty"`
	SelectedProfileID    string            `json:"selected_profile_id,omitempty"`
	SelectedBackendID    string            `json:"selected_backend_id,omitempty"`
	SessionID            string            `json:"session_id,omitempty"`
	RenderedPromptHash   string            `json:"rendered_prompt_hash,omitempty"`
	Messages             []LLMDebugMessage `json:"messages,omitempty"`
	EffectiveModelParams map[string]any    `json:"effective_model_params,omitempty"`
	OutputContract       map[string]any    `json:"output_contract,omitempty"`
	StructuredOutput     map[string]any    `json:"structured_output,omitempty"`
	InputHashes          map[string]string `json:"input_hashes,omitempty"`
}

type LLMDebugProviderError added in v0.4.0 

type LLMDebugProviderError struct {
	StatusCode int    `json:"status_code,omitempty"`
	Code       string `json:"code,omitempty"`
	Type       string `json:"type,omitempty"`
	Message    string `json:"message,omitempty"`
}

type LLMDebugResponse added in v0.2.0 

type LLMDebugResponse struct {
	Content              string                 `json:"content,omitempty"`
	RunID                string                 `json:"run_id,omitempty"`
	PromptID             string                 `json:"prompt_id,omitempty"`
	PromptVersion        string                 `json:"prompt_version,omitempty"`
	PromptHash           string                 `json:"prompt_hash,omitempty"`
	RenderedPromptHash   string                 `json:"rendered_prompt_hash,omitempty"`
	SelectedProfileID    string                 `json:"selected_profile_id,omitempty"`
	ModelName            string                 `json:"model_name,omitempty"`
	Endpoint             string                 `json:"endpoint,omitempty"`
	EffectiveModelParams map[string]any         `json:"effective_model_params,omitempty"`
	InputHashes          map[string]string      `json:"input_hashes,omitempty"`
	Validation           map[string]any         `json:"validation,omitempty"`
	Usage                LLMDebugUsage          `json:"usage,omitempty"`
	ProviderError        *LLMDebugProviderError `json:"provider_error,omitempty"`
}

type LLMDebugUsage added in v0.2.0 

type LLMDebugUsage struct {
	PromptTokens     int `json:"prompt_tokens,omitempty"`
	CompletionTokens int `json:"completion_tokens,omitempty"`
	TotalTokens      int `json:"total_tokens,omitempty"`
	CachedTokens     int `json:"cached_tokens,omitempty"`
	CacheWriteTokens int `json:"cache_write_tokens,omitempty"`
}

type LLMGenerationError added in v0.4.0 

type LLMGenerationError struct {
	// contains filtered or unexported fields
}

func NewLLMGenerationError added in v0.4.0 

func NewLLMGenerationError(status int, diagnostic string) *LLMGenerationError

func (*LLMGenerationError) Error added in v0.4.0 

func (e *LLMGenerationError) Error() string

func (*LLMGenerationError) StatusCode added in v0.4.0 

func (e *LLMGenerationError) StatusCode() int

func (*LLMGenerationError) Unwrap added in v0.4.0 

func (e *LLMGenerationError) Unwrap() error

type LLMInputMaterial added in v0.2.0 

type LLMInputMaterial struct {
	Name      string `json:"name"`
	MediaType string `json:"media_type,omitempty"`
	Content   []byte `json:"-"`
	Digest    string `json:"digest,omitempty"`
	OriginURI string `json:"origin_uri,omitempty"`
	SizeBytes int64  `json:"size_bytes,omitempty"`
}

func NewLLMInputMaterial added in v0.2.0 

func NewLLMInputMaterial(name string, mediaType string, content []byte, digest string, originURI string) LLMInputMaterial

func (LLMInputMaterial) Clone added in v0.2.0 

func (material LLMInputMaterial) Clone() LLMInputMaterial

type LLMInputSet added in v0.2.0 

type LLMInputSet map[string]LLMInputMaterial

func (LLMInputSet) Clone added in v0.2.0 

func (set LLMInputSet) Clone() LLMInputSet

type LLMProfileManifestProvider added in v0.2.0 

type LLMProfileManifestProvider interface {
	LLMProfileManifests() []artifacts.LLMProfileManifest
}

type ManifestMetadataProvider 

type ManifestMetadataProvider interface {
	ManifestMetadata() map[string]any
}

type MergeArtifact added in v0.2.0 

type MergeArtifact[T any] struct {
	LaneID    string
	MergerKey string
	SourceID  string
	Value     T
}

MergeArtifact carries a typed merged value with framework provenance.

type Merger 

type Merger[T any] interface {
	Key() string
	Merge(context.Context, TypedMergeRequest[T]) (TypedMergeResult[T], error)
}

type ModelCandidate added in v0.4.0 

type ModelCandidate struct {
	Response []byte             `json:"-"`
	Protocol CorrectionProtocol `json:"-"`
}

ModelCandidate preserves the exact single model response that directly controlled a producer result. It is attempt-local and never durable data.

func CloneModelCandidate added in v0.4.0 

func CloneModelCandidate(candidate *ModelCandidate) (*ModelCandidate, error)

func NewModelCandidate added in v0.4.0 

func NewModelCandidate(response []byte, protocol CorrectionProtocol) (*ModelCandidate, error)

func (ModelCandidate) Validate added in v0.4.0 

func (candidate ModelCandidate) Validate() error

type NormalizeArtifact added in v0.2.0 

type NormalizeArtifact[T any] struct {
	LaneID        string
	NormalizerKey string
	SourceID      string
	Value         T
}

NormalizeArtifact carries a typed normalized value with framework provenance.

type NormalizeRetry added in v0.2.0 

type NormalizeRetry struct {
	ReasonCode          string
	Message             string
	FallbackDiagnostics []ProducerDiagnostic
}

NormalizeRetry asks the framework to retry normalization while retaining a safe candidate for acceptance if the retry budget is exhausted.

type Normalizer 

type Normalizer[T any] interface {
	Key() string
	ReferenceSlots() []ReferenceSlot
	Normalize(context.Context, TypedNormalizeRequest[T]) (TypedNormalizeResult[T], error)
}

type OutputEncoder 

type OutputEncoder interface {
	Key() string
	Encode(ctx context.Context, req OutputRequest) (OutputResult, error)
}

type OutputFile 

type OutputFile struct {
	Name        string `json:"name"`
	ContentType string `json:"content_type,omitempty"`
	Bytes       []byte `json:"-"`
}

type OutputRequest 

type OutputRequest struct {
	Manifest                       artifacts.RunManifest `json:"manifest"`
	NormalizeOutputs               []SerializedOutput    `json:"normalize_outputs,omitempty"`
	Rejected                       []RejectedOutput      `json:"rejected,omitempty"`
	Diagnostics                    DiagnosticCollection  `json:"diagnostics,omitempty"`
	LLMProfile                     string                `json:"llm_profile,omitempty"`
	StructuredOutputRepairAttempts *int                  `json:"structured_output_repair_attempts,omitempty"`
	Metadata                       map[string]any        `json:"metadata,omitempty"`
	ChunkMap                       *SerializedArtifact   `json:"chunk_map,omitempty"`
	EvidenceContext                *SerializedArtifact   `json:"evidence_context,omitempty"`
}

type OutputResult 

type OutputResult struct {
	Files []OutputFile `json:"files,omitempty"`
}

type ParseRequest 

type ParseRequest struct {
	SourceID                       string         `json:"source_id,omitempty"`
	Path                           string         `json:"path,omitempty"`
	Raw                            []byte         `json:"-"`
	LLMProfile                     string         `json:"llm_profile,omitempty"`
	StructuredOutputRepairAttempts *int           `json:"structured_output_repair_attempts,omitempty"`
	Metadata                       map[string]any `json:"metadata,omitempty"`
}

type ProducerDiagnostic added in v0.5.0 

type ProducerDiagnostic struct {
	Disposition        DiagnosticDisposition `json:"disposition"`
	Category           DiagnosticCategory    `json:"category"`
	ReasonCode         string                `json:"reason_code"`
	OccurrenceCount    int                   `json:"occurrence_count"`
	Samples            []DiagnosticSample    `json:"samples"`
	OmittedSampleCount int                   `json:"omitted_sample_count"`
}

ProducerDiagnostic is the locally grouped form returned by one producer or validator. It intentionally has no pipeline origin.

func CloneProducerDiagnostics added in v0.5.0 

func CloneProducerDiagnostics(diagnostics []ProducerDiagnostic) []ProducerDiagnostic

CloneProducerDiagnostics returns independent diagnostic slice ownership.

func (ProducerDiagnostic) Validate added in v0.5.0 

func (diagnostic ProducerDiagnostic) Validate() error

Validate checks a producer-local diagnostic against the public safety and classification contract.

type ReferenceItem added in v0.2.0 

type ReferenceItem struct {
	SlotName       string            `json:"slot_name"`
	MediaType      string            `json:"media_type,omitempty"`
	Content        []byte            `json:"-"`
	Digest         string            `json:"digest,omitempty"`
	Origin         ReferenceOrigin   `json:"origin"`
	SizeBytes      int64             `json:"size_bytes,omitempty"`
	BindingSource  string            `json:"binding_source,omitempty"`
	ArtifactKind   ArtifactKind      `json:"artifact_kind,omitempty"`
	ArtifactSchema ArtifactSchema    `json:"artifact_schema,omitempty"`
	Producer       ReferenceProducer `json:"producer,omitempty"`
}

func CloneReferenceItem added in v0.2.0 

func CloneReferenceItem(item ReferenceItem) ReferenceItem

func (ReferenceItem) MarshalJSON added in v0.2.0 

func (item ReferenceItem) MarshalJSON() ([]byte, error)

type ReferenceOrigin added in v0.2.0 

type ReferenceOrigin struct {
	Type string `json:"type"`
	URI  string `json:"uri,omitempty"`
}

type ReferenceProducer added in v0.2.0 

type ReferenceProducer struct {
	PipelineID string `json:"pipeline_id,omitempty"`
	StepID     string `json:"step_id,omitempty"`
	LaneID     string `json:"lane_id,omitempty"`
	ModuleKey  string `json:"module_key,omitempty"`
}

ReferenceProducer identifies the operation that produced a generated reference. It contains provenance only; referenced bytes remain in Content.

type ReferenceSet added in v0.2.0 

type ReferenceSet struct {
	Slots map[string]ResolvedReferenceSlot `json:"slots,omitempty"`
}

type ReferenceSlot added in v0.2.0 

type ReferenceSlot struct {
	Name                  string         `json:"name"`
	Description           string         `json:"description,omitempty"`
	Required              bool           `json:"required,omitempty"`
	AcceptedMediaTypes    []string       `json:"accepted_media_types,omitempty"`
	AcceptedArtifactKinds []ArtifactKind `json:"accepted_artifact_kinds,omitempty"`
	Multiple              bool           `json:"multiple,omitempty"`
	MaxBytes              int64          `json:"max_bytes,omitempty"`
}

func CloneReferenceSlots added in v0.2.0 

func CloneReferenceSlots(slots []ReferenceSlot) []ReferenceSlot

type RejectedOutput added in v0.2.0 

type RejectedOutput struct {
	Stage                  string                       `json:"stage"`
	StepID                 string                       `json:"step_id,omitempty"`
	LaneID                 string                       `json:"lane_id,omitempty"`
	ModuleKey              string                       `json:"module_key,omitempty"`
	ChunkID                string                       `json:"chunk_id,omitempty"`
	ChunkIndex             int                          `json:"chunk_index,omitempty"`
	ValidatorName          string                       `json:"validator_name,omitempty"`
	ReasonCode             string                       `json:"reason_code,omitempty"`
	Message                string                       `json:"message"`
	AttemptCount           int                          `json:"attempt_count,omitempty"`
	DiagnosticArtifactPath string                       `json:"diagnostic_artifact_path,omitempty"`
	Validation             *artifacts.ValidationSummary `json:"validation,omitempty"`
}

type ResolvedReferenceSlot added in v0.2.0 

type ResolvedReferenceSlot struct {
	Slot  ReferenceSlot   `json:"slot"`
	Items []ReferenceItem `json:"items,omitempty"`
}

type SemanticCorrection added in v0.4.0 

type SemanticCorrection struct {
	AssistantResponse []byte `json:"-"`
	UserGuidance      string `json:"-"`
}

SemanticCorrection carries the latest model response and application-owned guidance for one fresh corrected request. Its content is sensitive and is deliberately excluded from ordinary JSON serialization.

func CloneSemanticCorrection added in v0.4.0 

func CloneSemanticCorrection(correction *SemanticCorrection) (*SemanticCorrection, error)

func NewSemanticCorrection added in v0.4.0 

func NewSemanticCorrection(assistantResponse []byte, userGuidance string) (*SemanticCorrection, error)

func (*SemanticCorrection) DebugSummary added in v0.4.0 

func (correction *SemanticCorrection) DebugSummary() *DebugSemanticCorrection

DebugSummary returns content-safe correction metadata suitable for ordinary diagnostics.

func (SemanticCorrection) Validate added in v0.4.0 

func (correction SemanticCorrection) Validate() error

type SerializedArtifact added in v0.2.0 

type SerializedArtifact struct {
	Kind      ArtifactKind   `json:"kind"`
	Schema    ArtifactSchema `json:"schema"`
	MediaType string         `json:"media_type"`
	Content   []byte         `json:"-"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

SerializedArtifact is the domain-neutral representation of a typed artifact at an explicit serialization boundary.

func CloneSerializedArtifact added in v0.2.0 

func CloneSerializedArtifact(artifact SerializedArtifact) SerializedArtifact

func CloneSerializedArtifactPointer added in v0.2.0 

func CloneSerializedArtifactPointer(artifact *SerializedArtifact) *SerializedArtifact

CloneSerializedArtifactPointer returns an independently owned artifact when one is present.

type SerializedOutput added in v0.2.0 

type SerializedOutput struct {
	StepID        string             `json:"step_id,omitempty"`
	LaneID        string             `json:"lane_id"`
	NormalizerKey string             `json:"normalizer_key"`
	SourceID      string             `json:"source_id,omitempty"`
	Artifact      SerializedArtifact `json:"artifact"`
}

SerializedOutput associates a domain-neutral artifact with the pipeline operation that produced it. Provenance remains outside codec-owned bytes.

func CloneSerializedOutput added in v0.2.0 

func CloneSerializedOutput(output SerializedOutput) SerializedOutput

type SerializedValidationRequest added in v0.2.0 

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
}

type SerializedValidator added in v0.2.0 

type SerializedValidator interface {
	Name() string
	ExecutionClass() ExecutionClass
	Validate(context.Context, SerializedValidationRequest) (ValidationResult, error)
}

type StructuredCompletionRequest 

type StructuredCompletionRequest struct {
	StageName                      string              `json:"stage_name"`
	PromptID                       string              `json:"prompt_id,omitempty"`
	PromptVersion                  string              `json:"prompt_version,omitempty"`
	ProfileID                      string              `json:"profile_id,omitempty"`
	SessionID                      string              `json:"session_id,omitempty"`
	Inputs                         LLMInputSet         `json:"inputs,omitempty"`
	Vars                           map[string]any      `json:"vars,omitempty"`
	StructuredOutputRepairAttempts *int                `json:"structured_output_repair_attempts,omitempty"`
	Correction                     *SemanticCorrection `json:"-"`
}

func CloneStructuredCompletionRequest added in v0.4.0 

func CloneStructuredCompletionRequest(request StructuredCompletionRequest) (StructuredCompletionRequest, error)

CloneStructuredCompletionRequest returns a request whose mutable values are owned by the caller. It is suitable for clients that retain requests after CompleteStructured returns.

func (StructuredCompletionRequest) DebugSummary added in v0.4.0 

func (request StructuredCompletionRequest) DebugSummary() DebugStructuredCompletionRequest

DebugSummary returns a content-safe representation suitable for ordinary diagnostics. It does not validate or retain correction content.

func (StructuredCompletionRequest) GoString added in v0.4.0 

func (request StructuredCompletionRequest) GoString() string

GoString gives %#v formatting the same content-safe behavior as String.

func (StructuredCompletionRequest) String added in v0.4.0 

func (request StructuredCompletionRequest) String() string

String prevents ordinary request formatting from exposing correction content. Use the explicitly requested debug trace for complete messages.

type StructuredCompletionResponse 

type StructuredCompletionResponse struct {
	Content          json.RawMessage   `json:"content"`
	Provider         string            `json:"provider,omitempty"`
	Model            string            `json:"model,omitempty"`
	ProfileID        string            `json:"profile_id,omitempty"`
	PromptTokens     int               `json:"prompt_tokens,omitempty"`
	CompletionTokens int               `json:"completion_tokens,omitempty"`
	TotalTokens      int               `json:"total_tokens,omitempty"`
	RepairAttempts   int               `json:"repair_attempts,omitempty"`
	Debug            *LLMDebugMaterial `json:"debug,omitempty"`
}

type StructuredLLMClient 

type StructuredLLMClient interface {
	CompleteStructured(ctx context.Context, req StructuredCompletionRequest, out any) (StructuredCompletionResponse, error)
}

type TypedExtractionRequest added in v0.2.0 

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 TypedExtractionResult added in v0.2.0 

type TypedExtractionResult[T any] struct {
	Value          T
	Diagnostics    []ProducerDiagnostic
	ModelCandidate *ModelCandidate
}

type TypedMergeRequest added in v0.2.0 

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
}

type TypedMergeResult added in v0.2.0 

type TypedMergeResult[T any] struct {
	Value          T
	Diagnostics    []ProducerDiagnostic
	ModelCandidate *ModelCandidate
}

type TypedNormalizeRequest added in v0.2.0 

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
}

type TypedNormalizeResult added in v0.2.0 

type TypedNormalizeResult[T any] struct {
	Value          T
	Diagnostics    []ProducerDiagnostic
	Retry          *NormalizeRetry
	ModelCandidate *ModelCandidate
}

type TypedValidationRequest added in v0.2.0 

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
}

type TypedValidator added in v0.2.0 

type TypedValidator[T any] interface {
	Name() string
	ExecutionClass() ExecutionClass
	Validate(context.Context, TypedValidationRequest[T]) (ValidationResult, error)
}

type ValidationResult 

type ValidationResult struct {
	Approved               bool                 `json:"approved"`
	ReasonCode             string               `json:"reason_code,omitempty"`
	Message                string               `json:"message,omitempty"`
	CorrectionGuidance     string               `json:"-"`
	DiagnosticArtifactPath string               `json:"diagnostic_artifact_path,omitempty"`
	Diagnostics            []ProducerDiagnostic `json:"diagnostics,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.