poseres 0.1.0__tar.gz

poseres-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daan Gerits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

poseres-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: poseres
+Version: 0.1.0
+Summary: Pose Resolution Architecture — validation harness and batched in-memory core
+Author: Daan Gerits
+License: MIT
+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
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; 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.
+
+See `specs/001-validation-harness/` for the spec, plan, and contracts, and
+`design/` for the architecture documents. The behavioral oracle is
+`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.
+
+## 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/event_source.py# EventSource seam + SensorimotorWorld (nonlinear, hidden latent)
+  core/                # contracts, bus, scorer, policies, the batched FrameGroup kernel, engine
+  motivation/          # Drive seam: curiosity (learning progress + novelty), weighted drive set
+  action/              # Policy seam: pinned random baseline + one-step curiosity lookahead
+  persistence/         # snapshot/restore: versioned blob + atomic SnapshotStore (opt-in)
+  anatomy/             # body: sensors/actuators, fixed-order composition, runtime tools
+  telemetry/recorder.py# deterministic per-seed summary
+  harness/             # acceptance (T1-T7/T-SCALE), runner, report, cli, scale, scan, agency
+tests/                 # unit (incl. batched-vs-reference proof) / contract (5 seams) / integration
+```
+
+## Behavioral oracle
+
+`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.

poseres-0.1.0/README.md

@@ -0,0 +1,85 @@
+# 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.
+
+See `specs/001-validation-harness/` for the spec, plan, and contracts, and
+`design/` for the architecture documents. The behavioral oracle is
+`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.
+
+## 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/event_source.py# EventSource seam + SensorimotorWorld (nonlinear, hidden latent)
+  core/                # contracts, bus, scorer, policies, the batched FrameGroup kernel, engine
+  motivation/          # Drive seam: curiosity (learning progress + novelty), weighted drive set
+  action/              # Policy seam: pinned random baseline + one-step curiosity lookahead
+  persistence/         # snapshot/restore: versioned blob + atomic SnapshotStore (opt-in)
+  anatomy/             # body: sensors/actuators, fixed-order composition, runtime tools
+  telemetry/recorder.py# deterministic per-seed summary
+  harness/             # acceptance (T1-T7/T-SCALE), runner, report, cli, scale, scan, agency
+tests/                 # unit (incl. batched-vs-reference proof) / contract (5 seams) / integration
+```
+
+## Behavioral oracle
+
+`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.

poseres-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "poseres"
+version = "0.1.0"
+description = "Pose Resolution Architecture — validation harness and batched in-memory core"
+readme = "README.md"
+requires-python = ">=3.13"
+license = { text = "MIT" }
+classifiers = ["License :: OSI Approved :: MIT License"]
+authors = [{ name = "Daan Gerits" }]
+dependencies = ["numpy>=2.4"]
+
+[project.urls]
+Homepage = "https://github.com/impire-io/poseres"
+Source = "https://github.com/impire-io/poseres"
+"Bug Tracker" = "https://github.com/impire-io/poseres/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[project.scripts]
+pra-validate = "pra.harness.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+extend-exclude = ["design", "archive", ".venv"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+filterwarnings = ["error"]

poseres-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

