Metadata-Version: 2.5
Name: oro-env-runtime
Version: 3.1.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.

`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` |
| Tools | `oro_task_tools_v6` |
| Verifier | `0.4.0` |
| Result schema | `v2` |
| Delivery subset | `oro.delivery_subset.v1` |
| Runtime contract (`RUNTIME_CONTRACT`) | `1` |

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.
