verifiers 0.2.1.dev20__tar.gz → 0.2.1.dev22__tar.gz

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: verifiers
-Version: 0.2.1.dev20
+Version: 0.2.1.dev22
 Summary: Verifiers: Environments for LLM Reinforcement Learning
 Project-URL: Homepage, https://github.com/primeintellect-ai/verifiers
 Project-URL: Documentation, https://github.com/primeintellect-ai/verifiers

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/tests/v1/test_color_codeword_tasks.py

@@ -10,9 +10,9 @@ def test_color_images_are_rendered_once(monkeypatch) -> None:
         return render(color, size)
 
     monkeypatch.setattr(taskset, "color_data_url", counted)
-    tasks = taskset.ColorCodewordTaskset(
-        taskset.ColorCodewordConfig(num_examples=100)
-    ).load()
+    tasks = taskset.ColorCodewordTaskset(taskset.ColorCodewordConfig()).select(
+        num_tasks=100
+    )
 
     assert len(tasks) == 100
     assert calls == list(taskset.COLOR_MAP)

verifiers-0.2.1.dev22/tests/v1/test_taskset.py

@@ -0,0 +1,71 @@
+"""`Taskset.select` over list, generator, and `INFINITE` `load` implementations."""
+
+import itertools
+
+import pytest
+
+import verifiers.v1 as vf
+
+
+class CountTask(vf.Task[vf.TaskData]):
+    pass
+
+
+class InfiniteTaskset(vf.Taskset[CountTask, vf.TasksetConfig]):
+    INFINITE = True
+
+    def load(self):
+        for i in itertools.count():
+            yield CountTask(vf.TaskData(idx=i, prompt=f"task {i}"))
+
+
+class FiniteTaskset(vf.Taskset[CountTask, vf.TasksetConfig]):
+    def load(self):
+        for i in range(10):
+            yield CountTask(vf.TaskData(idx=i, prompt=f"task {i}"))
+
+
+def idxs(tasks: list[CountTask]) -> list[int]:
+    return [task.data.idx for task in tasks]
+
+
+def test_select_bounds_an_infinite_taskset() -> None:
+    tasks = InfiniteTaskset(vf.TasksetConfig()).select(num_tasks=5)
+    assert idxs(tasks) == [0, 1, 2, 3, 4]
+
+
+def test_select_infinite_requires_num_tasks() -> None:
+    with pytest.raises(ValueError, match="infinite"):
+        InfiniteTaskset(vf.TasksetConfig()).select()
+
+
+def test_select_infinite_ignores_shuffle() -> None:
+    tasks = InfiniteTaskset(vf.TasksetConfig()).select(num_tasks=3, shuffle=True)
+    assert idxs(tasks) == [0, 1, 2]
+
+
+def test_select_finite() -> None:
+    taskset = FiniteTaskset(vf.TasksetConfig())
+    assert len(taskset.select()) == 10
+    assert idxs(taskset.select(num_tasks=4)) == [0, 1, 2, 3]
+
+
+def test_select_shuffle_samples_the_whole_taskset_reproducibly() -> None:
+    taskset = FiniteTaskset(vf.TasksetConfig())
+    first = idxs(taskset.select(num_tasks=5, shuffle=True))
+    assert first == idxs(taskset.select(num_tasks=5, shuffle=True))
+    assert len(first) == 5 and set(first) <= set(range(10))
+    assert first != [0, 1, 2, 3, 4]  # sampled from the whole set, not the head
+
+
+def test_select_only_builds_what_the_run_takes() -> None:
+    built: list[int] = []
+
+    class RecordingTaskset(InfiniteTaskset):
+        def load(self):
+            for i in itertools.count():
+                built.append(i)
+                yield CountTask(vf.TaskData(idx=i, prompt=f"task {i}"))
+
+    RecordingTaskset(vf.TasksetConfig()).select(num_tasks=3)
+    assert built == [0, 1, 2]

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/cli/debug.py

@@ -30,7 +30,6 @@ from verifiers.v1.task import Task
 from verifiers.v1.trace import Error, Trace, TraceTask
 from verifiers.v1.utils.interrupt import install_interrupt
 from verifiers.v1.utils.logging import setup_logging
-from verifiers.v1.utils.sampling import sample
 
 logger = logging.getLogger(__name__)
 
@@ -274,7 +273,7 @@ async def debug_task(task: Task, config: DebugConfig) -> tuple[Trace, bool]:
 
 async def run_debug(config: DebugConfig) -> list[Trace]:
     taskset = vf.load_taskset(config.taskset)
-    tasks = sample(taskset.load(), config.shuffle, config.num_tasks)
+    tasks = taskset.select(config.num_tasks, config.shuffle)
     if isinstance(config.runtime, vf.SubprocessConfig) and any(
         type(t).NEEDS_CONTAINER or t.data.image for t in tasks
     ):

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/cli/eval/runner.py

@@ -21,7 +21,7 @@ logger = logging.getLogger(__name__)
 async def run_eval(env: Environment, config: EvalConfig) -> list[Trace]:
     logger.info("eval config:\n%s", config.model_dump_json(indent=2))
     client = resolve_client(config.client)
-    tasks = sample(env.taskset.load(), config.shuffle, config.num_tasks)
+    tasks = env.taskset.select(config.num_tasks, config.shuffle)
     ctx = ModelContext(client=client, model=config.model, sampling=config.sampling)
     # One episode of `num_rollouts` rollouts per task; the shared semaphore bounds total
     # concurrent rollouts (across episodes), so group rewards still see their whole episode.
@@ -70,7 +70,7 @@ async def run_eval(env: Environment, config: EvalConfig) -> list[Trace]:
         await append_trace(out, trace, write_lock)
 
     # Shared tool servers (if any) come up once here and their URLs flow into every rollout
-    # (non-shared ones start per rollout inside the episodes); the interception pool comes up
+    # (non-shared ones start per rollout inside the episodes); the interception comes up
     # here too, so concurrent rollouts share its servers + tunnels rather than one each. Build
     # episodes inside `serving` so each rollout is wired to those resources at construction.
     async with env.serving():
@@ -162,7 +162,20 @@ async def run_eval_server(config: EvalConfig) -> list[Trace]:
         await client.wait_for_server_startup(timeout=600)
         info = await client.info()
         group_scored = info.requires_group_scoring
-        idxs = sample(list(range(info.num_tasks)), config.shuffle, config.num_tasks)
+        if info.num_tasks is None:  # infinite taskset - the run must be bounded
+            if config.num_tasks is None:
+                raise ValueError(
+                    f"{config.env_id} is infinite - bound the run with -n/--num-tasks"
+                )
+            if config.shuffle:
+                logger.warning(
+                    "shuffle is a no-op on an infinite taskset - "
+                    "taking the first %d generated tasks",
+                    config.num_tasks,
+                )
+            idxs = list(range(config.num_tasks))
+        else:
+            idxs = sample(list(range(info.num_tasks)), config.shuffle, config.num_tasks)
         out = output_path(config)
         finished: list[Trace] = []
         if config.resume is not None:

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/cli/gepa.py

@@ -60,7 +60,7 @@ def main(argv: list[str] | None = None) -> None:
         return
 
     # First Ctrl-C / SIGTERM warns and raises KeyboardInterrupt so a killed/timed-out run still
-    # runs the runner's `serving()` teardown (interception pool / tool-server runtimes); further
+    # runs the runner's `serving()` teardown (interception / tool-server runtimes); further
     # signals during that cleanup are swallowed so an impatient second Ctrl-C can't orphan them.
     install_interrupt()
 

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/cli/validate.py

@@ -26,7 +26,6 @@ from verifiers.v1.task import Task
 from verifiers.v1.trace import Trace, TraceTask
 from verifiers.v1.utils.interrupt import install_interrupt
 from verifiers.v1.utils.logging import setup_logging
-from verifiers.v1.utils.sampling import sample
 
 logger = logging.getLogger(__name__)
 
@@ -198,7 +197,7 @@ async def _validate_task(task: Task, config: ValidateConfig) -> ResultRow:
 
 async def run_validate(config: ValidateConfig) -> list[dict]:
     taskset = vf.load_taskset(config.taskset)
-    tasks = sample(taskset.load(), config.shuffle, config.num_tasks)
+    tasks = taskset.select(config.num_tasks, config.shuffle)
     if isinstance(config.runtime, vf.SubprocessConfig) and any(
         type(t).NEEDS_CONTAINER or t.data.image for t in tasks
     ):

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/configs/debug.py

