cpomdp-workshop 0.1.0__tar.gz

cpomdp_workshop-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.ipynb_checkpoints/
+
+.claude/
+artifacts/

cpomdp_workshop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DanBoringName
+
+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.

cpomdp_workshop-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: cpomdp-workshop
+Version: 0.1.0
+Summary: Build a curious rocket — the AII 2026 symposium workshop for cpomdp.
+Project-URL: Repository, https://github.com/inferogenesis/cpomdp-workshop
+Author: Inferogenesis
+License-Expression: MIT
+License-File: LICENSE
+Keywords: active-inference,cpomdp,teaching,workshop
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: cpomdp==0.5.0
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: nbclient>=0.10; extra == 'dev'
+Requires-Dist: nbformat>=5.10; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Requires-Dist: ty>=0.0.1a1; extra == 'dev'
+Provides-Extra: nb
+Requires-Dist: ipykernel>=6.29; extra == 'nb'
+Requires-Dist: jupyter>=1.1; extra == 'nb'
+Description-Content-Type: text/markdown
+
+# Build a curious rocket
+
+A two-hour hands-on workshop on [cpomdp](https://github.com/inferogenesis/cpomdp),
+continuous active inference in Python, for the 6th Applied Active Inference Symposium.
+You build three rockets. The first is the 1960 controller, a Kalman filter with a goal,
+and the library reports that no move can teach it more than another. The second reads its
+position through a sensor that depends on where it is, and bends its path toward a
+beacon. In the third, three rockets fly past a rock none of them was told about.
+
+## Open it
+
+The live session runs on Colab. There is nothing to install. A browser and a Google
+account are enough. Edits vanish when the tab closes unless you save a copy to Drive.
+
+[Open the notebook in Colab](https://colab.research.google.com/github/inferogenesis/cpomdp-workshop/blob/main/notebooks/build_a_curious_rocket.ipynb)
+
+Please write the lines yourself rather than asking a generative AI tool for them. The
+point of the session is the two lines you work out. The hints and the reference cells
+are there for when you are stuck. Using them is fine.
+
+## Run it locally
+
+With [uv](https://docs.astral.sh/uv/):
+
+```sh
+git clone https://github.com/inferogenesis/cpomdp-workshop
+cd cpomdp-workshop
+uv sync --extra nb
+uv run jupyter lab notebooks/build_a_curious_rocket.ipynb
+```
+
+Python 3.11 or newer. The workshop pins the cpomdp release it was measured on, and the
+first cell stops if a different one is installed.
+
+Do not name a file in the folder you run from after a standard-library module, such as
+`types.py`, `dis.py` or `random.py`. Python imports yours instead. The error that
+follows points nowhere near the cause.
+
+## What is in the repo
+
+| Path | What it holds |
+| --- | --- |
+| `src/cpomdp_workshop/` | The package the notebook imports: the world, the two rockets, the flight loop, the checks, the figures |
+| `notebooks/` | The notebook, generated and run by `scripts/build_notebook.py`. Never edited by hand |
+| `scripts/lesson.py` | What the notebook says, cell by cell |
+| `delivery/hints_chat.txt` | The hint lines pasted into chat. The notebook's hint and reference cells are built from it |
+| `assets/` | Figures, regenerated from the package by `scripts/render_assets.py` |
+| `tests/test_measured_claims.py` | One test per number the notebook or the deck shows |
+| `tests/test_api_contract.py` | The cpomdp forms the workshop is written against |
+
+## Working on it
+
+Every command runs from the repo root.
+
+```sh
+uv sync --extra dev --extra nb
+uv run --no-sync pytest -q -m "not slow"     # fast tests
+uv run --no-sync pytest -q                   # everything, the notebook run included
+uv run --no-sync pre-commit run --all-files  # the gate CI runs
+uv run --no-sync python scripts/build_notebook.py
+uv run --no-sync python scripts/render_assets.py
+```
+
+A change to the lesson, the hints or the package means rebuilding the notebook. A stale
+notebook fails a test.
+
+## Releasing
+
+The notebook's first cell installs the exact version it was built from, so bump
+`version` in `pyproject.toml`, rebuild the notebook and merge. Then publish a GitHub
+release tagged `v` plus that version. `.github/workflows/publish.yml` runs the tests,
+installs the wheel into a clean environment and uploads to PyPI through Trusted
+Publishing.
+
+## Licence
+
+MIT. See `LICENSE`.

cpomdp_workshop-0.1.0/README.md

@@ -0,0 +1,77 @@
+# Build a curious rocket
+
+A two-hour hands-on workshop on [cpomdp](https://github.com/inferogenesis/cpomdp),
+continuous active inference in Python, for the 6th Applied Active Inference Symposium.
+You build three rockets. The first is the 1960 controller, a Kalman filter with a goal,
+and the library reports that no move can teach it more than another. The second reads its
+position through a sensor that depends on where it is, and bends its path toward a
+beacon. In the third, three rockets fly past a rock none of them was told about.
+
+## Open it
+
+The live session runs on Colab. There is nothing to install. A browser and a Google
+account are enough. Edits vanish when the tab closes unless you save a copy to Drive.
+
+[Open the notebook in Colab](https://colab.research.google.com/github/inferogenesis/cpomdp-workshop/blob/main/notebooks/build_a_curious_rocket.ipynb)
+
+Please write the lines yourself rather than asking a generative AI tool for them. The
+point of the session is the two lines you work out. The hints and the reference cells
+are there for when you are stuck. Using them is fine.
+
+## Run it locally
+
+With [uv](https://docs.astral.sh/uv/):
+
+```sh
+git clone https://github.com/inferogenesis/cpomdp-workshop
+cd cpomdp-workshop
+uv sync --extra nb
+uv run jupyter lab notebooks/build_a_curious_rocket.ipynb
+```
+
+Python 3.11 or newer. The workshop pins the cpomdp release it was measured on, and the
+first cell stops if a different one is installed.
+
+Do not name a file in the folder you run from after a standard-library module, such as
+`types.py`, `dis.py` or `random.py`. Python imports yours instead. The error that
+follows points nowhere near the cause.
+
+## What is in the repo
+
+| Path | What it holds |
+| --- | --- |
+| `src/cpomdp_workshop/` | The package the notebook imports: the world, the two rockets, the flight loop, the checks, the figures |
+| `notebooks/` | The notebook, generated and run by `scripts/build_notebook.py`. Never edited by hand |
+| `scripts/lesson.py` | What the notebook says, cell by cell |
+| `delivery/hints_chat.txt` | The hint lines pasted into chat. The notebook's hint and reference cells are built from it |
+| `assets/` | Figures, regenerated from the package by `scripts/render_assets.py` |
+| `tests/test_measured_claims.py` | One test per number the notebook or the deck shows |
+| `tests/test_api_contract.py` | The cpomdp forms the workshop is written against |
+
+## Working on it
+
+Every command runs from the repo root.
+
+```sh
+uv sync --extra dev --extra nb
+uv run --no-sync pytest -q -m "not slow"     # fast tests
+uv run --no-sync pytest -q                   # everything, the notebook run included
+uv run --no-sync pre-commit run --all-files  # the gate CI runs
+uv run --no-sync python scripts/build_notebook.py
+uv run --no-sync python scripts/render_assets.py
+```
+
+A change to the lesson, the hints or the package means rebuilding the notebook. A stale
+notebook fails a test.
+
+## Releasing
+
+The notebook's first cell installs the exact version it was built from, so bump
+`version` in `pyproject.toml`, rebuild the notebook and merge. Then publish a GitHub
+release tagged `v` plus that version. `.github/workflows/publish.yml` runs the tests,
+installs the wheel into a clean environment and uploads to PyPI through Trusted
+Publishing.
+
+## Licence
+
+MIT. See `LICENSE`.

cpomdp_workshop-0.1.0/delivery/hints_chat.txt

@@ -0,0 +1,69 @@
+Pasted into the chat on the timer. The notebook's hint and reference cells are built
+from this file, so what is pasted and what is in the notebook never differ. A hint is
+one line of code that replaces the line of the same name in the attempt cell. A nudge
+is the step before its hint, pasted first. In the notebook it shows under the hint's
+title, with the hint's line behind Show code.
+
+[session 1, nudge 1]
+`observation_matrix` describes how the rocket's position (x, y) turns into a sensor reading (x, y).
+Here the reading is simply the position itself, so this is the identity matrix.
+In JAX, you can create an n-by-n identity matrix with `jnp.eye(n)`.
+We need n = 2: one dimension for x and one for y.
+
+[session 1, hint 1]
+observation_matrix = jnp.eye(2)
+
+[session 1, nudge 2]
+`observation_noise` (R) describes how far each reading tends to stray from the true position.
+It's a covariance matrix: the variance for each axis sits on the diagonal, with zeros everywhere else.
+In this task, the variance is 0.05 on both axes.
+Multiplying a matrix by a number scales every entry, so `v * jnp.eye(n)` puts v along the diagonal.
+
+[session 1, hint 2]
+observation_noise = 0.05 * jnp.eye(2)
+
+[session 1, reference]
+Reference for task 1: the collapsed cell under hint 2. Run it, then the checkpoint.
+
+[session 2, nudge 1]
+`pull` is the extra noise the beacon adds at position x.
+It's k multiplied by `distance_squared`, with the squared distance capped first so it never goes above the cap.
+`jnp.minimum(a, b)` returns whichever of a and b is smaller, which is a handy way to cap a at b.
+You'll find k in `params["beacon_gain"]` and the cap in `params["beacon_cap"]`.
+
+[session 2, hint 1]
+pull = params["beacon_gain"] * jnp.minimum(distance_squared, params["beacon_cap"])
+
+[session 2, nudge 2]
+`k` controls how quickly the reading gets noisier as the rocket moves away from the beacon.
+With a small k, the path stays nearly straight.
+With a large k, staying near the beacon becomes more appealing than reaching the pad, and the rocket stops short.
+Try raising k from 0.08 in steps of about 0.1 and watch how high the path climbs.
+
+[session 2, hint 2]
+beacon_gain = 0.4
+
+[session 2, reference]
+Reference for task 2: the collapsed cell under hint 2. Run it, then the checkpoint.
+
+[session 3, nudge 1]
+`blindness` is the extra noise the blackout adds at position x.
+It's strongest at the centre of the blackout and fades with distance, in a bell shape.
+`jnp.exp(-d / w)` equals 1 when d is 0 and falls towards 0 as d grows, more slowly when w is larger.
+Here, d is `from_blackout`, w is `width`, and `height` sets how strong the peak is.
+
+[session 3, hint 1]
+blindness = height * jnp.exp(-from_blackout / width)
+
+[session 3, nudge 2]
+A backend is the engine that updates the rocket's belief after each reading.
+`KalmanBackend(model)` is the classic Kalman filter.
+cpomdp's other engine passes messages on a graph, the form it uses for models made of several linked parts.
+`one_node` rewrites a model as a graph with just one node, so the same rocket can run on that engine.
+Use `model`, the 1960 rocket's model from Task 1, which the checkpoint has restored for you.
+
+[session 3, hint 2]
+backend = one_node(model)
+
+[session 3, reference]
+Reference for task 3: the collapsed cell under hint 2. Run it, then the checkpoint.