Zilinghan/readthedoc

.gitignore

@@ -21,6 +21,7 @@ data/*
 *.png
 !docs/images/*.png
 *.txt
+!docs/requirements.txt
 *.csv
 !tests/references/*.csv
 *.pdf
@@ -162,6 +163,7 @@ celerybeat.pid
 .env
 .envrc
 .venv
+.venv-docs/
 env/
 venv/
 ENV/

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs build configuration.
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+sphinx:
+  configuration: docs/conf.py
+  # The build is warning-clean; keep it that way.
+  fail_on_warning: true
+
+# Only the light docs dependencies are installed; torch, river, evidently, wandb
+# and friends are mocked in docs/conf.py via autodoc_mock_imports.
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/README.md

@@ -1,25 +1,49 @@
-# BaseSim Documentation
+# Apeiron Documentation
 
-This directory contains the detailed reference docs for the framework's three main extension points and configurations:
+This directory is a [Sphinx](https://www.sphinx-doc.org/) project written in
+[MyST-Markdown](https://myst-parser.readthedocs.io/) and published on
+Read the Docs. Every `.md` file here is a page in that site; `conf.py` and
+`../.readthedocs.yaml` configure the build.
 
-- `configurations.md`: required and optional configuration settings
-- `model_harness.md`: model + data-stream integration contract
-- `drift_detectors.md`: detector classes, detector config, and detector wiring
-- `continuous_learning.md`: continual-learning trainer, updater modes, and training config
-- `tracking.md`: enabling the W&B or MLflow backend, the logged metric namespace, and reading run charts
+## Building locally
 
-## Read Order
+Heavy runtime dependencies (torch, river, evidently, wandb, ...) are mocked in
+`conf.py`, so a docs build does **not** need the full project environment:
 
-1. Start with `configurations.md` to learn on the required and optional configuration parameters used by Apeiron.
-2. Continue with `model_harness.md` to understand how models and stream loaders are exposed.
-3. Read `drift_detectors.md` to see how monitoring decisions are made.
-4. Read `continuous_learning.md` to understand what happens after drift is detected.
+```bash
+python -m venv .venv-docs && source .venv-docs/bin/activate
+pip install -r docs/requirements.txt
+sphinx-build -b html docs docs/_build/html
+open docs/_build/html/index.html
+```
 
-## Runtime Flow
+Add `-W` to turn warnings into errors, and `-a -E` to force a full rebuild after
+changing `conf.py`.
 
-1. `src/main.py` builds `Config` from TOML, env vars, and CLI overrides.
-2. `examples/utils.py` selects a concrete `BaseModelHarness` by `cfg.data.name`.
-3. `src/driver/continuous_monitor.py` evaluates streaming batches and calls a detector at intervals.
-4. On drift, `src/training/continuous_trainer.py` runs a CL loop with an updater from `src/training/updater/create_updater.py`.
-5. Logging is stage-aware (`eval`, `drift`, `cl`) via `src/logger/`.
+## Page map
 
+| Page | Contents |
+| --- | --- |
+| `index.md` | Landing page and the toctrees that define site navigation. |
+| `installation.md` | Python/Poetry setup, using Apeiron as a dependency, dev commands. |
+| `quickstart.md` | First run, reading the metrics CSV, config overrides. |
+| `architecture.md` | Runtime flow, module map, the four extension points. |
+| `configurations.md` | Every TOML section and key the config parser accepts. |
+| `model_harness.md` | Model + data-stream integration contract. |
+| `drift_detectors.md` | Detector classes, options, and wiring. |
+| `choosing_a_detector.md` | Decision guide for picking and tuning a detector. |
+| `continuous_learning.md` | CL trainer, updater modes, training config. |
+| `tracking.md` | W&B / MLflow backends, logged metric namespace, reading charts. |
+| `profiler.md` | FLOPS profiler and the `cperf_*` metrics. |
+| `deployment.md` | Frontier / Perlmutter HPC setup (included from the deployment READMEs). |
+| `agent_skills.md` | The Claude Code and Codex skills shipped with the repo. |
+| `api/` | Autodoc API reference generated from `src/apeiron/` docstrings. |
+
+## Conventions
+
+- `profiler.md` and `deployment.md` use `{include}` to pull in READMEs that live
+  next to the code, so those pages stay in sync with the scripts they document.
+- Prefer `{doc}` / `{ref}` cross-references over raw relative links so Sphinx
+  can validate them at build time.
+- New pages must be added to a toctree in `index.md`, otherwise Sphinx warns
+  that the document is not included in any toctree.

docs/_static/custom.css

@@ -0,0 +1,26 @@
+/* Apeiron docs -- small refinements on top of the Furo theme. */
+
+/* Keep wide config/metric tables scrollable instead of overflowing the page. */
+.rst-content table,
+article table {
+  display: block;
+  overflow-x: auto;
+  max-width: 100%;
+}
+
+/* Mermaid diagrams: center and constrain. */
+.mermaid {
+  display: flex;
+  justify-content: center;
+  margin: 1.5rem 0;
+}
+
+.mermaid svg {
+  max-width: 100%;
+  height: auto;
+}
+
+/* Slightly tighter grid cards from sphinx-design. */
+.sd-card {
+  border-radius: 0.5rem;
+}

