Content Schemas¶

The 4 HitlType families (Approval, Decision, Context, Edit) and their concrete {SubType}{Family}Content classes, plus the element types nested inside them (Choice, Option, etc.). See the Integration Guide for one worked example per family.

hgateway_sdk.HitlContent `dataclass` ¶

HitlContent(prompt: str)

Bases: Generic[TResp], ABC

Abstract base for all HITL interrupt content objects.

Parameterised by TResp — the TypedDict that describes the operator's reply for the concrete subclass. Developers never instantiate this class directly; use one of the 10 concrete subclasses.

Attributes: prompt: Human-readable question or instruction displayed to the operator above the interaction widget (e.g. "Please approve the following outbound message."). type: Class-level constant (HitlType) set by each family base class (ApprovalContent, DecisionContent, etc.). Written to the wire payload automatically — do not set manually. sub_type: Class-level constant (HitlSubType.*) set by each concrete leaf class. Narrows type to the specific interaction variant. Written to the wire payload automatically — do not set manually.

hgateway_sdk.ApprovalContent `dataclass` ¶

ApprovalContent(prompt: str)

Bases: HitlContent[TResp]

Base for Approval-family interrupts (type = HitlType.APPROVAL).

Approval interrupts ask an operator to accept or reject something the agent has produced or is about to do. The two concrete variants differ in whether the operator can also make edits:

BinaryApprovalContent — approve/reject only (no editing).
ModifyApprovalContent — approve/reject and optionally modify fields.

Attributes: type: Always HitlType.APPROVAL; set at the class level, not per instance.

hgateway_sdk.BinaryApprovalContent `dataclass` ¶

BinaryApprovalContent(prompt: str, choices: list[Choice] = (lambda: [Choice(constants.APPROVE_KEY, constants.APPROVE_LABEL), Choice(constants.REJECT_KEY, constants.REJECT_LABEL)])())

Bases: ApprovalContent[BinaryApprovalResponse]

Approval interrupt that asks the operator to approve or reject an action.

The operator is shown a prompt and two buttons (by default Approve and Reject). The gateway returns a BinaryApprovalResponse whose decision key contains the key string of the chosen Choice.

Usage example::

import hgateway_sdk as hg

content = hg.BinaryApprovalContent(
    prompt="Approve sending this email to the customer?",
    choices=[
        hg.Choice("approve", "Send it"),
        hg.Choice("reject", "Cancel", irreversible=False),
    ],
)
hg.raise_interrupt("send_email_approval", content)
# Operator response shape: BinaryApprovalResponse
# {"decision": "approve"}  or  {"decision": "reject"}

If choices is omitted the SDK defaults to a standard Approve / Reject pair (keys "approve" / "reject").

Attributes: prompt: Human-readable question shown to the operator. choices: Ordered list of Choice objects the operator can select. Defaults to [Choice("approve", "Approve"), Choice("reject", "Reject")]. sub_type: Always HitlSubType.Approval.BINARY; class-level constant.

hgateway_sdk.ModifyApprovalContent `dataclass` ¶

ModifyApprovalContent(prompt: str, choices: list[Choice] = list(), modifiable: list[ModifiableField] = list())

Bases: ApprovalContent[ModifyApprovalResponse]

Approval interrupt that lets the operator edit fields before approving.

Similar to BinaryApprovalContent but also surfaces a set of ModifiableField values the operator can change before they submit their decision. The gateway returns a ModifyApprovalResponse with the chosen decision key and a values dict of any edited fields.

Usage example::

import hgateway_sdk as hg

content = hg.ModifyApprovalContent(
    prompt="Review and approve the refund amount.",
    choices=[
        hg.Choice("approve", "Approve"),
        hg.Choice("reject", "Reject"),
    ],
    modifiable=[
        hg.ModifiableField("amount", "Refund Amount", 50.00, hg.FieldType.NUMBER),
    ],
)
hg.raise_interrupt("refund_approval", content)
# Operator response shape: ModifyApprovalResponse
# {"decision": "approve", "values": {"amount": 45.00}}
# values key is NotRequired — absent when the operator made no edits.

