Metadata-Version: 2.4
Name: poseres
Version: 2.1.0
Summary: Pose Resolution Architecture — validation harness and batched in-memory core
Author: Daan Gerits
License: Copyright (c) 2026 Daan Gerits
        
        Portions of this software are licensed as follows:
        
        - All third party components incorporated into the software are licensed
          under the original license provided by the owner of the applicable
          component.
        - Content outside of the above mentioned restrictions is available under
          the "Sustainable Use License" as defined below.
        
        Versions of this software published under the MIT License before the
        adoption of these terms remain available under the MIT License; these
        terms apply to all later versions.
        
        
        Sustainable Use License
        
        Version 1.0
        
        Acceptance
        
        By using the software, you agree to all of the terms and conditions
        below.
        
        Copyright License
        
        The licensor grants you a non-exclusive, royalty-free, worldwide,
        non-sublicensable, non-transferable license to use, copy, distribute,
        make available, and prepare derivative works of the software, in each
        case subject to the limitations below.
        
        Limitations
        
        You may use or modify the software only for your own internal business
        purposes or for non-commercial or personal use. You may distribute the
        software or provide it to others only if you do so free of charge for
        non-commercial purposes. You may not alter, remove, or obscure any
        licensing, copyright, or other notices of the licensor in the software.
        Any use of the licensor's trademarks is subject to applicable law.
        
        Patents
        
        The licensor grants you a license, under any patent claims the licensor
        can license, or becomes able to license, to make, have made, use, sell,
        offer for sale, import and have imported the software, in each case
        subject to the limitations and conditions in this license. This license
        does not cover any patent claims that you cause to be infringed by
        modifications or additions to the software. If you or your company make
        any written claim that the software infringes or contributes to
        infringement of any patent, your patent license for the software granted
        under these terms ends immediately. If your company makes such a claim,
        your patent license ends immediately for work on behalf of your company.
        
        Notices
        
        You must ensure that anyone who gets a copy of any part of the software
        from you also gets a copy of these terms. If you modify the software,
        you must include in any modified copies of the software a prominent
        notice stating that you have modified the software.
        
        No Other Rights
        
        These terms do not imply any licenses other than those expressly granted
        in these terms.
        
        Termination
        
        If you use the software in violation of these terms, such use is not
        licensed, and your license will automatically terminate. If the licensor
        provides you with a notice of your violation, and you cease all
        violation of this license no later than 30 days after you receive that
        notice, your license will be reinstated retroactively. However, if you
        violate these terms after such reinstatement, any additional violation
        of these terms will cause your license to terminate automatically and
        permanently.
        
        No Liability
        
        As far as the law allows, the software comes as is, without any warranty
        or condition, and the licensor will not be liable to you for any damages
        arising out of these terms or the use or nature of the software, under
        any kind of legal claim.
        
        Definitions
        
        The "licensor" is the entity offering these terms.
        
        The "software" is the software the licensor makes available under these
        terms, including any portion of it.
        
        "You" refers to the individual or entity agreeing to these terms.
        
        "Your company" is any legal entity, sole proprietorship, or other kind
        of organization that you work for, plus all organizations that have
        control over, are under the control of, or are under common control with
        that organization. Control means ownership of substantially all the
        assets of an entity, or the power to direct its management and policies
        by vote, contract, or otherwise. Control can be direct or indirect.
        
        "Your license" is the license granted to you for the software under
        these terms.
        
        "Use" means anything you do with the software requiring your license.
        
        "Trademark" means trademarks, service marks, and similar rights.
        
Project-URL: Homepage, https://github.com/impire-io/poseres
Project-URL: Source, https://github.com/impire-io/poseres
Project-URL: Bug Tracker, https://github.com/impire-io/poseres/issues
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.4
Provides-Extra: gym
Requires-Dist: gymnasium>=1.0; extra == "gym"
Provides-Extra: nats
Requires-Dist: nats-py>=2.9; extra == "nats"
Provides-Extra: s3
Requires-Dist: boto3>=1.34; extra == "s3"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
Requires-Dist: gymnasium>=1.0; extra == "dev"
Dynamic: license-file

# PRA — Pose Resolution Architecture

An in-memory, batched, deterministic core (PRA-01) and the validation harness
(PRA-02) that runs the acceptance suite **T1–T6** plus the investigatory
**T-SCALE**, emitting an honest, reproducible PASS/FAIL verdict per test.

New here? **[GETTING-STARTED.md](GETTING-STARTED.md)** walks you from install
to hooking up your own sensors/actuators and configuring the drive — or just
run `pra-rover` and watch a PRA brain learn a 2D rover world, live in your
browser (one command, zero extra dependencies, byte-reproducible).
**[hq/03-IMPLEMENTATION/roadmap.md](hq/03-IMPLEMENTATION/roadmap.md)** is where the project is going: an OSS
continuously-learning brain for hobbyists and makers.

See `specs/001-validation-harness/` for the spec, plan, and contracts, and
`hq/02-DESIGN/` for the architecture documents. The behavioral oracle is
`hq/02-DESIGN/validate/pra_sim_v4.py`.

## Quickstart

