ai

package
v0.4.5 Latest Latest
Warning

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

 Go to latest Published: May 24, 2026 License: AGPL-3.0 Imports: 15 Imported by: 0

Documentation

Overview

Package ai defines contracts and helpers for AI jobs and results.

Index

Constants

View Source 
const (
	ClaimVerifyLLMModule        = "claim_verify_llm"
	ClaimVerifyLLMPolicyVersion = "v1"

	ClaimVerifyRetrievalModeProvidedOnly    = "provided_only"
	ClaimVerifyRetrievalModeOpenAIWebSearch = "openai_web_search"

	ClaimVerifySearchContextLow    = "low"
	ClaimVerifySearchContextMedium = "medium"
	ClaimVerifySearchContextHigh   = "high"
)

ClaimVerifyLLMModule and ClaimVerifyLLMPolicyVersion identify the claim verification module and schema version.

View Source 
const (
	ModerationTextLLMModule        = "moderation_text_llm"
	ModerationTextLLMPolicyVersion = "v1"

	ModerationImageLLMModule        = "moderation_image_llm"
	ModerationImageLLMPolicyVersion = "v1"
)

Moderation*LLMModule and Moderation*LLMPolicyVersion identify moderation modules and versions.

View Source 
const (
	RenderSummaryLLMModule        = "render_summary_llm"
	RenderSummaryLLMPolicyVersion = "v1"
)

RenderSummaryLLMModule and RenderSummaryLLMPolicyVersion identify the render-summary module and version.

Variables

This section is empty.

Functions

func CacheKey 

func CacheKey(scope CacheScope, scopeKey string, module string, policyVersion string, modelSet string, inputsHash string) (string, error)

CacheKey builds the cache key for an AI result given the scope and module contract fields.

func CanonicalJSON 

func CanonicalJSON(v any) (string, error)

CanonicalJSON encodes a value as JSON suitable for hashing and caching.

func ExtractClaimsDeterministicV1 

func ExtractClaimsDeterministicV1(text string, maxClaims int) []string

ExtractClaimsDeterministicV1 extracts simple claims from text without any model calls.

func InputsHash 

func InputsHash(v any) (string, error)

InputsHash returns a stable hash of the canonical JSON encoding of v.

func SummarizeTextDeterministic 

func SummarizeTextDeterministic(in string, maxLen int) string

SummarizeTextDeterministic returns a bounded, deterministic summary string.

Types

type BudgetDecision 

type BudgetDecision struct {
	Allowed    bool   `json:"allowed"`
	OverBudget bool   `json:"over_budget"`
	Reason     string `json:"reason,omitempty"`

	Month string `json:"month,omitempty"`

	IncludedCredits  int64 `json:"included_credits,omitempty"`
	UsedCredits      int64 `json:"used_credits,omitempty"`
	RemainingCredits int64 `json:"remaining_credits,omitempty"`

	RequestedCredits int64 `json:"requested_credits"`
	DebitedCredits   int64 `json:"debited_credits"`
}

BudgetDecision describes the outcome of a credit budget check and debit.

type CacheScope 

type CacheScope string

CacheScope controls how AI results are scoped for caching. 

const (
	// CacheScopeInstance scopes cache entries to a single instance.
	CacheScopeInstance CacheScope = "instance"
	// CacheScopeGlobal scopes cache entries globally across instances.
	CacheScopeGlobal CacheScope = "global"
)

type ClaimVerifyCitationV1 

type ClaimVerifyCitationV1 struct {
	SourceID string `json:"source_id"`
	Quote    string `json:"quote,omitempty"`
}

ClaimVerifyCitationV1 references an evidence source and quote.

type ClaimVerifyClaimV1 

type ClaimVerifyClaimV1 struct {
	ClaimID string `json:"claim_id"`
	Text    string `json:"text"`

	Classification string  `json:"classification"` // checkable|opinion|unclear
	Verdict        string  `json:"verdict"`        // supported|refuted|inconclusive
	Confidence     float64 `json:"confidence"`     // 0-1

	Reason    string                  `json:"reason,omitempty"`
	Citations []ClaimVerifyCitationV1 `json:"citations,omitempty"`
}

ClaimVerifyClaimV1 is a single claim verification result.

type ClaimVerifyEvidenceV1 

type ClaimVerifyEvidenceV1 struct {
	SourceID string `json:"source_id"`
	URL      string `json:"url,omitempty"`
	Title    string `json:"title,omitempty"`
	RenderID string `json:"render_id,omitempty"`

	// Text is bounded untrusted evidence text provided by callers.
	Text string `json:"text"`
}

ClaimVerifyEvidenceV1 is an evidence snippet used to verify claims.

type ClaimVerifyInputsV1 

