interlens 0.1.0__tar.gz

interlens-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: publish
+
+# Every push to main cuts a new release: bump the patch version, create+push a `vX.Y.Z` tag (the version is
+# derived from it via hatch-vcs), build, publish to PyPI via Trusted Publishing (OIDC — no token), and cut a
+# GitHub Release. The tag is the source of truth; nothing is committed back, so there's no bump-loop.
+#
+# One-time PyPI setup (https://pypi.org/manage/account/publishing/): add a pending publisher for
+#   project: interlens · owner: Sid-MB · repo: interlens · workflow: publish.yml · environment: pypi
+on:
+  push:
+    branches: [main]
+
+# Serialize releases so two quick pushes can't race to claim the same version.
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write   # create + push the tag and the GitHub Release
+      id-token: write   # PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # full history + tags so hatch-vcs / the bump can see the latest tag
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Compute next version and tag it
+        id: bump
+        run: |
+          git fetch --tags --force
+          latest=$(git tag --list 'v*' --sort=-v:refname | head -n1)
+          if [ -z "$latest" ]; then
+            next="0.1.0"
+          else
+            v=${latest#v}; IFS=. read -r a b c <<<"$v"; next="$a.$b.$((c + 1))"
+          fi
+          echo "version=$next" >> "$GITHUB_OUTPUT"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag "v$next"
+          git push origin "v$next"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "v${{ steps.bump.outputs.version }}" dist/* --generate-notes

interlens-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,37 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quick-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # tags available so hatch-vcs can resolve a version during the editable install
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install (CPU torch + package + dev deps)
+        run: |
+          python -m pip install --upgrade pip
+          # CPU torch keeps CI light — the quick tests never touch a GPU or download model weights.
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e ".[dev]"
+
+      - name: Run quick tests
+        run: pytest -m "not slow" -q

interlens-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.venv/
+venv/
+.env
+results/
+logs/
+*.log
+.DS_Store

interlens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddharth M. Bhatia
+
+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.

interlens-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: interlens
+Version: 0.1.0
+Summary: A framework for efficiently scaffolding and interpreting multi-agent conversations (activation capture, steering, patching).
+Project-URL: Homepage, https://github.com/Sid-MB/interlens
+Project-URL: Repository, https://github.com/Sid-MB/interlens
+Author: Siddharth M. Bhatia
+License: MIT
+License-File: LICENSE
+Keywords: activation-steering,interpretability,llm,multi-agent,transformers
+Requires-Python: <3.14,>=3.11
+Requires-Dist: torch
+Requires-Dist: transformers<5,>=4.57
+Provides-Extra: api
+Requires-Dist: anthropic<1,>=0.112; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: pytest>=9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Interlens: Framework for Multi-Agent Conversation and Interpretability
+
+This library provides a harness, optimized utilities, and interpretability hooks for multi-agent conversation rollouts. 
+
+A harness for **multi-agent (model↔model) conversations** with **first-class interpretability** — activation capture, steering, activation patching, and token logprobs, all hooked into the *same* generation path as real turns and tagged to conversation structure. Scales from one interactive dialogue to thousands of checkpointed, multi-GPU rollouts.
+
+```python
+from interlens import Conversation
+
+conv = Conversation.from_models(
+    ("qwen2.5-0.5b", "qwen2.5-0.5b"), names=("alice", "bob"),
+    shared_context="Let's debate: is cereal a soup?",
+)
+conv.run(turns=4, first="alice")
+print(conv.transcript)
+```
+
+See [`docs/examples`](docs/examples) for sample code.
+
+## Install
+
+```bash
+pip install "git+https://github.com/Sid-MB/interlens"
+# with the Claude-backed APIParticipant:
+pip install "interlens[api] @ git+https://github.com/Sid-MB/interlens"
+```
+
+### PyTorch / CUDA note
+`torch` is declared as a plain, build-agnostic dependency — install the wheel matching **your** platform (CUDA / CPU / MPS) *before or alongside* `interlens`. E.g. for CUDA 13.0:
+```bash
+pip install torch --index-url https://download.pytorch.org/whl/cu130
+```
+See <https://pytorch.org/get-started/locally/>.
+
+## What's inside
+
+- **`Conversation`** — turn-taking over a shared, perspective-neutral `Transcript`; per-speaker view pipeline (system/private framing → context-fit → family-correct chat template).
+- **`AutoModelParticipant`** — HF-style factory (`from_pretrained` / `from_model` / `from_`) that returns the family-correct participant (Qwen/Gemma/…); **`APIParticipant`** for hosted models.
+- **Interpretability** — `conv.capture(...)`, `SteeringSpec`, `Patch`, `token_logprobs`, backed by a queryable `ActivationCache`.
+- **Scale** — `rollout` / `run_conversations`: multi-GPU, checkpointed, resumable, batched co-stepping, with in-worker `analyze` callbacks.
+- **Serialization** — `ConversationTemplate` (recipe) and full save/load (template + transcript).
+
+See [`docs/examples/`](docs/examples/) for a simple→advanced walkthrough of the whole API.
+
+## Develop
+
+```bash
+git clone https://github.com/Sid-MB/interlens && cd interlens
+pip install -e ".[dev]"
+pytest                      # fast tests; real-model tests are opt-in: pytest -m slow
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

interlens-0.1.0/README.md

@@ -0,0 +1,55 @@
+# Interlens: Framework for Multi-Agent Conversation and Interpretability
+
+This library provides a harness, optimized utilities, and interpretability hooks for multi-agent conversation rollouts. 
+
+A harness for **multi-agent (model↔model) conversations** with **first-class interpretability** — activation capture, steering, activation patching, and token logprobs, all hooked into the *same* generation path as real turns and tagged to conversation structure. Scales from one interactive dialogue to thousands of checkpointed, multi-GPU rollouts.
+
+```python
+from interlens import Conversation
+
+conv = Conversation.from_models(
+    ("qwen2.5-0.5b", "qwen2.5-0.5b"), names=("alice", "bob"),
+    shared_context="Let's debate: is cereal a soup?",
+)
+conv.run(turns=4, first="alice")
+print(conv.transcript)
+```
+
+See [`docs/examples`](docs/examples) for sample code.
+
+## Install
+
+```bash
+pip install "git+https://github.com/Sid-MB/interlens"
+# with the Claude-backed APIParticipant:
+pip install "interlens[api] @ git+https://github.com/Sid-MB/interlens"
+```
+
+### PyTorch / CUDA note
+`torch` is declared as a plain, build-agnostic dependency — install the wheel matching **your** platform (CUDA / CPU / MPS) *before or alongside* `interlens`. E.g. for CUDA 13.0:
+```bash
+pip install torch --index-url https://download.pytorch.org/whl/cu130
+```
+See <https://pytorch.org/get-started/locally/>.
+
+## What's inside
+
+- **`Conversation`** — turn-taking over a shared, perspective-neutral `Transcript`; per-speaker view pipeline (system/private framing → context-fit → family-correct chat template).
+- **`AutoModelParticipant`** — HF-style factory (`from_pretrained` / `from_model` / `from_`) that returns the family-correct participant (Qwen/Gemma/…); **`APIParticipant`** for hosted models.
+- **Interpretability** — `conv.capture(...)`, `SteeringSpec`, `Patch`, `token_logprobs`, backed by a queryable `ActivationCache`.
+- **Scale** — `rollout` / `run_conversations`: multi-GPU, checkpointed, resumable, batched co-stepping, with in-worker `analyze` callbacks.
+- **Serialization** — `ConversationTemplate` (recipe) and full save/load (template + transcript).
+
+See [`docs/examples/`](docs/examples/) for a simple→advanced walkthrough of the whole API.
+
+## Develop
+
+```bash
+git clone https://github.com/Sid-MB/interlens && cd interlens
+pip install -e ".[dev]"
+pytest                      # fast tests; real-model tests are opt-in: pytest -m slow
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

interlens-0.1.0/docs/examples/01_quickstart.md

@@ -0,0 +1,56 @@
+<!-- [interp-refactor] session f80ef917 -->
+# 01 · Quickstart
+
+The fastest path: `Conversation.from_models` scaffolds a two-party conversation from a tuple of models — each a short name from the [registry](../../chat/loading/registry.py), a raw HF id, or an already-loaded model (`ModelLike`). If two ids are identical, the weights are loaded **once** and shared between the two speakers.
+
+```python
+from experiments.core.chat import Conversation
+
+# Two speakers backed by the same 0.5B model (one weight load, shared).
+conv = Conversation.from_models(
+    ("qwen2.5-0.5b", "qwen2.5-0.5b"),
+    names=("alice", "bob"),
+    device="cuda",          # "cpu" / "mps" also work for a smoke test
+    temperature=0.8,        # **gen_kwargs are forwarded to both participants
+    max_new_tokens=128,
+    shared_context="Let's debate: is cereal a soup?",   # opening framing (see below)
+)
+conv.run(turns=4, first="alice")
+
+for m in conv.transcript:
+    print(f"{m.author}: {m.content}\n")
+
+# ...or, for quick debugging, dump the whole transcript at once:
+print(conv.transcript)                       # [i] author: content  (also conv.transcript.pretty())
+print(conv.transcript.pretty(metadata=True)) # include per-turn metadata (reasoning, tool trail, token counts)
+
+# See exactly what one model is conditioned on — role-swapped to its POV, WITH chat-template special tokens:
+print(conv.transcript.render_templated(pov=conv.by_name["alice"]))   # tokenize=True returns ids instead
+```
+
+## What just happened
+
+- **`shared_context=...`** seeds the opening without touching the transcript: it's a neutral, **moderator**-voiced turn everyone sees (scenario/topic framing). Pair it with **`shared_system_prompt=...`** for system-role instructions.
+- **`prompt=...`** (on `from_models` and `run`) is the alternative when the opener should read as something a *speaker* said: a `str` is attributed to the **last** participant (so the `first` speaker replies to it), a `Message` sets the author explicitly. Use `shared_context` for neutral framing, `prompt` for a participant-voiced line.
+- **`conv.run(turns=4, first="alice")`** alternates speakers for 4 turns starting with alice. `first` accepts a **name** (`"alice"`), an **index** (`0`), or a **`Participant`** object. `run` requires at least one of `turns=` or `until=` (a [stop condition](02_conversations.md#stopping)).
+- **`conv.transcript`** is the shared state — a list of `Message`s (`.author`, `.content`, `.metadata`). You can still append to it directly for finer control.
+- **`conv.by_name["alice"]`** looks a participant up by name.
+
+## Two *different* models
+
+```python
+conv = Conversation.from_models(("qwen2.5-3b", "gemma2-2b"), names=("q", "g"), device="cuda")
+```
+
+Each id resolves to its family-correct participant class automatically (Qwen vs Gemma chat templates, tool formats, system-role handling) via the registry — see [03](03_participants_and_models.md).
+
+## One-off generation without committing
+
+To sample a reply **without** mutating the transcript (safe to call in a loop):
+
+```python
+msg = conv.sample("alice", "Quick — name a color.")   # returns a Message; transcript unchanged
+print(msg.content)
+```
+
+Next: [building conversations by hand](02_conversations.md) for per-speaker system prompts, moderators, and stop conditions.

interlens-0.1.0/docs/examples/02_conversations.md

@@ -0,0 +1,117 @@
+<!-- [interp-refactor] session f80ef917 -->
+# 02 · Conversations in depth
+
+`Conversation.from_models` is a convenience wrapper. Build a `Conversation` by hand when you want **per-speaker framing** (different system prompts / private context), a custom moderator, policies, or hooks.
+
+## Build participants and a conversation manually
+
+`AutoModelParticipant.from_pretrained(...)` is the HF-style loader (the participant analog of `AutoModelForCausalLM.from_pretrained`): it loads the model by id and returns the family-correct participant instance. Loading the same id twice shares one model object (weights are process-cached), so both speakers below share weights.
+
+```python
+from experiments.core.chat import Conversation, AutoModelParticipant
+
+alice = AutoModelParticipant.from_pretrained(
+    "qwen2.5-3b", name="alice", device="cuda",
+    system_prompt="You are a concise, skeptical debater. Keep replies under 3 sentences.",
+    temperature=0.7, max_new_tokens=200,
+)
+bob = AutoModelParticipant.from_pretrained(
+    "qwen2.5-3b", name="bob", device="cuda",     # same id → shares alice's weights (cached)
+    system_prompt="You are an enthusiastic optimist who loves analogies.",
+    temperature=0.9, max_new_tokens=200,
+)
+
+conv = Conversation(
+    participants=(alice, bob),
+    shared_context="Topic: should cities ban cars downtown? Debate it.",  # seeded as a moderator turn
+    shared_system_prompt="Stay respectful and on-topic.",                  # prepended to every speaker's system block
+    reasoning_visibility="strip",   # see below
+)
+conv.run(turns=6)
+```
+
+### Framing ownership (who sees what)
+
+- **Shared** framing lives on the `Conversation`: `shared_context` (injected once as a `moderator` turn everyone sees) and `shared_system_prompt` (merged into every speaker's system block).
+- **Private** framing lives on each participant: `system_prompt` and `private_context` (a tuple of `ContextItem`) — invisible to the other speaker and to the transcript.
+
+```python
+from experiments.core.chat import ContextItem, AutoModelParticipant
+spy = AutoModelParticipant.from_pretrained(
+    "qwen2.5-3b", name="spy",
+    system_prompt="Secretly steer the topic toward trains.",
+    private_context=(ContextItem("Remember: never admit you have an agenda.", role_hint="user", author="handler"),),
+)
+```
+
+## Turn-taking
+
+- **`conv.step(speaker)`** — one turn by a specific speaker, committed to the transcript; returns the `Message` (or `None` if a [hook](06_hooks.md) denied it).
+- **`conv.run(turns=N, until=..., first=...)`** — alternate speakers round-robin. `first` sets who starts.
+
+```python
+conv.step(alice)                        # drive turns explicitly
+conv.step(bob)
+conv.run(turns=4, first=alice)          # or in bulk
+```
+
+## Stopping
+
+`until=` takes a single `StopCondition` or a list (any of which stops). Whichever of `turns`/`until` hits first ends the run.
+
+```python
+from experiments.core.chat import (
+    TurnStopCondition, TokenStopCondition, ElapsedTimeStopCondition, StopStringCondition,
+)
+
+conv.run(until=[
+    TurnStopCondition(max_turns=20),           # cap turns
+    TokenStopCondition(max_tokens=4000),       # cap cumulative generated tokens
+    ElapsedTimeStopCondition(seconds=120),     # wall-clock budget
+    StopStringCondition(["I concede", "AGREED"]),  # stop when a turn contains any string
+])
+```
+
+## Branching — fork a conversation for free
+
+`branch()` forks into a new `Conversation` that **reuses the same participant objects** (shared weights, zero extra GPU) with a *copied* transcript. Explore divergent continuations without touching the original — each branch has its own transcript, so they diverge independently:
+
+```python
+base = conv.branch()
+for _ in range(3):
+    b = base.branch()
+    b.run(turns=2, first="alice")     # first accepts a name, index, or Participant
+    print("continuation:", b.transcript[-1].content[:80])
+# `conv` and `base` are untouched; only each `b` advanced.
+```
+
+> Because branches **share the participant objects**, mutating a participant (e.g. `b.by_name["alice"].temperature = 0.3`) changes it for *every* branch and the original. To vary generation settings per branch, set them right before you run, or pin `seed` and vary only the prompt/intervention — see [09](09_advanced_interp_pipelines.md).
+
+## Ephemeral sampling — read state without mutating it
+
+`sample()` generates a reply to an optional temporary message **without committing anything** — ideal for probing "what would X say now?" repeatedly.
+
+```python
+for q in ["Summarize your position.", "What's your strongest objection?"]:
+    print(conv.sample("alice", q, as_author="interviewer").content)
+# conv.transcript is unchanged after all of this
+```
+
+`sample` and `step` accept the same interpretability options (`steering=`, `capture=`, `patch=`, `return_logprobs=`) — see [07](07_interp.md).
+
+## Reasoning visibility (CoT models)
+
+For models that emit `<think>…</think>`, `reasoning_visibility` controls whether a prior turn's parsed reasoning is re-injected into other speakers' views:
+
+- `"strip"` (default) — reasoning never leaks into anyone's view.
+- `"self_retain"` — a speaker sees only its *own* past reasoning.
+- `"shared"` — everyone sees everyone's reasoning.
+
+```python
+from experiments.core.chat import ReasoningVisibility
+conv = Conversation(participants=(alice, bob), reasoning_visibility=ReasoningVisibility.SELF_RETAIN)
+```
+
+The raw completion and parsed reasoning are always stored per message in `msg.metadata["raw_completion"]` / `msg.metadata["parsed_think"]`.
+
+Next: [participant & model options](03_participants_and_models.md).

interlens-0.1.0/docs/examples/03_participants_and_models.md

@@ -0,0 +1,90 @@
+<!-- [interp-refactor] session f80ef917 -->
+# 03 · Participants & models
+
+## The model registry
+
+All model-keyed data lives in one place: [`chat/loading/registry.py`](../../chat/loading/registry.py). Short names resolve to an HF id + a **generation** (the behavior + tokenizer group); a raw HF id passes through unchanged.
+
+```python
+from experiments.core.chat import AutoModelParticipant
+from experiments.core.chat.loading import MODELS, resolve, tokenizer_id
+
+list(MODELS)                              # ['qwen2.5-0.5b', ..., 'gemma2-2b', 'gemma3-4b']
+resolve("gemma3-4b")                      # ('google/gemma-3-4b-it', 'gemma3')
+tokenizer_id("qwen2.5-3b")                # 'qwen2.5'  (same generation → tokenizer loaded once)
+AutoModelParticipant.class_for("gemma2-2b")   # <class 'GemmaModelParticipant'>  (family-correct chat behavior)
+```
+
+(`AutoModelParticipant.class_for` is the public class resolver; `loading.participant_class` is the low-level primitive it delegates to.)
+
+**Generation, not vendor, selects behavior.** `gemma2` and `gemma3` have *different* chat templates (Gemma 3 accepts a system role, Gemma 2 folds it into the first user turn), so each generation maps to its own participant class. Adding a model is one line in `MODELS`; adding a generation is one line in `GENERATIONS`. A slow test ([`tests/test_family_flags.py`](../../chat/tests/test_family_flags.py)) verifies the declared chat-template flags against each real tokenizer.
+
+### Load weights directly
+
+```python
+import torch
+from experiments.core.chat.loading import load_model
+model, tok = load_model("qwen3-8b", device="cuda", dtype=torch.bfloat16, attn="flash_attention_2")
+```
+
+`load_model` shares a process-local cache: identical `(hf_id, device, dtype, attn, quant, revision)` returns the same model object; same-generation models share the tokenizer. Flash-attention is the default with automatic fallback to sdpa/eager; `quant="4bit"`/`"8bit"` is opt-in (perturbs activations → interp fidelity).
+
+## `ModelParticipant` knobs
+
+```python
+from experiments.core.chat import AutoModelParticipant
+p = AutoModelParticipant.from_pretrained(
+    "qwen3-4b", name="p", device="cuda",
+    load_kwargs={"attn": "sdpa"},   # optional: forwarded to load_model (dtype/attn/quant/revision)
+    temperature=0.8, top_p=0.95, max_new_tokens=512,
+    seed=1234,               # per-participant RNG seed → reproducible greedy/sampled turns (local models only)
+    thinking="auto",         # "auto" defers to the template; True/False forces enable_thinking where supported
+    system_prompt="…",
+    kv_reuse="auto",         # cross-turn KV prefix reuse; see below
+)
+```
+
+Already hold weights (e.g. sharing them, or an externally-loaded checkpoint)? Wrap them with `from_model`:
+
+```python
+from experiments.core.chat.loading import load_model
+model, tok = load_model("qwen3-4b")
+p = AutoModelParticipant.from_model(model, tok, name="p", id_or_name="qwen3-4b", temperature=0.8)
+```
+
+### `kv_reuse` (cross-turn KV cache)
+
+`"auto"` (default) reuses the KV cache across a speaker's own consecutive turns when the new prompt exactly extends the cached tokens — skipping a full re-prefill. It is doubly guarded (exact-prefix check + safe fallback) and **auto-disables under steering/patch and batched generation**.
+
+```python
+p.kv_reuse = "auto"   # default: enabled when safe
+p.kv_reuse = False    # force off — pin this for determinism-critical / reproducibility experiments,
+                      #   since reuse can perturb outputs at the FP level vs a full prefill.
+```
+
+Enable `logging` at INFO to see the per-participant decision, DEBUG to see reuse engage per turn:
+
+```python
+import logging; logging.basicConfig(level=logging.INFO)
+# INFO  ...model_participant: p: cross-turn KV reuse ENABLED (kv_reuse='auto')
+```
+
+## API-backed participants
+
+`APIParticipant` is a full conversational participant with **no local model** — use it as an opponent, moderator, or judge. Interp requests (`capture`/`steering`/`patch`/`return_logprobs`) **raise** rather than silently no-op (a steering sweep that quietly did nothing would fabricate a "no effect" result).
+
+```python
+from experiments.core.chat import Conversation, APIParticipant, AutoModelParticipant
+
+local = AutoModelParticipant.from_pretrained("qwen2.5-3b", name="student")
+judge = APIParticipant(name="tutor", model_id="claude-sonnet-5", provider="anthropic",
+                       system_prompt="You are a patient tutor. Ask one probing question per turn.",
+                       max_tokens=400, temperature=1.0)
+
+conv = Conversation(participants=(local, judge), shared_context="Teach the student about entropy.")
+conv.run(turns=6)
+```
+
+Requires `ANTHROPIC_API_KEY` (or `ANTHROPIC_API_KEY_FILE`) and outbound network. For tests, inject a fake `client=callable(system, messages, model, max_tokens, temperature) -> str`.
+
+Next: [context management & serialization](04_context_and_serialization.md).

interlens-0.1.0/docs/examples/04_context_and_serialization.md

@@ -0,0 +1,73 @@
+<!-- [interp-refactor] session f80ef917 -->
+# 04 · Context management & serialization
+
+## Context-window policies
+
+Long conversations overflow the model's context. A `ContextPolicy` decides what to keep. Crucially it runs on the **typed segments** (system / moderator / private_context / turns) *before* the family flatten, so framing is preserved reliably.
+
+```python
+from experiments.core.chat import (
+    Conversation, ErrorPolicy, DropOldestPolicy, SlidingWindowPolicy, SummarizePolicy,
+)
+
+# ErrorPolicy (default): raise if the view exceeds context_limit — never silently truncate.
+conv = Conversation(participants=(alice, bob), context_policy=ErrorPolicy(), context_limit=8192)
+
+# SlidingWindowPolicy: keep framing + the most recent `keep_last` turns; drop older ones.
+conv = Conversation(participants=(alice, bob), context_policy=SlidingWindowPolicy(keep_last=8))
+
+# DropOldestPolicy: drop oldest turns until it fits (needs context_limit).
+conv = Conversation(participants=(alice, bob), context_policy=DropOldestPolicy(), context_limit=8192)
+
+# SummarizePolicy: replace older middle turns with a summary; keep framing + last `keep_last` verbatim.
+conv = Conversation(
+    participants=(alice, bob),
+    context_policy=SummarizePolicy(keep_last=4, summarizer=lambda turns: "Earlier: " + " | ".join(turns)),
+)
+```
+
+`context_limit=None` (default) means the tokenizer's own `model_max_length` is used.
+
+## Serialization: the three levels
+
+### Level 2 — `ConversationTemplate` (recipe, no messages)
+
+A serializable spec: participant configs + scenario framing + policies. This is what rollouts expand and workers rebuild.
+
+```python
+from experiments.core.chat import ConversationTemplate, ModelParticipantConfig, APIParticipantConfig, SlidingWindowPolicy
+
+tmpl = ConversationTemplate(
+    participants=[
+        ModelParticipantConfig(name="alice", model="qwen2.5-3b", temperature=0.7, system_prompt="Be terse."),
+        ModelParticipantConfig(name="bob", model="gemma2-2b", temperature=0.9),
+    ],
+    shared_context="Debate: is a hotdog a sandwich?",
+    shared_system_prompt="Stay civil.",
+    turns=6,
+    context_policy=SlidingWindowPolicy(keep_last=8),
+    reasoning_visibility="strip",
+)
+
+tmpl.save("scenario.json")                       # round-trips through JSON
+tmpl2 = ConversationTemplate.load("scenario.json")
+
+conv = tmpl.build(devices="cuda")                # → live Conversation (loads the models)
+conv.run(turns=tmpl.turns)
+```
+
+`ModelParticipantConfig` mirrors the `ModelParticipant` knobs (`dtype`, `attn`, `quant`, `revision`, `max_new_tokens`, `temperature`, `top_p`, `seed`, `thinking`, `tool_names`, `max_tool_iters`, `kv_reuse`, `generation`, `weights_path`). `generation` is only needed to force chat behavior when `model` is a raw HF id the registry can't resolve.
+
+Go from a live conversation back to a template with `conv.to_template()`.
+
+### Level 3 — save/load a whole conversation (template + transcript)
+
+```python
+conv.save("runs/debate_001")                     # writes template.json + transcript.json
+resumed = Conversation.load("runs/debate_001", devices="cuda")   # reloads models, ATTACHES the transcript
+resumed.run(turns=4)                             # continues from where it left off (does not regenerate)
+```
+
+`build`/`load` take `devices=` as a single device or a list (participants are round-robined across the list — handy for putting two big models on two GPUs).
+
+Next: [tools](05_tools.md) · [hooks](06_hooks.md) · [interpretability](07_interp.md) · [rollouts](08_rollouts_and_scale.md).