models

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 13, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package models defines the core domain types of the Sphinx HITL control plane. Field values and JSON keys mirror the original Python service so the REST surface stays wire-compatible.

Index

Constants

This section is empty.

Variables

View Source 
var TerminalStatuses = []RequestStatus{
	StatusApproved, StatusRejected, StatusAutoApproved, StatusAutoRejected, StatusCancelled,
}

TerminalStatuses are the decided/cancelled states used by metrics.

Functions

func IsTerminal 

func IsTerminal(s RequestStatus) bool

func NewRef 

func NewRef() string

NewRef returns a short human-friendly reference like "SPH-1A2B3C".

func NewUUID 

func NewUUID() string

NewUUID returns a random UUID v4 string.

Types

type ApprovalRequest 

type ApprovalRequest struct {
	ID              string
	Ref             string
	SessionID       string
	AgentID         string
	Framework       string
	Title           string
	Description     string
	ActionPayload   json.RawMessage
	RiskLevel       RiskLevel
	Priority        int
	Status          RequestStatus
	Requester       string
	Metadata        json.RawMessage
	PolicyID        *string
	PolicyName      *string
	TimeoutSeconds  *int
	Escalated       bool
	EscalatedAt     *time.Time
	EscalationNote  string
	TimeoutFired    bool
	ReviewerID      *string
	ReviewerNote    string
	DecisionPayload json.RawMessage
	ResolvedBy      *string
	Outcome         *Outcome
	OutcomeNote     string
	CreatedAt       time.Time
	UpdatedAt       time.Time
	DecidedAt       *time.Time
}

ApprovalRequest is a ticket an agent opens to get human (or policy) sign-off before executing a risky action.

func (*ApprovalRequest) ActionPayloadMap 

func (r *ApprovalRequest) ActionPayloadMap() map[string]any

ActionPayloadMap decodes the stored action payload as an object.

func (*ApprovalRequest) Deadline 

func (r *ApprovalRequest) Deadline() *time.Time

Deadline returns the SLA deadline while the request is still pending.

func (*ApprovalRequest) DecisionPayloadMap 

func (r *ApprovalRequest) DecisionPayloadMap() (map[string]any, bool)

DecisionPayloadMap decodes the stored decision payload (nil when empty).

func (*ApprovalRequest) SecondsPending 

func (r *ApprovalRequest) SecondsPending() float64

SecondsPending returns how long the request has been waiting (or waited).

func (*ApprovalRequest) ToDTO 

func (r *ApprovalRequest) ToDTO() *ApprovalRequestDTO

ToDTO renders the request in the wire format.

type ApprovalRequestDTO 

type ApprovalRequestDTO struct {
	ID              string          `json:"id"`
	Ref             string          `json:"ref"`
	SessionID       string          `json:"session_id"`
	AgentID         string          `json:"agent_id"`
	Framework       string          `json:"framework"`
	Title           string          `json:"title"`
	Description     string          `json:"description"`
	ActionPayload   json.RawMessage `json:"action_payload"`
	RiskLevel       RiskLevel       `json:"risk_level"`
	Priority        int             `json:"priority"`
	Status          RequestStatus   `json:"status"`
	Requester       string          `json:"requester"`
	Metadata        json.RawMessage `json:"metadata"`
	PolicyID        *string         `json:"policy_id"`
	PolicyName      *string         `json:"policy_name"`
	TimeoutSeconds  *int            `json:"timeout_seconds"`
	Escalated       bool            `json:"escalated"`
	EscalatedAt     *string         `json:"escalated_at"`
	EscalationNote  string          `json:"escalation_note"`
	ReviewerID      *string         `json:"reviewer_id"`
	ReviewerNote    string          `json:"reviewer_note"`
	DecisionPayload json.RawMessage `json:"decision_payload"`
	ResolvedBy      *string         `json:"resolved_by"`
	Outcome         *Outcome        `json:"outcome"`
	OutcomeNote     string          `json:"outcome_note"`
	CreatedAt       string          `json:"created_at"`
	UpdatedAt       string          `json:"updated_at"`
	DecidedAt       *string         `json:"decided_at"`
	SecondsPending  float64         `json:"seconds_pending"`
}

DTO mirrors the JSON shape emitted by the original service.