@@ -28,6 +28,7 @@ class DebugConfig(BaseConfig):
     for the debug command/script."""
     num_tasks: int | None = Field(
         None,
+        ge=1,
         validation_alias=AliasChoices("num_tasks", "n", "num_examples", "batch_size"),
     )
     """How many tasks to debug (None = all)."""

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/configs/eval.py

@@ -22,6 +22,7 @@ class EvalConfig(EnvServerConfig):
     sampling: SamplingConfig = SamplingConfig()
     num_tasks: int | None = Field(
         None,
+        ge=1,
         validation_alias=AliasChoices("batch_size", "num_examples", "num_tasks", "n"),
     )
     """How many tasks to evaluate (None = all)."""

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/configs/validate.py

@@ -26,6 +26,7 @@ class ValidateConfig(BaseConfig):
     """Run only `Task.setup` and `Task.validate`."""
     num_tasks: int | None = Field(
         None,
+        ge=1,
         validation_alias=AliasChoices("num_tasks", "n", "num_examples", "batch_size"),
     )
     """How many tasks to validate (None = all)."""

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/env.py

@@ -12,7 +12,14 @@ from verifiers.v1.clients import ModelContext
 from verifiers.v1.decorators import discover_decorated
 from verifiers.v1.episode import Episode
 from verifiers.v1.types import ID
-from verifiers.v1.interception import InterceptionPool, RolloutLimits
+from verifiers.v1.interception import (
+    ElasticInterceptionPoolConfig,
+    Interception,
+    InterceptionConfig,
+    make_interception,
+    requires_tunnel,
+)
+from verifiers.v1.session import RolloutLimits
 from verifiers.v1.retries import RetryConfig
 from verifiers.v1.rollout import Rollout
 from verifiers.v1.runtimes import (
@@ -20,7 +27,7 @@ from verifiers.v1.runtimes import (
     SubprocessConfig,
     runtime_is_local,
 )
-from verifiers.v1.task import Task
+from verifiers.v1.task import Task, resolve_server_config
 from verifiers.v1.taskset import Taskset, TasksetConfig
 from verifiers.v1.utils.generic import generic_type
 from verifiers.v1.mcp import SharedToolServer, serve_shared
@@ -100,10 +107,11 @@ class EnvConfig(BaseConfig):
     max_total_tokens: int | None = None
     """Max total (prompt + completion) tokens per rollout (None = no limit). Caps the
     trace's `num_total_tokens`; framework-enforced between turns."""
-    multiplex: int = Field(32, ge=1)
-    """Rollouts that share one interception server (and, behind a remote runtime, one
-    tunnel). N concurrent rollouts use ~N/multiplex servers + tunnels instead of one each —
-    key past the per-token tunnel cap. 1 = a server (+ tunnel) per rollout."""
+    interception: InterceptionConfig = ElasticInterceptionPoolConfig()
+    """The interception shape (see `verifiers.v1.interception`): `elastic` (the
+    default — servers grown on demand, `multiplex` rollouts each), `server` (one server,
+    with a tunnel choice incl. a bring-your-own endpoint), or `static` (a fixed list of
+    such servers)."""
     # --- legacy (v0) backwards-compat -----------------------------------------
     id: ID | None = None
     """Classic (v0) env id (`name`, `org/name`, or `org/name@version` — installed from the
@@ -274,9 +282,9 @@ class Environment:
         )
         self._warned_resources: set[tuple[str, str]] = set()
         self._shared_tools: dict[str, SharedToolServer] = {}
-        self._interception: InterceptionPool | None = None
+        self._interception: Interception | None = None
         """Eval-level serving resources, live only inside `serving()`: shared tool servers
-        ({name: SharedToolServer}) and the interception pool. `episode()` injects them into every rollout
+        ({name: SharedToolServer}) and the interception. `episode()` injects them into every rollout
         so neither runner has to thread them through `Episode.run`/`Rollout.run`."""
 
     def runtime_for(self, task: Task) -> RuntimeConfig:
@@ -358,24 +366,44 @@ class Environment:
     @contextlib.asynccontextmanager
     async def serving(self):
         """Hold the env-level serving resources for the duration of an eval: the shared tool
