safety

package

v1.10.4 Latest Latest Go to latest Published: Nov 4, 2026 License: MIT Imports: 3 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/xraph/cortex

Links

Open Source Insights

Documentation ¶

Overview ¶

Package safety defines the interface for content safety scanning in the Cortex agent engine. Implementations bridge external safety engines (e.g. Shield) to the Cortex runtime without introducing a direct dependency on any specific safety library.

Constants ¶

This section is empty.

Variables ¶

View Source

var (
	ErrBlocked     = errors.New("cortex: content blocked by publication policy")
	ErrUnavailable = errors.New("cortex: publication policy unavailable")
	ErrLimit       = errors.New("cortex: publication byte limit exceeded")
)

Functions ¶

This section is empty.

Types ¶

type Decision ¶

type Decision string

Decision is the safety verdict.

const (
	DecisionAllow  Decision = "allow"
	DecisionBlock  Decision = "block"
	DecisionFlag   Decision = "flag"
	DecisionRedact Decision = "redact"
)

type Direction ¶

type Direction string

Direction indicates the scan direction.

const (
	DirectionInput  Direction = "input"
	DirectionOutput Direction = "output"
)

type Finding ¶

type Finding struct {
	Layer    string  `json:"layer"`
	Source   string  `json:"source"`
	Severity string  `json:"severity"`
	Message  string  `json:"message"`
	Score    float64 `json:"score,omitempty"`
}

Finding is a single detection from a safety layer.

type IncrementalGate ¶

type IncrementalGate interface {
	PublicationGate
	NewSegmentChecker(context.Context, PublicationRequest) (SegmentChecker, error)
}

IncrementalGate explicitly advertises a boundary-aware streaming checker. Each stream owns its own checker. It must hold prefixes whose safety depends on future bytes; approving a prefix is irrevocable. Full-document policies must use buffered mode instead.

type Mode ¶

type Mode string

Mode controls when approved content may leave the engine.

const (
	ModeBuffered        Mode = "buffered"
	ModeCheckedSegments Mode = "checked_segments"
	ModeDisabled        Mode = "disabled_explicit"
)

type Policy ¶

type Policy struct {
	Version            int  `json:"version"`
	Mode               Mode `json:"mode"`
	Required           bool `json:"required"`
	MaxInputBytes      int  `json:"max_input_bytes"`
	MaxOutputBytes     int  `json:"max_output_bytes"`
	MaxToolOutputBytes int  `json:"max_tool_output_bytes"`
}

Policy is host configuration, never instructions read from model or tool text. Byte limits apply even when scanning is explicitly disabled. Zero selects the bounded default. Required refuses execution when no gate is configured.

func (Policy) Resolve ¶

func (p Policy) Resolve() (Policy, error)

Resolve validates the policy and fills in finite limits.

type PublicationDecision ¶

type PublicationDecision struct {
	Text   string
	Status PublicationStatus
}

PublicationDecision contains only the text authorized for the next boundary. An empty redaction is intentional. An error must never return candidate text.

func DecisionFromScan ¶ added in v1.10.0

func DecisionFromScan(req PublicationRequest, result *ScanResult) (PublicationDecision, error)

DecisionFromScan turns a scan result into the decision a gate returns for req. A blocked result is ErrBlocked. An allow or a flag publishes the scanner's Redacted text, with StatusRedacted, when it set one (a scanner that quotes untrusted text returns the quoted text this way), and the request's own content otherwise. A redact publishes Redacted, even an empty one. A nil result or an unknown decision is ErrUnavailable, so a gate that cannot read the result fails closed.

type PublicationGate ¶

type PublicationGate interface {
	Check(context.Context, PublicationRequest) (PublicationDecision, error)
}

PublicationGate screens complete content. Implementations must be safe for concurrent use and honor context cancellation. The engine validates statuses.

type PublicationRequest ¶

type PublicationRequest struct {
	ScanRequest
	Source string `json:"source"`
}

PublicationRequest carries content and trusted provenance separately.

type PublicationStatus ¶

type PublicationStatus string

PublicationStatus describes content screening, not factual verification.

const (
	StatusApproved  PublicationStatus = "approved"
	StatusRedacted  PublicationStatus = "redacted"
	StatusFlagged   PublicationStatus = "flagged"
	StatusUnscanned PublicationStatus = "unscanned"
)

type ScanRequest ¶

type ScanRequest struct {
	Content     string         `json:"content"`
	Direction   Direction      `json:"direction"`
	AgentID     string         `json:"agent_id"`
	RunID       string         `json:"run_id"`
	ProfileName string         `json:"profile_name,omitempty"`
	AppID       string         `json:"app_id,omitempty"`
	TenantID    string         `json:"tenant_id,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

ScanRequest is the input to a safety scan.

type ScanResult ¶

type ScanResult struct {
	Decision    Decision      `json:"decision"`
	Blocked     bool          `json:"blocked"`
	Findings    []Finding     `json:"findings,omitempty"`
	Redacted    string        `json:"redacted,omitempty"`
	PIICount    int           `json:"pii_count,omitempty"`
	ProfileUsed string        `json:"profile_used,omitempty"`
	Duration    time.Duration `json:"duration"`
}

ScanResult is the output of a safety scan.

type Scanner ¶

type Scanner interface {
	// ScanInput scans content before it is sent to the LLM.
	ScanInput(ctx context.Context, req *ScanRequest) (*ScanResult, error)
	// ScanOutput scans content after it is received from the LLM.
	ScanOutput(ctx context.Context, req *ScanRequest) (*ScanResult, error)
}

Scanner is the interface the cortex engine uses for safety scanning. Implementations must be safe for concurrent use.

type ScannerGate ¶

type ScannerGate struct{ Scanner Scanner }

ScannerGate adapts the existing input/output scanner with closed error handling. Scanner errors are deliberately not wrapped: providers can include raw content or credentials in their error text.

func (ScannerGate) Check ¶

func (g ScannerGate) Check(ctx context.Context, req PublicationRequest) (PublicationDecision, error)

Check approves, flags or redacts content using the configured scanner.

type SegmentChecker ¶

type SegmentChecker interface {
	CheckSegment(ctx context.Context, pending string, final bool) (decision PublicationDecision, consumed int, err error)
}

SegmentChecker approves a prefix of the supplied pending text. Consumed is a byte count on a UTF-8 boundary. Zero holds the entire pending text. A final check must consume all pending bytes. The engine bounds pending and total text.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
rules Package rules screens bounded text against explicit host-owned regular expressions.	Package rules screens bounded text against explicit host-owned regular expressions.
shield Package shield bridges the Shield safety engine to Cortex: content scans through safety.Scanner and safety.PublicationGate, streamed model output a segment at a time through safety.IncrementalGate, and tool-call scans layered under the host's cortex.ToolAuthorizer (see NewToolAuthorizer).	Package shield bridges the Shield safety engine to Cortex: content scans through safety.Scanner and safety.PublicationGate, streamed model output a segment at a time through safety.IncrementalGate, and tool-call scans layered under the host's cortex.ToolAuthorizer (see NewToolAuthorizer).

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL