pyaif-toolkit 0.1.0__tar.gz

pyaif_toolkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.1.0 - 2026-07-24
+
+### Added
+
+- Component-based `GenerativeModel`, `CategoricalLikelihood`,
+  `ShallowInference`, and `DeepTemporalInference` APIs.
+- Reusable shallow and deep categorical inference strategies.
+- Reusable categorical parameter learning for `A`, `B`, `C`, `D`, and `E`.
+- Numerical and end-to-end learning-example regression tests.
+- Reproducible VFE-surprise animation for the uncertainty-learning example.
+- Wheel validation, continuous integration, and guarded release automation.
+- BSD-3-Clause licensing for the packaged software.
+
+### Changed
+
+- PyPI distribution name set to `pyaif-toolkit`; the import package remains
+  `PyAIF`.
+- Domain-specific likelihood construction moved out of the package.
+- `ActiveInfAgent` now delegates reusable inference and learning behavior to
+  focused modules.
+- The retained learning-under-uncertainty example now uses the public component
+  API and supports configurable trials, output directories, and random seeds.
+- Deep expected-free-energy signs and cumulative initial-state learning retain
+  the behavior of the validated research simulation.
+- The obsolete handover and autonomous pick-and-place examples were removed.
+
+### Compatibility
+
+- The legacy agent constructor remains available while examples migrate.
+- Continuous-observation support is planned for the `0.2.x` release line.

pyaif_toolkit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+## Development setup
+
+```bash
+python -m venv .venv
+python -m pip install -e ".[dev]"
+```
+
+Run the local checks before opening a pull request:
+
+```bash
+ruff check PyAIF tests
+ruff format --check PyAIF tests
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+## Change policy
+
+- Keep reusable inference and learning code under `PyAIF/`.
+- Keep domain-specific generative models and likelihood construction under
+  `examples/` or in an application repository.
+- Add numerical regression tests for changes to inference, expected free
+  energy, learning, or policy construction.
+- Preserve structural zeros in categorical `A` and `B` updates.
+- Do not add continuous-observation behavior to the `0.1.x` release line.
+
+## Pull requests
+
+Pull requests should describe the behavioral change, identify affected
+examples, and include test evidence. CI tests Python 3.9 through 3.13 and builds
+the wheel and source distribution.
+
+## Releases
+
+1. Update the version in `pyproject.toml`.
+2. Update `CHANGELOG.md`.
+3. Merge a pull request with all CI checks passing.
+4. Create and publish a GitHub release for the matching version tag.
+5. The protected `pypi` environment publishes with PyPI Trusted Publishing.
+
+The repository owner must configure the PyPI trusted publisher and GitHub
+`pypi` environment before the first release.

pyaif_toolkit-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Diluna A. Warnakulasuriya
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

pyaif_toolkit-0.1.0/MANIFEST.in

@@ -0,0 +1,15 @@
+include CHANGELOG.md
+include CONTRIBUTING.md
+include LICENSE
+recursive-include docs *.md
+recursive-include examples *.py *.md *.png *.gif
+
+prune profiling_results
+prune PyAIF/likelihood_models
+
+global-exclude *.csv
+global-exclude *.jsonl
+global-exclude *.log
+global-exclude *.npy
+global-exclude *.npz
+global-exclude *.zip

pyaif_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: pyaif-toolkit
+Version: 0.1.0
+Summary: A Python package for Active Inference agents and simulations
+Author: Diluna A. Warnakulasuriya
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/Diluna98/python_active_inference
+Project-URL: Issues, https://github.com/Diluna98/python_active_inference/issues
+Project-URL: Repository, https://github.com/Diluna98/python_active_inference.git
+Keywords: active-inference,bayesian-inference,generative-models
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+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.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: joblib
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.12; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# PyAIF
+
+PyAIF is a Python package for constructing discrete active-inference agents
+with factorised hidden states. Version 0.1 provides categorical observations,
+single-step inference, deep temporal inference, policy evaluation, action
+selection, and categorical parameter learning.
+
+Continuous-observation likelihoods are intentionally reserved for version 0.2.
+Research applications and domain-specific likelihood construction belong in
+the `examples/` directory or in separate repositories.
+
+## Installation
+
+PyAIF requires Python 3.9 or newer.
+
+Install the published distribution:
+
+```bash
+python -m pip install pyaif-toolkit
+```
+
+The distribution is named `pyaif-toolkit` on PyPI, while the Python import
+package remains `PyAIF`.
+
+To install from a source checkout:
+
+```bash
+python -m pip install .
+```
+
+For development:
+
+```bash
+python -m pip install -e ".[dev]"
+pytest
+```
+
+## Quick start
+
+The public API separates the state-transition model, observation model, and
+inference algorithm.
+
+```python
+import numpy as np
+
+from PyAIF import (
+    ActiveInfAgent,
+    CategoricalLikelihood,
+    GenerativeModel,
+    ShallowInference,
+)
+
+
+def object_array(*values):
+    result = np.empty(len(values), dtype=object)
+    for index, value in enumerate(values):
+        result[index] = np.asarray(value, dtype=float)
+    return result
+
+
+# A[o, s]: categorical observation likelihood.
+A = object_array(
+    np.array([
+        [0.95, 0.05],
+        [0.05, 0.95],
+    ])
+)
+
+# B[s_next, s_previous, action]: controlled transitions.
+B_factor = np.zeros((2, 2, 2))
+B_factor[:, :, 0] = np.eye(2)
+B_factor[:, :, 1] = np.fliplr(np.eye(2))
+B = object_array(B_factor)
+
+# D[s]: initial-state prior. C[o]: outcome preferences.
+D = object_array(np.array([0.5, 0.5]))
+C = object_array(np.zeros(2))
+
+model = GenerativeModel(
+    B=B,
+    D=D,
+    controls_dim=[2],
+    controllable_factors=[0],
+)
+likelihood = CategoricalLikelihood(
+    A=A,
+    preferences=C,
+    modality_dependencies=[[0]],
+)
+agent = ActiveInfAgent(
+    model=model,
+    likelihood=likelihood,
+    inference=ShallowInference(),
+    action_selection="deterministic",
+)
+
+agent.reset()
+agent.observe([0])
+agent.infer_states()
+expected_free_energy, _ = agent.infer_policies()
+action = agent.select_action()
+```
+
+Use `DeepTemporalInference(horizon=...)` for policy-dependent beliefs over
+multiple time steps. Deep preferences have shape
+`(number_of_outcomes, horizon)`.
+
+## Agent lifecycle
+
+The supported component-based lifecycle is:
+
+```python
+agent.reset(trial=trial)
+agent.observe(observation, time_step=t)
+agent.infer_states()
+agent.infer_policies()
+action = agent.select_action()
+agent.learn()  # only when parameter learning is enabled
+```
+
+The older matrix-heavy constructor and methods such as `choose_action()` and
+`perform_learning()` remain available while examples migrate, but new projects
+should use the component constructor and lifecycle above.
+
+## Model structure
+
+- `GenerativeModel` owns state transitions (`B`), initial-state priors (`D`),
+  control dimensions, controllable factors, and optional policies.
+- `CategoricalLikelihood` owns observation likelihoods (`A`), preferences
+  (`C`), and modality-to-factor dependencies.
+- `ShallowInference` performs single-step factorised inference.
+- `DeepTemporalInference` performs marginal message passing over a horizon.
+- `PyAIF.learning` contains reusable categorical updates for `A`, `B`, `C`,
+  `D`, and `E`.
+
+See [Model shapes](docs/model-shapes.md) and
+[Public API](docs/public-api.md) for details.
+
+## Examples
+
+- `examples/quickstart_discrete.py`: minimal categorical agent.
+- `examples/learning_under_uncertainty/`: deep temporal parameter-learning
+  experiments under epistemic and aleatoric uncertainty.
+
+Model-selection and bounded-rationality experiments are maintained separately
+from the reusable PyAIF package.
+
+The automated regression suite covers the reusable component API and executes
+one trial of each parameter-learning experiment.
+
+Run the minimal component example with:
+
+```bash
+python examples/quickstart_discrete.py
+```
+
+## Version policy
+
+- `0.1.x`: categorical observations and discrete parameter learning.
+- `0.2.x`: planned continuous-observation likelihood components.
+
+Behavioral changes are protected with numerical regression tests. Research
+experiments may evolve independently from the packaged API.
+
+## License
+
+PyAIF is distributed under the
+[BSD 3-Clause License](LICENSE). Copyright © 2026
+Diluna A. Warnakulasuriya.
+
+This software license does not automatically apply to papers, datasets,
+figures, trained models, or other research artifacts.
+
+## Development
+
+```bash
+ruff check PyAIF tests
+ruff format --check PyAIF tests
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the pull-request and release
+process.

