Constants & Exceptions

Every SDK exception subclasses HGatewayError, so a single except HGatewayError is a safe catch-all if you don't need to branch on cause.

Constants

hgateway_sdk.HitlType

Bases: str, Enum

Top-level category of a HITL interrupt raised to the gateway.

Every interrupt must declare a HitlType. The gateway uses this value to determine which responder workflow to invoke and what UI chrome to render. Pair each HitlType with its corresponding HitlSubType inner enum to fully specify the interaction.

Members

APPROVAL ("approval") The agent is requesting a human to approve or reject an action or artifact. Sub-types: HitlSubType.Approval. DECISION ("decision") The agent presents a set of options and needs the human to choose. Sub-types: HitlSubType.Decision. CONTEXT ("context") The agent needs additional information or clarification from the human before it can proceed. Sub-types: HitlSubType.Context. EDIT ("edit") The agent has produced content or tool arguments that the human should review and possibly revise before the agent continues. Sub-types: HitlSubType.Edit.

hgateway_sdk.HitlSubType

Namespace of enums that refine each top-level HitlType.

Each inner class corresponds to one HitlType value and enumerates the concrete interaction variants the gateway can route for that type. Because each inner class is a str enum, its members serialise directly to their wire string (e.g. HitlSubType.Approval.BINARY → "binary").

Usage example::

from hgateway_sdk.constants import HitlType, HitlSubType

raise_interrupt(
    hitl_type=HitlType.APPROVAL,
    hitl_sub_type=HitlSubType.Approval.BINARY,
    ...
)

Inner enums

Approval Sub-types for HitlType.APPROVAL interrupts.

- ``BINARY`` (``"binary"``) — simple approve / reject decision; the
  gateway presents two buttons and returns one of the two choices.
- ``MODIFY`` (``"modify"``) — approve with optional edits; the responder
  can change the proposed content before approving.

Decision Sub-types for HitlType.DECISION interrupts.

- ``SINGLE`` (``"single"``) — responder picks exactly one option from a
  list.
- ``MULTI`` (``"multi"``) — responder picks one or more options.
- ``RANK`` (``"rank"``) — responder orders the options by preference.

Context Sub-types for HitlType.CONTEXT interrupts (information gathering).

- ``FREETEXT`` (``"freetext"``) — open text box; no schema enforced.
- ``FORM`` (``"form"``) — structured form whose fields are typed via
  ``FieldType``; response is a key→value map.
- ``CONFIRM`` (``"confirm"``) — responder simply acknowledges that they
  have read the provided information (no data returned).

Edit Sub-types for HitlType.EDIT interrupts (content revision).

- ``CONTENT`` (``"content"``) — responder edits a freeform text block
  such as a draft message or document.
- ``TOOL_ARGS`` (``"tool_args"``) — responder edits structured
  arguments destined for a tool call before execution proceeds.

hgateway_sdk.FieldType

Bases: str, Enum

Wire-level data type for a single form field within a HITL interrupt.

Used when building a HitlSubType.Context.FORM interrupt to declare the expected input type for each field rendered in the responder's UI. The string value is embedded directly in the JSON payload sent to the gateway.

Members

STRING Free-form text input ("string"). NUMBER Numeric input — integer or float ("number"). BOOLEAN Boolean toggle / checkbox ("boolean"). DATE ISO-8601 date picker input ("date"). DROPDOWN Single-select dropdown ("dropdown"). The field's value is a list/array of the selectable options rather than a scalar.

hgateway_sdk.OnExpiry

Bases: str, Enum

Governs gateway behaviour when a HITL interrupt's response deadline passes.

Set this on a RunFeatures object to tell the gateway what to do if the assigned responder does not reply within the configured timeout window. The string value is embedded in the wire payload under the "features" key.

Members

DEFAULT_RESPONSE ("default-response") The gateway resolves the interrupt automatically using a pre-configured default answer (e.g. auto-approve or auto-reject) so the graph can continue without human input. FORWARD_TO_SECONDARY ("forward-to-secondary-responder") The gateway escalates the interrupt to a secondary responder queue instead of auto-resolving it. Use this when a missed deadline should trigger a human escalation path rather than a silent fallback.

Exceptions

hgateway_sdk.HGatewayError

Bases: Exception

Base class for every exception this SDK raises.

Catching HGatewayError is sufficient to handle any error that originates from hgateway_sdk, regardless of the specific failure mode (configuration, network, or misuse).