Attributes: prompt: Human-readable question shown to the operator. choices: List of Choice objects for the approval decision buttons. Defaults to an empty list; populate at least one choice. modifiable: List of ModifiableField objects the operator may edit. Defaults to an empty list (no editable fields). sub_type: Always HitlSubType.Approval.MODIFY; class-level constant.

hgateway_sdk.DecisionContent `dataclass` ¶

DecisionContent(prompt: str)

Bases: HitlContent[TResp]

Base for Decision-family interrupts (type = HitlType.DECISION).

Decision interrupts present the operator with a list of Option objects and ask them to choose. The three concrete variants differ in how many items can be selected and in what form the result is returned:

SingleDecisionContent — pick exactly one option.
MultiDecisionContent — pick one-to-many options with optional bounds.
RankDecisionContent — order all options by preference.

Attributes: type: Always HitlType.DECISION; set at the class level, not per instance.

hgateway_sdk.SingleDecisionContent `dataclass` ¶

SingleDecisionContent(prompt: str, options: list[Option] = list())

Bases: DecisionContent[SingleDecisionResponse]

Decision interrupt that asks the operator to choose exactly one option.

The operator is shown a prompt and a list of Option objects. They must select exactly one. The gateway returns a SingleDecisionResponse whose selected key is the key of the chosen option.

Usage example::

import hgateway_sdk as hg

content = hg.SingleDecisionContent(
    prompt="Which deployment environment should we target?",
    options=[
        hg.Option("staging", "Staging", description="Safe sandbox"),
        hg.Option("prod", "Production", impact_hint="Irreversible"),
    ],
)
hg.raise_interrupt("deploy_env_decision", content)
# Operator response shape: SingleDecisionResponse
# {"selected": "staging"}

Attributes: prompt: Human-readable question shown to the operator. options: Ordered list of Option objects to present. Defaults to an empty list; populate at least two options. sub_type: Always HitlSubType.Decision.SINGLE; class-level constant.

hgateway_sdk.MultiDecisionContent `dataclass` ¶

MultiDecisionContent(prompt: str, options: list[Option] = list(), min_select: int = 1, max_select: int | None = None)

Bases: DecisionContent[MultiDecisionResponse]

Decision interrupt that asks the operator to choose one or more options.

Like SingleDecisionContent but the operator may select multiple items. The selection is bounded by min_select (inclusive lower bound) and max_select (inclusive upper bound; None means no upper limit). The gateway returns a MultiDecisionResponse whose selected key is a list of the chosen option keys.

Usage example::

import hgateway_sdk as hg

content = hg.MultiDecisionContent(
    prompt="Select the teams to notify about this incident.",
    options=[
        hg.Option("infra", "Infrastructure"),
        hg.Option("backend", "Backend"),
        hg.Option("frontend", "Frontend"),
    ],
    min_select=1,
    max_select=2,
)
hg.raise_interrupt("notify_teams", content)
# Operator response shape: MultiDecisionResponse
# {"selected": ["infra", "backend"]}

Attributes: prompt: Human-readable question shown to the operator. options: Ordered list of Option objects to present. Defaults to an empty list. min_select: Minimum number of options the operator must select. Defaults to 1. max_select: Maximum number of options the operator may select. None means unlimited. Defaults to None. sub_type: Always HitlSubType.Decision.MULTI; class-level constant.

hgateway_sdk.RankDecisionContent `dataclass` ¶

RankDecisionContent(prompt: str, options: list[Option] = list())

Bases: DecisionContent[RankDecisionResponse]

Decision interrupt that asks the operator to rank all options.

All options are presented and the operator must order them from most to least preferred. The gateway returns a RankDecisionResponse whose ranking key is an ordered list of all option keys, highest preference first.

Usage example::

import hgateway_sdk as hg

content = hg.RankDecisionContent(
    prompt="Rank these outreach channels by priority.",
    options=[
        hg.Option("email", "Email"),
        hg.Option("sms", "SMS"),
        hg.Option("push", "Push Notification"),
    ],
)
hg.raise_interrupt("channel_rank", content)
# Operator response shape: RankDecisionResponse
# {"ranking": ["push", "email", "sms"]}

Attributes: prompt: Human-readable question shown to the operator. options: Ordered list of Option objects to rank. Defaults to an empty list; populate at least two options. sub_type: Always HitlSubType.Decision.RANK; class-level constant.