docs/agent_skills.md

@@ -0,0 +1,76 @@
+# Agent Skills
+
+The repository ships task-oriented **agent skills** that walk an AI coding agent
+through the common Apeiron workflows. Each skill is maintained for both tools:
+
+- **Claude Code** — `.claude/skills/<name>/SKILL.md`
+- **Codex** — `.codex/skills/<name>/SKILL.md`
+
+```{important}
+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`.
+```
+
+## Available skills
+
+| 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 utilities, 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. |
+| `choose-detector` | Pick a drift detector (including whether to combine several into an `EnsembleDetector` and which voting rule to use), tune its settings, then emit or patch a validated `[drift_detection]` block. |
+
+## Choosing between them
+
+```{mermaid}
+flowchart TD
+    A{What do you want to do?} --> B[Try the framework<br/>on shipped data]
+    A --> C[Run on my own<br/>data + model]
+    A --> D[Keep my own<br/>training loop]
+    A --> E[Just configure<br/>drift detection]
+    B --> B1[explore-examples]
+    C --> C1[custom-experiment]
+    D --> D1[install-apeiron<br/>then integrate-apeiron]
+    E --> E1[choose-detector]
+```
+
+- **`explore-examples`** vs **`custom-experiment`** — the former runs a bundled
+  config, the latter scaffolds everything for your dataset and architecture.
+- **`custom-experiment`** vs **`integrate-apeiron`** — use `custom-experiment`
+  for a self-contained Apeiron run; use `integrate-apeiron` when you already have
+  a PyTorch / Lightning / HF Trainer loop and want to bolt drift detection onto it.
+- **`install-apeiron`** is only for adding Apeiron to a *separate* project.
+  Developing inside this repo is just `poetry install`.
+- **`choose-detector`** stops at a validated config block — it does not run an
+  experiment.
+
+## Using them
+
+### Claude Code
+
+The skills are exposed as slash commands. Type `/` and the skill name:
+
+```text
+/explore-examples
+/install-apeiron ../my-project
+/choose-detector examples/mnist/mnist.toml
+```
+
+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 the
+request. The skills are tool-agnostic in intent — only the file format differs
+between the two trees.
+
+## Authoring notes
+
+Skills should defer to these docs rather than restating numbers that can drift.
+For example, `choose-detector` names {doc}`drift_detectors` as its authoritative
+reference for detector behavior and options, and re-checks
+`src/apeiron/drift_detection/load_drift_detector.py` before relying on which
+detectors are wired up.

docs/api/config.md

@@ -0,0 +1,11 @@
+# Configuration
+
+The frozen dataclasses produced by the TOML/env/CLI parser. For the meaning of
+each field, see {doc}`../configurations`.
+
+```{eval-rst}
+.. automodule:: apeiron.config.configuration
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

