praval.hitl.models

HITL domain models.

Classes

InterventionDecision(*values)

Human decisions supported for a blocked tool call.

InterventionPolicy([enabled, ...])

Simple policy controls for approval gating.

InterventionRequest(id, run_id, agent_name, ...)

Persistent representation of a pending/decided intervention.

InterventionStatus(*values)

Lifecycle status for a human intervention request.

SuspendedRunState(run_id, agent_name, ...[, ...])

Durable continuation state for interrupted runs.
class praval.hitl.models.InterventionStatus(*values)[source]

Bases: Enum

Lifecycle status for a human intervention request.

PENDING = 'PENDING'
APPROVED = 'APPROVED'
REJECTED = 'REJECTED'
EXPIRED = 'EXPIRED'
CANCELLED = 'CANCELLED'
class praval.hitl.models.InterventionDecision(*values)[source]

Bases: Enum

Human decisions supported for a blocked tool call.

APPROVE = 'APPROVE'
EDIT = 'EDIT'
REJECT = 'REJECT'
class praval.hitl.models.InterventionPolicy(enabled=False, default_requires_approval=False)[source]

Bases: object

Simple policy controls for approval gating.

Parameters:

  • enabled (bool)

  • default_requires_approval (bool)

enabled: bool = False
default_requires_approval: bool = False
__init__(enabled=False, default_requires_approval=False)
Parameters:

  • enabled (bool)

  • default_requires_approval (bool)

Return type:

None

class praval.hitl.models.InterventionRequest(id, run_id, agent_name, provider_name, tool_name, tool_call_id, status, decision=None, reason='', reviewer='', original_args=<factory>, edited_args=None, risk_level='low', approval_reason='', requested_at=<factory>, decided_at=None, expires_at=None, trace_id=None, metadata=<factory>)[source]

Bases: object

Persistent representation of a pending/decided intervention.

Parameters:

  • id (str)

  • run_id (str)

  • agent_name (str)

  • provider_name (str)

  • tool_name (str)

  • tool_call_id (str)

  • status (InterventionStatus)

  • decision (InterventionDecision | None)

  • reason (str)

  • reviewer (str)

  • original_args (Dict[str, Any])

  • edited_args (Dict[str, Any] | None)

  • risk_level (str)

  • approval_reason (str)

  • requested_at (datetime)

  • decided_at (datetime | None)

  • expires_at (datetime | None)

  • trace_id (str | None)

  • metadata (Dict[str, Any])

id: str
run_id: str
agent_name: str
provider_name: str
tool_name: str
tool_call_id: str
status: InterventionStatus
decision: InterventionDecision | None = None
reason: str = ''
reviewer: str = ''
original_args: Dict[str, Any]
edited_args: Dict[str, Any] | None = None
risk_level: str = 'low'
approval_reason: str = ''
requested_at: datetime
decided_at: datetime | None = None
expires_at: datetime | None = None
trace_id: str | None = None
metadata: Dict[str, Any]
to_dict()[source]

Convert intervention request to a JSON-safe dictionary.

Return type:

Dict[str, Any]

__init__(id, run_id, agent_name, provider_name, tool_name, tool_call_id, status, decision=None, reason='', reviewer='', original_args=<factory>, edited_args=None, risk_level='low', approval_reason='', requested_at=<factory>, decided_at=None, expires_at=None, trace_id=None, metadata=<factory>)
Parameters:

  • id (str)

  • run_id (str)

  • agent_name (str)

  • provider_name (str)

  • tool_name (str)

  • tool_call_id (str)

  • status (InterventionStatus)

  • decision (InterventionDecision | None)

  • reason (str)

  • reviewer (str)

  • original_args (Dict[str, Any])

  • edited_args (Dict[str, Any] | None)

  • risk_level (str)

  • approval_reason (str)

  • requested_at (datetime)

  • decided_at (datetime | None)

  • expires_at (datetime | None)

  • trace_id (str | None)

  • metadata (Dict[str, Any])

Return type:

None

class praval.hitl.models.SuspendedRunState(run_id, agent_name, provider_name, status, state, created_at=<factory>, updated_at=<factory>)[source]

Bases: object

Durable continuation state for interrupted runs.

Parameters:

  • run_id (str)

  • agent_name (str)

  • provider_name (str)

  • status (str)

  • state (Dict[str, Any])

  • created_at (datetime)

  • updated_at (datetime)

run_id: str
agent_name: str
provider_name: str
status: str
state: Dict[str, Any]
created_at: datetime
updated_at: datetime
to_dict()[source]

Convert suspended run state to a JSON-safe dictionary.

Return type:

Dict[str, Any]

__init__(run_id, agent_name, provider_name, status, state, created_at=<factory>, updated_at=<factory>)
Parameters:

  • run_id (str)

  • agent_name (str)

  • provider_name (str)

  • status (str)

  • state (Dict[str, Any])

  • created_at (datetime)

  • updated_at (datetime)

Return type:

None