actopo 0.1.0__tar.gz

actopo-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: ci
+
+on:
+  push:
+    paths: ["actopo/**"]
+  pull_request:
+    paths: ["actopo/**"]
+  workflow_dispatch:        # manual trigger for the heavy integration job
+  schedule:
+    - cron: "0 6 * * 1"     # weekly integration run (Mondays 06:00 UTC)
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+    defaults:
+      run:
+        working-directory: actopo
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (CPU deps + dev)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests (CPU; skips GPU, real-model integration, data-dependent golden)
+        run: pytest -q -m "not gpu and not integration" --deselect tests/test_topology_golden.py
+      - name: Golden synthetic fixtures + bundled example data (locks paper baselines)
+        run: pytest -q tests/test_topology_fixtures.py tests/test_example_data.py
+
+  integration:
+    # Heavy: downloads real ~1GB Qwen checkpoints. Run on demand / nightly.
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'schedule'
+    defaults:
+      run:
+        working-directory: actopo
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface
+          key: hf-${{ runner.os }}
+      - name: Install with extraction extra (CPU torch)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install "transformers>=4.40" "datasets>=2.14" tqdm
+      - name: Integration tests (real small models)
+        run: pytest -q -m integration

actopo-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.actopo_cache/
+.coverage
+htmlcov/

actopo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xuhao Lin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

actopo-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: actopo
+Version: 0.1.0
+Summary: Activation Topology — reproducible persistent-homology measurement of LLM activation manifolds
+Project-URL: Homepage, https://github.com/linxuhao/actopo
+Project-URL: Repository, https://github.com/linxuhao/actopo
+Author: Lin Xuhao
+License: MIT
+License-File: LICENSE
+Keywords: betti-numbers,interpretability,llm,persistent-homology,topological-data-analysis
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.23
+Requires-Dist: persim>=0.3.1
+Requires-Dist: ripser>=0.6.4
+Requires-Dist: scikit-learn>=1.1
+Provides-Extra: all
+Requires-Dist: datasets>=2.14; extra == 'all'
+Requires-Dist: gudhi>=3.8; extra == 'all'
+Requires-Dist: pytest-cov; extra == 'all'
+Requires-Dist: pytest>=7; extra == 'all'
+Requires-Dist: ruff; extra == 'all'
+Requires-Dist: torch>=2.0; extra == 'all'
+Requires-Dist: tqdm>=4.65; extra == 'all'
+Requires-Dist: transformers>=4.40; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: extract
+Requires-Dist: datasets>=2.14; extra == 'extract'
+Requires-Dist: torch>=2.0; extra == 'extract'
+Requires-Dist: tqdm>=4.65; extra == 'extract'
+Requires-Dist: transformers>=4.40; extra == 'extract'
+Provides-Extra: gpu-ripser
+Requires-Dist: ripserplusplus>=1.1.2; extra == 'gpu-ripser'
+Provides-Extra: gudhi
+Requires-Dist: gudhi>=3.8; extra == 'gudhi'
+Description-Content-Type: text/markdown
+
+# actopo — Activation Topology
+
+Reproducible persistent-homology measurement of LLM activation manifolds.
+
+`actopo` provides **one** measurement protocol, **one** activation-extraction
+function, and **one** topology implementation, so β₁ / survival / PHI numbers
+stay consistent across every experiment. It is the tooling behind the
+*Mathematical Life* paper, packaged so the experiments can be reproduced.
+
+## Why
+
+Re-implementing "compute β₁" in each analysis script lets the measurement
+silently diverge (different ε thresholds, wrong last-token extraction, etc.).
+`actopo` centralises the protocol in a single `ProtocolConfig` and stamps every
+result with the exact config + version + git revision that produced it.
+
+## Install
+
+```bash
+pip install actopo                 # topology layer (CPU only)
+pip install "actopo[extract]"      # + activation extraction (torch/transformers)
+pip install "actopo[all]"          # everything incl. dev/test
+```
+
+## Quickstart
+
+The package ships a tiny real example: reasoning activations from
+**Qwen2.5-0.5B (base)** vs **Qwen2.5-0.5B-Instruct** — the paper's core
+base-vs-instruct comparison.
+
+```python
+from actopo import FROZEN_V5, measure
+from actopo.metrics import union_test, center_distance
+from actopo.data import load_example_cloud
+
+base = load_example_cloud("base")        # (600, 896) reasoning activations
+inst = load_example_cloud("instruct")
+
+print(measure(base, FROZEN_V5).beta1)    # 12
+print(measure(inst, FROZEN_V5).beta1)    # 50  → alignment EXPANDS β₁ here
+
+# base and instruct occupy the SAME topological region (β₁ changes within it):
+u = union_test(base, inst, FROZEN_V5, independent_eps=True)
+print(u["verdict"])                      # SHARED
+print(center_distance(base, inst))       # 0.62
+```
+
+### Extract your own activations (needs `actopo[extract]`)
+
+```python
+from actopo import FROZEN_V5, measure
+from actopo.models import load_model
+from actopo.extract import extract_activations
+
+model, tok = load_model("Qwen/Qwen2.5-0.5B", FROZEN_V5)
+acts = extract_activations(model, tok, my_prompts, FROZEN_V5)   # correct last-token
+print(measure(acts, FROZEN_V5).beta1)
+```
+
+Every result can be stamped + verified against the frozen protocol:
+
+```python
+from actopo import save_result, verify, load_result, FROZEN_V5
+save_result("out.json", {"beta1": 12}, FROZEN_V5)
+assert verify(load_result("out.json"), FROZEN_V5) == []   # produced on-protocol
+```
+
+## The frozen protocol (`FROZEN_V5`)
+
+| Parameter | Value |
+|-----------|-------|
+| β₁ threshold | lifetime > `0.03 × ε_max` |
+| survival/PHI threshold | lifetime > `0.01 × ε_max` |
+| layer | `L/2` |
+| token | last (attention-mask based) |
+| point cloud | 1319 prompts |
+| PH backend | ripser, `maxdim=1`, euclidean |
+
+See `actopo.protocol.ProtocolConfig` for the full, documented field set.
+
+## License
+
+MIT.