-        servers (built once, see `shared_tools`) and the interception pool. Stash them so
+        servers (built once, see `shared_tools`) and the interception. Stash them so
         every `episode()` built inside this context injects them into its rollouts — that's
         what keeps both eval runners (in-process and env-server) on one serving path. Build
         episodes inside this context; the resources are torn down on exit."""
-        async with (
-            self.shared_tools() as shared,
-            self.interception_pool() as interception,
-        ):
-            self._shared_tools = shared
-            self._interception = interception
-            try:
-                yield
-            finally:
-                self._shared_tools = {}
-                self._interception = None
-
-    def interception_pool(self) -> InterceptionPool:
-        return InterceptionPool(self.harness.config.runtime, self.config.multiplex)
+        async with self.shared_tools() as shared:
+            interception = make_interception(
+                self.config.interception, requires_tunnel=self._requires_tunnel(shared)
+            )
+            async with interception:
+                self._shared_tools = shared
+                self._interception = interception
+                try:
+                    yield
+                finally:
+                    self._shared_tools = {}
+                    self._interception = None
+
+    def _requires_tunnel(self, shared: dict[str, SharedToolServer]) -> bool:
+        """`requires_tunnel` over the consumers known before any rollout: the harness
+        runtime (by config), the live `shared` servers, and the task class's tool/user
+        servers — read class-level (like `validate_pairing`) with their configs resolved
+        the way `Task.server_config` resolves them. A task that *overrides* that pairing
+        isn't statically knowable, so it conservatively counts as remote (the tunnel then
+        reaches everything; a wrongly-assumed localhost would reach nothing remote)."""
+        task_cls = generic_type(type(self.taskset), Task, origin=Taskset) or Task
+        server_classes = [*task_cls.tools, *([task_cls.user] if task_cls.user else [])]
+        if server_classes and task_cls.server_config is not Task.server_config:
+            return True
+        sole = len({*task_cls.tools} | ({task_cls.user} - {None})) == 1
+        configs = [
+            resolve_server_config(
+                task_cls.__name__, self.taskset.config.task, server_cls, sole=sole
+            )
+            for server_cls in server_classes
+        ]
+        return requires_tunnel(
+            runtime_is_local(self.harness.config.runtime), configs, shared.values()
+        )
 
     @contextlib.asynccontextmanager
     async def shared_tools(self):

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/errors.py

@@ -10,7 +10,7 @@ Four mechanisms, each in one place:
    raises plain Python errors — it never constructs a `vf` error type; `boundary` classifies them.
    Infra that fails raises its type at the source (`runtimes` → `SandboxError`, `clients` →
    `ProviderError`, tunnels → `TunnelError`); an already-typed `RolloutError` passes through unchanged.
-3. Surfacing (`interception.RolloutSession.error`): a model/tool/user call fails behind the harness
+3. Surfacing (`session.RolloutSession.error`): a model/tool/user call fails behind the harness
    subprocess and comes back as HTTP, so the interception server stashes the real error there and
    the rollout re-raises it once the harness returns — not a secondary `HarnessError`.
 4. Capture (`Rollout.run`, mirrored by the env-server): the one place that records a failure (typed

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/gepa/config.py

@@ -42,7 +42,7 @@ class GEPAConfig(EnvConfig):
     """Tasks held out to score each candidate system prompt for the pareto frontier."""
     shuffle: bool = Field(True, validation_alias=AliasChoices("shuffle", "s"))
     """Shuffle tasks before splitting into train/val — v1 tasksets have no generic train/val
