Add framework contract interfaces

2026-07-03 06:07:58 +00:00
parent 346eebe815
commit 94286c70b6
2 changed files with 262 additions and 0 deletions
--- a/internal/framework/contracts/contracts.go
+++ b/internal/framework/contracts/contracts.go
@@ -0,0 +1,97 @@
+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:"-"`
+	Metadata map[string]any `json:"metadata,omitempty"`
+}
+
+type InputAdapter interface {
+	Key() string
+	Parse(ctx context.Context, req ParseRequest) (*source.SourceDocument, error)
+}
+
+type ExtractionRequest struct {
+	Source    *source.SourceDocument `json:"-"`
+	LLMClient StructuredLLMClient    `json:"-"`
+	Metadata  map[string]any         `json:"metadata,omitempty"`
+}
+
+type ExtractionResult struct {
+	Candidates []artifacts.Candidate `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 ValidationRequest struct {
+	Source     *source.SourceDocument `json:"-"`
+	Candidates []artifacts.Candidate  `json:"candidates"`
+	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"`
+}