Metadata-Version: 2.5
Name: oro-env-runtime
Version: 3.0.3
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`.
- `validate_epoch(epoch_dir)`: fails closed unless the pack's file set, checksums, manifest
  contracts and task schemas are valid.
- `build_delivery_subset_archive(...)`: builds deterministic qualifying or race delivery bytes
  from a parent pack. `validate_delivery_binding(...)` checks those bytes against the scope and
  roster they were authorized for.
- `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` |

The event and replay contract versions are exported from `oro_env_runtime.contracts`. These are
execution compatibility identities, separate from the package version.

## 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.
