judgment

type Assessor ¶

type Assessor struct {
	Name            string         `json:"name"`
	Domain          Domain         `json:"domain"`
	Weight          float64        `json:"weight,omitempty"` // contribution to combined score
	Config          map[string]any `json:"config,omitempty"`
	RequiresContext bool           `json:"requires_context,omitempty"` // needs source material
}

Assessor defines a judgment assessment strategy.

type Domain ¶

type Domain string

Domain defines what area of safety a judgment covers.

const (
	// DomainGrounding evaluates factual accuracy and hallucination.
	DomainGrounding Domain = "grounding"
	// DomainRelevance evaluates response relevance to input.
	DomainRelevance Domain = "relevance"
	// DomainConsistency evaluates self-consistency of output.
	DomainConsistency Domain = "consistency"
	// DomainCompliance evaluates regulatory compliance.
	DomainCompliance Domain = "compliance"
	// DomainCustom is a user-defined domain.
	DomainCustom Domain = "custom"
)

type Judge ¶

type Judge interface {
	Assess(ctx context.Context, req *JudgeRequest) (*JudgeVerdict, error)
}

Judge assesses risk with a model. The engine calls it only when Config.ModelJudge is on, under the scan's context and Config.JudgeTimeout, and treats its answer as untrusted: the judgment's risk becomes the larger of the deterministic risk and the verdict's score, so a judge can raise a risk and never lower it. An error, a timeout or a score outside [0,1] leaves the deterministic result standing.

type JudgeRequest ¶

type JudgeRequest struct {
	Text      string
	Direction string
	Judgment  string // judgment name
	Domain    Domain
	Findings  []string
}

JudgeRequest is what a model judge is asked to assess.

Text is never the scanned text as it came in: every secret and personal data span the awareness layer or shield's built-in detectors found is replaced by a placeholder first, whatever the profile does with those findings and even when it has no awareness, because the judge is a remote model. For a tool call it holds one "path: value" line per argument unit. Findings lists "<layer>:<source>" of the detections so far and carries no matched text.

type JudgeVerdict ¶

type JudgeVerdict struct {
	Score  float64
	Reason string
}

JudgeVerdict is a judge's answer. Score is a risk in [0,1]. Reason is untrusted model text. The engine never stores it: a judgment finding keeps the score only, as judge_score in its details.

type Judgment ¶

type Judgment struct {
	shield.Entity
	ID          id.JudgmentID  `json:"id" bun:",pk"`
	Name        string         `json:"name" bun:",notnull"`
	Description string         `json:"description,omitempty"`
	AppID       string         `json:"app_id" bun:",notnull"`
	TenantID    string         `json:"tenant_id,omitempty"`
	Domain      Domain         `json:"domain" bun:",notnull"`
	Assessors   []Assessor     `json:"assessors,omitempty" bun:"type:jsonb"`
	Threshold   float64        `json:"threshold,omitempty"`   // risk threshold for action (0.0-1.0)
	Action      string         `json:"action" bun:",notnull"` // "flag", "block", "warn"
	Enabled     bool           `json:"enabled" bun:",notnull,default:true"`
	Metadata    map[string]any `json:"metadata,omitempty" bun:"type:jsonb"`
}

Judgment represents a learned ability to assess risk in context. Judgments are the fifth layer of the safety engine, the slowest but most sophisticated, capable of contextual risk assessment.

type ListFilter ¶

type ListFilter struct {
	AppID    string
	TenantID string
	Domain   Domain
	Enabled  *bool
	Limit    int
	Offset   int
}

ListFilter defines filtering options for listing judgments.

type RiskLevel ¶

type RiskLevel string

RiskLevel represents the assessed risk from a judgment evaluation.

const (
	// RiskNone indicates no risk detected.
	RiskNone RiskLevel = "none"
	// RiskLow indicates low risk.
	RiskLow RiskLevel = "low"
	// RiskMedium indicates moderate risk.
	RiskMedium RiskLevel = "medium"
	// RiskHigh indicates high risk.
	RiskHigh RiskLevel = "high"
	// RiskCritical indicates critical risk.
	RiskCritical RiskLevel = "critical"
)

type Store ¶

type Store interface {
	CreateJudgment(ctx context.Context, j *Judgment) error
	GetJudgment(ctx context.Context, jID id.JudgmentID) (*Judgment, error)
	GetJudgmentByName(ctx context.Context, appID, name string) (*Judgment, error)
	UpdateJudgment(ctx context.Context, j *Judgment) error
	DeleteJudgment(ctx context.Context, jID id.JudgmentID) error
	ListJudgments(ctx context.Context, filter *ListFilter) ([]*Judgment, error)
}

Store defines persistence operations for judgments.