cpomdp 0.1.0__tar.gz

cpomdp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel superseded runs on the same ref to save CI minutes.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint + types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - run: uv sync --locked
+      # Cache the pre-commit hook environments, keyed on the config.
+      - uses: actions/cache@v5
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+      # Run the same hooks contributors run locally (ruff lint + format + file
+      # hygiene), so CI and pre-commit can never disagree. Fails if any hook would
+      # change a file. The commit-msg hook isn't run here (no commit to check).
+      - name: pre-commit
+        run: uv run pre-commit run --all-files --show-diff-on-failure
+      - name: ty (strict types)
+        run: uv run ty check
+
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      # The pure-Python suite: no Julia installed, so this also proves the
+      # rxinfer-marked tests deselect cleanly when the optional extra is absent.
+      - name: pytest + coverage gate
+        run: >-
+          uv run pytest -m "not rxinfer"
+          --cov=cpomdp --cov-report=term-missing --cov-fail-under=80
+
+  oracle:
+    name: rxinfer oracle (Julia)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - run: uv sync --locked --extra rxinfer
+      # juliacall provisions its own Julia + RxInfer (per juliapkg.json) on first
+      # import; cache the depot so only the first run pays the full download/build.
+      - name: Cache Julia depot
+        uses: actions/cache@v5
+        with:
+          path: ~/.julia
+          key: julia-depot-${{ runner.os }}-${{ hashFiles('src/cpomdp/juliapkg.json') }}
+          restore-keys: julia-depot-${{ runner.os }}-
+      - name: pytest (rxinfer only)
+        run: uv run pytest -m rxinfer

cpomdp-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Let the workflow publish to GitHub Pages. One-time repo setup:
+# Settings -> Pages -> Source = "GitHub Actions".
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Never run two Pages deploys at once.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - run: uv sync --locked --group docs
+      - run: uv run mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

cpomdp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - run: uv sync --locked
+      # Don't ship a red build.
+      - run: uv run pytest -m "not rxinfer"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cpomdp
+    permissions:
+      id-token: write # the OIDC token Trusted Publishing exchanges for an upload
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

cpomdp-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Julia / juliacall (RxInfer backend)
+.CondaPkg/
+*.jl.cov
+*.jl.*.cov
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Docs build output (MkDocs)
+site/
+
+# Project-local
+.remember/
+.claude/
+
+# Tracked artifacts, remove on release.
+spike/

cpomdp-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+# One-time setup after cloning (installs both the pre-commit and commit-msg hooks):
+#   uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
+# The ruff hooks mirror the CI `lint` job, so a clean commit here is a green CI.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Keep this in sync with the `ruff` pin in pyproject's dev group, so local
+    # and CI agree on exactly which ruff is judging the code.
+    rev: v0.15.16
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+
+  # Enforce Conventional Commit messages (feat:, fix:, docs:, ...), matching the
+  # style already used in the git history. Runs at the commit-msg stage.
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.4.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]