actopo-0.1.0/README.md

@@ -0,0 +1,83 @@
+# actopo — Activation Topology
+
+Reproducible persistent-homology measurement of LLM activation manifolds.
+
+`actopo` provides **one** measurement protocol, **one** activation-extraction
+function, and **one** topology implementation, so β₁ / survival / PHI numbers
+stay consistent across every experiment. It is the tooling behind the
+*Mathematical Life* paper, packaged so the experiments can be reproduced.
+
+## Why
+
+Re-implementing "compute β₁" in each analysis script lets the measurement
+silently diverge (different ε thresholds, wrong last-token extraction, etc.).
+`actopo` centralises the protocol in a single `ProtocolConfig` and stamps every
+result with the exact config + version + git revision that produced it.
+
+## Install
+
+```bash
+pip install actopo                 # topology layer (CPU only)
+pip install "actopo[extract]"      # + activation extraction (torch/transformers)
+pip install "actopo[all]"          # everything incl. dev/test
+```
+
+## Quickstart
+
+The package ships a tiny real example: reasoning activations from
+**Qwen2.5-0.5B (base)** vs **Qwen2.5-0.5B-Instruct** — the paper's core
+base-vs-instruct comparison.
+
+```python
+from actopo import FROZEN_V5, measure
+from actopo.metrics import union_test, center_distance
+from actopo.data import load_example_cloud
+
+base = load_example_cloud("base")        # (600, 896) reasoning activations
+inst = load_example_cloud("instruct")
+
+print(measure(base, FROZEN_V5).beta1)    # 12
+print(measure(inst, FROZEN_V5).beta1)    # 50  → alignment EXPANDS β₁ here
+
+# base and instruct occupy the SAME topological region (β₁ changes within it):
+u = union_test(base, inst, FROZEN_V5, independent_eps=True)
+print(u["verdict"])                      # SHARED
+print(center_distance(base, inst))       # 0.62
+```
+
+### Extract your own activations (needs `actopo[extract]`)
+
+```python
+from actopo import FROZEN_V5, measure
+from actopo.models import load_model
+from actopo.extract import extract_activations
+
+model, tok = load_model("Qwen/Qwen2.5-0.5B", FROZEN_V5)
+acts = extract_activations(model, tok, my_prompts, FROZEN_V5)   # correct last-token
+print(measure(acts, FROZEN_V5).beta1)
+```
+
+Every result can be stamped + verified against the frozen protocol:
+
+```python
+from actopo import save_result, verify, load_result, FROZEN_V5
+save_result("out.json", {"beta1": 12}, FROZEN_V5)
+assert verify(load_result("out.json"), FROZEN_V5) == []   # produced on-protocol
+```
+
+## The frozen protocol (`FROZEN_V5`)
+
+| Parameter | Value |
+|-----------|-------|
+| β₁ threshold | lifetime > `0.03 × ε_max` |
+| survival/PHI threshold | lifetime > `0.01 × ε_max` |
+| layer | `L/2` |
+| token | last (attention-mask based) |
+| point cloud | 1319 prompts |
+| PH backend | ripser, `maxdim=1`, euclidean |
+
+See `actopo.protocol.ProtocolConfig` for the full, documented field set.
+
+## License
+
+MIT.

actopo-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "actopo"
+version = "0.1.0"
+description = "Activation Topology — reproducible persistent-homology measurement of LLM activation manifolds"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Lin Xuhao" }]
+keywords = ["topological-data-analysis", "persistent-homology", "llm", "interpretability", "betti-numbers"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+# Core deps are CPU-only so the topology layer + golden tests run anywhere.
+dependencies = [
+    "numpy>=1.23",
+    "scikit-learn>=1.1",
+    "ripser>=0.6.4",
+    "persim>=0.3.1",
+]
+
+[project.optional-dependencies]
+# Model loading / activation extraction (the GPU stage).
+extract = ["torch>=2.0", "transformers>=4.40", "datasets>=2.14", "tqdm>=4.65"]
+# Alternative persistent-homology backends.
+gudhi = ["gudhi>=3.8"]
+gpu-ripser = ["ripserplusplus>=1.1.2"]
+dev = ["pytest>=7", "pytest-cov", "ruff"]
+all = ["actopo[extract,gudhi,dev]"]
+
+[project.scripts]
+actopo = "actopo.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/linxuhao/actopo"
+Repository = "https://github.com/linxuhao/actopo"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/actopo"]
+# Ship the bundled example fixtures (npy/json) inside the wheel.
+artifacts = ["src/actopo/data/*.npy", "src/actopo/data/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "golden: regression tests that reproduce published paper numbers",
+    "gpu: tests that require a GPU + torch",
+    "integration: end-to-end tests that load real (tiny) models; need actopo[extract]",
+]

actopo-0.1.0/src/actopo/__init__.py

@@ -0,0 +1,79 @@
+"""actopo — Activation Topology.
+
+Reproducible persistent-homology measurement of LLM activation manifolds.
+One protocol object, one extraction function, one topology implementation —
+so β₁ / survival / PHI numbers stay consistent across every experiment.
+
+Quickstart (topology only, CPU)::
+
+    import numpy as np
+    from actopo import FROZEN_V5, measure
+
+    pts = np.load("reasoning.npy")
+    r = measure(pts, FROZEN_V5)
+    print(r.beta1, r.beta1_raw, r.eps_pred)
+"""
+
+__version__ = "0.1.0"
+
+from .protocol import ProtocolConfig, FROZEN_V5, PROTOCOL_SCHEMA_VERSION
+from .topology import (
+    measure,
+    PersistenceResult,
+    eps_max,
+    persistence_diagram,
+    lifetimes,
+    survival_curve,
+    phi,
+)
+from .provenance import stamp, verify, Provenance
+from .io import save_result, load_result
+from .extract import extract_activations, select_tokens, last_token_indices
+from .devices import (
+    detect_backend,
+    list_gpus,
+    balance,
+    GPUSpec,
+    WorkItem,
+    estimate_model_vram_gb,
+)
+from .metrics import center_distance, bottleneck_distance, union_test, union_verdict
+from .cache import ActivationCache, cache_key
+
+__all__ = [
+    "__version__",
+    "ProtocolConfig",
+    "FROZEN_V5",
+    "PROTOCOL_SCHEMA_VERSION",
+    "measure",
+    "PersistenceResult",
+    "eps_max",
+    "persistence_diagram",
+    "lifetimes",
+    "survival_curve",
+    "phi",
+    "stamp",
+    "verify",
+    "Provenance",
+    "save_result",
+    "load_result",
+    # extraction (GPU stage)
+    "extract_activations",
+    "select_tokens",
+    "last_token_indices",
+    # hardware / scheduling
+    "detect_backend",
+    "list_gpus",
+    "balance",
+    "GPUSpec",
+    "WorkItem",
+    "estimate_model_vram_gb",
+    # five-dimension metrics
+    "center_distance",
+    "bottleneck_distance",
+    "union_test",
+    "union_verdict",
+    # caching
+    "ActivationCache",
+    "cache_key",
+]

actopo-0.1.0/src/actopo/cache.py

@@ -0,0 +1,66 @@
+"""Disk cache for extracted activations, keyed by (model, prompts, config).
+
+Extraction is the expensive GPU stage; topology is cheap CPU. Caching activations
+lets you re-measure (new ε, new metric) without re-running models, and makes the
+two-stage pipeline skip work that's already done. Keys include the config
+fingerprint, so changing the protocol correctly invalidates the cache.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, Optional, Sequence
+import hashlib
+import json
+
+import numpy as np
+
+from .protocol import ProtocolConfig, FROZEN_V5
+
+
+def _prompts_hash(prompts: Sequence[str]) -> str:
+    h = hashlib.sha256()
+    h.update(str(len(prompts)).encode())
+    for p in prompts:
+        h.update(b"\x00")
+        h.update(p.encode("utf-8", "replace"))
+    return h.hexdigest()[:12]
+
+
+def cache_key(model_id: str, prompts: Sequence[str], cfg: ProtocolConfig) -> str:
+    """Stable filename stem for a (model, prompts, protocol) triple."""
+    safe_model = model_id.replace("/", "__")
+    return f"{safe_model}__{_prompts_hash(prompts)}__{cfg.fingerprint()}"
+
+
+class ActivationCache:
+    """Tiny content-addressed cache of (n, dim) float32 activation arrays."""
+
+    def __init__(self, cache_dir: str | Path = ".actopo_cache"):
+        self.dir = Path(cache_dir)
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def _paths(self, key: str) -> tuple[Path, Path]:
+        return self.dir / f"{key}.npy", self.dir / f"{key}.json"
+
+    def get(self, key: str) -> Optional[np.ndarray]:
+        npy, _ = self._paths(key)
+        return np.load(npy) if npy.exists() else None
+
+    def put(self, key: str, acts: np.ndarray, meta: Optional[dict] = None) -> None:
+        npy, side = self._paths(key)
+        np.save(npy, np.ascontiguousarray(acts, dtype=np.float32))
+        with open(side, "w") as f:
+            json.dump({"key": key, "shape": list(acts.shape), **(meta or {})}, f, indent=2)
+
+    def get_or_compute(self, model_id: str, prompts: Sequence[str],
+                       cfg: ProtocolConfig,
+                       compute: Callable[[], np.ndarray]) -> np.ndarray:
+        """Return cached activations or compute, store, and return them."""
+        key = cache_key(model_id, prompts, cfg)
+        hit = self.get(key)
+        if hit is not None:
+            return hit
+        acts = compute()
+        self.put(key, acts, meta={"model_id": model_id, "n_prompts": len(prompts),
+                                  "config_fingerprint": cfg.fingerprint()})
+        return acts

actopo-0.1.0/src/actopo/cli.py

@@ -0,0 +1,127 @@
+"""Thin CLI over the library — replaces the dozens of ad-hoc analysis scripts.
+
+    actopo betti       a.npy b.npy ...      -> β₁ table
+    actopo curve       a.npy ...            -> persistence curves
+    actopo bottleneck  a.npy b.npy          -> shape distance
+    actopo union       a.npy b.npy          -> SEPARATE/SHARED/MIXED (Iron-Law guarded)
+    actopo verify      result.json          -> check a result's provenance vs FROZEN_V5
+
+Every command takes the same protocol knobs (--eps, --survival-eps, --backend),
+so there is exactly one place a constant can be set.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from .protocol import FROZEN_V5, ProtocolConfig
+from . import topology, metrics, io as aio, provenance
+
+
+def _cfg_from_args(a) -> ProtocolConfig:
+    return FROZEN_V5.with_(
+        betti_eps_frac=a.eps,
+        survival_eps_frac=a.survival_eps,
+        ph_backend=a.backend,
+    )
+
+
+def _add_protocol_args(p):
+    p.add_argument("--eps", type=float, default=FROZEN_V5.betti_eps_frac,
+                   help="β₁ threshold as fraction of ε_max (default 0.03)")
+    p.add_argument("--survival-eps", type=float, default=FROZEN_V5.survival_eps_frac,
+                   help="survival/PHI threshold fraction (default 0.01)")
+    p.add_argument("--backend", default=FROZEN_V5.ph_backend,
+                   choices=["ripser", "gudhi", "ripserpp"])
+    p.add_argument("-o", "--output", help="write stamped JSON result here")
+
+
+def _cmd_betti(a):
+    cfg = _cfg_from_args(a)
+    rows = []
+    for f in a.files:
+        r = topology.measure(np.load(f), cfg)
+        rows.append({"file": f, **r.to_dict()})
+        print(f"{Path(f).name:<48s} β₁={r.beta1:<4d} raw={r.beta1_raw:<5d} "
+              f"surv={r.survival_rate:>5.1f}% ε_pred={r.eps_pred}")
+    if a.output:
+        aio.save_result(a.output, {"betti": rows}, cfg)
+    return 0
+
+
+def _cmd_curve(a):
+    cfg = _cfg_from_args(a)
+    out = [{"file": f, **topology.survival_curve(np.load(f), cfg)} for f in a.files]
+    if a.output:
+        aio.save_result(a.output, {"curves": out}, cfg)
+    for r in out:
+        print(f"{Path(r['file']).name:<48s} raw={r['beta1_raw']:<5d} ε_max={r['eps_max']}")
+    return 0
+
+
+def _cmd_bottleneck(a):
+    cfg = _cfg_from_args(a)
+    res = metrics.bottleneck_distance(np.load(a.a), np.load(a.b), cfg)
+    print(json.dumps(res, indent=2))
+    if a.output:
+        aio.save_result(a.output, res, cfg)
+    return 0
+
+
+def _cmd_union(a):
+    cfg = _cfg_from_args(a)
+    res = metrics.union_test(np.load(a.a), np.load(a.b), cfg,
+                             independent_eps=a.independent_eps,
+                             same_basis=not a.cross_basis)
+    print(json.dumps(res, indent=2))
+    if a.output:
+        aio.save_result(a.output, res, cfg)
+    return 0
+
+
+def _cmd_verify(a):
+    doc = aio.load_result(a.result)
+    warns = provenance.verify(doc, FROZEN_V5)
+    if not warns:
+        print(f"OK — {a.result} produced with FROZEN_V5")
+        return 0
+    print(f"WARNINGS for {a.result}:")
+    for w in warns:
+        print(f"  - {w}")
+    return 1
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="actopo", description="Activation Topology toolkit")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pb = sub.add_parser("betti", help="β₁ table for point clouds")
+    pb.add_argument("files", nargs="+"); _add_protocol_args(pb); pb.set_defaults(fn=_cmd_betti)
+
+    pc = sub.add_parser("curve", help="persistence/survival curves")
+    pc.add_argument("files", nargs="+"); _add_protocol_args(pc); pc.set_defaults(fn=_cmd_curve)
+
+    pbn = sub.add_parser("bottleneck", help="barcode shape distance")
+    pbn.add_argument("a"); pbn.add_argument("b"); _add_protocol_args(pbn)
+    pbn.set_defaults(fn=_cmd_bottleneck)
+
+    pu = sub.add_parser("union", help="region-overlap test (Iron-Law guarded)")
+    pu.add_argument("a"); pu.add_argument("b")
+    pu.add_argument("--independent-eps", action="store_true")
+    pu.add_argument("--cross-basis", action="store_true",
+                    help="acknowledge clouds are not same-basis (warns)")
+    _add_protocol_args(pu); pu.set_defaults(fn=_cmd_union)
+
+    pv = sub.add_parser("verify", help="check a result's provenance vs FROZEN_V5")
+    pv.add_argument("result"); pv.set_defaults(fn=_cmd_verify)
+
+    args = p.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

actopo-0.1.0/src/actopo/data/__init__.py

@@ -0,0 +1,41 @@
+"""Bundled mini example data — doubles as the documented example and as
+deterministic integration/regression fixtures.
+
+Contents (shipped in the wheel) — a base vs instruct duo of ONE model, the
+paper's core comparison (does alignment reshape reasoning topology?):
+  - example_prompts.json  : 40 reasoning + 40 control prompts (subset of paper set)
+  - example_base.npy      : 600 reasoning activations, Qwen2.5-0.5B (base), L/2, fp16
+  - example_instruct.npy  : 600 reasoning activations, Qwen2.5-0.5B-Instruct, L/2, fp16
+
+These are small subsamples — illustrative and reproducible, NOT the full
+1319-point protocol clouds. Use them to learn the API and to smoke-test a build.
+"""
+from __future__ import annotations
+
+import json
+from importlib import resources
+from typing import Dict, List
+
+import numpy as np
+
+_PKG = "actopo.data"
+
+
+def load_example_prompts() -> Dict[str, List[str]]:
+    """Return {"reasoning": [...], "control": [...]} example prompt lists."""
+    with resources.files(_PKG).joinpath("example_prompts.json").open() as f:
+        return json.load(f)
+
+
+def load_example_cloud(kind: str = "base") -> np.ndarray:
+    """Load a bundled example reasoning cloud as float32 (n=600, dim=896).
+
+    kind: "base" (Qwen2.5-0.5B) | "instruct" (Qwen2.5-0.5B-Instruct).
+    """
+    if kind not in ("base", "instruct"):
+        raise ValueError(f"kind must be 'base' or 'instruct', got {kind!r}")
+    with resources.files(_PKG).joinpath(f"example_{kind}.npy").open("rb") as f:
+        return np.load(f).astype(np.float32)
+
+
+__all__ = ["load_example_prompts", "load_example_cloud"]