APGI Framework

Allostatic Precision-Gated Ignition — a computational framework for consciousness research.

Manuscript

Pesochin, D. (0009-0005-0328-2896) (2026). Thresholds Make Consciousness Selective: Allostatic Precision-Gated Ignition via Predictive Processing and Interoceptive Integration. Manuscript submitted for publication.

This repository is the companion code release for the paper series above. Figure scripts are in figures/ (current 1.1 series in figures/v1_1/, frozen 1.0 figures in figures/v1_0/) and scripts/. Version 1.1 protocol specifications are in protocols/. The OSF project is osf.io/t5hcq; the registration is osf.io/yk29g (base registration August 24, 2026; Amendment 1, October 22, 2026).

Project links

To reproduce all figures from locally regenerated seed data in one command:

bash reproduce_all.sh --local

Overview

The APGI framework implements the core equations from the APGI paper series:

• Paper 1 — core APGI equations; EEG interoceptive gating, insular causal neuromodulation (tFUS/dTMS), active inference simulations, DoC biomarkers, fMRI anticipation, and iEEG ignition-dynamics protocols
• Paper 2 — Liquid Neural Network extension (apgi.extensions.liquid_network)
• Paper 3 — Five-level hierarchical architecture (apgi.extensions.hierarchical)
• Paper 4 — Three-tier epistemic architecture (no code; scoring tables in the release)

Repository structure

apgi-framework/
├── src/apgi/              # pip-installable library
│   ├── core.py            # Sₜ, θₜ, Πⁱ_eff equations
│   ├── normalizer.py      # APGINormalizer
│   ├── integration.py     # APGICoreIntegration (stateful session)
│   ├── clinical.py        # EnhancedClinicalInterpreter
│   ├── parameter_recovery.py
│   └── extensions/        # optional
│       ├── liquid_network.py
│       └── hierarchical.py
├── protocols/             # pre-registered experimental protocols
│   ├── schemas/           # JSON Schema validation
│   └── *.json
├── tests/                 # pytest suite
├── notebooks/             # worked examples
├── figures/               # see figures/README.md
│   ├── common/            # shared helpers (utils.py)
│   ├── v1_0/              # frozen 1.0 figures: protocols/, paper1–4/, output/
│   └── v1_1/              # current 1.1 review series (generate.py, validate.py, output/)
├── scripts/               # standalone CLI helpers
├── data/                  # local data cache + seed datasets
│   ├── seeds/             # .npz + .csv + .h5 (sim3) seed files (generated, not committed)
│   │   └── seed_manifest.json  # tracked v1.1.0 release record of the seed files
│   ├── generate_seeds.py  # deterministic seed generator (fixed MASTER_SEED)
│   └── checksums.sha256
├── DATA_DICTIONARY.md     # full variable codebook for all seed datasets
└── POWER_ANALYSIS.md      # sample-size and power justifications

Installation

git clone https://github.com/apgiframework/apgi-framework.git
cd apgi-framework
pip install -e ".[dev]"

Conda (HPC / clean-machine replication)

conda env create -f environment.yml
conda activate apgi
pip install -e ".[dev]"

Optional: Paper 2 LNN extension (requires PyTorch)

pip install -e ".[lnn]"

Quick start

import apgi

# Core equations — available directly from the package
pi_i_eff = apgi.compute_pi_i_eff(pi_i_baseline=1.0, beta_sm=0.6, M_hat=0.5)
S_t      = apgi.compute_S_t(pi_e=1.2, z_e=0.8, pi_i_eff=pi_i_eff, z_i=0.5)
theta_t  = apgi.theta_equilibrium(C=1.0, I_val=0.5)          # θ* where dθ/dt = 0
theta_1  = apgi.step_theta(theta_t, C_t=1.0, I_t=0.5)        # one Euler step of Eq. 3

print(f"Sₜ={S_t:.4f}  θₜ={theta_t:.4f}  ignition={apgi.ignition_criterion(S_t, theta_t)}")

Stateful session integration

from apgi.integration import APGICoreIntegration
import apgi

# Built-in sample data — no Zenodo download required
session = apgi.datasets.make_sample_session(n_trials=200, seed=0)

integ = APGICoreIntegration(beta_sm=0.6, theta_0=0.60, lambda_theta=0.30, kappa_meta=0.20, delta_info=0.15, gamma_sig=5.0)
integ.run_sequence(**{k: session[k] for k in
    ("pi_e", "z_e", "pi_i", "z_i", "C_metabolic", "V_information")})
print(f"Ignition rate: {integ.ignition_rate():.3f}")

Paper 2 / 3 extensions (not pulled in by default)

from apgi.extensions.liquid_network import LiquidNeuralNetwork
from apgi.extensions.hierarchical  import APGIHierarchy

Notebooks

