Alberta Framework is a JAX research package for continual learning and continual reinforcement learning, guided by The Alberta Plan for AI Research. It provides online learners, adaptive optimizers, prediction and control agents, learned-state mechanisms, planning and option components, non-stationary streams, benchmarks, and strict evidence validators.
This repository is a development fork of lalalune/alberta at fork point 2ac3533.
VENDORING.md records the relationship to upstream and the local divergence.
The continual-RL subset is also imported in-process by the elizaOS robot track, so the
package keeps Python 3.12 compatibility and a NumPy 1.26 floor.
The framework contains implementation surfaces related to all twelve steps of the Alberta Plan. That is not an integrated Alberta Plan completion claim. Individual mechanisms range from contract-tested kernels to narrow historical evidence packages; important end-to-end, retention, control-benefit, resource-matching, and integration gates remain open.
Keep these boundaries in mind:
- Development and screening runs are permanently nonpromoting unless a separate frozen protocol explicitly says otherwise.
- A passing unit test, smoke run, replay, or benchmark does not promote a scientific claim.
- Registered evidence claims are narrow. Acceptance of one does not certify the package or establish Alberta Plan completion.
- Pinned artifacts are immutable historical records. Source drift makes compatibility checks fail closed; it is not repaired by editing the artifact or loosening its validator.
- Consumed development or evidence seeds cannot be reused as fresh promotion seeds.
See the research status for the current requirement-to-evidence map and the evidence methodology for promotion rules, artifact contracts, and validator semantics.
Alberta Framework requires Python 3.12 or newer, JAX/JAXlib 0.7.1 or newer, and NumPy 1.26 or newer.
This development fork is not published under a fork-controlled PyPI name. The
existing alberta-framework project on PyPI is a different distribution and
does not install this repository. Install from a checkout:
git clone https://github.com/elizaOS/asi.git
cd asi
python3.12 -m venv .venv
.venv/bin/python -m pip install -e .Optional dependency groups are available for common workflows:
.venv/bin/python -m pip install -e '.[gymnasium]' # Gymnasium adapters
.venv/bin/python -m pip install -e '.[forager]' # continual-foragax testbed
.venv/bin/python -m pip install -e '.[research]' # plotting, datasets, parallel helpers
.venv/bin/python -m pip install -e '.[gpu]' # JAX CUDA 12 build
.venv/bin/python -m pip install -e '.[dev]' # tests, lint, and type checkingFor repository development, use that project virtual environment for every command.
This example runs an online linear predictor on a drifting synthetic stream. JAX keys are
explicit, and the learning loop uses jax.lax.scan.
import jax.random as jr
from alberta_framework import (
Autostep,
LinearLearner,
RandomWalkStream,
run_learning_loop,
)
stream = RandomWalkStream(feature_dim=10, drift_rate=0.01)
learner = LinearLearner(optimizer=Autostep())
state, metrics = run_learning_loop(
learner,
stream,
num_steps=10_000,
key=jr.key(42),
)The repository also exposes short Step 1 and Step 2 integration probes:
.venv/bin/alberta-step1-smoke --steps 256 --seed 0
.venv/bin/alberta-step2-smoke --steps 128 --seed 0These commands check that the selected kernel runs and returns finite metrics. They are not scientific experiments or evidence gates.
The console scripts are grouped by responsibility; every command supports --help.
| Commands | Purpose |
|---|---|
alberta-step1-smoke, alberta-step2-smoke |
Nonpromoting mechanism smoke checks |
alberta-evidence-status |
Validate the complete five-claim evidence registry |
alberta-recurring-feature-evidence, alberta-scale-robust-evidence, alberta-ftl-evidence, alberta-multiagent-evidence, alberta-ia-evidence |
Validate or build one claim's versioned artifact under its strict protocol |
alberta-forager-benchmark |
Run development Forager comparisons; its historical subcommand exposes reconstructed historical-family inspection |
alberta-historical-forager |
Compatibility alias for the historical inspection subcommand |
alberta-foragax-open-screen |
Operate the bounded open-screen workflow documented in the runbook |
alberta-foragax-oci |
Prepare, archive, build, inspect, probe, emit, or qualify the attested OCI execution environment |
alberta-forager-matched-campaign, alberta-forager-matched-qualification, alberta-forager-matched-sealed-evaluation |
Operate the matched-comparison campaign stages |
Benchmark commands are not shortcuts around the evidence rules. Read
FORAGER_BENCHMARK.md and the
foragax-open-screen runbook before using them.
alberta_framework/
core/ online learners, optimizers, control, state, models, memory,
planning, options, feature lifecycles, and agent composition
streams/ synthetic prediction, closed-loop, Pavlovian, and recurring
multi-agent streams
evaluation/ evidence schemas, strict validators, registries, and CLIs
benchmarks/ IPMNIST and Forager integrations and campaign runners
utils/ experiment, metric, statistics, and export helpers
steps/ public Step 1-12 mechanism kernels and smoke integration
tests/ unit, integration, scientific, and replay tests
outputs/ evidence and campaign artifacts; see the immutability rules
Most numerical state is represented by immutable Chex dataclasses and carried as JAX PyTrees. Randomness is passed explicitly. Host orchestration, artifact validation, external benchmark loading, and some bounded lifecycle operations remain Python-level by design.
The major package surfaces include:
| Area | Examples |
|---|---|
| Online prediction | LinearLearner, MLPLearner, TD learners, Horde |
| Adaptation | LMS, IDBD, Autostep, SwiftTD, UPGD, normalization, bounding |
| Control | SARSA, actor-critic, average-reward and off-policy variants |
| Continual mechanisms | learned state, feature lifecycles, memory, world models |
| Temporal abstraction | subtasks, STOMP, OaK, option models and bounded planning |
| Composition | PrototypeAgent and explicit transition/decision ownership |
| Evaluation | versioned artifacts, strict validators, evidence registry |
API presence means that a mechanism is available for research. It does not imply empirical benefit, calibrated thresholds, autonomous integration, or scientific acceptance.
From a repository checkout, inspect every registered claim with:
.venv/bin/alberta-evidence-statusThe exit-code contract is:
| Code | Meaning |
|---|---|
0 |
every registered narrow claim is accepted |
1 |
at least one artifact is missing or is a valid rejection |
2 |
at least one artifact is invalid |
The registry validates artifact schema, protocol metadata, and registered source hashes. It is an operational index of narrow claims, not a package-wide evidence score or completion certificate.
Wheels and source distributions intentionally exclude outputs/. Consequently, running the
status command from a normal package installation reports missing artifacts. Use a checkout
when validating the repository's stored evidence chain.
Do not overwrite, repair, or regenerate a pinned artifact in place. A new run must use a new path and, when required by its contract, a new schema version. The full rules are in the evidence methodology.
The current headline lane is IPMNIST screening and confirmation. It is development-grade and permanently nonpromoting. Results change as new shards are appended, so this README does not copy arm rankings, means, test counts, or seed counts.
Use the primary records instead:
- IPMNIST theory and forward hypotheses
- Campaign runbook
- Stored development report
- Artifact and reproducibility audit
- Publication-run record
outputs/ipmnist_screening/summary_*.jsonfor the latest stored summaries
Remeasure the intended baseline under the current development protocol before making an A/B comparison. Do not infer a scientific or state-of-the-art claim from the screening record.
Forager integration and comparator details are in FORAGER_BENCHMARK.md.
Before repeating a failed or bounded idea, check the negative-results ledger.
Run targeted tests first, then broaden verification as appropriate:
.venv/bin/python -m pytest tests/path/to/test_file.py -q
.venv/bin/python -m pytest tests -q
.venv/bin/python -m ruff check .
.venv/bin/python -m mypyThe repository uses these pytest markers:
unit: fast, isolated behavior or contract testsintegration: component, persistence, process, or CLI boundariesscientific: frozen promoted-evidence protocolsslow: wall-clock-heavy tests excluded from the fast per-change lanepackage: built-distribution and installed-entry-point contracts run only in the package lane
Benchmark campaigns run through their scripts or console CLIs, never as ordinary pytest work. Keep tests CI-cheap unless the protocol is deliberately registered as scientific evidence.
Library changes should start with a failing test. Preserve immutable state, explicit
jax.random keys, Python 3.12 support, and the NumPy 1.26 minimum. Before editing evaluation
or benchmark sources, check whether a stored artifact registers their hashes.
Do not auto-promote results, retune a frozen threshold after seeing held-out data, reuse
consumed seeds, or modify immutable outputs/ records. See
the evidence methodology before changing any evidence lane.
- Research status and completion gates
- Evidence methodology and property map
- Negative and bounded results
- IPMNIST theory
- RTU Taylor-correction derivation
- Forager comparator audit
- Historical Forager reconstruction
- OPMNIST closure provenance
Project citation metadata is provided in CITATION.cff. Cite the original papers for algorithms and benchmarks used in a particular experiment, including the Alberta Plan.
Alberta Framework is licensed under the Apache License 2.0.