Metadata-Version: 2.5
Name: oro-env-runtime
Version: 0.2.0
Summary: Portable sealed-pack runtime and verifier for Oro environments
Project-URL: Homepage, https://oroagents.com
Author: ORO AI
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: iso4217>=1.12
Requires-Dist: openai>=1.50
Requires-Dist: pydantic>=2.7
Requires-Dist: rank-bm25>=0.2.2
Description-Content-Type: text/markdown

# oro-env-runtime

Portable sealed-pack execution and verification for ORO environments.

The package owns the public runtime contract used by environment generators and validators:

- sealed-pack schemas, versions, integrity checks, and portable validation;
- catalog and local-search loading;
- `TaskSession`, environment execution, replay, and user simulation;
- deterministic verification, rewards, and runtime family behavior.

It deliberately excludes private catalogs and task packs, seed search, task-family generation,
catalog profiling, compiler orchestration, model configuration, and deterministic recompilation.

Requires Python 3.11 or newer and is distributed under the MIT License.

## Policy boundary and state visibility

`TaskSession.policy_view()` returns the task query, local tool schemas, and contract versions.
`TaskSession.step()` and `step_parallel()` return only `observation`, `done`, and `error`. The
complete immutable ledger stays inside the session for replay and verification.

State has these visibility classes:

- Public: the goal, budget, frozen catalog facts, cart, tool schemas, policy errors, and terminal
  status.
- Private: `gold_set`, `acceptance`, admission evidence, verifier checks and rewards, the complete
  ledger, verifier signals, and true-state hashes.
- Conditionally revealed: the market-event kind and delta. The environment applies the event to
  the first product that the cart accepts. The solver already supplied this product. The
  environment reveals the event only in the response to that successful `add_to_cart` call.

Before and after the trigger, a change to a private field must not change any policy-visible value
when public state, seed, and actions are equal. The event target comes from the public action, not
from acceptance, gold, admission, or verifier state. Acceptance, gold, admission, verifier, ledger,
and true-state hash data stay private. A task without an event has no conditionally revealed state.
The sealed-pack validator records its event noninterference check as `not_applicable`.

For an event task, the first successful add is also the family-owned public commitment used by the
reward contract. Exploratory adds remain valid environment actions, but an add before the intended
commitment makes the event construct unsuccessful.

## Shopper interaction protocol (`oro_task_tools_v2`)

The `message` tool is the only pull mechanism. It may be called once or alongside other tools in an
ordered solver turn. After the group finishes, a non-terminal session returns at most one simulator
reply in `user_message`; the reply is also appended to the authoritative ledger as a `user_message`
entry. A group containing multiple `message` calls still produces one reply to the complete turn.

The harness may push one unsolicited reply after a visible market event. It deliberately waits for
one unaided solver turn after the event fires, then returns the reply in that turn's `user_message`
field if the session remains active and the task is not state-blind. It does not push for arbitrary
policy actions. A terminal action during the unaided turn ends the episode without simulator rescue.

Every call response includes `user_message`, either a `{content}` object or `null`. An adapter MUST
append non-null content to policy context before the next solver turn and MUST NOT infer a message
from `null`. Calls are strictly ordered by positive turn number. Retrying an identical call with the
same idempotency key replays the cached response without another simulator call or ledger entry;
reusing a call ID or idempotency key for different input, or sending an out-of-order turn, is an
error. Replies are synchronous: there is no late-message channel.

The simulator has dialogue authority only. It cannot mutate commerce state or assign reward.
Provider timeout, unavailability, or invalid output is an environment failure and quarantines the
session; it is never classified as miner failure. Episode evidence records each delivered message
and the simulator model, prompt, configuration, normalized response, latency, and sanitized failure
type. Credentials, provider exception detail, hidden task fields, verifier state, and reward remain
private.

## Releasing

Bump `project.version` in this package's `pyproject.toml` as part of a reviewed pull request.
When that change reaches `main`, GitHub Actions creates the matching `runtime-vMAJOR.MINOR.PATCH`
tag and dispatches the protected publish workflow at that tag. The publish workflow reruns the
generator tests and lint, builds and audits the public wheel, verifies it in a clean Python 3.11
environment, and publishes it to PyPI through Trusted Publishing.

PyPI releases are immutable. Fix a bad release with a new version rather than reusing a tag or
overwriting an existing artifact.
