Documentation
¶
Overview ¶
Package signals is the unified, graph-attached signal model - the single row type that every observability dimension lands on.
AgentProvenance observes sandboxed agent execution along two pillars over one causality graph - behavior and quality/security - plus cost as a cross-cutting dimension that feeds both. Historically each dimension had its own storage silo (risk_signals, baseline_deviations, cost_samples, and a Python-only EvalSignal export). This package collapses them into one `signals` table keyed to the same graph, so consumers (collectors, evaluators, policies, audit) build against one contract instead of N silos.
Index ¶
- Constants
- func Backfill(db *sql.DB) (int, error)
- func Counts(db *sql.DB, runID string) (map[Dimension]int, error)
- func ProjectBaselineDeviations(db *sql.DB) (int, error)
- func ProjectCostSamples(db *sql.DB) (int, error)
- func ProjectRiskSignals(db *sql.DB) (int, error)
- func Record(db *sql.DB, s Signal) (string, error)
- func RecordCounting(db *sql.DB, s Signal) (bool, error)
- func ValidateSet(set SignalSet) error
- func ValidateSignal(s Signal) error
- type Dimension
- type Filter
- type Signal
- type SignalSet
Constants ¶
const SchemaVersion = "agentprovenance.signals/v1"
SchemaVersion identifies the unified signal wire format. It is the versioned contract external collectors, evaluators, policies, and auditors build against. Bump it only with a documented migration.
Variables ¶
This section is empty.
Functions ¶
func Backfill ¶
Backfill projects every legacy silo into the unified model and returns the total number of rows projected. Safe to run repeatedly (idempotent).
func ProjectBaselineDeviations ¶
ProjectBaselineDeviations projects the baseline silo into the unified model. Deviations are security signals (deviation-from-expected-norm).
func ProjectCostSamples ¶
ProjectCostSamples projects the system-side resource-attribution rows (cost_samples) into the unified model under the Cost dimension. This is the only cost that rides the correlation graph; app-side token/$ cost is deliberately out of scope.
func ProjectRiskSignals ¶
ProjectRiskSignals projects the security silo (risk_signals) into the unified model under the Security dimension.
func Record ¶
Record validates and persists a single signal. It fills in id, confidence, created_at, and JSON defaults when unset. Records projected from a legacy silo (SourceTable+SourceID set) are idempotent: re-projecting the same source row is a no-op rather than a duplicate.
func RecordCounting ¶
RecordCounting persists a signal and reports whether a new row was inserted (false when an idempotent projection/import hit an existing source row).
func ValidateSet ¶
ValidateSet checks a SignalSet envelope: schema version, count/counts consistency, and every signal.
func ValidateSignal ¶
ValidateSignal checks a single signal against the contract invariants.
Types ¶
type Dimension ¶
type Dimension string
Dimension is the observability lens a signal belongs to.
const ( // Behavior is the factual substrate (what happened, who caused it). Behavior Dimension = "behavior" // Cost is the cross-cutting resource/economic dimension (not a peer pillar). Cost Dimension = "cost" // Quality scores task success / reward. Quality Dimension = "quality" // Security scores safety-policy / baseline deviation. Security Dimension = "security" )
type Filter ¶
type Filter struct {
RunID string
Dimension Dimension
GraphRefKind string
GraphRefID string
ProcessID string
}
Filter narrows a Query. Empty fields are ignored.
type Signal ¶
type Signal struct {
ID string `json:"id"`
Dimension Dimension `json:"dimension"`
Type string `json:"type"`
GraphRefKind string `json:"graph_ref_kind"`
GraphRefID string `json:"graph_ref_id"`
RunID string `json:"run_id"`
SessionID string `json:"session_id,omitempty"`
ToolCallID string `json:"tool_call_id,omitempty"`
ProcessID string `json:"process_id,omitempty"`
EventID string `json:"event_id,omitempty"`
ObjectRef string `json:"object_ref,omitempty"`
Severity string `json:"severity,omitempty"` // security/risk only
Label string `json:"label,omitempty"` // categorical tag (e.g. quality pass/reject)
Value float64 `json:"value"`
Reference string `json:"reference,omitempty"`
Confidence float64 `json:"confidence"`
RecommendedAction string `json:"recommended_action,omitempty"`
ProducedBy string `json:"produced_by"`
EvidenceRefs string `json:"evidence_refs"` // JSON array; defaults to "[]"
Payload string `json:"payload"` // JSON object; defaults to "{}"
SourceTable string `json:"source_table,omitempty"`
SourceID string `json:"source_id,omitempty"`
CreatedAt string `json:"created_at"`
}
Signal is one graph-attached observation. The graph reference fields locate the node/edge this signal annotates; the scoring fields carry the judgment. JSON tags define the stable wire form; keep them and SchemaVersion in sync.
type SignalSet ¶
type SignalSet struct {
SchemaVersion string `json:"schema_version"`
RunID string `json:"run_id"`
Count int `json:"count"`
Counts map[string]int `json:"counts"`
Signals []Signal `json:"signals"`
}
SignalSet is the versioned export envelope for a run's signals - the unit a downstream consumer ingests. Counts is the per-dimension breakdown so an RL reward shaper or a security reviewer can see the shape at a glance.
func ValidateWireBytes ¶
ValidateWireBytes decodes and validates a SignalSet from its JSON wire form. This is the entry point an external consumer uses to confirm a payload conforms to agentprovenance.signals/v1 before trusting it.
Source Files