halguard

type BlockLabel string

type BlockScore struct {
	// Text is the original block text.
	Text string

	// Label is the consistency verdict: ACCURATE, CONTRADICTION, or NEUTRAL.
	Label BlockLabel

	// Reason explains the verdict (populated for CONTRADICTION and NEUTRAL).
	Reason string
}

type BlockScores []BlockScore

type Config struct {
	// LightThresholdChars is the output length above which the light
	// verification tier is applied. Default: 200.
	LightThresholdChars int `yaml:"light_threshold_chars,omitempty" toml:"light_threshold_chars,omitempty"`

	// FullThresholdChars is the output length above which the full
	// cross-model Finch-Zk verification tier is applied. Default: 500.
	FullThresholdChars int `yaml:"full_threshold_chars,omitempty" toml:"full_threshold_chars,omitempty"`

	// EnablePreCheck controls whether pre-delegation grounding checks run.
	// Default: true.
	EnablePreCheck bool `yaml:"enable_pre_check,omitempty" toml:"enable_pre_check,omitempty"`

	// EnablePostCheck controls whether post-execution verification runs.
	// Default: true.
	EnablePostCheck bool `yaml:"enable_post_check,omitempty" toml:"enable_post_check,omitempty"`

	// CrossModelSamples is the number of cross-model samples to generate
	// for full verification. Finch-Zk shows 3 samples with batch judging
	// maintains accuracy while keeping cost manageable. Default: 3.
	CrossModelSamples int `yaml:"cross_model_samples,omitempty" toml:"cross_model_samples,omitempty"`

	// MaxBlocksToJudge caps the number of blocks sent for cross-consistency
	// judging to limit cost on very long outputs. Default: 20.
	MaxBlocksToJudge int `yaml:"max_blocks_to_judge,omitempty" toml:"max_blocks_to_judge,omitempty"`

	// PreCheckThreshold is the confidence score below which a sub-agent
	// goal is rejected as likely fabricated. Range: (0.0–1.0]. Default: 0.4.
	// Lower = more permissive, higher = more strict. A value of 0 (or an
	// omitted field) is treated as "unset" and causes the default to be used.
	PreCheckThreshold float64 `yaml:"pre_check_threshold,omitempty" toml:"pre_check_threshold,omitempty"`
}

type GroundingSignals struct {
	// RolePlay detects explicit role-play instructions
	// (e.g. "you are an SRE", "imagine you're", "pretend to be").
	RolePlay float64

	// FabricationPattern detects invented operational data
	// (e.g. "p99 latency spiked from", "error rate jumped from").
	FabricationPattern float64

	// SecondPersonRole detects "You are..." framing at the start of goals.
	SecondPersonRole float64

	// SpecificMetrics detects suspiciously precise numeric claims
	// without tool backing (e.g. "342ms", "2.4%", "1500 req/s").
	SpecificMetrics float64

	// InformationDensity detects an unusually high density of specific
	// technical claims per sentence.
	InformationDensity float64

	// TemporalUrgency detects artificial time pressure language
	// (e.g. "production is down", "immediately", "urgent").
	TemporalUrgency float64
}

type Guard interface {
	// PreCheck scores the sub-agent goal for fabrication risk before execution.
	// Returns a PreCheckResult with a Confidence score between 0.0 (certainly
	// fabricated) and 1.0 (certainly genuine). The caller decides whether to
	// proceed based on the score and a configurable threshold.
	//
	// Uses multi-signal analysis based on structural indicators, semantic
	// patterns, and information density rather than brittle keyword matching.
	PreCheck(ctx context.Context, req PreCheckRequest) (PreCheckResult, error)

	// PostCheck verifies sub-agent output after execution.
	// Returns a VerificationResult with per-block scores and, when contradictions
	// are found, a corrected version of the output. The corrected text preserves
	// accurate blocks and only rewrites contradicted ones.
	PostCheck(ctx context.Context, req PostCheckRequest) (VerificationResult, error)
}

type Option func(*Config)

type PostCheckRequest struct {
	// Goal is the original goal given to the sub-agent.
	Goal string

	// Context is the optional context string provided alongside the goal.
	Context string

	// Output is the sub-agent's raw text output to verify.
	Output string

	// ToolCallsMade is the number of tool calls the sub-agent executed.
	// A higher count suggests the output is more grounded in real data.
	ToolCallsMade int

	// GenerationModel identifies the model that generated the output
	// (e.g. "claude-sonnet-4-6"). Used to select a different model family
	// for cross-model verification per Finch-Zk §2.5.
	GenerationModel modelprovider.ModelMap
}

type PreCheckRequest struct {
	// Goal is the sub-agent's goal as specified by the parent agent.
	Goal string

	// Context is the optional context string provided alongside the goal.
	Context string

	// ToolNames lists the tools assigned to the sub-agent.
	ToolNames []string
}

type PreCheckResult struct {
	// Confidence is the probability that the goal is genuine and grounded
	// in reality. Range: 0.0 (certainly fabricated) to 1.0 (certainly genuine).
	// The caller compares this against a configurable threshold to decide
	// whether to proceed with execution.
	Confidence float64

	// Signals contains the individual signal contributions that produced
	// the confidence score. Each field represents a distinct fabrication
	// signal with its weighted penalty.
	Signals GroundingSignals

	// Summary is a human-readable explanation of the assessment.
	Summary string
}

type TextGeneratorFunc func(ctx context.Context, m model.Model, prompt string) (string, error)

type VerificationResult struct {
	// IsFactual is true when no contradictions were detected.
	IsFactual bool

	// CorrectedText holds the corrected output when contradictions were
	// found and targeted corrections were applied. When IsFactual is true,
	// this equals the original output unchanged.
	CorrectedText string

	// BlockScores holds per-block verification results for observability.
	// Only populated for Light and Full tier verifications.
	BlockScores []BlockScore

	// Tier indicates which verification level was applied.
	Tier VerifyTier
}

type VerifyTier string