type ClaimVerifyInputsV1 struct {
	ActorURI    string `json:"actor_uri,omitempty"`
	ObjectURI   string `json:"object_uri,omitempty"`
	ContentHash string `json:"content_hash,omitempty"`

	// Text is the content to extract claims from. Optional if Claims is provided.
	Text string `json:"text,omitempty"`
	// Claims optionally provides explicit claims; when set, extraction is skipped.
	Claims []string `json:"claims,omitempty"`

	// Evidence is required; citations must reference these SourceIDs.
	Evidence []ClaimVerifyEvidenceV1 `json:"evidence"`

	// Retrieval controls whether the verifier may augment evidence (e.g., OpenAI web search).
	Retrieval *ClaimVerifyRetrievalV1 `json:"retrieval,omitempty"`
}

ClaimVerifyInputsV1 is the input payload for claim verification.

type ClaimVerifyResultV1 

type ClaimVerifyResultV1 struct {
	Kind     string               `json:"kind"`    // claim_verify
	Version  string               `json:"version"` // v1
	Claims   []ClaimVerifyClaimV1 `json:"claims"`
	Warnings []string             `json:"warnings,omitempty"`

	// Sources optionally echoes the bounded evidence texts used for citations (useful when web search retrieval is enabled).
	Sources []ClaimVerifyEvidenceV1 `json:"sources,omitempty"`
	// Disclaimer provides a short disclosure when retrieval/web search was used.
	Disclaimer string `json:"disclaimer,omitempty"`
}

ClaimVerifyResultV1 is the output schema for claim verification.

func ClaimVerifyDeterministicV1 

func ClaimVerifyDeterministicV1(in ClaimVerifyInputsV1) ClaimVerifyResultV1

ClaimVerifyDeterministicV1 generates a best-effort claim verification result without any model calls.

type ClaimVerifyRetrievalV1 

type ClaimVerifyRetrievalV1 struct {
	Mode string `json:"mode,omitempty"` // provided_only|openai_web_search

	// MaxSources limits how many sources retrieval may add (bounded to 0..5).
	MaxSources int `json:"max_sources,omitempty"`
	// SearchContextSize is provider-specific; for OpenAI it maps to the web search tool context size.
	SearchContextSize string `json:"search_context_size,omitempty"` // low|medium|high
}

ClaimVerifyRetrievalV1 configures optional retrieval behavior for claim verification.

type InstanceConfig 

type InstanceConfig struct {
	Enabled bool

	ModelSet string

	BatchingMode       string
	BatchMaxItems      int64
	BatchMaxTotalBytes int64

	PricingMultiplierBps int64

	MaxInflightJobs int64
}

InstanceConfig is the effective AI configuration for an instance.

func DefaultInstanceConfig 

func DefaultInstanceConfig() InstanceConfig

DefaultInstanceConfig returns the default AI instance configuration.

func EffectiveInstanceConfig 

func EffectiveInstanceConfig(inst *models.Instance) InstanceConfig

EffectiveInstanceConfig resolves an InstanceConfig from an instance record.

type JobMessage 

type JobMessage struct {
	Kind   string   `json:"kind"`
	JobID  string   `json:"job_id,omitempty"`
	JobIDs []string `json:"job_ids,omitempty"`
}

JobMessage is the queue payload for AI worker jobs.

type JobStatus 

type JobStatus string

JobStatus describes the lifecycle status of an AI job. 

const (
	// JobStatusQueued indicates an AI job has been queued but not yet completed.
	JobStatusQueued JobStatus = "queued"
	// JobStatusOK indicates an AI job completed successfully and a result is available.
	JobStatusOK JobStatus = "ok"
	// JobStatusNotCheckedBudget indicates the job could not be queued due to missing or exceeded budget.
	JobStatusNotCheckedBudget JobStatus = "not_checked_budget"
	// JobStatusError indicates the job failed due to an internal error.
	JobStatusError JobStatus = "error"
)

type ModerationCategoryV1 

type ModerationCategoryV1 struct {
	Code       string  `json:"code"`
	Confidence float64 `json:"confidence"`
	Severity   string  `json:"severity"` // low|medium|high
	Summary    string  `json:"summary,omitempty"`
}

ModerationCategoryV1 describes a single moderation category signal.

type ModerationImageInputsV1 

type ModerationImageInputsV1 struct {
	ObjectKey string `json:"object_key"`

	// ObjectETag/Bytes/ContentType are for stable caching + guardrails without reading the object.
	ObjectETag  string `json:"object_etag,omitempty"`
	Bytes       int64  `json:"bytes,omitempty"`
	ContentType string `json:"content_type,omitempty"`
}

ModerationImageInputsV1 is the input payload for image moderation.

type ModerationResultV1 

type ModerationResultV1 struct {
	Kind    string `json:"kind"`    // moderation_text|moderation_image
	Version string `json:"version"` // v1

	Decision string `json:"decision"` // allow|review|block

	Categories []ModerationCategoryV1 `json:"categories,omitempty"`
	Highlights []string               `json:"highlights,omitempty"`
	Notes      string                 `json:"notes,omitempty"`
}