hgateway_sdk.ContextContent `dataclass` ¶

ContextContent(prompt: str)

Bases: HitlContent[TResp]

Base for Context-family interrupts (type = HitlType.CONTEXT).

Context interrupts ask the operator to provide information that the agent needs before it can continue. The three concrete variants differ in the structure of the expected input:

FreetextContextContent — open-ended text answer.
FormContextContent — structured multi-field form.
ConfirmContextContent — simple acknowledgement (read and confirm).

Attributes: type: Always HitlType.CONTEXT; set at the class level, not per instance.

hgateway_sdk.FreetextContextContent `dataclass` ¶

FreetextContextContent(prompt: str, input: FreetextInput = None)

Bases: ContextContent[FreetextContextResponse]

Context interrupt that collects a free-form text response from the operator.

The operator sees a prompt and a single text-area input described by the FreetextInput element. The gateway returns a FreetextContextResponse whose value key holds the typed text.

Usage example::

import hgateway_sdk as hg

content = hg.FreetextContextContent(
    prompt="What is the customer's preferred resolution?",
    input=hg.FreetextInput(
        label="Customer preference",
        placeholder="Describe in a few sentences…",
    ),
)
hg.raise_interrupt("customer_pref", content)
# Operator response shape: FreetextContextResponse
# {"value": "The customer prefers a full refund."}

Attributes: prompt: Human-readable question shown to the operator. input: A FreetextInput describing the text-area label and optional placeholder hint. Must be provided (no useful default). sub_type: Always HitlSubType.Context.FREETEXT; class-level constant.

hgateway_sdk.FormContextContent `dataclass` ¶

FormContextContent(prompt: str, fields: list[FormField] = list())

Bases: ContextContent[FormContextResponse]

Context interrupt that collects structured data via a multi-field form.

Each FormField in fields becomes one input row in the gateway UI with its own label, type, and optional placeholder. The gateway returns a FormContextResponse whose values key is a dict mapping each field key to the value the operator entered.

Usage example::

import hgateway_sdk as hg
from hgateway_sdk.constants import FieldType

content = hg.FormContextContent(
    prompt="Provide the ticket details before we escalate.",
    fields=[
        hg.FormField("ticket_id", "Ticket ID", FieldType.STRING, required=True),
        hg.FormField("priority", "Priority (1-5)", FieldType.NUMBER),
        hg.FormField("is_urgent", "Mark as urgent?", FieldType.BOOLEAN),
    ],
)
hg.raise_interrupt("ticket_details", content)
# Operator response shape: FormContextResponse
# {"values": {"ticket_id": "TKT-123", "priority": 2, "is_urgent": True}}

Attributes: prompt: Human-readable instruction shown above the form. fields: Ordered list of FormField elements defining the form rows. Defaults to an empty list; populate at least one field. sub_type: Always HitlSubType.Context.FORM; class-level constant.

hgateway_sdk.ConfirmContextContent `dataclass` ¶

ConfirmContextContent(prompt: str, statement: str = '')

Bases: ContextContent[ConfirmContextResponse]

Context interrupt that asks the operator to acknowledge a statement.

Useful when the agent needs to ensure a human has read a notice, warning, or policy disclosure before the workflow continues. No data is collected beyond the acknowledgement itself. The gateway returns a ConfirmContextResponse whose confirmed key is True when the operator clicks "Confirm".

Usage example::

import hgateway_sdk as hg

content = hg.ConfirmContextContent(
    prompt="Please confirm you have read the data-retention policy.",
    statement=(
        "By confirming, you acknowledge that all customer PII will be "
        "deleted after 90 days as required by our data policy."
    ),
)
hg.raise_interrupt("policy_ack", content)
# Operator response shape: ConfirmContextResponse
# {"confirmed": True}

Attributes: prompt: Human-readable instruction shown to the operator (e.g. "Please read and confirm the following."). statement: The body text the operator must read before confirming. Defaults to an empty string. sub_type: Always HitlSubType.Context.CONFIRM; class-level constant.

hgateway_sdk.EditContent `dataclass` ¶

EditContent(prompt: str)

Bases: HitlContent[TResp]

Base for Edit-family interrupts (type = HitlType.EDIT).