The SDK's concrete exceptions also subclass standard library roots (ValueError, RuntimeError, …) so that isinstance checks against those roots continue to work as expected.

hgateway_sdk.FeatureValidationError

Bases: HGatewayError, ValueError

Raised when a RunFeatures object is misconfigured.

This is a construction-time error: the SDK validates feature combinations eagerly so that the developer receives a clear traceback at the call site (e.g. inside raise_interrupt) rather than a cryptic rejection from the gateway later.

Common triggers

• A required field for a given HitlType / HitlSubType combination is missing or has the wrong Python type.
• Mutually exclusive features are both enabled.
• An enum value from a different category is used (e.g. an OnExpiry value passed where a FieldType is expected).

What to do

Read the exception message — it names the offending field and the expected constraint. Fix the RunFeatures keyword arguments and retry.

hgateway_sdk.GatewayBootstrapError

Bases: HGatewayError, RuntimeError

Raised when a required gateway configuration value cannot be resolved.

The SDK reads its configuration from environment variables (optionally supplemented by a .env file). If any mandatory variable is absent from both sources when the SDK is first used, it raises this exception instead of silently operating with a broken configuration.

Mandatory environment variables

• HGATEWAY_AGENT_API_KEY — API key used to authenticate with the gateway.

The gateway's base URL and register endpoint are fixed (not configurable via environment variables), so they can never be the cause of this error.

What to do

Set the missing variable(s) listed in the exception message in your process environment or in a .env file that is loaded before the SDK is imported.

hgateway_sdk.GatewayUnreachable

Bases: HGatewayError

Raised when the SDK cannot reach the hgateway HTTP endpoint.

This exception is raised (and then internally caught) when the outbound HTTP POST to the gateway register/interrupt endpoint fails — for example due to a network partition, DNS failure, TLS error, or the gateway service being down.

Recovery behaviour

The SDK does not propagate this exception to the caller by default. Instead it falls back to raising a standard LangGraph NodeInterrupt so that the graph still pauses for human review, just without the gateway routing the task to a responder. Developers who want to observe or suppress the fallback behaviour can catch this exception in a custom on_gateway_unreachable hook if the SDK exposes one.

What to do

• Check that the gateway service (https://api.theved.ai) is reachable from the agent host — the gateway's URL and register endpoint are fixed and not something to reconfigure.
• Inspect the exception's __cause__ for the underlying network error.

hgateway_sdk.HitlNodeRequired

Bases: HGatewayError, RuntimeError

Raised when raise_interrupt is invoked outside an @hitl_node node.

The @hitl_node decorator injects a RuntimeContext into the execution frame. That context carries the LangGraph thread ID, run ID, current state snapshot, and interrupt occurrence counter — all of which the SDK needs to build the wire payload sent to the gateway.

If raise_interrupt is called from a plain LangGraph node (one that is not decorated with @hitl_node), the SDK cannot derive any of that information and raises this error immediately, before any network call is attempted.

What to do

Decorate the node function that calls raise_interrupt with @hitl_node::

from hgateway_sdk import hitl_node, raise_interrupt

@hitl_node
def my_node(state, config):
    raise_interrupt(...)

hgateway_sdk.TtlForwardNeedsSecondary

Bases: CrossFeatureRule

Emitted by Ttl, constrains Routing: forwarding on expiry needs somewhere to forward to.

hgateway_sdk.Ack dataclass

Ack(accepted: bool, hitl_instance_id: Optional[str] = None, status: Optional[str] = None, raw: Optional[dict] = None)

Acknowledgement returned by the HITL gateway after registering an interrupt.

The SDK surfaces this internally to confirm that the gateway accepted the interrupt spec. Developers rarely interact with Ack directly; it is checked by the client before the LangGraph interrupt() is raised.

Attributes: accepted: True when the gateway successfully registered the interrupt. False indicates the gateway rejected the payload. hitl_instance_id: Opaque identifier assigned by the gateway for this interrupt occurrence, used for deduplication on retry. None if the gateway did not return one (e.g., on rejection). status: Lifecycle status string from the gateway success body (e.g. "raised"). None when the gateway did not return one (rejection or an older gateway). raw: The full raw JSON response body from the gateway as a plain dict, preserved for debugging or future gateway protocol fields. On a rejection this holds the structured error body (code/message/request_id/details).