Metadata-Version: 2.5
Name: oro-env-runtime
Version: 3.4.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: httpx>=0.27
Requires-Dist: iso4217>=1.12
Requires-Dist: openai>=1.50
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# oro-env-runtime

Portable sealed-pack execution and verification for ORO environments.

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

```
pip install oro-env-runtime
```

## Public API

- `TaskSession(epoch_dir, task_id, ...)`: opens one task of a sealed pack. `policy_view()` returns
  the task query, tool schemas and contract versions; `step()` and `step_parallel()` run one
  ordered action group and return `observation`, `done` and `error` per call; `run()` runs the
  managed solver and shopper-simulator loop; `verdict()` returns the `VerifierResult`.
- `check_epoch(epoch_dir)`: the loading checks `TaskSession` runs on a pack it has not seen:
  file set and checksums, pack format, the delivery declaration and its runtime contract, and
  every task row. Returns the errors, empty when the pack loads.
- `validate_delivery_binding(...)`: checks delivered bytes against the scope and roster they were
  authorized for, and refuses a delivery whose `runtime_contract` is not this runtime's
  `RUNTIME_CONTRACT`.
- `replay_actions`, `make_replay_artifact`, `validate_replay_artifact`: deterministic replay of
  recorded action groups.
- `failure_classes(verdict, situation)`: see below.

Configured Readers require an explicit `reader_completion` run client; the runtime does
not choose a funding account. Validators bind the same miner-funded simulator client for
Reader, shopper and rewording requests. `TaskSession.run(reader_completion=...)` uses that
client for its shopper loop. Rewording uses Jev when the bound client supports `decide`,
with the LLM meaning-preservation judge as fallback. Without `decide`, that LLM judge
uses the same bound client. Reader policy and reference state are
pack data, outside this public package. The inference account owner and validator host
may inspect those requests; using a separate request does not make them confidential.

`step()` and `step_parallel()` do not deliver queued shopper lines, and an order is refused with
`line_pending` while one is unsaid. An adapter with its own turn boundary runs each turn in this
order, as `replay_actions` does: `session.env.begin_solver_turn(n)` for the coming turn (`n = session.solver_turn_count + 1`); then
`oro_env_runtime.loop.reword_utterances` and `say_utterances` to deliver the lines that boundary
fired; then `step_parallel(group)`; then `reword_utterances` and `say_utterances` again for lines
the group fired. Shopper replies are recorded with `oro_env_runtime.loop.record_user_message`.

A pack is a directory with exactly `manifest.json`, `checksums.sha256` and
`data/tasks/private_tasks.jsonl`. `TaskSession` caches each file digest while its
size and `mtime_ns` are unchanged, so consumers must mount each pack on a read-only or otherwise
immutable filesystem for the full execution lifetime.

## Contract versions

| Contract | Version |
| --- | --- |
| Pack format | `oro_compiled_epoch_v7` |
| Environment | `oro.env.v3` |
| Runtime | `0.3.4` |
| Result schema | `v2` |
| Delivery subset | `oro.delivery_subset.v1` |
| Runtime contract (`RUNTIME_CONTRACT`) | `3` |

The event and replay contract versions are exported from `oro_env_runtime.contracts`. These are
labels, separate from the package version. `RUNTIME_CONTRACT` is the one compatibility gate: every
delivery declares the contract it was built for and runs only on a runtime with the same one.

## Failure feedback

`failure_classes(verdict, situation)` returns `{"primary", "categories"}` for one episode.
`verdict` is the validator's episode result (`outcome` and the verifier result under `verdict`)
or a verifier result alone; `situation` is the episode task's own situation. `categories` follow
the order of `oro_env_runtime.failure.CATEGORIES` and `primary` is the first:
`did_not_finish` (no order placed, or the agent errored), `request_not_met`, `needs_not_found`,
`changes_missed`, `process_issue`, `not_best_option`, `extra_questions`. `infrastructure` (an
environment or verifier error, or a missing or ungradable verdict) is never the miner's failure
and is then the only entry.

## Releasing

Bump `project.version` in `pyproject.toml` in a reviewed pull request. Merging it to `main` tags
`runtime-vMAJOR.MINOR.PATCH` and publishes to PyPI. PyPI releases are immutable: fix a bad
release with a new version.