Edit interrupts surface agent-generated content or planned tool arguments for the operator to inspect and optionally revise before execution proceeds. The two concrete variants differ in what is being edited:

ContentEditContent — a free-form text draft (e.g. an email body).
ToolArgsEditContent — structured arguments for a pending tool call.

Attributes: type: Always HitlType.EDIT; set at the class level, not per instance.

hgateway_sdk.ContentEditContent `dataclass` ¶

ContentEditContent(prompt: str, draft: str = '')

Bases: EditContent[ContentEditResponse]

Edit interrupt that surfaces a free-form text draft for the operator to revise.

The operator sees the draft text in an editable text area together with the prompt. They may change it freely or leave it as-is and submit. The gateway returns a ContentEditResponse whose content key holds the (possibly edited) text.

Usage example::

import hgateway_sdk as hg

content = hg.ContentEditContent(
    prompt="Review the generated email and edit if needed before sending.",
    draft=(
        "Hi Jane,\n\n"
        "We're following up on your recent support request…\n\n"
        "Best, Support Team"
    ),
)
hg.raise_interrupt("email_draft_review", content)
# Operator response shape: ContentEditResponse
# {"content": "Hi Jane,\n\nThank you for reaching out…\n\nBest, Support Team"}

Attributes: prompt: Instruction shown to the operator above the editable text area. draft: Initial text the operator sees and may edit. Defaults to an empty string. sub_type: Always HitlSubType.Edit.CONTENT; class-level constant.

hgateway_sdk.ToolArgsEditContent `dataclass` ¶

ToolArgsEditContent(prompt: str, tool_name: str = '', args: list[ToolArg] = list())

Bases: EditContent[ToolArgsEditResponse]

Edit interrupt that exposes a tool call's arguments for operator review.

Before the agent invokes a tool, the operator can inspect each ToolArg and change the value of any editable arguments. Non-editable args are shown read-only. The gateway returns a ToolArgsEditResponse whose args key is a dict mapping each arg key to its (possibly updated) value.

Usage example::

import hgateway_sdk as hg
from hgateway_sdk.constants import FieldType

content = hg.ToolArgsEditContent(
    prompt="Review the SQL query arguments before execution.",
    tool_name="run_sql",
    args=[
        hg.ToolArg("table", "Target Table", "orders", FieldType.STRING, editable=False),
        hg.ToolArg("limit", "Row Limit", 1000, FieldType.NUMBER, editable=True),
    ],
)
hg.raise_interrupt("sql_args_review", content)
# Operator response shape: ToolArgsEditResponse
# {"args": {"table": "orders", "limit": 500}}

Attributes: prompt: Instruction shown to the operator above the argument list. tool_name: Name of the tool that will be called. Displayed as context. Defaults to an empty string. args: List of ToolArg elements representing each argument. Defaults to an empty list; populate at least one arg. sub_type: Always HitlSubType.Edit.TOOL_ARGS; class-level constant.

hgateway_sdk.Choice `dataclass` ¶

Choice(key: str, label: str, irreversible: bool = False, impact_hint: Optional[str] = None)

A labelled button option presented to the operator in an Approval interrupt.

Used inside BinaryApprovalContent.choices and ModifyApprovalContent.choices to define the available decision buttons.

Usage example (nested inside content)::

import hgateway_sdk as hg

hg.BinaryApprovalContent(
    prompt="Approve the refund?",
    choices=[
        hg.Choice("approve", "Approve Refund"),
        hg.Choice("reject", "Reject", irreversible=False, impact_hint="No refund issued"),
    ],
)

Attributes: key: Machine-readable identifier returned in the response decision field when this choice is selected. label: Human-readable button label displayed to the operator. irreversible: When True, the gateway UI may add a confirmation step before accepting this choice, signalling the action cannot be undone. Defaults to False. impact_hint: Optional short text displayed alongside the button to give the operator a risk or consequence hint (e.g. "Permanent deletion"). Defaults to None.

hgateway_sdk.Option `dataclass` ¶

Option(key: str, label: str, description: Optional[str] = None, irreversible: bool = False, impact_hint: Optional[str] = None)

A labelled selectable item presented to the operator in a Decision interrupt.