docs/api/drift_detection.md

@@ -0,0 +1,40 @@
+# Drift Detection
+
+See {doc}`../drift_detectors` for behavior and options, and
+{doc}`../choosing_a_detector` for picking one.
+
+## Core types
+
+```{eval-rst}
+.. automodule:: apeiron.drift_detection.detectors.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Statistical detectors
+
+```{eval-rst}
+.. automodule:: apeiron.drift_detection.detectors.statistical_detectors
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Model performance detector
+
+```{eval-rst}
+.. automodule:: apeiron.drift_detection.detectors.model_performance_detector
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Factory
+
+```{eval-rst}
+.. automodule:: apeiron.drift_detection.load_drift_detector
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

docs/api/driver.md

@@ -0,0 +1,11 @@
+# Driver
+
+`ContinuousMonitor` orchestrates the monitoring loop: evaluate batches, check
+drift at intervals, dispatch continual learning on drift.
+
+```{eval-rst}
+.. automodule:: apeiron.driver.continuous_monitor
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

docs/api/evaluation.md

@@ -0,0 +1,16 @@
+# Evaluation
+
+Metric functions used to populate a harness's `eval_metrics` map. Their order in
+that map is what `drift_detection.metric_index` indexes into.
+
+```{eval-rst}
+.. automodule:: apeiron.evaluation.metrics
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: apeiron.evaluation.evaluation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

docs/api/index.md

@@ -0,0 +1,34 @@
+# API Reference
+
+Generated from the docstrings in `src/apeiron/`. The heavy runtime dependencies
+are mocked during the docs build, so signatures involving `torch` types render
+as plain names.
+
+## Top-level package
+
+Everything below is re-exported from `apeiron` itself:
+
+```python
+from apeiron import (
+    Config, ModelCfg, DataCfg, TrainCfg, ContinualLearningCfg,
+    DriftDetectionCfg, VisualizationCfg, LoggingCfg, build_config,
+    BaseModelHarness, ContinuousMonitor, ContinuousTrainer, BaseUpdater,
+    BaseDriftDetector, DriftSignal, LearningRegime,
+    ADWINDetector, KSWINDetector, PageHinkleyDetector,
+    ModelPerformanceDetector, ModelEvalDetector, EnsembleDetector,
+    Logger, get_logger,
+)
+```
+
+```{toctree}
+:maxdepth: 2
+
+config
+model
+driver
+drift_detection
+training
+evaluation
+logger
+profilers
+```

docs/api/logger.md

@@ -0,0 +1,36 @@
+# Logger
+
+Stage-aware logging (`eval`, `drift`, `cl`) with pluggable metrics backends,
+selected by `[logging] backend`.
+
+## Logger
+
+```{eval-rst}
+.. automodule:: apeiron.logger.logger
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Console output
+
+```{eval-rst}
+.. automodule:: apeiron.logger.console_logger
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Metrics backends
+
+```{eval-rst}
+.. automodule:: apeiron.logger.wandb_logger
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: apeiron.logger.mlflow_logger
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

docs/api/model.md

@@ -0,0 +1,11 @@
+# Model Harness
+
+The contract every model + data-stream integration implements. See
+{doc}`../model_harness` for the narrative version.
+
+```{eval-rst}
+.. automodule:: apeiron.model.torch_model_harness
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

docs/api/profilers.md

@@ -0,0 +1,11 @@
+# Profilers
+
+FLOP and wall-time measurement built on PyTorch's `FlopCounterMode`. See
+{doc}`../profiler` for usage.
+
+```{eval-rst}
+.. automodule:: apeiron.profilers.count_flops
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```