**Fastest — install from PyPI with [`uv`](https://docs.astral.sh/uv/):**

```bash
uvx --from poseres pra-validate suite
```

No Python version juggling, no venv to manage. `uv` fetches Python 3.13 automatically if you don't have it.

**From source:**

```bash
git clone https://github.com/impire-io/poseres.git
cd pra
python3.13 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[dev]"            # numpy + pytest + ruff

pra-validate suite                 # 8 seeds, true_dim=3, checkpoints 18/30/50
pra-validate suite --json out/report.json
pra-validate determinism --seed 1  # byte-identical re-run check
pra-validate scale --true-dims 20,35,50
pra-validate scan --true-dim 20 --hidden-sizes 12,32,64   # diagnostic dimension scan
pra-validate agency                # curious vs random (T7) + value-signal telemetry

ruff format --check . && ruff check . && pytest -q
```

Independent seeds run in parallel worker processes by default (`--workers`,
0 = one per seed up to the CPU count) — parallelism never changes results
(byte-identical to sequential; each run keeps its own seeded, single-threaded
pipeline). The full default suite runs in ~20s on a 14-core machine.

`suite` emits, for each of **T1–T6**, the measured aggregate (mean ± std), the
exact pass criterion, and PASS/FAIL. **T4** is shown as the full per-seed `best_dim`
spread at every horizon checkpoint and PASSes only if the within-one-of-true
majority holds at *every* checkpoint — it can never pass on a lucky single horizon.
**T5** PASSes only when the population genuinely self-limits (no seed strictly
growing over its final third), not merely because it hit a cap. A single-seed run is
labelled **FOR DEBUGGING ONLY**. Exit code is 0 even when a test FAILs (a FAIL is
data, not a CLI error) unless `--strict` is passed.

## Documentation

The docs site — getting started, the design documents 0001–0008, a
worlds gallery, and the public-API promise — lives at
**<https://impire-io.github.io/poseres/>**. It is built from this
repository by `.github/workflows/docs.yml`: the committed pages under
`docs/` plus build-time copies of `hq/02-DESIGN/*.md`,
[GETTING-STARTED.md](GETTING-STARTED.md), and the interactive
explainer — the repo holds exactly one copy of each document, and
`tests/unit/test_docs_site.py` guards every file the site references.

The PRA book — the long-form telling of why frozen brains fail and what
this architecture does about it — lives in its own repository,
[impire-io/poseres-book](https://github.com/impire-io/poseres-book), and
reads at **<https://impire.io/poseres-book/>**. Its chapters cite this
repo's `hq/` record; the book repo's `/sync-from-pra` skill keeps the
two in step.

## Public API & versioning

From v1.0 the public surface is a promise: everything listed in
[Doc 0008](hq/02-DESIGN/0008-public-api-versioning.md) — the world/body
seam, anatomy, drives, persistence, the run surface, the CLI tools, and
the versioned subject space — is stable for all of v1.x (patch = fixes,
minor = additive only, removals only at a major after a deprecation
grace). The list is machine-enforced by the surface guard in the test
gate; everything not listed is internal by default. See
[CHANGELOG.md](CHANGELOG.md).

## Governing principle — honest summary

Where a tidy report and a faithful one conflict, the faithful one wins (FR-008): a
failing test is shown as FAIL *with the numbers that explain it*; a test needing a
spread is never reported by its mean alone; a seed that errors is surfaced and the
aggregate flagged incomplete, never silently dropped; too few samples reads
"not available", never a fabricated number. Two runs of a seed produce
byte-identical telemetry (single seeded RNG, fixed draw order, single-threaded BLAS).

## Layout

```
src/pra/
  config.py            # every PRA-01 §8 parameter + validation
  world/               # EventSource seam + SensorimotorWorld + the complexity-ladder worlds
  core/                # contracts, bus, scorer, policies, the batched FrameGroup kernel, engine
  motivation/          # Drive seam: curiosity (learning progress + novelty), competence, weighted set
  action/              # Policy seam: pinned random baseline + one-step curiosity lookahead
  persistence/         # snapshot/restore: versioned blob + atomic SnapshotStore (opt-in)
  anatomy/             # body: sensors/actuators, composition, tools + the Gymnasium and ROS2 adapters
  examples/rover/      # the pra-rover demo: 2D rover body + stdlib live viewer
  telemetry/recorder.py# deterministic per-seed summary
  harness/             # acceptance (T1-T7/T-SCALE), runner, report, cli, scale, scan, agency, ladder
examples/              # worked examples (CartPole via Gymnasium; a Gazebo rover via ROS2, in Docker)
tests/                 # unit (incl. batched-vs-reference proof) / contract (5 seams) / integration
```

## Behavioral oracle

`hq/02-DESIGN/validate/pra_sim_v4.py` is the validated reference run. The batched core
reproduces its T1–T6 trajectory at the default config (the per-frame-vs-batched
equivalence is enforced by `tests/unit/test_batched_equivalence.py`) at roughly 40×
the speed. The full default suite (8 seeds × predictive + ablation × 50 cycles)
completes in well under a minute.

## Contributing

New worlds, sensors, actuators, and drives are the on-ramp — the public seams
they mount through are frozen for all of v1.x ([Doc 0008](hq/02-DESIGN/0008-public-api-versioning.md)).
[CONTRIBUTING.md](CONTRIBUTING.md) has the seams, the worked examples, the gate, and the rules.

## License

[Fair-code](https://faircode.io), under the [Sustainable Use License](LICENSE) —
free to use, modify, and self-host for internal or non-commercial use; offering
it to others as a paid product or service requires an agreement — see
[impire.io/license](https://impire.io/license/). Versions up to and including
v1.1.0 remain MIT.