Used inside SingleDecisionContent.options, MultiDecisionContent.options, and RankDecisionContent.options to enumerate the choices the operator can select or rank.

Usage example (nested inside content)::

import hgateway_sdk as hg

hg.SingleDecisionContent(
    prompt="Which deployment environment?",
    options=[
        hg.Option("staging", "Staging", description="Low-risk test environment"),
        hg.Option("prod", "Production", irreversible=True, impact_hint="Affects live users"),
    ],
)

Attributes: key: Machine-readable identifier returned in the response selected / ranking field when this option is chosen. label: Human-readable option label displayed to the operator. description: Optional longer text providing context about this option. Displayed below the label in the gateway UI. Defaults to None. irreversible: When True, the gateway UI may add a confirmation step before accepting this option, signalling the action cannot be undone. Defaults to False. impact_hint: Optional short text warning the operator of consequences (e.g. "Irreversible"). Defaults to None.

hgateway_sdk.FreetextInput `dataclass` ¶

FreetextInput(label: str, placeholder: Optional[str] = None)

Descriptor for the single open-text input in a FreetextContextContent.

Defines the label and optional placeholder shown to the operator inside the text-area widget. There is exactly one FreetextInput per FreetextContextContent.

Usage example (nested inside content)::

import hgateway_sdk as hg

hg.FreetextContextContent(
    prompt="Describe the customer's preferred outcome.",
    input=hg.FreetextInput(
        label="Customer preference",
        placeholder="Summarise in 1-3 sentences…",
    ),
)

Attributes: label: Human-readable label rendered above the text area. placeholder: Optional greyed-out hint text shown inside an empty text area. Defaults to None.

hgateway_sdk.FormField `dataclass` ¶

FormField(key: str, label: str, type: FieldType, required: bool = False, placeholder: Optional[str] = None)

A single typed input row inside a FormContextContent interrupt.

Each FormField maps to one labelled input widget in the gateway UI. The type attribute controls what kind of widget is rendered and what value type is returned in FormContextResponse.values.

Usage example (nested inside content)::

import hgateway_sdk as hg
from hgateway_sdk.constants import FieldType

hg.FormContextContent(
    prompt="Provide escalation details.",
    fields=[
        hg.FormField("ticket_id", "Ticket ID", FieldType.STRING, required=True,
                     placeholder="e.g. TKT-001"),
        hg.FormField("priority", "Priority (1-5)", FieldType.NUMBER),
        hg.FormField("urgent", "Mark urgent?", FieldType.BOOLEAN),
    ],
)

Attributes: key: Machine-readable field identifier. Used as the key in FormContextResponse.values. label: Human-readable field label shown next to the input. type: FieldType enum value controlling the input widget type (STRING, NUMBER, BOOLEAN, or DATE). required: When True the gateway enforces that the operator fills in this field before submitting. Defaults to False. placeholder: Optional hint text shown inside an empty input (e.g. "Enter your name"). Defaults to None.

hgateway_sdk.ModifiableField `dataclass` ¶

ModifiableField(key: str, label: str, value: Any, type: FieldType)

A named, typed value the operator can change as part of a modify-approval.

Used inside ModifyApprovalContent.modifiable to expose fields that the operator may adjust before they submit their approval decision. All fields in this list are always editable; use ToolArg with editable=False if you need read-only display.

Usage example (nested inside content)::

import hgateway_sdk as hg
from hgateway_sdk.constants import FieldType

hg.ModifyApprovalContent(
    prompt="Review and approve the refund.",
    choices=[hg.Choice("approve", "Approve"), hg.Choice("reject", "Reject")],
    modifiable=[
        hg.ModifiableField("amount", "Refund Amount (USD)", 75.00, FieldType.NUMBER),
        hg.ModifiableField("note", "Internal Note", "", FieldType.STRING),
        hg.ModifiableField(
            "reason", "Reason", ["duplicate", "fraud", "other"], FieldType.DROPDOWN
        ),
    ],
)

Attributes: key: Machine-readable field identifier. Used as the key in ModifyApprovalResponse.values when the operator edits this field. label: Human-readable label shown next to the input widget. value: Current (pre-populated) value shown to the operator. Can be any JSON-serialisable type consistent with type. For FieldType.DROPDOWN this is a list/array of the selectable options (the operator picks one); the selected option is returned in ModifyApprovalResponse.values. type: FieldType enum value controlling the input widget type (STRING, NUMBER, BOOLEAN, DATE, or DROPDOWN).

