Apeiron

A PyTorch framework for continual learning that automatically detects concept drift in data streams and adapts models through JVP regularized retraining. For more information on Apeiron modules and a Quickstart guide, please refer to the Apeiron Documentation.

What This Repository Does

The pipeline runs on a changing data stream and loops through these stages:

1. Evaluate the current model on stream batches.
2. Aggregate monitored metrics at a configured interval.
3. Run a drift detector on the aggregated metric.
4. If drift is detected, pause monitoring and run a continual-learning update loop.
5. Resume monitoring on the updated model and continue until stream limits are reached.

Core modules:

• src/main.py: entry point
• src/apeiron/config/configuration.py: TOML/env/CLI config assembly
• src/apeiron/driver/continuous_monitor.py: monitoring + drift loop
• src/apeiron/training/continuous_trainer.py: CL training loop
• src/apeiron/training/updater/: CL update strategies
• src/apeiron/drift_detection/: detectors and detector factory
• examples/: standalone example projects (each declares apeiron as a dependency)

Installation

As a dependency in your project

Install from GitHub. Don't pip install apeiron: that name on PyPI belongs to an unrelated project.

# A uv project, pinned to a release tag
uv add "git+https://github.com/AI-ModCon/BaseSIM_APEIRON" --tag v0.1.0

# Or an editable local checkout, during development
uv add --editable ../BaseSIM_APEIRON

# Or with pip
pip install "apeiron @ git+https://github.com/AI-ModCon/BaseSIM_APEIRON@v0.1.0"

from apeiron import BaseModelHarness, ContinuousMonitor, build_config
from apeiron.drift_detection import ADWINDetector
from apeiron.training.updater import BaseUpdater

For development in this repo

Requires Python >=3.13,<3.14 and uv.

uv sync

This creates .venv with exactly the versions pinned in uv.lock. See docs/installation.md for CPU-only and ROCm machines.

Running Experiments

From the project root:

uv run python -m src.main --config examples/mnist/mnist.toml
uv run python -m src.main --config examples/cifar/cifar10_vit.toml
uv run python -m src.main --config examples/imagenet/imagenet_vit.toml  # requires ImageNet data at data.path

Metrics Logging

Currently, we support two metrics logging backends: Weights & Biases (WandB) and MLflow. You can configure the desired backend in the config file's logging section. To disable logging, you can set the logging section to none to disable logging. Alternatively, you can set the logging choice via command line arguments, for example:

uv run python -m src.main --config examples/mnist/mnist.toml --set logging.backend=mlflow --set logging.experiment_name="My Experiment"
# To view results for MLflow, run `mlflow ui` in another terminal and navigate to http://localhost:5000

Currently the mnist example sets the logging to wandb in the toml config file. The other examples do not set any metric for the logging backend, which defaults to wandb.

Configuration Overview

Primary sections in config TOML:

• [model]
• [data]
• [train]
• [drift_detection]
• [continual_learning] (optional but recommended)
• [visualization] (optional)

Top-level fields commonly used:

• seed
• device
• multi_gpu
• verbosity

Override precedence:

1. Base TOML (--config)
2. Environment overrides prefixed with APP_
3. CLI overrides via repeated --set key=value

Example override:

uv run python -m src.main \
  --config examples/mnist/mnist.toml \
  --set drift_detection.detector_name=\"KSWINDetector\" \
  --set train.max_iter=200

Agent Skills (Claude Code & Codex)

This repo ships task-oriented agent skills that walk an AI coding agent through the common Apeiron workflows. The same four skills are maintained for both tools:

• Claude Code — .claude/skills/<name>/SKILL.md
• Codex — .codex/skills/<name>/SKILL.md

Skill	What it does
install-apeiron	Add Apeiron as a dependency to another project (path/git), verify import apeiron, pick CPU vs CUDA PyTorch.
explore-examples	Run a bundled example (MNIST/CIFAR) to see drift detection + CL in action; picks a config and reports the metrics CSV.
custom-experiment	Scaffold a harness, data utils, and TOML for your own dataset/model, register it in the example factory, smoke-test, and run.
integrate-apeiron	Add Apeiron's drift detection / CL to an existing training loop; inspects your repo and writes the lightest adapter that fits.

Using them

Claude Code — the skills are exposed as slash commands. Type / and the skill name, e.g.:

/explore-examples
/install-apeiron ../my-project

You can also just describe the task in plain language ("add apeiron to my training loop") and the matching skill triggers from its description.

Codex — the equivalent skills live under .codex/skills/. Invoke a skill by name or describe the task; Codex selects the skill whose description matches your request. The skills are tool-agnostic in intent — only the file format differs between the two trees.

Keep the two trees in sync: a change to a workflow should be reflected in both .claude/skills/<name>/SKILL.md and .codex/skills/<name>/SKILL.md.

Documentation

Detailed docs are in docs/:

• docs/README.md
• docs/model_harness.md
• docs/drift_detectors.md
• docs/continuous_learning.md

Development Commands

Common tasks are wrapped in the Makefile:

make install      # uv sync
make lock         # uv lock, after changing dependencies
make test         # pytest
make test-cov     # pytest with an HTML + terminal coverage report
make lint         # ruff check . and ruff format --check .
make format       # ruff format .
make type-check   # mypy .
make docs         # build the Sphinx docs into docs/_build/html
make clean        # remove build artifacts and caches

Run make help for the full list. These are the same checks CI runs, so a clean make lint && make type-check && make test should mean a green build.

What main.py Does

• Builds a Config from the TOML file, APP_ environment variables, and --set CLI overrides (src/apeiron/config/configuration.py).
• Configures the logging backend and console logger (src/apeiron/logger/), before constructing the harness so a harness that logs from __init__ cannot pin the config.
• Selects a concrete BaseModelHarness from cfg.data.name via examples/utils.py:get_example.
• Runs ContinuousMonitor (src/apeiron/driver/continuous_monitor.py), which evaluates streaming batches and calls the drift detector every detection_interval batches.
• On drift, dispatches ContinuousTrainer (src/apeiron/training/continuous_trainer.py) with the updater named by [continual_learning] update_mode.

See docs/architecture.md for the full pipeline, including the detection-only (src/drift_only.py) and adaptation-only (src/cl_only.py) entry points.

Tuning Tips

• Change the CL loop's outer/inner iteration counts and learning rate through the [continual_learning] and [train] config sections.
• Swap the adaptation strategy with [continual_learning] update_mode (base, jvp_reg, ewc_online, kfac_online, none).
• Tune detection sensitivity with [drift_detection] detector_name and its per-detector parameters — see docs/drift_detectors.md.
• Update batch size and worker count with [train] batch_size and [train] num_workers.

Output

The console logger reports per-stage metrics (eval, drift, cl). When [visualization] input is set, the run also writes a metrics CSV at that path for external plotting.

Deployment

Platform-specific deployment guides:

• OLCF Frontier
• NERSC Perlmutter

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to contribute to this project, including our guidelines for AI/LLM-assisted contributions.

Changes are recorded in CHANGELOG.md.

Support

This work was supported by the U.S. Department of Energy (DOE), Office of Science, Office of Advanced Scientific Computing Research in alignment with DOE's Genesis Mission.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Security

To report a security vulnerability, please follow the process in SECURITY.md — please do not open a public issue.

Questions or Issues?

For questions or to report issues, please open an issue on GitHub.