Python API

Policy sessions

The runtime supplies a policy-safe turn; the policy returns a proposal, no action, or a lifecycle request. A proposal does not itself mutate the environment.

from ora.agent.contracts import (
    PolicySession,
    PolicySessionCapabilities,
    PolicyTurnInput,
    PolicyRuntimeEvent,
    ActionProposal,
    NoAction,
    LifecycleRequest,
)

PolicySession

class PolicySession(Protocol)
Attribute Type Default Description
capabilities PolicySessionCapabilities

start

start() -> None

act

act(turn: PolicyTurnInput) -> PolicyOutcome

accept_runtime_event

accept_runtime_event(event: PolicyRuntimeEvent) -> None

interrupt

interrupt(reason: str = 'operator_interrupt') -> None

close

close() -> None

PolicySessionCapabilities

class PolicySessionCapabilities

Backend facts used for orchestration, never policy coaching.

Attribute Type Default Description
runtime_kind Literal['scripted', 'managed_coder', 'native']
context_owner Literal['none', 'managed', 'harness']
tool_transport Literal['in_process', 'mcp', 'direct']
request_visibility Literal['none', 'project_exact', 'wire_exact']
supports_images bool
supports_interrupt bool

PolicyTurnInput

class PolicyTurnInput

Immutable, privilege-clean input for one observation-scoped policy turn.

Attribute Type Default Description
task_id str
task_instruction str
context Mapping[str, Any]
image_path Path | None
observation_id str | None
observation_step int | None
budget Mapping[str, Any] field(default_factory=dict)
interaction_phase str 'observation_ready'
fresh_observation_required bool False
allow_reminder bool True
terminal_lifecycle bool False
task_sha256 str ''
image_paths tuple[Path, ...] ()

runtime_kwargs

runtime_kwargs() -> dict[str, Any]

Project the typed turn into the runtime-owned invocation shape.

turn_budget is the round budget left when this turn starts. The observation's context.remaining_budget was published with the observation and goes stale when the Supervisor asks again on the same observation, so a core caps its model calls by turn_budget.

PolicyRuntimeEvent

class PolicyRuntimeEvent

One trusted outer-loop fact delivered identically to every policy backend.

Attribute Type Default Description
kind Literal['fresh_observation', 'environment_receipt', 'action_discarded', 'official_verdict', 'run_termination', 'operator_message']
payload Mapping[str, Any]
observation_id str | None None
observation_step int | None None

mutable_payload

mutable_payload() -> dict[str, Any]

ActionProposal

class ActionProposal
Attribute Type Default Description
action Mapping[str, Any] | None
model_calls int
details Mapping[str, Any] field(default_factory=dict)
kind Literal['action'] 'action'

as_record

as_record() -> dict[str, Any]

NoAction

class NoAction
Attribute Type Default Description
reason str
model_calls int
details Mapping[str, Any] field(default_factory=dict)
kind Literal['no_action'] 'no_action'

as_record

as_record() -> dict[str, Any]

LifecycleRequest

class LifecycleRequest
Attribute Type Default Description
reason str
model_calls int
details Mapping[str, Any] field(default_factory=dict)
kind Literal['lifecycle'] 'lifecycle'

as_record

as_record() -> dict[str, Any]

Source: docs/api/policy.md