hgateway_sdk.ToolArg `dataclass` ¶

ToolArg(key: str, label: str, value: Any, type: FieldType, editable: bool = True)

A single named argument in a pending tool call, surfaced for operator review.

Used inside ToolArgsEditContent.args to expose each argument of a planned tool call. Arguments with editable=True can be changed by the operator; arguments with editable=False are shown read-only as context.

Usage example (nested inside content)::

import hgateway_sdk as hg
from hgateway_sdk.constants import FieldType

hg.ToolArgsEditContent(
    prompt="Review SQL arguments before execution.",
    tool_name="run_sql",
    args=[
        hg.ToolArg("table", "Target Table", "orders", FieldType.STRING, editable=False),
        hg.ToolArg("limit", "Row Limit", 1000, FieldType.NUMBER, editable=True),
        hg.ToolArg("dry_run", "Dry Run?", False, FieldType.BOOLEAN, editable=True),
    ],
)

Attributes: key: Machine-readable argument name. Used as the key in ToolArgsEditResponse.args. label: Human-readable argument label shown in the gateway UI. value: Pre-populated current value of the argument. Can be any JSON-serialisable type consistent with type. type: FieldType enum value controlling how the value is rendered and validated (STRING, NUMBER, BOOLEAN, or DATE). editable: When True (default) the operator can change this value. When False the argument is shown read-only as context.

Content Schemas¶

hgateway_sdk.HitlContent dataclass ¶

hgateway_sdk.ApprovalContent dataclass ¶

hgateway_sdk.BinaryApprovalContent dataclass ¶

hgateway_sdk.ModifyApprovalContent dataclass ¶

hgateway_sdk.DecisionContent dataclass ¶

hgateway_sdk.SingleDecisionContent dataclass ¶

hgateway_sdk.MultiDecisionContent dataclass ¶

hgateway_sdk.RankDecisionContent dataclass ¶

hgateway_sdk.ContextContent dataclass ¶

hgateway_sdk.FreetextContextContent dataclass ¶

hgateway_sdk.FormContextContent dataclass ¶

hgateway_sdk.ConfirmContextContent dataclass ¶

hgateway_sdk.EditContent dataclass ¶

hgateway_sdk.ContentEditContent dataclass ¶

hgateway_sdk.ToolArgsEditContent dataclass ¶

hgateway_sdk.Choice dataclass ¶

hgateway_sdk.Option dataclass ¶

hgateway_sdk.FreetextInput dataclass ¶

hgateway_sdk.FormField dataclass ¶

hgateway_sdk.ModifiableField dataclass ¶

hgateway_sdk.ToolArg dataclass ¶

hgateway_sdk.HitlContent `dataclass` ¶

hgateway_sdk.ApprovalContent `dataclass` ¶

hgateway_sdk.BinaryApprovalContent `dataclass` ¶

hgateway_sdk.ModifyApprovalContent `dataclass` ¶

hgateway_sdk.DecisionContent `dataclass` ¶

hgateway_sdk.SingleDecisionContent `dataclass` ¶

hgateway_sdk.MultiDecisionContent `dataclass` ¶

hgateway_sdk.RankDecisionContent `dataclass` ¶

hgateway_sdk.ContextContent `dataclass` ¶

hgateway_sdk.FreetextContextContent `dataclass` ¶

hgateway_sdk.FormContextContent `dataclass` ¶

hgateway_sdk.ConfirmContextContent `dataclass` ¶

hgateway_sdk.EditContent `dataclass` ¶

hgateway_sdk.ContentEditContent `dataclass` ¶

hgateway_sdk.ToolArgsEditContent `dataclass` ¶

hgateway_sdk.Choice `dataclass` ¶

hgateway_sdk.Option `dataclass` ¶

hgateway_sdk.FreetextInput `dataclass` ¶

hgateway_sdk.FormField `dataclass` ¶

hgateway_sdk.ModifiableField `dataclass` ¶

hgateway_sdk.ToolArg `dataclass` ¶