type CaptureEvent 

type CaptureEvent struct {
	ID            string
	SessionID     string
	AgentID       string
	EventType     CaptureEventType
	EventName     string
	Sequence      int
	InputPayload  json.RawMessage
	OutputPayload json.RawMessage
	Metadata      json.RawMessage
	Status        string
	ContentHash   string
	PrevHash      *string
	Signature     string
	CreatedAt     time.Time
}

CaptureEvent is one recorded agent step with tamper-evidence chain fields.

func (*CaptureEvent) ToDTO 

func (e *CaptureEvent) ToDTO() map[string]any

type CaptureEventType 

type CaptureEventType string

CaptureEventType is the kind of agent step being recorded. 

const (
	EventToolCall     CaptureEventType = "tool_call"
	EventLLMInference CaptureEventType = "llm_inference"
	EventStateChange  CaptureEventType = "state_change"
)

func ParseCaptureEventType 

func ParseCaptureEventType(s string) (CaptureEventType, error)

type DecisionLog 

type DecisionLog struct {
	ID            string
	RequestID     string
	RequestRef    *string
	AgentDecision json.RawMessage
	HumanDecision json.RawMessage
	Delta         json.RawMessage
	Agreement     *bool
	Source        DecisionSource
	ReviewerID    *string
	Note          string
	CreatedAt     time.Time
}

DecisionLog records one decision in the governance trail.

func (*DecisionLog) ToDTO 

func (d *DecisionLog) ToDTO() map[string]any

type DecisionSource 

type DecisionSource string

DecisionSource records how a decision was reached. 

const (
	SourceHumanReview   DecisionSource = "human_review"
	SourcePolicyTimeout DecisionSource = "policy_timeout"
	SourceAutoPolicy    DecisionSource = "auto_policy"
	SourceAgentFeedback DecisionSource = "agent_feedback"
)

type Outcome 

type Outcome string

Outcome is the real-world result reported by the agent after execution. 

const (
	OutcomeSuccess Outcome = "success"
	OutcomeFailure Outcome = "failure"
	OutcomePartial Outcome = "partial"
)

func ParseOutcome 

func ParseOutcome(s string) (Outcome, error)

type Policy 

type Policy struct {
	ID                   string
	Name                 string
	Description          string
	RiskLevels           []RiskLevel
	TimeoutSeconds       int
	OnTimeout            TimeoutAction
	AutoApproveBelowRisk bool
	MinReviewers         int
	Enabled              bool
	CreatedAt            time.Time
	UpdatedAt            time.Time
}

Policy is an SLA / risk policy that governs approval requests.

func (*Policy) ToDTO 

func (p *Policy) ToDTO() map[string]any

ToDTO renders the policy in the wire format.

type RequestStatus 

type RequestStatus string

RequestStatus is the lifecycle state of an approval request. 

const (
	StatusPending      RequestStatus = "pending"
	StatusApproved     RequestStatus = "approved"
	StatusRejected     RequestStatus = "rejected"
	StatusCancelled    RequestStatus = "cancelled"
	StatusAutoApproved RequestStatus = "auto_approved"
	StatusAutoRejected RequestStatus = "auto_rejected"
)

func ParseRequestStatus 

func ParseRequestStatus(s string) (RequestStatus, error)

func (RequestStatus) Approved 

func (s RequestStatus) Approved() bool

func (RequestStatus) Decided 

func (s RequestStatus) Decided() bool

type RiskLevel 

type RiskLevel string

RiskLevel classifies how dangerous an action is. 

const (
	RiskLow      RiskLevel = "low"
	RiskMedium   RiskLevel = "medium"
	RiskHigh     RiskLevel = "high"
	RiskCritical RiskLevel = "critical"
)

func ParseRiskLevel 

func ParseRiskLevel(s string) (RiskLevel, error)

type TimeoutAction 

type TimeoutAction string

TimeoutAction is what the SLA engine does when a pending request times out. 

const (
	ActionAutoApprove TimeoutAction = "auto_approve"
	ActionAutoReject  TimeoutAction = "auto_reject"
	ActionEscalate    TimeoutAction = "escalate"
)

func ParseTimeoutAction 

func ParseTimeoutAction(s string) (TimeoutAction, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.