Files
notarius/internal/framework/contracts/contracts.go

223 lines
7.6 KiB
Go

package contracts
import (
"context"
"encoding/json"
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
)
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(name string, mediaType string, content []byte, digest string, originURI string) LLMInputMaterial {
return LLMInputMaterial{
Name: name,
MediaType: mediaType,
Content: append([]byte(nil), content...),
Digest: digest,
OriginURI: originURI,
SizeBytes: int64(len(content)),
}
}
func (material LLMInputMaterial) Clone() LLMInputMaterial {
material.Content = append([]byte(nil), material.Content...)
return material
}
type LLMInputSet map[string]LLMInputMaterial
func (set LLMInputSet) Clone() LLMInputSet {
if len(set) == 0 {
return nil
}
out := make(LLMInputSet, len(set))
for key, material := range set {
out[key] = material.Clone()
}
return out
}
type ParseRequest struct {
SourceID string `json:"source_id,omitempty"`
Path string `json:"path,omitempty"`
Raw []byte `json:"-"`
LLMProfile string `json:"llm_profile,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
type InputAdapter interface {
Key() string
Parse(ctx context.Context, req ParseRequest) (*source.SourceDocument, error)
}
type ChunkRequest struct {
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 {
// Fallback is an optional module-owned algorithm for deterministic rejection.
Fallback func(context.Context) (source.ChunkPlan, error) `json:"-"`
Outcome ProducerOutcome `json:"outcome"`
Plan source.ChunkPlan `json:"plan"`
Diagnostics []ProducerDiagnostic `json:"diagnostics,omitempty"`
}
type Chunker interface {
Key() string
ReferenceSlots() []ReferenceSlot
Plan(ctx context.Context, req ChunkRequest) (ChunkPlanResult, error)
}
const (
ReferenceBindingSourceConfig = "config"
ReferenceBindingSourceCLI = "cli"
)
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(slots []ReferenceSlot) []ReferenceSlot {
if len(slots) == 0 {
return nil
}
out := make([]ReferenceSlot, len(slots))
for i, slot := range slots {
slot.AcceptedMediaTypes = append([]string(nil), slot.AcceptedMediaTypes...)
slot.AcceptedArtifactKinds = append([]ArtifactKind(nil), slot.AcceptedArtifactKinds...)
out[i] = slot
}
return out
}
type ReferenceOrigin struct {
Type string `json:"type"`
URI string `json:"uri,omitempty"`
}
// ReferenceProducer identifies the operation that produced a generated
// reference. It contains provenance only; referenced bytes remain in Content.
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"`
}
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(item ReferenceItem) ReferenceItem {
item.Content = append([]byte(nil), item.Content...)
item.ArtifactSchema = CloneArtifactSchema(item.ArtifactSchema)
return item
}
func (item ReferenceItem) MarshalJSON() ([]byte, error) {
type referenceItemJSON struct {
SlotName string `json:"slot_name"`
MediaType string `json:"media_type,omitempty"`
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"`
}
encoded := referenceItemJSON{
SlotName: item.SlotName,
MediaType: item.MediaType,
Digest: item.Digest,
Origin: item.Origin,
SizeBytes: item.SizeBytes,
BindingSource: item.BindingSource,
ArtifactKind: item.ArtifactKind,
}
if item.ArtifactSchema.ID != "" || item.ArtifactSchema.Name != "" || item.ArtifactSchema.Version != "" || len(item.ArtifactSchema.JSONSchema) > 0 {
schema := CloneArtifactSchema(item.ArtifactSchema)
encoded.ArtifactSchema = &schema
}
if item.Producer.PipelineID != "" || item.Producer.StepID != "" || item.Producer.LaneID != "" || item.Producer.ModuleKey != "" {
producer := item.Producer
encoded.Producer = &producer
}
return json.Marshal(encoded)
}
type ResolvedReferenceSlot struct {
Slot ReferenceSlot `json:"slot"`
Items []ReferenceItem `json:"items,omitempty"`
}
type ReferenceSet struct {
Slots map[string]ResolvedReferenceSlot `json:"slots,omitempty"`
}
type ExecutionClass string
const (
ExecutionClassDeterministic ExecutionClass = "deterministic"
ExecutionClassLLMBacked ExecutionClass = "llm_backed"
)
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"`
}
type OutputRequest struct {
NormalizeOutputs []SerializedOutput `json:"normalize_outputs,omitempty"`
ChunkMap *SerializedArtifact `json:"chunk_map,omitempty"`
EvidenceContext *SerializedArtifact `json:"evidence_context,omitempty"`
}
type OutputFile struct {
Name string `json:"name"`
ContentType string `json:"content_type,omitempty"`
Bytes []byte `json:"-"`
}
type OutputResult struct {
Files []OutputFile `json:"files,omitempty"`
}
type OutputEncoder interface {
Key() string
Encode(ctx context.Context, req OutputRequest) (OutputResult, error)
}