poseres-0.1.0/src/poseres.egg-info/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: poseres
+Version: 0.1.0
+Summary: Pose Resolution Architecture — validation harness and batched in-memory core
+Author: Daan Gerits
+License: MIT
+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
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; 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.
+
+See `specs/001-validation-harness/` for the spec, plan, and contracts, and
+`design/` for the architecture documents. The behavioral oracle is
+`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.
+
+## 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/event_source.py# EventSource seam + SensorimotorWorld (nonlinear, hidden latent)
+  core/                # contracts, bus, scorer, policies, the batched FrameGroup kernel, engine
+  motivation/          # Drive seam: curiosity (learning progress + novelty), weighted drive set
+  action/              # Policy seam: pinned random baseline + one-step curiosity lookahead
+  persistence/         # snapshot/restore: versioned blob + atomic SnapshotStore (opt-in)
+  anatomy/             # body: sensors/actuators, fixed-order composition, runtime tools
+  telemetry/recorder.py# deterministic per-seed summary
+  harness/             # acceptance (T1-T7/T-SCALE), runner, report, cli, scale, scan, agency
+tests/                 # unit (incl. batched-vs-reference proof) / contract (5 seams) / integration
+```
+
+## Behavioral oracle
+
+`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.

poseres-0.1.0/src/poseres.egg-info/SOURCES.txt

@@ -0,0 +1,40 @@
+LICENSE
+README.md
+pyproject.toml
+src/poseres.egg-info/PKG-INFO
+src/poseres.egg-info/SOURCES.txt
+src/poseres.egg-info/dependency_links.txt
+src/poseres.egg-info/entry_points.txt
+src/poseres.egg-info/requires.txt
+src/poseres.egg-info/top_level.txt
+src/pra/__init__.py
+src/pra/config.py
+src/pra/action/__init__.py
+src/pra/action/policy.py
+src/pra/anatomy/__init__.py
+src/pra/anatomy/body.py
+src/pra/core/__init__.py
+src/pra/core/bus.py
+src/pra/core/contracts.py
+src/pra/core/engine.py
+src/pra/core/frame.py
+src/pra/core/policies.py
+src/pra/core/scorer.py
+src/pra/harness/__init__.py
+src/pra/harness/acceptance.py
+src/pra/harness/agency.py
+src/pra/harness/cli.py
+src/pra/harness/report.py
+src/pra/harness/runner.py
+src/pra/harness/scale.py
+src/pra/harness/scan.py
+src/pra/motivation/__init__.py
+src/pra/motivation/context.py
+src/pra/motivation/drive.py
+src/pra/persistence/__init__.py
+src/pra/persistence/snapshot.py
+src/pra/persistence/store.py
+src/pra/telemetry/__init__.py
+src/pra/telemetry/recorder.py
+src/pra/world/__init__.py
+src/pra/world/event_source.py

poseres-0.1.0/src/poseres.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

poseres-0.1.0/src/poseres.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pra-validate = pra.harness.cli:main

poseres-0.1.0/src/poseres.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy>=2.4
+
+[dev]
+pytest>=8.0
+ruff>=0.6

poseres-0.1.0/src/poseres.egg-info/top_level.txt

@@ -0,0 +1 @@
+pra

poseres-0.1.0/src/pra/__init__.py

@@ -0,0 +1,26 @@
+"""Pose Resolution Architecture (PRA).
+
+A single in-memory, batched, deterministic core (PRA-01) plus the validation
+harness (PRA-02) that runs the acceptance suite T1-T6 and the investigatory
+T-SCALE.
+
+Determinism (FR-010, SC-007, PRA-01 §7.1) requires a fixed float-accumulation
+order. We pin every BLAS backend to a single thread *before* numpy is imported
+anywhere in the process, so reductions are byte-stable across runs on one
+machine. This module is imported before any ``pra`` submodule pulls in numpy.
+"""
+
+import os as _os
+
+# Pin BLAS threading before numpy is first imported (PRA-01 §7.1, research R3).
+for _var in (
+    "OMP_NUM_THREADS",
+    "OPENBLAS_NUM_THREADS",
+    "MKL_NUM_THREADS",
+    "VECLIB_MAXIMUM_THREADS",
+    "NUMEXPR_NUM_THREADS",
+):
+    _os.environ.setdefault(_var, "1")
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

poseres-0.1.0/src/pra/action/__init__.py

@@ -0,0 +1 @@
+"""Action component (design Doc 05 §4): policy seam -> action selection."""

poseres-0.1.0/src/pra/action/policy.py

@@ -0,0 +1,98 @@
+"""Policies: action selection (Doc 05 §4).
+
+The Policy seam replaces the engine's inline random action draw. The default
+``RandomPolicy`` reproduces that draw EXACTLY — one ``rng.integers(n_actions)``
+per step, nothing else — so every existing mode (the validated T1-T6 suite,
+determinism, scale, scan) consumes an identical RNG stream and stays
+byte-identical to the validated build (FR-008, research R1).
+
+``CuriosityLookaheadPolicy`` is the shipped directed default (Doc 05 §4.2/§4.3):
+ε-gate first; uniformly random when exploring, when no best frame exists, or
+when the best frame is younger than the maturity bar; otherwise a one-step
+lookahead — predict each candidate action's outcome with the best frame's
+transition model, decode it, value it via the drive set — choosing the argmax
+with ties broken by the lowest action index (no further draws). Policies are
+stateless across steps; all randomness comes from the run's single seeded
+generator in this fixed order (FR-007).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+from pra.config import Config
+
+__all__ = ["PolicyContext", "Policy", "RandomPolicy", "CuriosityLookaheadPolicy", "PolicyParams"]
+
+
+@dataclass(frozen=True)
+class PolicyContext:
+    """The read-only view a policy selects from (data-model §3)."""
+
+    observation: np.ndarray
+    n_actions: int
+    best_frame_age: int | None  # None when no frame exists
+    predict_decoded: Callable[[int], np.ndarray | None]  # best-frame one-step, decoded
+    drive_value_of: Callable[[np.ndarray], float]  # drive set valued at a hypothetical obs
+
+
+@runtime_checkable
+class Policy(Protocol):
+    def select_action(self, context: PolicyContext, rng: np.random.Generator) -> int: ...
+
+
+class RandomPolicy:
+    """The pinned validation baseline: exactly the validated engine's inline draw."""
+
+    def select_action(self, context: PolicyContext, rng: np.random.Generator) -> int:
+        return int(rng.integers(context.n_actions))
+
+
+@dataclass(frozen=True)
+class PolicyParams:
+    exploration_epsilon: float
+    lookahead_min_age_cycles: int
+
+    @classmethod
+    def from_config(cls, config: Config) -> PolicyParams:
+        return cls(
+            exploration_epsilon=config.exploration_epsilon,
+            lookahead_min_age_cycles=config.lookahead_min_age_cycles,
+        )
+
+
+class CuriosityLookaheadPolicy:
+    """One-step curiosity lookahead with ε-exploration and a cold-start gate."""
+
+    def __init__(self, params: PolicyParams):
+        self.params = params
+        self.last_was_directed = False  # telemetry only; overwritten every step
+
+    def select_action(self, context: PolicyContext, rng: np.random.Generator) -> int:
+        # Fixed draw order (research R3): one uniform for the ε-gate, then one
+        # integer draw only on the random path. Exploit draws nothing further.
+        explore = rng.random() < self.params.exploration_epsilon
+        immature = (
+            context.best_frame_age is None
+            or context.best_frame_age < self.params.lookahead_min_age_cycles
+        )
+        if explore or immature:
+            self.last_was_directed = False
+            return int(rng.integers(context.n_actions))
+
+        best_action = 0
+        best_value = -np.inf
+        for action in range(context.n_actions):  # ascending: lowest index wins ties
+            predicted = context.predict_decoded(action)
+            if predicted is None:
+                continue
+            value = context.drive_value_of(predicted)
+            if value > best_value:
+                best_value = value
+                best_action = action
+        self.last_was_directed = True
+        return best_action

poseres-0.1.0/src/pra/anatomy/__init__.py

@@ -0,0 +1 @@
+"""Anatomy component (design Doc 02): sensors, actuators, the composed body, tools."""