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.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrBlocked = errors.New("cortex: content blocked by publication policy") ErrLimit = errors.New("cortex: publication byte limit exceeded") )
Functions ¶
This section is empty.
Types ¶
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 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.
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.
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
Directories
¶
| Path | Synopsis |
|---|---|
|
Package rules screens bounded text against explicit host-owned regular expressions.
|
Package rules screens bounded text against explicit host-owned regular expressions. |
|
Package shield bridges the Shield safety engine to the Cortex safety.Scanner interface, following the same DI auto-discovery pattern as cortex/llm/nexus.
|
Package shield bridges the Shield safety engine to the Cortex safety.Scanner interface, following the same DI auto-discovery pattern as cortex/llm/nexus. |