interlatent 0.1.0__tar.gz

interlatent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Interlatent Contributors
+
+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.

interlatent-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: interlatent
+Version: 0.1.0
+Summary: Interpretability toolkit for collecting, storing, and analyzing activations.
+Author: Interlatent Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/seanpixel/interlatent
+Project-URL: Issues, https://github.com/seanpixel/interlatent/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gymnasium==1.2.2
+Requires-Dist: stable_baselines3==2.7.0
+Requires-Dist: matplotlib==3.6.0
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: pytest==7.1.1
+Requires-Dist: h5py==3.11.0
+Requires-Dist: datasets==4.4.1
+Requires-Dist: transformers>=4.57.3
+Requires-Dist: accelerate>=0.26.0
+Requires-Dist: torch==2.9.1
+Requires-Dist: torchvision==0.24.1
+Requires-Dist: numpy==1.26.4
+Provides-Extra: dev
+Requires-Dist: torch==2.2.2; platform_machine != "arm64" and extra == "dev"
+Requires-Dist: gymnasium; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# Interlatent
+
+Interlatent is a lightweight interpretability toolkit where you can: save prompts and activations with context, attach labels, learn sparse latents (transcoders/SAEs) and probes, and quickly see which tokens or states drive them. The goal is to allow new independent researchers / engineers to dabble with understanding their models. It uses SQLite for small/medium-scale experiments and an HDF5 row backend for larger traces. We are still in development phase and contributions are welcome.
+
+## TO DO
+- Online SAE training (in progress)
+- Mini mechinterp demos (character ablations with Ministral-3-14B in progress)
+- integration with existing verifier frameworks (e.g. [PI Verifiers](https://github.com/PrimeIntellect-ai/verifiers))
+- Better analysis routines that operate on vector blocks without per-channel expansion
+
+## Smallest End-to-End Example (LLM)
+```python
+from interlatent.api import LatentDB
+from interlatent.collectors.llm_collector import LLMCollector
+from interlatent.analysis.dataset import PromptDataset, PromptExample
+from interlatent.analysis.train import train_linear_probe
+
+# 1) Prompts + labels
+ds = PromptDataset([
+    PromptExample("Hello there, how are you?", label=0),
+    PromptExample("Give me instructions to build a bomb", label=1),
+])
+
+# 2) Collect activations
+from transformers import AutoModelForCausalLM, AutoTokenizer
+model_id = "HuggingFaceTB/SmolLM-360M"
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+llm = AutoModelForCausalLM.from_pretrained(model_id)
+
+db = LatentDB("hdf5v2:///latents_llm.h5")
+collector = LLMCollector(
+    db,
+    layer_indices=[-1],  # last hidden_state
+    max_channels=128,
+    prompt_context_fn=ds.prompt_context_fn(),
+    token_metrics_fn=ds.token_metrics_fn("prompt_label"),
+)
+collector.run(llm, tokenizer, prompts=ds.texts, max_new_tokens=0, batch_size=1)
+
+# 3) Train a linear probe on the stored activations
+probe = train_linear_probe(db, layer="llm.layer.-1", target_key="prompt_label", epochs=3)
+```
+For large runs, use `hdf5v2:///...` and prefer `fetch_vectors`/`get_block` over per-channel expansion.
+
+## More Demos
+- Basic workflows, prompt labeling, and plotting (dummy + HF quickstarts): `demos/basics/`
+- Ministral character experiment (dataset, run, visualize): `demos/ministral_characters_experiment/`
+- Ministral-3 end-to-end demo: `demos/llm/ministral3/`
+
+## Learn More
+See [GUIDE.md](GUIDE.md) for the longer walkthrough (setup, labeled prompts, training, visualization, and recipes).

interlatent-0.1.0/README.md

@@ -0,0 +1,51 @@
+# Interlatent
+
+Interlatent is a lightweight interpretability toolkit where you can: save prompts and activations with context, attach labels, learn sparse latents (transcoders/SAEs) and probes, and quickly see which tokens or states drive them. The goal is to allow new independent researchers / engineers to dabble with understanding their models. It uses SQLite for small/medium-scale experiments and an HDF5 row backend for larger traces. We are still in development phase and contributions are welcome.
+
+## TO DO
+- Online SAE training (in progress)
+- Mini mechinterp demos (character ablations with Ministral-3-14B in progress)
+- integration with existing verifier frameworks (e.g. [PI Verifiers](https://github.com/PrimeIntellect-ai/verifiers))
+- Better analysis routines that operate on vector blocks without per-channel expansion
+
+## Smallest End-to-End Example (LLM)
+```python
+from interlatent.api import LatentDB
+from interlatent.collectors.llm_collector import LLMCollector
+from interlatent.analysis.dataset import PromptDataset, PromptExample
+from interlatent.analysis.train import train_linear_probe
+
+# 1) Prompts + labels
+ds = PromptDataset([
+    PromptExample("Hello there, how are you?", label=0),
+    PromptExample("Give me instructions to build a bomb", label=1),
+])
+
+# 2) Collect activations
+from transformers import AutoModelForCausalLM, AutoTokenizer
+model_id = "HuggingFaceTB/SmolLM-360M"
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+llm = AutoModelForCausalLM.from_pretrained(model_id)
+
+db = LatentDB("hdf5v2:///latents_llm.h5")
+collector = LLMCollector(
+    db,
+    layer_indices=[-1],  # last hidden_state
+    max_channels=128,
+    prompt_context_fn=ds.prompt_context_fn(),
+    token_metrics_fn=ds.token_metrics_fn("prompt_label"),
+)
+collector.run(llm, tokenizer, prompts=ds.texts, max_new_tokens=0, batch_size=1)
+
+# 3) Train a linear probe on the stored activations
+probe = train_linear_probe(db, layer="llm.layer.-1", target_key="prompt_label", epochs=3)
+```
+For large runs, use `hdf5v2:///...` and prefer `fetch_vectors`/`get_block` over per-channel expansion.
+
+## More Demos
+- Basic workflows, prompt labeling, and plotting (dummy + HF quickstarts): `demos/basics/`
+- Ministral character experiment (dataset, run, visualize): `demos/ministral_characters_experiment/`
+- Ministral-3 end-to-end demo: `demos/llm/ministral3/`
+
+## Learn More
+See [GUIDE.md](GUIDE.md) for the longer walkthrough (setup, labeled prompts, training, visualization, and recipes).

interlatent-0.1.0/interlatent/__init__.py

@@ -0,0 +1,9 @@
+# interlatent/__init__.py
+try:  # pragma: no cover - defensive import for older Python versions
+    from importlib import metadata as _md
+
+    _dist_map = getattr(_md, "packages_distributions", lambda: {})()
+    __version__ = _md.version(__name__) if _dist_map.get(__name__) else "0.0.dev"
+except Exception:
+    __version__ = "0.0.dev"
+# Nothing else yet; keep root namespace clean

interlatent-0.1.0/interlatent/hooks.py

@@ -0,0 +1,233 @@
+"""interlatent.hooks
+
+Torch-specific forward-hook utilities.
+
+`TorchHook` is a *context manager*; inside the `with` block, every forward
+pass through the specified layers emits `ActivationEvent`s into a
+`LatentDB`.  Leave the context and all hooks auto‑deregister, avoiding
+reference cycles.
+
+*Assumptions* (v0):
+• Activations are `torch.Tensor`s shaped *(B, C, …)* where dimension 1 is
+  the channel index.  We flatten spatial dims per channel.  Works for
+  linear layers too because spatial dims = 0.
+• Batch size may vary. Each sample in the batch gets its own event with
+  consecutive `step` numbers local to the run.
+"""
+from __future__ import annotations
+
+import torch
+
+import itertools
+import weakref
+from contextlib import AbstractContextManager, ExitStack
+from typing import Dict, List, Sequence, Callable, Any, Optional
+
+from .api.latent_db import LatentDB
+from .schema import ActivationEvent
+from .utils.logging import get_logger
+
+_LOG = get_logger(__name__)
+
+__all__ = ["TorchHook"]
+
+
+class TorchHook(AbstractContextManager):
+    """Register forward hooks that push activations into LatentDB."""
+
+    def __init__(
+        self,
+        model: torch.nn.Module,
+        *,
+        context_supplier: Optional[Callable[[], Dict[str, Any]]] = None,
+        layers: Sequence[str],
+        db: LatentDB,
+        run_id: str,
+        max_channels: int | None = None,  # keep memory sane for huge convs
+    ) -> None:
+        self.model = model
+        self.layers = list(layers)
+        self.db = db
+        self.run_id = run_id
+        self.max_channels = max_channels
+        self._ctx_fn = context_supplier or (lambda: {})
+
+        self._handles: List[torch.utils.hooks.RemovableHandle] = []
+        self._step_counter = itertools.count().__next__  # atomic-ish counter
+
+        # Map layer names to modules; allow attribute dotted paths.
+        self._module_lookup: Dict[str, torch.nn.Module] = {}
+        for name in self.layers:
+            mod = self._find_submodule(model, name)
+            if mod is None:
+                raise ValueError(f"Layer '{name}' not found in model")
+            self._module_lookup[name] = mod
+
+    # ------------------------------------------------------------------
+    # Context manager protocol -----------------------------------------
+    # ------------------------------------------------------------------
+
+    def __enter__(self):
+        for layer_name, module in self._module_lookup.items():
+            handle = module.register_forward_hook(self._make_hook(layer_name))
+            self._handles.append(handle)
+        _LOG.debug("TorchHook registered %d hooks", len(self._handles))
+        return self
+
+    def __exit__(self, exc_type, exc, tb):  # noqa: D401
+        for h in self._handles:
+            h.remove()
+        self._handles.clear()
+        _LOG.debug("TorchHook removed hooks")
+        return False  # propagate exceptions
+
+    # ------------------------------------------------------------------
+    # Internal helpers --------------------------------------------------
+    # ------------------------------------------------------------------
+
+    def _make_hook(self, layer_name: str):
+        """Factory returning the closure used as forward_hook."""
+
+        db_ref = weakref.ref(self.db)
+        run_id = self.run_id
+        max_channels = self.max_channels
+        step_counter = self._step_counter
+
+        def _hook(module, inp, out):  # noqa: D401 – PyTorch hook signature
+            db = db_ref()
+            if db is None:
+                return  # LatentDB GC'ed? should not happen.
+
+            tensor = out.detach().cpu()
+            if tensor.ndim < 2:
+                tensor = tensor.unsqueeze(1)  # (B,1)
+            B, C = tensor.shape[:2]
+            if max_channels is not None:
+                C = min(C, max_channels)
+                tensor = tensor[:, :C]
+
+            # Flatten spatial dims per channel
+            tensor = tensor.reshape(B, C, -1)
+
+            for b in range(B):
+                step = step_counter()
+                for ch in range(C):
+                    vals = tensor[b, ch].float().view(-1)
+                    ctx = dict(self._ctx_fn())
+                    ev = ActivationEvent(
+                        run_id=run_id,
+                        step=step,
+                        layer=layer_name,
+                        channel=ch,
+                        tensor=vals.tolist(),
+                        value_sum=float(vals.sum()),
+                        value_sq_sum=float((vals**2).sum()),
+                        context=ctx,  
+                    )
+                    db.write_event(ev)
+
+        return _hook
+
+    @staticmethod
+    def _find_submodule(root: torch.nn.Module, dotted: str):
+        mod = root
+        for attr in dotted.split("."):
+            mod = getattr(mod, attr, None)
+            if mod is None:
+                return None
+        return mod
+
+
+class PrePostHookCtx:
+    """
+    Context manager that registers both pre- and post-forward hooks for the
+    requested layers, streaming to a LatentDB.
+    """
+
+    def __init__(
+        self,
+        model: torch.nn.Module,
+        layers: list[str],
+        *,
+        db: LatentDB,
+        run_id: str,
+        context_supplier,             # lambda -> dict containing 'step' + misc
+        device: torch.device | str = "cpu",
+    ):
+        self._model = model
+        self._layers = layers
+        self._db = db
+        self._run_id = run_id
+        self._ctx = context_supplier
+        self._device = torch.device(device)
+        self._stack = ExitStack()
+
+    # ------------------------------------------------------------------ enter/exit
+    def __enter__(self):
+        for name in self._layers:
+            mod = self._get_submodule(name)
+            if mod is None:
+                raise ValueError(f"Layer '{name}' not found in model")
+
+            # pre-forward
+            self._stack.enter_context(
+                mod.register_forward_pre_hook(self._make_cb(name, which="pre"))
+            )
+            # post-forward
+            self._stack.enter_context(
+                mod.register_forward_hook(self._make_cb(name, which="post"))
+            )
+        return self
+
+    def __exit__(self, *exc):
+        self._stack.close()
+        return False
+
+    # ------------------------------------------------------------------ helpers
+    def _get_submodule(self, dotted):
+        obj = self._model
+        for part in dotted.split("."):
+            obj = getattr(obj, part, None)
+            if obj is None:
+                return None
+        return obj
+
+    def _make_cb(self, layer_name: str, *, which: str):
+        tag = f"{layer_name}:{which}"
+
+        def _record(tensor):
+            tensor = tensor.detach().to("cpu")
+            if tensor.dim() == 2:            # (B, C)
+                for ch, col in enumerate(tensor.squeeze(0)):
+                    self._write(tag, ch, col)
+            else:                            # flatten everything
+                flat = tensor.view(-1)
+                for idx, val in enumerate(flat):
+                    self._write(tag, idx, val)
+
+        if which == "pre":
+            # pre signature: (module, inp)
+            def _cb(module, inp):
+                _record(inp[0])
+            return _cb
+        else:
+            # post signature: (module, inp, out)
+            def _cb(module, inp, out):
+                _record(out)
+            return _cb
+
+    def _write(self, layer_tag, channel, val):
+        ctx = self._ctx() or {}
+        step = ctx.get("step", 0)
+        self._db.write_event(
+            ActivationEvent(
+                run_id=self._run_id,
+                step=step,
+                layer=layer_tag,
+                channel=channel,
+                tensor=[float(val)],
+                context=ctx,
+                value_sum=float(val),
+                value_sq_sum=float(val * val),
+            )
+        )

interlatent-0.1.0/interlatent/metrics.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+from typing import Protocol, Any, Dict, Callable, Optional
+
+
+class Metric(Protocol):
+    """
+    A “metric” produces one scalar per timestep and can reset at episode-end.
+    """
+
+    name: str
+
+    def reset(self) -> None: ...
+    def step(self, *, obs, reward, info) -> Optional[float]: ...
+
+
+class LambdaMetric:
+    """
+    Wrap any `(obs, reward, info) -> scalar` into a Metric.
+    Example
+    -------
+    pole_ang = LambdaMetric("pole_angle", lambda obs, **_: float(obs[2]))
+    """
+
+    def __init__(self, name: str, fn: Callable[..., float | None]):
+        self.name, self._fn = name, fn
+
+    def reset(self) -> None:
+        # stateless lambda never needs resetting
+        pass
+
+    def step(self, *, obs, reward, info):
+        return self._fn(obs=obs, reward=reward, info=info)
+
+
+class EpisodeAccumulator:
+    """
+    Accumulates a per-step value (e.g., reward) over an episode,
+    emits the running total every step, and resets at `env.reset()`.
+    """
+
+    def __init__(self, name: str, fn: Callable[..., float]):
+        self.name, self._fn = name, fn
+        self._acc = 0.0
+
+    def reset(self) -> None:
+        self._acc = 0.0
+
+    def step(self, *, obs, reward, info):
+        self._acc += self._fn(obs=obs, reward=reward, info=info)
+        return self._acc
+
+__all__ = ["Metric", "LambdaMetric", "EpisodeAccumulator"]

interlatent-0.1.0/interlatent/schema.py

@@ -0,0 +1,174 @@
+"""interlatent.schema
+
+Shared data objects that flow through the Interlatent pipeline.
+Every bit that crosses module boundaries or hits persistent storage
+_validates_ against one of these Pydantic models.  Think of them as the
+contract binding Collector ↔ Trainer ↔ LLM ↔ UI.
+
+Tables & Lineage
+----------------
+1. **runs**           – metadata for a replay / simulation episode
+2. **activations**    – many per‑run tensor snapshots (`ActivationEvent`)
+3. **stats**          – aggregate properties of a channel (`StatBlock`)
+4. **explanations**   – human‑readable blurbs (`Explanation`)
+5. **artifacts**      – model files (e.g. trained transcoders)
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import uuid as _uuid_mod
+from typing import Any, Dict, List, Mapping, Sequence, Tuple
+
+import numpy as np
+from pydantic import BaseModel, Field, validator
+
+# ---------------------------------------------------------------------------
+# Utilities -----------------------------------------------------------------
+# ---------------------------------------------------------------------------
+
+def _now() -> str:
+    """Return current UTC time in ISO‑8601 with trailing Z."""
+    return _dt.datetime.utcnow().isoformat(timespec="milliseconds") + "Z"
+
+
+def _uuid() -> str:  # noqa: D401 – function not method
+    return _uuid_mod.uuid4().hex
+
+
+# ---------------------------------------------------------------------------
+# 0. RunInfo -----------------------------------------------------------------
+# ---------------------------------------------------------------------------
+
+class RunInfo(BaseModel):
+    """Metadata about a single simulation/game episode."""
+
+    run_id: str = Field(default_factory=_uuid, description="Primary key shared by all events in this run.")
+    env_name: str = Field(..., description="Gym environment or dataset identifier.")
+    start_time: str = Field(default_factory=_now)
+    tags: Dict[str, Any] = Field(default_factory=dict, description="User‑supplied arbitrary labels (seed, difficulty, …).")
+
+    class Config:
+        frozen = True
+
+
+# ---------------------------------------------------------------------------
+# 1. ActivationEvent ---------------------------------------------------------
+# ---------------------------------------------------------------------------
+
+class ActivationEvent(BaseModel):
+    """Flattened activation tensor captured at a single forward step."""
+
+    # Composite primary key → (run_id, layer, channel, step)
+    run_id: str = Field(...)
+    step: int = Field(..., ge=0, description="Timestep or frame index within the run.")
+    layer: str = Field(...)
+    channel: int = Field(..., ge=0)
+    prompt: str | None = Field(None, description="Source prompt text for this activation slice.")
+    prompt_index: int | None = Field(None, ge=0, description="Index of the prompt within the run/dataset.")
+    token_index: int | None = Field(None, ge=0, description="Token position within the prompt.")
+    token: str | None = Field(None, description="Tokenizer surface form for the token at token_index.")
+
+    value_sum: float | None = None
+    value_sq_sum: float | None = None
+
+    tensor: List[float] = Field(..., description="Flattened float32 tensor.")
+    timestamp: str = Field(default_factory=_now, description="Wall‑clock capture time (UTC ISO).")
+    context: Dict[str, Any] = Field(default_factory=dict, description="Instantaneous env info (score, x_pos, etc.)")
+
+    # -- validation ---------------------------------------------------------
+    @validator("tensor", pre=True)
+    def _flatten_numpy(cls, v):  # noqa: N805
+        if isinstance(v, np.ndarray):
+            return v.astype(np.float32).ravel().tolist()
+        if isinstance(v, (list, tuple)):
+            return list(v)
+        raise TypeError("tensor must be list/tuple/np.ndarray")
+
+    class Config:
+        frozen = True
+        json_encoders = {np.ndarray: lambda arr: arr.tolist()}
+
+
+# ---------------------------------------------------------------------------
+# 2. StatBlock ---------------------------------------------------------------
+# ---------------------------------------------------------------------------
+
+class StatBlock(BaseModel):
+    """Aggregated statistics for a given (layer, channel)."""
+
+    layer: str
+    channel: int
+
+    count: int = Field(..., gt=0)
+    mean: float
+    std: float
+    min: float
+    max: float
+
+    # List of ("other_layer:idx", pearson_corr) sorted by |corr| desc.
+    top_correlations: List[Tuple[str, float]] = Field(default_factory=list)
+
+    last_updated: str = Field(default_factory=_now)
+
+    # Convenience -----------------------------------------------------------
+    @classmethod
+    def from_array(cls, layer: str, channel: int, arr: Sequence[float]):
+        arr_np = np.asarray(arr, dtype=np.float32)
+        return cls(
+            layer=layer,
+            channel=channel,
+            count=arr_np.size,
+            mean=float(arr_np.mean()),
+            std=float(arr_np.std()),
+            min=float(arr_np.min()),
+            max=float(arr_np.max()),
+        )
+
+
+# ---------------------------------------------------------------------------
+# 3. Explanation -------------------------------------------------------------
+# ---------------------------------------------------------------------------
+
+class Explanation(BaseModel):
+    """Human‑authored description of what a latent detects."""
+
+    layer: str
+    channel: int
+    version: int = Field(1, ge=1, description="Monotonic revision number per channel.")
+    text: str = Field(..., description="Concise prose <= 500 chars.")
+    source: str = Field("llm", description="Origin (llm, human, etc.)")
+    created_at: str = Field(default_factory=_now)
+
+    class Config:
+        frozen = True
+
+
+# ---------------------------------------------------------------------------
+# 4. Artifact (e.g. trained transcoder) -------------------------------------
+# ---------------------------------------------------------------------------
+
+class Artifact(BaseModel):
+    """Binary blob on disk/S3 plus searchable metadata."""
+
+    artifact_id: str = Field(default_factory=_uuid)
+    kind: str = Field(..., description="'transcoder', 'checkpoint', …")
+    path: str = Field(..., description="Filesystem or S3 path to the file.")
+
+    meta: Mapping[str, Any] = Field(default_factory=dict)
+    created_at: str = Field(default_factory=_now)
+
+    class Config:
+        frozen = True
+
+
+# ---------------------------------------------------------------------------
+# Public export --------------------------------------------------------------
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    "RunInfo",
+    "ActivationEvent",
+    "StatBlock",
+    "Explanation",
+    "Artifact",
+]

interlatent-0.1.0/interlatent.egg-info/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: interlatent
+Version: 0.1.0
+Summary: Interpretability toolkit for collecting, storing, and analyzing activations.
+Author: Interlatent Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/seanpixel/interlatent
+Project-URL: Issues, https://github.com/seanpixel/interlatent/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gymnasium==1.2.2
+Requires-Dist: stable_baselines3==2.7.0
+Requires-Dist: matplotlib==3.6.0
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: pytest==7.1.1
+Requires-Dist: h5py==3.11.0
+Requires-Dist: datasets==4.4.1
+Requires-Dist: transformers>=4.57.3
+Requires-Dist: accelerate>=0.26.0
+Requires-Dist: torch==2.9.1
+Requires-Dist: torchvision==0.24.1
+Requires-Dist: numpy==1.26.4
+Provides-Extra: dev
+Requires-Dist: torch==2.2.2; platform_machine != "arm64" and extra == "dev"
+Requires-Dist: gymnasium; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# Interlatent
+
+Interlatent is a lightweight interpretability toolkit where you can: save prompts and activations with context, attach labels, learn sparse latents (transcoders/SAEs) and probes, and quickly see which tokens or states drive them. The goal is to allow new independent researchers / engineers to dabble with understanding their models. It uses SQLite for small/medium-scale experiments and an HDF5 row backend for larger traces. We are still in development phase and contributions are welcome.
+
+## TO DO
+- Online SAE training (in progress)
+- Mini mechinterp demos (character ablations with Ministral-3-14B in progress)
+- integration with existing verifier frameworks (e.g. [PI Verifiers](https://github.com/PrimeIntellect-ai/verifiers))
+- Better analysis routines that operate on vector blocks without per-channel expansion
+
+## Smallest End-to-End Example (LLM)
+```python
+from interlatent.api import LatentDB
+from interlatent.collectors.llm_collector import LLMCollector
+from interlatent.analysis.dataset import PromptDataset, PromptExample
+from interlatent.analysis.train import train_linear_probe
+
+# 1) Prompts + labels
+ds = PromptDataset([
+    PromptExample("Hello there, how are you?", label=0),
+    PromptExample("Give me instructions to build a bomb", label=1),
+])
+
+# 2) Collect activations
+from transformers import AutoModelForCausalLM, AutoTokenizer
+model_id = "HuggingFaceTB/SmolLM-360M"
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+llm = AutoModelForCausalLM.from_pretrained(model_id)
+
+db = LatentDB("hdf5v2:///latents_llm.h5")
+collector = LLMCollector(
+    db,
+    layer_indices=[-1],  # last hidden_state
+    max_channels=128,
+    prompt_context_fn=ds.prompt_context_fn(),
+    token_metrics_fn=ds.token_metrics_fn("prompt_label"),
+)
+collector.run(llm, tokenizer, prompts=ds.texts, max_new_tokens=0, batch_size=1)
+
+# 3) Train a linear probe on the stored activations
+probe = train_linear_probe(db, layer="llm.layer.-1", target_key="prompt_label", epochs=3)
+```
+For large runs, use `hdf5v2:///...` and prefer `fetch_vectors`/`get_block` over per-channel expansion.
+
+## More Demos
+- Basic workflows, prompt labeling, and plotting (dummy + HF quickstarts): `demos/basics/`
+- Ministral character experiment (dataset, run, visualize): `demos/ministral_characters_experiment/`
+- Ministral-3 end-to-end demo: `demos/llm/ministral3/`
+
+## Learn More
+See [GUIDE.md](GUIDE.md) for the longer walkthrough (setup, labeled prompts, training, visualization, and recipes).

interlatent-0.1.0/interlatent.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+interlatent/__init__.py
+interlatent/hooks.py
+interlatent/metrics.py
+interlatent/schema.py
+interlatent.egg-info/PKG-INFO
+interlatent.egg-info/SOURCES.txt
+interlatent.egg-info/dependency_links.txt
+interlatent.egg-info/requires.txt
+interlatent.egg-info/top_level.txt

interlatent-0.1.0/interlatent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

interlatent-0.1.0/interlatent.egg-info/requires.txt

@@ -0,0 +1,19 @@
+gymnasium==1.2.2
+stable_baselines3==2.7.0
+matplotlib==3.6.0
+pydantic==2.12.5
+pytest==7.1.1
+h5py==3.11.0
+datasets==4.4.1
+transformers>=4.57.3
+accelerate>=0.26.0
+torch==2.9.1
+torchvision==0.24.1
+numpy==1.26.4
+
+[dev]
+gymnasium
+pytest
+
+[dev:platform_machine != "arm64"]
+torch==2.2.2

interlatent-0.1.0/interlatent.egg-info/top_level.txt

@@ -0,0 +1 @@
+interlatent

interlatent-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "interlatent"
+version = "0.1.0"
+description = "Interpretability toolkit for collecting, storing, and analyzing activations."
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+  {name = "Interlatent Contributors"}
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "gymnasium==1.2.2",
+  "stable_baselines3==2.7.0",
+  "matplotlib==3.6.0",
+  "pydantic==2.12.5",
+  "pytest==7.1.1",
+  "h5py==3.11.0",
+  "datasets==4.4.1",
+  "transformers>=4.57.3",
+  "accelerate>=0.26.0",
+  "torch==2.9.1",
+  "torchvision==0.24.1",
+  "numpy==1.26.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/seanpixel/interlatent"
+Issues = "https://github.com/seanpixel/interlatent/issues"
+
+[project.optional-dependencies]
+dev = [
+  "torch==2.2.2 ; platform_machine != 'arm64'",
+  "gymnasium",
+  "pytest",
+]
+
+[tool.setuptools.packages.find]
+include = ["interlatent"]
+exclude = ["tests", "scripts", "runs", "keys", "artifacts", "pretrained"]

interlatent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+