Metadata-Version: 2.5
Name: touchstone-us
Version: 0.1.11
Summary: Reviewed, deterministic regression tests for RL environments and graders, run on your own infrastructure and gated in CI.
Project-URL: Homepage, https://www.touchstone-us.com
Project-URL: Documentation, https://www.touchstone-us.com/docs
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: cryptography>=46
Requires-Dist: fastapi>=0.162.0
Requires-Dist: uvicorn>=0.54.0
Provides-Extra: modal
Requires-Dist: modal>=1.6.3; extra == 'modal'
Description-Content-Type: text/markdown

# TouchStone

Reviewed regression tests for reinforcement learning environments and graders.

TouchStone turns the requirements of an RL environment into deterministic tests
that run on your own infrastructure. Candidate tests are proposed from a Harbor
task, a template, your own JSON, or a model; a person reviews each one and
approves the exact content; only approved tests can fail CI. When the grader or
environment changes, the same approved tests run again, so a reward loophole you
fixed stays fixed.

## Install

```sh
uv tool install touchstone-us
```

Linux or WSL with Python 3.12 or newer. A container engine is needed only for
Harbor tasks and the legacy grader audits.

## Connect a grader in one command

```sh
# A Harbor task directory: controls and probes are drafted for you
touchstone init ./suite --from-harbor ./tasks/my-task

# A grader behind an HTTP endpoint
touchstone init ./suite --requirement "Reward requires a paid order" \
  --http http://grader:8080/evaluate

# A grader that runs as a command
touchstone init ./suite --requirement "Reward requires a paid order" \
  --command "python grade.py"
```

Then try, review and gate:

```sh
touchstone check ./suite --experimental      # see what each candidate observes
touchstone review ./suite CASE --decision approve --reviewer "Name"
touchstone check ./suite                      # exit 0 pass, 2 fail, 3 inconclusive
```

Assertions are declarative (`eq`, `ne`, `lte`, `gte`, `contains`,
`not_contains`) over the observations your adapter returns. There is no `eval`,
no model in the verdict, and a missing observation can never pass.

## What a pass means

The approved tests met their assertions on that adapter, at that content hash,
for that run. It does not prove an environment is safe or detect every reward
hack. Generated candidates are hypotheses until a person approves them.

Documentation: https://www.touchstone-us.com/docs

TouchStone is proprietary software; see the LICENSE file in the distribution.
