HumanReview Config

Consolidate all human-in-the-loop settings into a single config object.

HumanReview groups all HITL settings into a single object instead of passing them as separate parameters. All workflow primitives accept human_review=HumanReview(...): Step, Loop, Router, Condition, Steps, and Parallel.

1from kern.workflow.step import Step
2from kern.workflow.types import HumanReview
3from kern.workflow import OnReject
4
5Step(
6    name="draft_email",
7    agent=draft_agent,
8    human_review=HumanReview(
9        requires_output_review=True,
10        output_review_message="Review the draft before sending.",
11        on_reject=OnReject.retry,
12        max_retries=3,
13        timeout=300,
14        on_timeout=OnTimeout.approve,
15    ),
16)

Flat parameters still work for backward compatibility:

1# Equivalent to the above
2Step(
3    name="draft_email",
4    agent=draft_agent,
5    requires_output_review=True,
6    output_review_message="Review the draft before sending.",
7    on_reject=OnReject.retry,
8    hitl_max_retries=3,
9    hitl_timeout=300,
10    on_timeout=OnTimeout.approve,
11)

If both human_review and flat parameters are provided, human_review takes priority.

All Fields

Field	Type	Default	Description
`requires_confirmation`	`bool`	`False`	Pause for user confirmation before execution
`confirmation_message`	`str`	`None`	Message shown during confirmation
`requires_user_input`	`bool`	`False`	Pause to collect user input before execution
`user_input_message`	`str`	`None`	Message shown when collecting input
`user_input_schema`	`List[UserInputField]`	`None`	Schema defining expected input fields
`requires_output_review`	`bool`	`False`	Pause after execution for output review
`output_review_message`	`str`	`None`	Message shown during output review
`requires_iteration_review`	`bool`	`False`	Pause after each loop iteration for review
`iteration_review_message`	`str`	`None`	Message shown during iteration review
`on_reject`	`OnReject`	`OnReject.skip`	Action when user rejects
`on_error`	`OnError`	`None`	Action when step errors
`max_retries`	`int`	`3`	Max retries on rejection (when `on_reject=OnReject.retry`)
`timeout`	`int`	`None`	Seconds to wait for user response
`on_timeout`	`OnTimeout`	`None`	Action when timeout expires

Supported Fields by Component

Not every field works on every component. Passing an unsupported field raises a ValueError at construction time.

Field	Step	Loop	Router	Condition	Steps	Parallel
`requires_confirmation`	✓	✓	✓	✓	✓	✓
`requires_user_input`	✓	-	✓	-	-	-
`requires_output_review`	✓	-	✓	-	-	-
`requires_iteration_review`	-	✓	-	-	-	-
`on_reject`	✓	✓	✓	✓	✓	✓
`on_error`	✓	-	-	-	-	-
`max_retries`	✓	✓	✓	✓	✓	✓
`timeout`	✓	✓	✓	✓	✓	✓
`on_timeout`	✓	✓	✓	✓	✓	✓

Condition, Steps, and Parallel only support requires_confirmation. Passing unsupported fields raises a clear error:

1from kern.workflow.condition import Condition
2from kern.workflow.types import HumanReview
3
4# This raises ValueError: requires_output_review is not supported on Condition.
5# Supported: requires_confirmation.
6Condition(
7    name="my_condition",
8    steps=[...],
9    human_review=HumanReview(requires_output_review=True),
10)

Validation Rules

requires_output_review and requires_iteration_review cannot both be True in the same config.
Each component validates at construction time. You get a clear error if a field is unsupported.

HITL Modes

Pre-execution: Confirmation

Pause before a step runs. The user approves or rejects.

1HumanReview(
2    requires_confirmation=True,
3    confirmation_message="Delete 1000 records?",
4    on_reject=OnReject.cancel,
5)

Pre-execution: User Input

Collect parameters from the user before execution.

1from kern.workflow.types import HumanReview, UserInputField
2
3HumanReview(
4    requires_user_input=True,
5    user_input_message="Configure report settings:",
6    user_input_schema=[
7        UserInputField(name="format", field_type="str", required=True),
8        UserInputField(name="include_charts", field_type="bool", required=False),
9    ],
10)

Post-execution: Output Review

Pause after a step completes so the user can review the output. Supported on Step and Router.

1HumanReview(
2    requires_output_review=True,
3    output_review_message="Review the generated report.",
4    on_reject=OnReject.retry,
5    max_retries=3,
6)

Per-iteration: Iteration Review

Pause after each loop iteration for review. Supported on Loop only.

1HumanReview(
2    requires_iteration_review=True,
3    iteration_review_message="Review this iteration's output.",
4    on_reject=OnReject.retry,
5)

Timeout

Set a timeout for how long to wait for a user response. If the timeout expires, on_timeout determines what happens.

1from kern.workflow import OnTimeout
2
3HumanReview(
4    requires_confirmation=True,
5    confirmation_message="Approve deployment?",
6    timeout=300,  # 5 minutes
7    on_timeout=OnTimeout.approve,  # Auto-approve after timeout
8)

`OnTimeout` Value	Behavior
`OnTimeout.approve`	Automatically approve and continue
`OnTimeout.reject`	Automatically reject
`OnTimeout.cancel`	Cancel the workflow

Serialization

HumanReview serializes to a single "human_review" key in the workflow state. Deserialization reads "human_review" first, then falls back to flat keys for backward compatibility with existing persisted data.

1config = HumanReview(
2    requires_confirmation=True,
3    confirmation_message="Proceed?",
4    timeout=60,
5)
6
7data = config.to_dict()
8# {"requires_confirmation": True, "confirmation_message": "Proceed?", "timeout": 60, ...}
9
10restored = HumanReview.from_dict(data)