ModerationResultV1 is the normalized output payload for moderation modules.

func ModerationTextDeterministicV1 

func ModerationTextDeterministicV1(text string) ModerationResultV1

ModerationTextDeterministicV1 performs a deterministic moderation pass over text.

type ModerationTextInputsV1 

type ModerationTextInputsV1 struct {
	// Text is bounded untrusted content to scan.
	Text string `json:"text"`
}

ModerationTextInputsV1 is the input payload for text moderation.

type ModuleContract 

type ModuleContract struct {
	Module        string    `json:"module"`
	PolicyVersion string    `json:"policy_version"`
	ModelSet      string    `json:"model_set"`
	InputsHash    string    `json:"inputs_hash"`
	CreatedAt     time.Time `json:"created_at"`
	ExpiresAt     time.Time `json:"expires_at"`
}

ModuleContract is the common envelope for all AI modules. It is the stable cache key and audit surface, not the module-specific payload schema.

type ModuleOutput 

type ModuleOutput struct {
	Contract ModuleContract   `json:"contract"`
	Result   json.RawMessage  `json:"result"`
	Usage    models.AIUsage   `json:"usage,omitempty"`
	Errors   []models.AIError `json:"errors,omitempty"`
}

ModuleOutput is the normalized output shape for all AI modules. Result is module-specific JSON (validated by the module).

type RenderSummaryInputsV1 

type RenderSummaryInputsV1 struct {
	RenderID      string `json:"render_id"`
	NormalizedURL string `json:"normalized_url"`
	ResolvedURL   string `json:"resolved_url,omitempty"`
	RenderedAt    string `json:"rendered_at,omitempty"`

	LinkRisk string `json:"link_risk,omitempty"`

	// Text is bounded evidence (e.g., RenderArtifact.textPreview).
	Text string `json:"text,omitempty"`
}

RenderSummaryInputsV1 is the input payload for render summarization.

type RenderSummaryResultV1 

type RenderSummaryResultV1 struct {
	Kind string `json:"kind"`
	// Version is the module-specific result schema version (not the policyVersion).
	Version string `json:"version"`

	ShortSummary string              `json:"short_summary"`
	KeyBullets   []string            `json:"key_bullets,omitempty"`
	Risks        []RenderSummaryRisk `json:"risks,omitempty"`
}

RenderSummaryResultV1 is the normalized output payload for render summarization.

func RenderSummaryDeterministicV1 

func RenderSummaryDeterministicV1(in RenderSummaryInputsV1) RenderSummaryResultV1

RenderSummaryDeterministicV1 produces a deterministic summary and risk signals from inputs.

type RenderSummaryRisk 

type RenderSummaryRisk struct {
	Code     string `json:"code"`
	Severity string `json:"severity"` // low|medium|high
	Summary  string `json:"summary"`
}

RenderSummaryRisk describes a single risk signal extracted during summarization.

type Request 

type Request struct {
	InstanceSlug string
	RequestID    string

	Module        string
	PolicyVersion string
	ModelSet      string

	CacheScope CacheScope

	Inputs   any
	Evidence []models.AIEvidenceRef

	// BaseCredits is the un-multiplied credit cost for a cache miss.
	BaseCredits int64

	// PricingMultiplierBps is applied to BaseCredits when debiting.
	PricingMultiplierBps int64

	// AllowOverage controls whether the budget debit is allowed to exceed IncludedCredits.
	AllowOverage bool

	// JobTTL controls how long queued jobs remain claimable before expiring.
	JobTTL time.Duration

	// MaxInflightJobs caps the number of queued AI jobs for the instance (best-effort).
	MaxInflightJobs int64
}

Request describes an AI module request for caching and queueing.

type Response 

type Response struct {
	Status JobStatus `json:"status"`
	Cached bool      `json:"cached"`

	JobID    string `json:"job_id,omitempty"`
	ResultID string `json:"result_id,omitempty"`

	Result *models.AIResult `json:"result,omitempty"`
	Budget BudgetDecision   `json:"budget"`
}

Response is the output of an AI request, either cached, queued, or error.

type Service 

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

Service provides caching, budgeting, and queueing for AI modules.

func NewService 

func NewService(st *store.Store) *Service

NewService constructs a new Service backed by the provided store.

func (*Service) GetOrQueue 

func (s *Service) GetOrQueue(ctx context.Context, req Request) (Response, error)

GetOrQueue returns a cached AIResult when available, otherwise queues an AIJob (budgeted) and returns queued. It never performs provider/tool calls.

Source Files

View all Source files

Directories

Path Synopsis
Package llm contains provider-specific LLM adapters.
 Package llm contains provider-specific LLM adapters.

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.