Interactive walkthroughs are in notebooks/. The protocol notebooks follow protocol specification v1.1.0: they read design counts and decision thresholds directly from protocols/*.json, and they classify each prediction as CONFIRMED, FALSIFIED or INDETERMINATE (failing to confirm is not falsification). All data are synthetic.

jupyter lab notebooks/

Reproducing figures

The APGI 1.1 figure review series is in figures/v1_1/, with a side-by-side comparison, revised captions, provenance and a complete mapping of all 31 legacy figures plus one new composite. Generate its 32 PNG/PDF/SVG sets with:

python3 figures/v1_1/generate.py
python3 figures/v1_1/validate.py

Two quantitative panels (parameter recovery and sensitivity/robustness) are explicitly pending verified 1.1 analysis outputs; their current replacements describe the required analyses. The following commands reproduce the frozen 1.0 protocol figures in figures/v1_0/, not the 1.1 review series. Run validate.py first: it checks the committed 1.0 images that these scripts overwrite.

python figures/v1_0/protocols/p0_hep_proxy.py            # Figure 1 — Protocol 0: HEP proxy validation (Pred 0.A–0.C)
python figures/v1_0/protocols/p1_cardiac_eeg.py          # Figure 2 — Protocol 1: Cardiac-EEG trial timeline
python figures/v1_0/protocols/p2_somatic_agent_sim.py    # Figure 3 — Protocol 2: somatic-marker agent advantage
python figures/v1_0/protocols/p3_anticipation_fmri.py    # Figure 4 — Protocol 3: vmPFC–insula anticipatory coupling
python figures/v1_0/protocols/p4_metabolic_crossover.py  # Figure 5 — Protocol 4: allostatic threshold modulation
python figures/v1_0/protocols/p5_causal_tms.py           # Figure 6 — Protocol 5: causal PCI/HEP dissociation
python figures/v1_0/protocols/p6_ignition_ieeg.py        # Figure 7 — Protocol 6: iEEG bimodality + AC1 slowing
python figures/v1_0/protocols/p7_doc_biomarker.py        # Figure 8 — Protocol 7: joint PCI–HEP model (N=110)

Scripts are named by protocol (pK_…); their outputs keep the published numbering, Figure N ↔ Protocol (N−1), matching the captions in the OSF preregistration, and land in figures/v1_0/output/figureN.{pdf,png}. The per-paper 1.0 figures are in figures/v1_0/paper1/–paper4/. See figures/README.md for the layout and the 1.0 → 1.1 mapping.

Running tests

pytest tests/ -v

The full suite (379 tests, 99% line coverage of src/apgi, scripts/ and figures/) covers core equations, normalizer, integration, clinical interpreter, parameter recovery, LNN, bifurcation analysis, five-level hierarchy, protocol validation, and the seed-manifest release record.

Data

The nine synthetic seed datasets (sim0–sim8) are not yet deposited on Zenodo; the v1.1 record (10.5281/zenodo.23551315) holds the manuscripts, protocols and companion documents. Regenerate them locally and check them against the release checksums:

python data/generate_seeds.py                    # all nine datasets → data/seeds/ (sim2 takes ~2 h)
python data/generate_seeds.py --dataset sim0,sim5
python data/generate_seeds.py --verify           # compare with data/checksums.sha256
bash reproduce_all.sh --local                    # figures from the local seeds

Once the datasets are deposited, apgi-fetch (--list, --dataset NAME, --verify) downloads them instead. Binder builds data/seeds/ automatically (binder/postBuild, all datasets except sim2).

Checksums are recorded in data/checksums.sha256; the release record data/seeds/seed_manifest.json adds each dataset's seed, consumers, generating environment and alignment with protocol specification v1.1.0. Full variable codebook: DATA_DICTIONARY.md. Sample-size justifications: POWER_ANALYSIS.md.

The LNN trajectory dataset (sim3_liquid_network) is also written as sim3_liquid_network.h5 (HDF5, gzip-compressed) for direct use in MNE-Python, NWB tools, MATLAB (h5read), and Julia (HDF5.jl):

states = h5read('sim3_liquid_network.h5', '/data/states');  % (100, 500, 20) — MATLAB and Julia reverse HDF5 dimension order relative to h5py

using HDF5
fid = h5open("sim3_liquid_network.h5", "r")
states = read(fid["data/states"])
close(fid)

Experimental protocols

The eight protocol specifications use version 1.1.0 (protocol release version). They contain 40 prediction records. Source conflicts and pending analysis locks are documented in protocols/CHANGELOG.md; JSON validation does not establish empirical validation or study readiness.

CI validates the schema, date/URI formats, release membership, cross-field consistency, report and SHA256 manifest:

python3 scripts/validate_protocols.py
python3 -m pytest tests/test_validate_protocols.py

An external release folder can be supplied as the first argument. Add --source-dir /path/to/FINAL to verify the source-document hashes. After intentional edits, --refresh-metadata regenerates VALIDATION.json and MANIFEST.json only after the protocol checks pass. Normal validation never rewrites files.

Citation

@software{apgi_framework_2026,
  author  = {Pesochin, Dimitry},
  title   = {Allostatic Precision-Gated Ignition (APGI): Simulation and Analysis Codebase},
  year    = {2026},
  version = {1.1.0},
  url     = {https://github.com/apgiframework/apgi-framework},
  note    = {ORCID: 0009-0005-0328-2896. Preregistration: https://doi.org/10.17605/OSF.IO/YK29G}
}

License

Code: MIT — see LICENSE. Manuscripts, protocols and data: CC BY 4.0.