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.