cpomdp-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+Everything worth noting lands here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [semantic versioning](https://semver.org). While we're pre-1.0, treat the minor version as the place breaking changes can show up.
+
+## [0.1.0] — 2026-06-15
+
+The first cut. Linear-Gaussian active inference, end to end: perceive with a Kalman filter, act with LQR, all behind a pymdp-style `Agent`.
+
+### Added
+
+- `Agent`, the stateful façade you actually drive. `infer_states` to perceive, `sample_action` to act, the same loop pymdp users know. It remembers the last action it took, so you don't have to thread that back in by hand. Build it without a goal and it's a pure tracker that perceives but won't act.
+- `LinearGaussianModel`, the generative model. Matrices are named for their role (`dynamics`, `control`, `sensor_model`, `dynamics_noise`, `sensor_noise`), with the control-theory letters (`A`/`B`/`C`/`Q`/`R`) kept as aliases for when you're reading the maths.
+- `Belief`, an immutable Gaussian belief: a mean and a covariance, validated on the way in.
+- `KalmanBackend`, exact Kalman filtering. Has an optional steady-state mode that solves the gain once up front and reuses it.
+- `LQRController`, steady-state LQR action selection. For a linear-Gaussian sensor this *is* the expected-free-energy-optimal action rather than a stand-in for it (the why is in DECISIONS.md, ADR-003).
+- `RxInferBackend`, an optional [RxInfer](https://github.com/ReactiveBayes/RxInfer.jl) (Julia) backend. It re-derives the same filtering results through completely separate machinery and exists as a correctness oracle for the native path. Lives behind the `rxinfer` extra so the core install stays Julia-free.
+- `InferenceBackend`, the protocol the backends satisfy, so you can drop in your own engine.
+
+This is pre-alpha. The API works and is tested against the RxInfer oracle, but it can still move before 1.0.

cpomdp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to cpomdp
+
+Thanks for taking a look. Here's how to get set up and what the tooling expects.
+
+## Setup
+
+The project uses [uv](https://docs.astral.sh/uv/). Once you've cloned it:
+
+```bash
+uv sync                  # install the package + dev tooling
+uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
+```
+
+That second line wires up the git hooks. You only do it once. After that the
+checks run automatically every time you commit, so you find problems before CI
+does rather than after.
+
+## How the rules are enforced
+
+There's one source of truth for style and linting: the `[tool.ruff]` section of
+`pyproject.toml`. Editor settings aren't checked in on purpose, so nothing depends
+on which editor you use. The config is enforced in two places that both read it:
+
+- **pre-commit**, locally, on every commit (see `.pre-commit-config.yaml`).
+- **CI**, on every push and PR, running the exact same hooks.
+
+So if it's green locally, it's green in CI. If you want your editor to format on
+save, point it at ruff yourself; just don't rely on it, the hooks are what count.
+
+## What the hooks check
+
+- **ruff** lints and formats the code. Line length is 88. Formatting isn't a
+  matter of taste here, ruff decides and that's that.
+- **docstrings** are required on public modules, classes, functions and methods in
+  `src/` (Google style). Tests are exempt; their names are the documentation.
+  Constructors can be documented at the class level instead of in `__init__`.
+- **commit messages** follow [Conventional Commits](https://www.conventionalcommits.org):
+  `feat:`, `fix:`, `docs:`, `test:`, `chore:`, and so on. The commit-msg hook will
+  bounce anything that doesn't.
+- a few **hygiene** checks: no trailing whitespace, files end in a newline, YAML and
+  TOML parse, no leftover merge-conflict markers.
+
+## Running things by hand
+
+```bash
+uv run pytest -m "not rxinfer"   # the fast, pure-Python suite
+uv run ty check                  # type checking
+uv run pre-commit run --all-files
+```
+
+The `rxinfer` tests boot a Julia runtime (the RxInfer backend is an independent
+oracle the native filter is checked against). They're slow and need the extra:
+
+```bash
+uv run --extra rxinfer pytest -m rxinfer
+```
+
+You don't need Julia for normal work. The pure-Python suite covers the core, and
+the rxinfer job runs separately in CI.

cpomdp-0.1.0/DECISIONS.md

@@ -0,0 +1,225 @@
+# Architecture Decisions
+
+Decisions are append-only. Each records the choice, the evidence, and the date.
+
+---
+
+## ADR-003 — v0.1 grows an acting agent: stateful `Agent` + front-loaded LQR
+
+**Date:** 2026-06-14
+**Status:** Accepted
+**Phase:** 2 (abstraction wall) → 3 (agent assembly)
+**Amends:** ADR-002 (reverses its "LQR/control side: deferred" scope guard)
+
+### Decision
+
+v0.1 ships an agent that *acts*, not just one that perceives. Two additions:
+
+1. A stateful `Agent` façade that owns the current belief and exposes
+   `infer_states(obs, action=None)` and `sample_action()` — the continuous answer
+   to pymdp's `Agent`.
+2. Action selection via a **front-loaded steady-state LQR** controller: solve the
+   control Riccati once at construction for `L∞`, then `u = -L∞·(mean − goal)` in
+   the loop.
+
+ADR-002 deferred the whole control side. We're pulling it back because without it
+the library is a Kalman filter with a nice type system, not the "continuous
+sibling of pymdp" the README promises. pymdp's shape is perceive → evaluate → act;
+shipping only the first verb undersells what turns out to be a small amount of
+remaining work.
+
+### Why LQR counts as active inference here (the load-bearing argument)
+
+The objection to adding LQR is that we've quietly swapped active inference for
+plain optimal control. We haven't, and the reason is specific to the
+linear-Gaussian case.
+
+Expected Free Energy has a pragmatic term (reach preferred observations) and an
+epistemic term (act to reduce uncertainty). In `LinearGaussianModel` the
+covariance recursion is **control-independent** — the same property that lets us
+front-load `K∞`. Control shifts the mean only; it never touches the covariance. So
+the epistemic value (expected entropy reduction `½·log(det Σ_pred / det Σ_post)`)
+is identical for every action and falls out of the argmin. EFE-minimising action
+selection *provably* reduces to its pragmatic term, and the pragmatic term under a
+Gaussian preference is a quadratic cost whose optimum is LQR.
+
+So LQR isn't a stand-in for EFE here — it's what EFE *is* when sensing doesn't
+depend on where you are. The epistemic term only re-enters once the observation
+model becomes state- or action-dependent (position-varying sensor precision,
+choosing a modality), which is out of scope for a fixed linear-Gaussian sensor. We
+record that as the seam, not a gap.
+
+### The symmetry we're buying
+
+Filter and controller become duals, both solved once at construction, neither
+dependent on data:
+
+- perception: Kalman/DARE → `K∞`, loop does `mean += K∞·prediction_error`
+- action:     control Riccati → `L∞`, loop does `u = -L∞·(mean − goal)`
+
+Together that's LQG. The front-loading thesis (RESEARCH.md) now covers both halves
+of the agent, not just perception.
+
+### Interface shape
+
+- `Agent` is stateful: it holds `belief` (the analog of pymdp's `qs`) and updates
+  it in place across `infer_states` calls. The backends stay functional/pure
+  underneath — façade for ergonomics, engine for testability.
+- Preferences live on the `Agent`, not the model. The model is the generative
+  story; the goal and the effort trade-off are the agent's. Role-named to avoid
+  the Q/R collision (`dynamics_noise`/`sensor_noise` are already "Q"/"R", and
+  LQR's cost matrices are conventionally Q/R too): `goal`, `effort_penalty`, etc.
+- `sample_action()` reads the current belief mean — one matrix-vector product, no
+  inference of its own.
+
+### Scope (v0.1, updated)
+
+- **Added:** stateful `Agent`, steady-state LQR controller (front-loaded `L∞`),
+  agent-side preferences, 2D point-mass reaching demo that closes the loop (the
+  agent chooses the action).
+- **Still deferred:** epistemic/exploratory EFE (named seam above), receding-
+  horizon and time-varying control, nonlinear control. `CovarianceRep`, BMR — as
+  in ADR-002.
+
+### Validation strategy
+
+Same discipline as the filter. `L∞` is checked against an independent oracle —
+scipy's `solve_discrete_are` (control algebraic Riccati) — so a bug in our own
+solve can't pass silently. The reaching demo is the end-to-end acceptance test:
+the point mass must converge to `goal` under the closed loop.
+
+---
+
+## ADR-002 — v0.1 inference engine: **native fixed-gain fast path; RxInfer as oracle + general fallback**
+
+**Date:** 2026-06-12
+**Status:** Accepted
+**Phase:** 2 (the abstraction wall)
+**Amends:** ADR-001 (does not revoke it — re-roles RxInfer rather than removing it)
+
+### Decision
+
+v0.1's *default* inference is a **native, front-loaded steady-state Kalman
+filter** (Option 1 in the build plan), exposed as a backend behind the
+`InferenceBackend` Protocol. **RxInfer (via juliacall, per ADR-001) is retained
+as a second backend** — serving now as the *correctness oracle* and later as the
+*general engine* for the cases the native fast path cannot handle (nonlinear,
+non-stationary, intermittent observations, structure learning, hierarchical).
+
+### Why this changes ADR-001's emphasis
+
+ADR-001 made RxInfer "the engine." The front-loading analysis (RESEARCH.md) shows
+that for the **LTI-Gaussian** v0.1 scope the inference loop reduces to a fixed-gain
+filter so cheap that RxInfer would never run in the hot path — it would be a Julia
+dependency carried for nothing. We arrive at the native path *not* because the
+bridge failed (it worked, ADR-001 stands as evidence) but because front-loading
+removes the only reason the bridge was load-bearing. The Phase-2 abstraction wall
+is exactly what lets both coexist as swappable backends instead of a fork.
+
+### The principle being implemented (RESEARCH.md)
+
+**Front-load the *structure* of the computation, never the *values*.** For an LTI
+Gaussian model the covariance/gain sequence is data-independent: solve the
+discrete algebraic Riccati equation (DARE) **once at agent construction** to get
+the steady-state gain `K∞`, then run a fixed-gain update in the loop. No
+inversion, no covariance update, no O(n³) op in the hot path.
+
+### Scope guards (resisting the doc's own scope creep)
+
+- **In for v0.1:** `Belief` (plain covariance, scalar), `InferenceBackend`
+  Protocol, native fixed-gain backend (DARE → `K∞` + warmup), RxInfer oracle
+  backend, 2D point-mass reaching demo validated against a full per-step Kalman.
+- **Deferred (named seams only, no impl):** `CovarianceRep` strategy/Protocol
+  (YAGNI until a 2nd representation exists — scalar is the trivial 1×1 case of
+  all three), BMR outer loop, LQR/control side.
+- **JAX:** not adopted reflexively. v0.1 scalar fixed-gain is instant in NumPy;
+  JAX is revisited when autodiff (EFE gradients, param learning) or vmap/GPU
+  actually pays. Core stays NumPy-only until then.
+
+### Boundaries where the native fast path is INVALID (fall back to RxInfer)
+
+- Nonlinear models — EKF/UKF gains depend on the linearisation point → the
+  estimate → the data → gains become data-dependent → not front-loadable.
+- Non-stationary `A,Q,R` — `K∞` goes stale; needs drift detection + re-solve.
+- **Intermittent / irregularly-sampled / varying-`R` observations** — breaks the
+  "regular complete observations" assumption that makes `K` constant.
+
+### Validation strategy
+
+The native filter's posterior is checked against (a) a plain NumPy RTS
+smoother / full per-step Kalman (analytic oracle) and (b) the RxInfer backend.
+The Phase-0 spike (`spike/`) is re-roled from "shipping engine prototype" to
+"oracle harness."
+
+---
+
+## ADR-001 — Backend bridge shape: **Shape A (juliacall, in-process)**
+
+**Date:** 2026-06-12
+**Status:** Accepted (emphasis amended by ADR-002)
+**Phase:** 0 (verification spike — the gate)
+
+### Decision
+
+cpomdp's v0.1 inference engine is **RxInfer.jl, reached in-process via `juliacall`**
+(Shape A). Not the HTTP `RxInferClient.py` → `RxInferServer.jl` route (Shape B).
+
+### Evidence from the spike (`spike/`, throwaway)
+
+A scalar linear-Gaussian state-space model was the test vehicle:
+
+    xₜ = A·xₜ₋₁ + 𝒩(0,Q),   yₜ = B·xₜ + 𝒩(0,R),   x₀ ~ 𝒩(m0,v0)
+
+1. **Julia-only ground truth** (`lgssm_groundtruth.jl`): RxInfer runs, posteriors
+   read out cleanly. **Validated correct** against an independent NumPy RTS
+   smoother (`rts_oracle.py`) — agreement to **5e-13** (machine precision).
+2. **juliacall bridge** (`juliacall_driver.py`): the *same* model driven from
+   Python — NumPy array in, array out — reproduced the Julia-only posteriors to
+   **5e-13**. The bridge introduces no numerical error.
+3. **Shape B not deeply evaluated.** The decision rule in the build plan defaults
+   to Shape A unless it proves unworkable. It held on the first real attempt, so
+   the default stands. Shape B remains a documented fallback, not a need.
+
+### Consequences / things learned (carry into Phase 1+)
+
+- **Toolchain that worked:** Julia **1.12.6** (via juliaup), **RxInfer v5.4.0**,
+  **juliacall 0.9.35**, on **CPython 3.14.5**. The feared Python-3.14
+  incompatibility did **not** materialise — 3.14 is fine.
+- **juliacall needs PythonCall.jl in the active Julia project.** It's juliacall's
+  Julia-side counterpart. The real backend must ensure both PythonCall.jl and
+  RxInfer.jl are present — juliacall ships a `juliapkg.json` mechanism for
+  declaring Julia deps; cpomdp should ship its own `juliapkg.json` declaring
+  RxInfer so `pip install cpomdp[rxinfer]` auto-provisions the Julia side.
+- **Startup cost is real but acceptable.** First-ever run paid a one-time
+  ~70s (registry update + PythonCall add + precompile). Steady-state startup is
+  the `import juliacall` + `using RxInfer` load (tens of seconds, JIT warmup),
+  paid once per process — not per inference. Not prohibitive for a library used
+  in a session; worth a note in user docs.
+- **Inference convention — SMOOTHER, not filter.** Handing RxInfer a whole
+  observation sequence at once yields the *smoothed* posterior p(xₜ|y₁..y_T)
+  (message passing flows both directions). The Phase-4 correctness oracle must
+  therefore be an **RTS smoother** (already written: `rts_oracle.py`), not a bare
+  Kalman filter. For an online agent acting in real time we will likely want the
+  *filter* instead — drive RxInfer in streaming/one-observation-at-a-time mode.
+  Decide this when building `agent.py`.
+
+### The wall (unchanged, restated)
+
+juliacall, PythonCall, RxInfer, and the `@model` DSL all live behind
+`backends/base.py`'s Protocol. None of it appears in any public signature, return
+type, exception, or docstring. Shape A vs B is an implementation detail the wall
+makes swappable.
+
+## On changing the matrices names
+To explicitly name the matricices to avoid further confusion and collision within the space.
+An example:
+
+LinearGaussianModel(
+    dynamics=...,        # A: state → next state
+    control=...,         # B: action → state
+    observation=...,     # C: state → observation
+    process_noise=...,   # Q
+    observation_noise=...,# R
+)
+
+The letters can survive as aliases/internal attributes and definitely in the docstrings but the primary interface is role-named.

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