pyaif_toolkit-0.1.0/PyAIF/__init__.py

@@ -0,0 +1,51 @@
+"""Public API for PyAIF's discrete active-inference package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from . import utils
+from .aif_agent import ActiveInfAgent
+from .generative_model import GenerativeModel
+from .inference import (
+    DeepPolicyInferenceResult,
+    DeepStateInferenceResult,
+    DeepTemporalInference,
+    ShallowInference,
+    ShallowPolicyInferenceResult,
+    ShallowStateInferenceResult,
+    deep_categorical_policy_ambiguity,
+    deep_categorical_policy_risk,
+    deep_expected_free_energy,
+)
+from .likelihoods import CategoricalLikelihood
+from .learning import (
+    CategoricalLearningResult,
+    categorical_observation_evidence,
+    categorical_transition_evidence,
+    update_dirichlet_parameters,
+)
+
+try:
+    __version__ = version("pyaif-toolkit")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "ActiveInfAgent",
+    "CategoricalLikelihood",
+    "CategoricalLearningResult",
+    "DeepPolicyInferenceResult",
+    "DeepStateInferenceResult",
+    "DeepTemporalInference",
+    "deep_categorical_policy_ambiguity",
+    "deep_categorical_policy_risk",
+    "deep_expected_free_energy",
+    "GenerativeModel",
+    "ShallowInference",
+    "ShallowPolicyInferenceResult",
+    "ShallowStateInferenceResult",
+    "categorical_observation_evidence",
+    "categorical_transition_evidence",
+    "update_dirichlet_parameters",
+    "utils",
+]