Skip to content
ActiveInferenceInstitutePublic

About

Installable Python package for reproducible ecological control, bioregion research, and auditable decision analysis, with a pymdp active-inference controller for simulating and comparing ecosystem trajectories.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

2 watching

Forks

Latest commit

 

History

158 Commits

Folders and files

Repository files navigation

Biofirm

Biofirm is an installable Python package for reproducible ecological control, bioregion research, deterministic text extraction, analysis, and auditable business decisions.

Documentation

Install

Biofirm supports Python 3.12 and newer; CI tests 3.12, 3.13 and 3.14.

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,analysis,visualization,documents]"
biofirm validate

For a hash-locked development environment, install uv and run uv sync --frozen --all-extras; the committed uv.lock covers Python 3.12 and newer with platform markers, and CI derives the hashed requirements export from it at run time rather than reading a committed copy.

All offline commands use the packaged configuration unless --config is provided. Live research is the only network-enabled path and requires both an explicit --live flag and PERPLEXITY_API_KEY in the environment. Copy .env.example as a reminder, but never put a key in a file tracked by git.

Commands

biofirm validate
biofirm validate-data
biofirm simulate --steps 25 --seed 11 --controller active-inference --output run.json
biofirm sweep --steps 10 --seeds 1 2 3 --controller slide-rule
biofirm compare --steps 10 --seeds 1 2 3 --controllers slide-rule random
biofirm analyze --input run.json
biofirm visualize --input run.json --output artifacts/trajectory.png
biofirm parse-description --input region.txt
biofirm business-evaluate --state state.json
biofirm scenarios --config baseline.json --config disturbed.json --steps 10 --seeds 1 2 3
biofirm graph --regions Bio_Perplexity/Biofirm_Regions.json
biofirm research --live --source regions.json --persona ecologist --output artifacts/research

simulate records every transition: values, observations, controls, action IDs, controller beliefs, variational free energy, expected free energy, policy distributions, metrics (including a posterior-entropy uncertainty term), and transition diagnostics. Variables can configure a symmetric observation binning (observation_bins, an odd number >= 3; the default 3 preserves the below/at/above model). Seeded runs are reproducible. New simulation artifacts include a schema version, configuration snapshot, configuration hash, controller identity, and package version. Invalid configuration, unavailable optional dependencies, malformed provider responses, and failed controller calls produce errors; they do not create empty success artifacts.

parse-description keeps signed decimal and leading-decimal ranges within their original sentences. Extracted values retain units and original evidence offsets; nearest-variable attribution and near-equidistant ambiguity reporting are unchanged. A range cannot borrow a variable alias from another sentence.

scenarios runs the same seeds across multiple validated ecosystem configurations and reports per-scenario summaries plus a final-uncertainty estimate, so scenario variants can be compared without asserting calibrated ecological performance. graph builds an experimental regional interaction graph from a region source; graph summaries and acceptance checks are explicitly descriptive, not validated ecological evidence.

Live research writes a JSON/Markdown pair for each region/persona plus a manifest containing integrity hashes. Every artifact records the request hash, prompt version, source hash, a provider-cost estimate, a human review state, and a set of structured findings extracted verbatim from the provider response (with hedge-aware confidence). Each complete pair is hashed and checkpointed to the manifest before another provider job starts. A later provider or rendering failure leaves committed pairs resumable; an incomplete pair is not a completed manifest entry. Resume requires both files, their hashes, the prompt version/hash, and the source hash to agree. Manifest costs estimate committed artifact entries, not billed provider usage. Structural validation establishes artifact integrity, never factual quality of citations or research claims. Execution remains split into independently rerunnable acquire/prepare/execute/parse/render stages.

Configuration

The packaged JSON schema is available at src/biofirm/data/ecosystem.json. Each variable declares its initial and target values, physical limits, trend, noise, control strength, and unit. Relationships are directed linear effects between variables. Validation rejects unknown fields and dependencies, non-finite values, invalid ranges, and cycles.

The transition equation is:

next = clip(current + trend + relationship_effect + control + bounded_noise,
            minimum, maximum)

A field-by-field reference for every configuration key is in CONFIGURATION.md.

The active-inference controller uses the installed PyMDP 1.x API with JAX arrays, explicit empirical priors, explicit policy inference, and deterministic action selection unless stochastic selection is configured.

Generative model specification

The controller's generative model is specified in Generalized Notation Notation (GNN) at models/biofirm_ecosystem_variable.gnn.md. models/README.md records the declared structure, the loader and drift guard in src/biofirm/gnn.py, and the pinned upstream revision (GNN v5.1.0, commit 75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf, also in .github/gnn-pin.json). The shared gnn.importers reader in ./run.sh gnn validates that pin, its pointer and the specification with the pinned parser. tests/test_gnn.py checks the specification against the matrices the package builds, for the default three-bin model and for generalized odd observation_bins values, and re-validates it with the pinned upstream parser from a clean export of that revision.

For new model work, start from the upstream framework integration guide and the downstream adoption guide. A related Active Inference Institute repository is GEO_INFER, whose geospatial and ecological models also carry GNN specifications and pin-freshness checks. Other repositories that already declare models this way:

  • ActiveBlockference — the closest sibling for control models; its specs/gridworld_3x3.gnn.md is validated with the upstream parser its own pin names.
  • active_fractal_rabbit — the reference layout this repository follows: models/, a loader module, and .github/gnn-pin.json.

Development checks

run.sh is the single gate entry point; CI calls the same arms, so a local run and a CI run execute the same commands:

./run.sh sync        # locked environment for BIOFIRM_PYTHON (default 3.12)
./run.sh test        # full suite, 90% coverage floor
./run.sh test-fast   # same suite without coverage or tests/test_gnn.py
./run.sh lint        # ruff check + ruff format --check
./run.sh types       # strict mypy on src/biofirm
./run.sh links       # tools/verify_repository.py (relative links, data, credentials)
./run.sh docs        # biofirm validate + biofirm validate-data
./run.sh gnn         # shared importer reader + pinned parser conformance
./run.sh all         # every arm, in CI order

./run.sh list prints the arms and ./run.sh --help the full table. Measured wall times, the test count and the coverage total are in docs/gate.md, which tools/gate_report.py refreshes from a real run; do not hand-edit those numbers.

Generated research, simulation, report, plot, log, and cache files belong in artifacts/ or another ignored runtime directory. Authoritative source data under One_Earth/ and Bio_Perplexity/ remains input data rather than a generated output contract.

Live research requires both --live and PERPLEXITY_API_KEY. The default endpoint is the official HTTPS provider endpoint. Custom endpoints require --allow-custom-endpoint and are intended only for trusted HTTPS-compatible providers; credentials are never sent over insecure HTTP by the CLI.

See docs/documentation-index.md for the boundary between implemented contracts, source data, and historical design material. Current work is scoped in TODO.md; completed items remain in Git history. Development setup and contribution conventions are in CONTRIBUTING.md; security boundaries and vulnerability reporting are in SECURITY.md.

Schema compatibility is explicit: consumers must validate simulation schema version 1, and future breaking changes require a new schema version and migration notes. The public package exports stable configuration, simulation, data-validation, and comparison entry points; internal modules remain implementation details.

InstituteOS sidecar

This repository carries a committed .aii/ sidecar with curated InstituteOS metadata (aii-sidecar/v1): category, maturity, ecosystem relations, key artifacts, provenance, and portable tasks. It is read by InstituteOS tooling and does not affect the project's build or runtime.

About

Installable Python package for reproducible ecological control, bioregion research, and auditable decision analysis, with a pymdp active-inference controller for simulating and comparing ecosystem trajectories.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages