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

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.

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])

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:

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)

See actopo.protocol.ProtocolConfig for the full, documented field set.

License

MIT.