-    split, so GEPA carves one out of `taskset.load()` the way `run_eval` samples (fixed
+    split, so GEPA carves one out of `Taskset.select` the way `run_eval` samples (fixed
     seed, so the split is reproducible across runs)."""
     seed: int = 0
     """Seed for GEPA's optimizer (candidate selection / minibatch sampling). Task shuffling

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/gepa/dataset.py

@@ -1,14 +1,13 @@
 """Train/val split and upfront validation for a GEPA run.
 
 v1 tasksets have no generic train/val split concept (`TasksetConfig` has no `split` field;
-individual tasksets define ad hoc ones inconsistently), so GEPA carves one out of
-`taskset.load()` itself: the shared fixed-seed shuffle (`verifiers.v1.utils.sampling.sample`,
-reproducible across runs like every other entrypoint), then two disjoint slices.
+individual tasksets define ad hoc ones inconsistently), so GEPA carves one out of the tasks
+`Taskset.select` hands it (the shared fixed-seed shuffle, reproducible across runs like every
+other entrypoint): two disjoint slices.
 """
 
 from verifiers.v1.decorators import discover_decorated
 from verifiers.v1.task import Task
-from verifiers.v1.utils.sampling import sample
 
 
 def reject_group_reward_tasksets(tasks: list[Task]) -> None:
@@ -26,19 +25,16 @@ def reject_group_reward_tasksets(tasks: list[Task]) -> None:
 
 
 def split_tasks(
-    tasks: list[Task], num_train: int, num_val: int, shuffle: bool
+    tasks: list[Task], num_train: int, num_val: int
 ) -> tuple[list[Task], list[Task]]:
-    """The taskset's tasks, split into disjoint `(train, val)` slices (`train` feeds reflection
+    """The selected tasks, split into disjoint `(train, val)` slices (`train` feeds reflection
     minibatches; `val` scores each candidate for the pareto frontier)."""
-    pool = sample(
-        tasks, shuffle
-    )  # shared fixed-seed shuffle; GEPA does its own slicing below
-    if num_train + num_val > len(pool):
+    if num_train + num_val > len(tasks):
         raise ValueError(
             f"requested {num_train} train + {num_val} val tasks, but the taskset only "
-            f"loaded {len(pool)}"
+            f"loaded {len(tasks)}"
         )
-    return pool[:num_train], pool[num_train : num_train + num_val]
+    return tasks[:num_train], tasks[num_train : num_train + num_val]
 
 
 def resolve_gepa_seed_prompt(tasks: list[Task], initial_prompt: str | None) -> str:

{verifiers-0.2.1.dev20 → verifiers-0.2.1.dev22}/verifiers/v1/gepa/runner.py

@@ -38,10 +38,8 @@ class _GEPALog:
 
 def run_gepa(env: Environment, config: GEPAConfig) -> GEPAResult:
     logger.info("gepa config:\n%s", config.model_dump_json(indent=2))
-    all_tasks = env.taskset.load()
-    train_tasks, val_tasks = split_tasks(
-        all_tasks, config.num_train, config.num_val, config.shuffle
-    )
+    all_tasks = env.taskset.select(config.num_train + config.num_val, config.shuffle)
+    train_tasks, val_tasks = split_tasks(all_tasks, config.num_train, config.num_val)
     selected_tasks = [*train_tasks, *val_tasks]
     reject_group_reward_tasksets(
         selected_tasks

verifiers-0.2.1.dev22/verifiers/v1/interception/__init__.py

@@ -0,0 +1,94 @@
+"""The interception layer.
+
+`server` catches a harness's model calls and proxies them to the client, multiplexing many
+rollouts on one server keyed by their secret — and is itself the single-server
+`Interception`. `pool` composes such servers, statically (a fixed set, e.g. bring-your-own
+endpoints) or elastically (grown on demand). `tunnel` makes a server reachable from remote
+consumers; `requires_tunnel` decides whether that's needed. `make_interception` picks the
+shape from the `InterceptionConfig` type.
+"""
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Annotated
+
+from pydantic import Field
+from pydantic_config import BaseConfig
+
+from verifiers.v1.interception.base import BaseInterceptionConfig, Interception, Slot
+from verifiers.v1.interception.pool import (
+    ElasticInterceptionPool,
+    ElasticInterceptionPoolConfig,
+    StaticInterceptionPool,
+    StaticInterceptionPoolConfig,
+)
+from verifiers.v1.interception.server import (
+    InterceptionServer,
+    InterceptionServerConfig,
+)
+from verifiers.v1.runtimes import runtime_is_local
+
+if TYPE_CHECKING:
+    from verifiers.v1.mcp import SharedToolServer
+
+# Discriminated on `type` so the CLI selects with `--interception.type server|static|elastic`.
+InterceptionConfig = Annotated[
+    InterceptionServerConfig
+    | StaticInterceptionPoolConfig
+    | ElasticInterceptionPoolConfig,
+    Field(discriminator="type"),
+]
+
+
+def requires_tunnel(
+    harness_is_local: bool,
+    server_configs: Iterable[BaseConfig] = (),
+    shared: "Iterable[SharedToolServer]" = (),
+) -> bool:
+    """Whether the interception must be exposed via a tunnel — some consumer is off the
+    host network: the harness itself, a live `shared` server in a remote runtime, or a
+    tool/user server config placing one there (each reaches the `/state` channel from
+    its own runtime). Skipped as non-consumers: a `colocated` server (shares the
+    harness's runtime, covered by `harness_is_local`), a config-`url` server (external —
+    it connects out), and an `external` shared server (outside the state machinery
+    entirely). False means every consumer reaches the server at localhost."""
+    if not harness_is_local:
+        return True
+    if any(not s.external and not s.local for s in shared):
+        return True
+    for config in server_configs:
+        if getattr(config, "url", None) or config.colocated:
+            continue
+        if not runtime_is_local(config.runtime):
+            return True
+    return False
+
+
+def make_interception(
+    config: InterceptionConfig, *, requires_tunnel: bool
+) -> Interception:
+    """The interception for a config, picked by type (the host-side counterpart to
+    `make_runtime`). With `requires_tunnel` (some consumer is off the host network — see
+    the `requires_tunnel` util) each server is exposed via its configured tunnel; without
+    it they get none and are reached at localhost. The caller computes it (see
+    `Environment._requires_tunnel`)."""
+    if isinstance(config, InterceptionServerConfig):
+        return InterceptionServer(config, requires_tunnel)
+    if isinstance(config, StaticInterceptionPoolConfig):
+        return StaticInterceptionPool(config, requires_tunnel)
+    return ElasticInterceptionPool(config, requires_tunnel)
+
+
+__all__ = [
+    "Interception",
+    "Slot",
+    "make_interception",
+    "requires_tunnel",
+    "InterceptionServer",
+    "StaticInterceptionPool",
+    "ElasticInterceptionPool",
+    "BaseInterceptionConfig",
+    "InterceptionConfig",
+    "InterceptionServerConfig",
+    "StaticInterceptionPoolConfig",
+    "ElasticInterceptionPoolConfig",
+]

verifiers-0.2.1.dev22/verifiers/v1/interception/base.py

@@ -0,0 +1,68 @@
+"""The interception contract: hand each rollout a slot on a host interception server.
+
+Three shapes, picked by `InterceptionConfig` type (see `make_interception`): a single
+`InterceptionServer`, a fixed `StaticInterceptionPool`, or an on-demand
+`ElasticInterceptionPool`. From the outside they behave the same: start/stop (or the async
+context manager wrapping them) bound the lifecycle — one eval, one topology run, or one
+agent `.run` — and each rollout `acquire`s a slot and frees it. An `Interception` can be
+shared: whoever entered it owns the lifecycle; borrowers only `acquire`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from contextlib import AbstractAsyncContextManager, AsyncExitStack
+from typing import TYPE_CHECKING, Self
+
+from pydantic_config import BaseConfig
+
+if TYPE_CHECKING:
+    from verifiers.v1.session import RolloutSession
+
+
+class BaseInterceptionConfig(BaseConfig):
+    """Base for the interception types — the discriminated union's common type. Per-type
+    fields live on the subclasses (server's `tunnel`, static's `servers`, elastic's
+    `multiplex`)."""
+
+
+# (base_url, secret): the interception server's reachable base URL for this rollout, and the
+# bearer the harness/tool/user servers authenticate with. The harness reaches the model at
+# `{base_url}/v1`; tool/user servers reach this rollout's shared state at `{base_url}/state`
+# + `/task`. `base_url` is universally reachable — the interception is exposed (tunnel)
+# whenever any consumer is remote.
+Slot = tuple[str, str]
+
+
+class Interception(ABC):
+    """How rollouts reach the host interception server. `start` brings the servers up (or
+    arms lazy growth), `stop` tears every server (+ its tunnel) down via `stack` — LIFO,
+    even if one teardown fails; `async with` wraps the two. Each rollout `acquire`s a slot
+    and frees it on exit."""
+
+    def __init__(self) -> None:
+        self.stack = AsyncExitStack()
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Bring the interception up; resources land on `stack` so `stop` frees them."""
+
+    async def stop(self) -> None:
+        await self.stack.aclose()
+
+    async def __aenter__(self) -> Self:
+        try:
+            await self.start()
+        except BaseException:
+            # unwind whatever `start` already put on the stack
+            await self.stop()
+            raise
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.stop()
+
+    @abstractmethod
+    def acquire(self, session: RolloutSession) -> AbstractAsyncContextManager[Slot]:
+        """Register `session` on a server (bringing one up if needed) and yield its `Slot`;
+        free it on exit."""