notarius/internal/framework/contracts/contracts.go

package contracts

import (
	"context"
	"encoding/json"

	"gitea.maximumdirect.net/eric/notarius/internal/core/artifacts"
	"gitea.maximumdirect.net/eric/notarius/internal/core/source"
)

type LLMMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type StructuredCompletionRequest struct {
	StageName          string          `json:"stage_name"`
	Messages           []LLMMessage    `json:"messages"`
	Model              string          `json:"model,omitempty"`
	ResponseSchemaName string          `json:"response_schema_name,omitempty"`
	ResponseSchema     json.RawMessage `json:"response_schema,omitempty"`
}

type StructuredCompletionResponse struct {
	Content          json.RawMessage `json:"content"`
	Provider         string          `json:"provider,omitempty"`
	Model            string          `json:"model,omitempty"`
	PromptTokens     int             `json:"prompt_tokens,omitempty"`
	CompletionTokens int             `json:"completion_tokens,omitempty"`
	TotalTokens      int             `json:"total_tokens,omitempty"`
}

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

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

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

type SourceChunk struct {
	ID       string              `json:"id"`
	SourceID string              `json:"source_id"`
	Index    int                 `json:"index"`
	Units    []source.SourceUnit `json:"units"`
	Metadata map[string]any      `json:"metadata,omitempty"`
}

type ChunkRequest struct {
	Source     *source.SourceDocument `json:"-"`
	LLMProfile string                 `json:"llm_profile,omitempty"`
	Options    map[string]any         `json:"options,omitempty"`
	Metadata   map[string]any         `json:"metadata,omitempty"`
}

type ChunkResult struct {
	Chunks   []SourceChunk `json:"chunks"`
	Warnings []Warning     `json:"warnings,omitempty"`
}

type Chunker interface {
	Key() string
	Chunk(ctx context.Context, req ChunkRequest) (ChunkResult, error)
}

type ExtractionRequest struct {
	Source         *source.SourceDocument `json:"-"`
	Chunk          *SourceChunk           `json:"chunk,omitempty"`
	AmbientContext map[string]any         `json:"ambient_context,omitempty"`
	LLMClient      StructuredLLMClient    `json:"-"`
	LLMProfile     string                 `json:"llm_profile,omitempty"`
	Options        map[string]any         `json:"options,omitempty"`
	Metadata       map[string]any         `json:"metadata,omitempty"`
}

type ExtractionResult struct {
	Candidates []artifacts.ArtifactCandidate `json:"candidates,omitempty"`
	Warnings   []Warning                     `json:"warnings,omitempty"`
}

type Extractor interface {
	Key() string
	ArtifactType() string
	SchemaVersion() string
	Validators() []Validator
	Extract(ctx context.Context, req ExtractionRequest) (ExtractionResult, error)
}

type ChunkArtifacts struct {
	Chunk      SourceChunk                   `json:"chunk"`
	Candidates []artifacts.ArtifactCandidate `json:"candidates"`
}

type MergeRequest struct {
	Source         *source.SourceDocument `json:"-"`
	LaneID         string                 `json:"lane_id"`
	ChunkArtifacts []ChunkArtifacts       `json:"chunk_artifacts"`
	LLMProfile     string                 `json:"llm_profile,omitempty"`
	Options        map[string]any         `json:"options,omitempty"`
	Metadata       map[string]any         `json:"metadata,omitempty"`
}

type MergeResult struct {
	Candidates []artifacts.ArtifactCandidate `json:"candidates"`
	Warnings   []Warning                     `json:"warnings,omitempty"`
}

type Merger interface {
	Key() string
	Merge(ctx context.Context, req MergeRequest) (MergeResult, error)
}

type NormalizeRequest struct {
	Source     *source.SourceDocument        `json:"-"`
	LaneID     string                        `json:"lane_id"`
	Candidates []artifacts.ArtifactCandidate `json:"candidates"`
	LLMProfile string                        `json:"llm_profile,omitempty"`
	Options    map[string]any                `json:"options,omitempty"`
	Metadata   map[string]any                `json:"metadata,omitempty"`
}

type NormalizeResult struct {
	Candidates []artifacts.ArtifactCandidate `json:"candidates"`
	Warnings   []Warning                     `json:"warnings,omitempty"`
}

type Normalizer interface {
	Key() string
	Normalize(ctx context.Context, req NormalizeRequest) (NormalizeResult, error)
}

type ValidationRequest struct {
	Source     *source.SourceDocument        `json:"-"`
	Candidates []artifacts.ArtifactCandidate `json:"candidates"`
	LLMProfile string                        `json:"llm_profile,omitempty"`
	Options    map[string]any                `json:"options,omitempty"`
	Metadata   map[string]any                `json:"metadata,omitempty"`
}

type ValidationDecision struct {
	CandidateIndex         int    `json:"candidate_index"`
	Approved               bool   `json:"approved"`
	ReasonCode             string `json:"reason_code"`
	Message                string `json:"message"`
	DiagnosticArtifactPath string `json:"diagnostic_artifact_path,omitempty"`
}

type ValidationResult struct {
	ValidatorName string               `json:"validator_name"`
	Decisions     []ValidationDecision `json:"decisions"`
	Warnings      []Warning            `json:"warnings,omitempty"`
}

type Validator interface {
	Name() string
	Validate(ctx context.Context, req ValidationRequest) (ValidationResult, error)
}

type Warning struct {
	Scope      string `json:"scope,omitempty"`
	ReasonCode string `json:"reason_code"`
	Message    string `json:"message"`
}

type OutputRequest struct {
	Manifest   artifacts.RunManifest        `json:"manifest"`
	Approved   []artifacts.Artifact         `json:"approved,omitempty"`
	Rejected   []artifacts.RejectedArtifact `json:"rejected,omitempty"`
	Warnings   []Warning                    `json:"warnings,omitempty"`
	LLMProfile string                       `json:"llm_profile,omitempty"`
	Options    map[string]any               `json:"options,omitempty"`
	Metadata   map[string]any               `json:"metadata,omitempty"`
}

type OutputResult struct {
	Bytes       []byte    `json:"-"`
	ContentType string    `json:"content_type,omitempty"`
	Warnings    []Warning `json:"warnings,omitempty"`
}

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