verifiers 0.2.2.dev42__tar.gz → 0.2.2.dev43__tar.gz

{verifiers-0.2.2.dev42 → verifiers-0.2.2.dev43}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: verifiers
-Version: 0.2.2.dev42
+Version: 0.2.2.dev43
 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.2.dev42 → verifiers-0.2.2.dev43}/tests/v1/conftest.py

@@ -180,7 +180,7 @@ def _eval_config(
         },
         rich=False,
         output_dir=output_dir,
-        **({"pool": pool} if pool else {}),
+        **({"serve": {"pool": pool}} if pool else {}),
         **({"model": model} if model else {}),
     )
 
@@ -237,7 +237,7 @@ async def live_ctx():
 
 @pytest.fixture
 def run_v0():
-    """Run a legacy v0 env through the v1 bridge (the eval CLI's `--id` path)."""
+    """Run a legacy v0 env through the v1 bridge (the eval CLI's `--legacy.id` path)."""
     from verifiers.v1.legacy import run_legacy_eval
 
     async def _run(
@@ -249,8 +249,7 @@ def run_v0():
         args: dict | None = None,
     ) -> list[Trace]:
         config = EvalConfig(
-            id=env_id,
-            args=args or {},
+            legacy={"id": env_id, "args": args or {}},
             num_tasks=1,
             num_rollouts=n,
             sampling={"max_tokens": max_tokens, "temperature": 0},

{verifiers-0.2.2.dev42 → verifiers-0.2.2.dev43}/verifiers/v1/__init__.py

@@ -14,16 +14,18 @@ from verifiers.v1.clients import (
     resolve_client,
 )
 from verifiers.v1.configs.agent import AgentConfig
-from verifiers.v1.configs.cli.env import (
-    ElasticPoolConfig,
-    EnvServerConfig,
-    StaticPoolConfig,
-    pool_serve_kwargs,
-)
+from verifiers.v1.configs.cli.env import narrowed_env_annotation, resolve_env_field
 from verifiers.v1.configs.env import EnvConfig, default_agent_harness
 from verifiers.v1.configs.harness import HarnessConfig
 from verifiers.v1.configs.judge import JudgeConfig, Judges
+from verifiers.v1.configs.legacy import LegacyEnvConfig
 from verifiers.v1.configs.retries import RetryConfig
+from verifiers.v1.configs.serve import (
+    ElasticPoolConfig,
+    ServingConfig,
+    StaticPoolConfig,
+    pool_serve_kwargs,
+)
 from verifiers.v1.configs.task import TaskConfig
 from verifiers.v1.configs.taskset import TasksetConfig
 from verifiers.v1.decorators import metric, reward, stop, tool
@@ -248,7 +250,10 @@ __all__ = [  # noqa: RUF022 - grouped by public API area
     "Env",
     "SingleAgentEnv",
     "EnvConfig",
-    "EnvServerConfig",
+    "ServingConfig",
+    "LegacyEnvConfig",
+    "resolve_env_field",
+    "narrowed_env_annotation",
     "SingleAgentEnvConfig",
     "AgentConfig",
     "StaticPoolConfig",

{verifiers-0.2.2.dev42 → verifiers-0.2.2.dev43}/verifiers/v1/agent.py

@@ -276,9 +276,9 @@ class Agent:
             max_total_tokens=config.max_total_tokens,
         )
         self.timeout = config.timeout
-        # Env episode agents replace this with the eval concurrency semaphore.
-        # Interactions acquire it only around active lifecycle work, never while
-        # awaiting the caller between segments.
+        # Env episode agents replace this with the episode's agent semaphore
+        # (`--env.max-concurrent-agents`). Interactions acquire it only around active
+        # lifecycle work, never while awaiting the caller between segments.
         self._gate: asyncio.Semaphore | None = None
         # Env-owned standing, not config: `Env.setup` marks fixed agents
         # untrainable and traces are stamped from here; inert outside an env.
@@ -578,9 +578,9 @@ class _EpisodeAgent(Agent):
     bundle of references — expensive resources are env-owned and borrowed, so no
     state spans concurrent episodes): traces get their agent standing the moment
     they're created, finished ones land in `completed` (the episode's traces),
-    each run takes the eval's gate. The taskset's shared tool servers ride only
-    its own tasks — on an env-minted task they'd wrongly put MCP in play
-    (`tools=` overrides)."""
+    each run takes one of the episode's agent permits. The taskset's shared tool
+    servers ride only its own tasks — on an env-minted task they'd wrongly put MCP
+    in play (`tools=` overrides)."""
 
     def __init__(
         self,
@@ -664,8 +664,9 @@ class _EpisodeAgent(Agent):
         """The agent's `interaction`, with every trace stamped with its standing
         at mint and captured in `completed` at close — an interaction driven from
         `Env.run` stays crash-safe. Setup, each active segment, and close acquire
-        the eval gate independently; the interaction holds no permit while awaiting
-        its caller, so peer interactions can interleave even at concurrency one."""
+        an agent permit independently; the interaction holds no permit while awaiting
+        its caller, so peer interactions still interleave where an episode plays one
+        agent at a time."""
         trace: Trace | None = None
 
         def remember(current: Trace) -> None:

{verifiers-0.2.2.dev42 → verifiers-0.2.2.dev43}/verifiers/v1/cli/dashboard/eval.py

@@ -95,7 +95,7 @@ def _limits(config: EvalConfig) -> list[str]:
             toks.append(f"{label}≤{v}")
     turns = _seat_value(config, lambda spec: spec.max_turns)
     return [
-        f"≤{config.max_concurrent} concurrent"
+        f"≤{config.max_concurrent} episodes"
         if config.max_concurrent
         else "no concurrency cap",
         "per-seat turn caps"

{verifiers-0.2.2.dev42 → verifiers-0.2.2.dev43}/verifiers/v1/cli/eval/main.py

@@ -24,7 +24,7 @@ from verifiers.v1.utils.logging import setup_logging
 logger = logging.getLogger(__name__)
 
 USAGE = (
-    "usage: uv run eval [<taskset-id>] [--env.id <id>] [--id <env-id> (legacy)] [options] [@ file.toml]\n"
+    "usage: uv run eval [<taskset-id>] [--env.id <id>] [--legacy.id <env-id> (v0)] [options] [@ file.toml]\n"
     "       uv run eval --resume <output-dir>   (re-run a previous run's missing/errored rollouts)"
 )
 
@@ -49,12 +49,14 @@ def main(argv: list[str] | None = None) -> None:
             )
         config = load_resume_config(resume_dir)
     else:
-        legacy_id = any(a == "--id" or a.startswith("--id=") for a in argv)  # v0 env id
-        # An env-block flag (or a retired flat axis) skips the usage gate so the
-        # typed parse renders its did-you-mean / pointer to the new flags instead
-        # of a bare usage line.
+        legacy_id = any(
+            a == "--legacy.id" or a.startswith("--legacy.id=") for a in argv
+        )
+        # An env-block flag (or a since-moved flat axis) skips the usage gate so the
+        # typed parse renders its did-you-mean instead of a bare usage line.
         typed_axis = any(
-            a.startswith(("--env.", "--taskset.", "--harness.")) for a in argv
+            a.startswith(("--env.", "--taskset.", "--harness.", "--serve."))
+            for a in argv
         )
         if (
             not extract_id(argv, "env.taskset")
@@ -64,7 +66,7 @@ def main(argv: list[str] | None = None) -> None:
         ):
             raise SystemExit(
                 USAGE
-            )  # need a taskset (positional / --env.taskset.id), a legacy --id, or a @ file.toml
+            )  # need a taskset (positional / --env.taskset.id), a v0 --legacy.id, or a @ file.toml
 
         with plugin_errors():
             config_type = narrow_config(EvalConfig, argv)

{verifiers-0.2.2.dev42 → verifiers-0.2.2.dev43}/verifiers/v1/cli/eval/runner.py

@@ -107,19 +107,24 @@ async def run_eval_server(config: EvalConfig) -> list[Episode]:
     import multiprocessing as mp
     from functools import partial
 
-    from verifiers.v1.configs.cli.env import pool_serve_kwargs
+    from verifiers.v1.configs.serve import pool_serve_kwargs
     from verifiers.v1.serve import EnvClient, env_config_data, serve_env
     from verifiers.v1.utils.logging import setup_logging
 
     legacy = config.is_legacy
     server_kwargs = (
         {
-            "env_id": config.id,
-            "env_args": config.args,
-            "extra_env_kwargs": config.extra_env_kwargs,
+            "env_id": config.legacy.id,
+            "env_args": config.legacy.args,
+            "extra_env_kwargs": config.legacy.extra_env_kwargs,
         }
         if legacy
-        else {"config_data": env_config_data(config.env)}  # picklable across the spawn
+        else {
+            "config_data": env_config_data(config.env),  # picklable across the spawn
+            # `-c` seeds each worker's episode bound unless `[serve]` pins one — so a
+            # pool carries `workers * bound` episodes, as `multiplex` implies.
+            "max_concurrent": config.worker_max_concurrent,
+        }
     )
     tasks = []
     if not legacy:
@@ -142,7 +147,7 @@ async def run_eval_server(config: EvalConfig) -> list[Episode]:
     proc = mpctx.Process(
         target=serve_env,
         kwargs=dict(
-            **pool_serve_kwargs(config.pool),
+            **pool_serve_kwargs(config.serve.pool),
             legacy=legacy,
             address="tcp://127.0.0.1:0",
             address_queue=address_queue,
@@ -210,7 +215,7 @@ async def run_eval_server(config: EvalConfig) -> list[Episode]:
                 "running %dx%d rollouts via the env-server %s pool on %s",
                 len(plan),
                 config.num_rollouts,
-                config.pool.type,
+                config.serve.pool.type,
                 config.model,
             )
         logger.info("results: %s", out)

{verifiers-0.2.2.dev42 → verifiers-0.2.2.dev43}/verifiers/v1/cli/serve.py

@@ -12,12 +12,12 @@ from verifiers.v1.cli.resolve import (
     references_config_file,
     with_positional_taskset,
 )
-from verifiers.v1.configs.cli.env import pool_serve_kwargs
 from verifiers.v1.configs.cli.serve import ServeConfig
+from verifiers.v1.configs.serve import pool_serve_kwargs
 from verifiers.v1.serve import serve_env
 from verifiers.v1.utils.logging import setup_logging
 
-USAGE = "usage: uv run serve [<taskset-id>] [--env.id <id>] [--id <env-id> (legacy)] [options] [@ file.toml]"
+USAGE = "usage: uv run serve [<taskset-id>] [--env.id <id>] [--legacy.id <env-id> (v0)] [options] [@ file.toml]"
 
 
 def main(argv: list[str] | None = None) -> None:
@@ -29,11 +29,12 @@ def main(argv: list[str] | None = None) -> None:
         with plugin_errors():
             cli(narrow_config(ServeConfig, argv))
         return
-    legacy_id = any(a == "--id" or a.startswith("--id=") for a in argv)  # v0 env id
-    # An env-block flag (or a retired flat axis) skips the usage gate so the typed
-    # parse renders its did-you-mean / pointer to the new flags instead of a bare
-    # usage line.
-    typed_axis = any(a.startswith(("--env.", "--taskset.", "--harness.")) for a in argv)
+    legacy_id = any(a == "--legacy.id" or a.startswith("--legacy.id=") for a in argv)
+    # An env-block flag (or a since-moved flat axis) skips the usage gate so the typed
+    # parse renders its did-you-mean instead of a bare usage line.
+    typed_axis = any(
+        a.startswith(("--env.", "--taskset.", "--harness.", "--serve.")) for a in argv
+    )
     if (
         not extract_id(argv, "env.taskset")
         and not legacy_id
@@ -42,7 +43,7 @@ def main(argv: list[str] | None = None) -> None:
     ):
         raise SystemExit(
             USAGE
-        )  # need a taskset (positional / --env.taskset.id), a legacy --id, or @ file.toml
+        )  # need a taskset (positional / --env.taskset.id), a v0 --legacy.id, or @ file.toml
 
     with plugin_errors():
         config_type = narrow_config(ServeConfig, argv)
@@ -60,17 +61,19 @@ def main(argv: list[str] | None = None) -> None:
     # in each one.
     server_kwargs = (
         {
-            "env_id": config.id,
-            "env_args": config.args,
-            "extra_env_kwargs": config.extra_env_kwargs,
+            "env_id": config.legacy.id,
+            "env_args": config.legacy.args,
+            "extra_env_kwargs": config.legacy.extra_env_kwargs,
         }
         if config.is_legacy
-        else {"config": config.env}
+        # `--serve.max-concurrent` is each v1 worker's episode bound; the legacy
+        # bridge has never had one.
+        else {"config": config.env, "max_concurrent": config.serve.max_concurrent}
     )
     serve_env(
-        **pool_serve_kwargs(config.pool),
+        **pool_serve_kwargs(config.serve.pool),
         legacy=config.is_legacy,
-        address=config.address,
+        address=config.serve.address,
         log_setup=partial(setup_logging, level),
         **server_kwargs,
     )

verifiers-0.2.2.dev43/verifiers/v1/configs/cli/env.py

@@ -0,0 +1,60 @@
+"""Run-config plumbing around the `[env]` block: narrowing the `env` field of every
+config that owns one, and the retired keys such a config refuses.
+
+A run composes the blocks it needs — `[env]` (what runs, `configs/env.py`),
+`[serve]` (how it's hosted, `configs/serve.py`), `[legacy]` (the v0 bridge,
+`configs/legacy.py`) — plus its own fields. Nothing here is a base class: the eval
+CLI, the `serve` CLI, GEPA and a trainer each declare their blocks and call these.
+
+Declare the env field as `SerializeAsAny[EnvConfig] = Field(default_factory=
+single_agent_env_config)`. The `SerializeAsAny` is load-bearing: pydantic serializes
+by declared type, so a plain `EnvConfig` silently drops a narrowed subclass's agents
+and knobs from `model_dump()` — the env-server wire's payload."""
+
+from pydantic import ValidationError
+from pydantic_config import BaseConfig
+
+from verifiers.v1.configs.env import EnvConfig
+from verifiers.v1.utils.generic import prefix_validation_error
+
+
+def resolve_env_field(data: dict, narrowed: "type[EnvConfig] | None" = None) -> dict:
+    """Shared `mode="before"` body for every run config owning an `env` field: narrow
+    `env` to the concrete env's config class. `narrowed` is the annotation the CLI
+    pre-resolved (`narrow_config`) — its id is authoritative, so validate against it
+    directly."""
+    if not isinstance(data, dict):
+        return data
+    raw = data.get("env")
+    if raw is None:
+        return data
+    try:
+        if narrowed is not None:
+            if not isinstance(raw, narrowed):
+                data["env"] = narrowed.model_validate(
+                    raw.model_dump() if isinstance(raw, BaseConfig) else raw
+                )
+            return data
+        from verifiers.v1.loaders import resolve_env_config
+
+        data["env"] = resolve_env_config(raw)
+    except ValidationError as e:
+        # Validating here (inside the owner's mode="before" validator) would
+        # surface the errors without their `env` segment — the CLI would render
+        # `--agent.model` for the `--env.agent.model` the user typed.
+        raise prefix_validation_error(e, ("env",)) from None
+    return data
+
+
+def narrowed_env_annotation(cls) -> "type[EnvConfig] | None":
+    """The env field's annotation when the CLI pre-narrowed it (`narrow_config`
+    swaps in a concrete subclass). The base declaration reads as `EnvConfig` itself
+    (SerializeAsAny unwraps), so only a proper subclass counts."""
+    annotation = cls.model_fields["env"].annotation
+    if (
+        isinstance(annotation, type)
+        and issubclass(annotation, EnvConfig)
+        and annotation is not EnvConfig
+    ):
+        return annotation
+    return None

{verifiers-0.2.2.dev42 → verifiers-0.2.2.dev43}/verifiers/v1/configs/cli/eval.py

@@ -3,14 +3,27 @@
 from pathlib import Path
 from uuid import uuid4
 
-from pydantic import AliasChoices, Field, model_validator
+from pydantic import AliasChoices, Field, SerializeAsAny, model_validator
+from pydantic_config import BaseConfig
 
 from verifiers.v1.clients import ClientConfig, EvalClientConfig
-from verifiers.v1.configs.cli.env import EnvServerConfig
+from verifiers.v1.configs.cli.env import narrowed_env_annotation, resolve_env_field
+from verifiers.v1.configs.env import EnvConfig
+from verifiers.v1.configs.legacy import LegacyEnvConfig
+from verifiers.v1.configs.serve import ServingConfig
+from verifiers.v1.envs.single_agent import SingleAgentEnvConfig
 from verifiers.v1.types import SamplingConfig
 
 
-class EvalConfig(EnvServerConfig):
+class EvalConfig(BaseConfig):
+    env: SerializeAsAny[EnvConfig] = SingleAgentEnvConfig()
+    """The environment — which env, its seed taskset, each agent, its knobs. Narrowed to
+    the selected env's config class by the env id, else the taskset id."""
+    serve: ServingConfig = ServingConfig()
+    """How the env is hosted under `--server`: the worker pool, each worker's episode
+    bound. Ignored by an in-process run."""
+    legacy: LegacyEnvConfig = LegacyEnvConfig()
+    """A classic (v0) environment to evaluate through the bridge instead of `[env]`."""
     uuid: str = Field(default_factory=lambda: str(uuid4()), exclude=True)
     """Auto-generated run id — the leaf of the output dir, so runs never overwrite.
     Excluded from the saved config so re-running `@ config.toml` lands in a fresh dir."""
@@ -37,9 +50,12 @@ class EvalConfig(EnvServerConfig):
     shuffle: bool = Field(False, validation_alias=AliasChoices("shuffle", "s"))
     """Shuffle tasks before taking the first `num_tasks`."""
     max_concurrent: int | None = Field(
-        128, validation_alias=AliasChoices("max_concurrent", "c")
+        128, ge=1, validation_alias=AliasChoices("max_concurrent", "c")
     )
-    """Max rollouts in flight at once."""
+    """Episodes in flight at once, `None` for no limit. An episode plays its agents one
+    at a time, so this is the live agent runs too — until `--env.max-concurrent-agents`
+    says otherwise. Under `--server` it seeds each worker's bound, unless
+    `--serve.max-concurrent` pins one."""
     verbose: bool = Field(False, validation_alias=AliasChoices("verbose", "v"))
     """Log at debug level instead of the default info."""
     dry_run: bool = Field(False, exclude=True)
@@ -49,7 +65,7 @@ class EvalConfig(EnvServerConfig):
     """Show a live dashboard instead of per-rollout logs (in-process only; an unset
     `rich` defaults off under `--server`)."""
     server: bool = False
-    """Drive rollouts through the env-server worker pool (sized by `--pool.*`) instead of
+    """Drive rollouts through the env-server worker pool (sized by `[serve]`) instead of
     in-process — the path prime-rl trains through. Incompatible with `--rich`."""
     push: bool = True
     """Upload the finished run to the Prime Intellect platform (the private Evaluations
@@ -80,3 +96,47 @@ class EvalConfig(EnvServerConfig):
                 "`--server`; drop `--rich`."
             )
         return self
+
+    @property
+    def is_legacy(self) -> bool:
+        """Whether this run goes through the v0 bridge: a legacy id and no v1 taskset."""
+        return self.legacy.id is not None and not self.env.taskset.id
+
+    @property
+    def env_id(self) -> str:
+        """The run's identifier: the v1 env's, else the v0 env id."""
+        return self.env.env_id or self.legacy.id or ""
+
+    @property
+    def worker_max_concurrent(self) -> int | None:
+        """A served worker's episode bound: its own pin, else the run's `--max-concurrent`."""
+        return (
+            self.serve.max_concurrent
+            if self.serve.max_concurrent is not None
+            else self.max_concurrent
+        )
+
+    @model_validator(mode="after")
+    def _refuse_mixed_run(self):
+        # A v0 id next to any v1 env identity leaves one of the two going nowhere, and
+        # which one depends on `is_legacy`: a taskset makes it False, so the v0 env never
+        # loads; a bare `--env.id` leaves it True, so the v0 env runs under the v1 name.
+        if self.legacy.id is None or not self.env.env_id:
+            return self
+        if self.env.taskset.id:
+            raise ValueError(
+                f"--legacy.id {self.legacy.id!r} is a classic (v0) env and can't combine "
+                f"with the v1 taskset {self.env.taskset.id!r}. Pairing a reusable env with "
+                f"a taskset is --env.id {self.legacy.id!r} (TOML: id under [env]); to run "
+                "the v0 env instead, drop the taskset."
+            )
+        raise ValueError(
+            f"--legacy.id {self.legacy.id!r} is a classic (v0) env and can't combine with "
+            f"the v1 env --env.id {self.env.id!r}: the v0 env is what would run, stamped "
+            "with the v1 env's name. Keep whichever one you meant to run."
+        )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _resolve_env(cls, data):
+        return resolve_env_field(data, narrowed_env_annotation(cls))

verifiers-0.2.2.dev43/verifiers/v1/configs/cli/serve.py

@@ -0,0 +1,62 @@
+"""Environment-server CLI configuration."""
+
+from pydantic import AliasChoices, Field, SerializeAsAny, model_validator
+from pydantic_config import BaseConfig
+
+from verifiers.v1.configs.cli.env import narrowed_env_annotation, resolve_env_field
+from verifiers.v1.configs.env import EnvConfig
+from verifiers.v1.configs.legacy import LegacyEnvConfig
+from verifiers.v1.configs.serve import ServingConfig
+from verifiers.v1.envs.single_agent import SingleAgentEnvConfig
+
+
+class ServeConfig(BaseConfig):
+    """`uv run serve`: what to serve (`[env]`, or `[legacy]` for a classic v0 env) and
+    how it's hosted (`[serve]`)."""
+
+    env: SerializeAsAny[EnvConfig] = SingleAgentEnvConfig()
+    """The environment — which env, its seed taskset, each agent, its knobs. Narrowed to
+    the selected env's config class by the env id, else the taskset id."""
+    serve: ServingConfig = ServingConfig()
+    """How it's served: the worker pool, the bind address, each worker's episode bound."""
+    legacy: LegacyEnvConfig = LegacyEnvConfig()
+    """A classic (v0) environment to serve through the bridge instead of `[env]`."""
+    verbose: bool = Field(False, validation_alias=AliasChoices("verbose", "v"))
+    """Log at debug level instead of info."""
+    dry_run: bool = False
+    """Resolve + validate the config and dump it, then exit."""
+
+    @property
+    def is_legacy(self) -> bool:
+        """Whether this run goes through the v0 bridge: a legacy id and no v1 taskset."""
+        return self.legacy.id is not None and not self.env.taskset.id
+
+    @property
+    def env_id(self) -> str:
+        """The run's identifier: the v1 env's, else the v0 env id."""
+        return self.env.env_id or self.legacy.id or ""
+
+    @model_validator(mode="after")
+    def _refuse_mixed_run(self):
+        # A v0 id next to any v1 env identity leaves one of the two going nowhere, and
+        # which one depends on `is_legacy`: a taskset makes it False, so the v0 env never
+        # loads; a bare `--env.id` leaves it True, so the v0 env runs under the v1 name.
+        if self.legacy.id is None or not self.env.env_id:
+            return self
+        if self.env.taskset.id:
+            raise ValueError(
+                f"--legacy.id {self.legacy.id!r} is a classic (v0) env and can't combine "
+                f"with the v1 taskset {self.env.taskset.id!r}. Pairing a reusable env with "
+                f"a taskset is --env.id {self.legacy.id!r} (TOML: id under [env]); to run "
+                "the v0 env instead, drop the taskset."
+            )
+        raise ValueError(
+            f"--legacy.id {self.legacy.id!r} is a classic (v0) env and can't combine with "
+            f"the v1 env --env.id {self.env.id!r}: the v0 env is what would run, stamped "
+            "with the v1 env's name. Keep whichever one you meant to run."
+        )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _resolve_env(cls, data):
+        return resolve_env_field(data, narrowed_env_annotation(cls))

{verifiers-0.2.2.dev42 → verifiers-0.2.2.dev43}/verifiers/v1/configs/env.py

@@ -3,7 +3,7 @@ each role as an `AgentConfig` field, and the env-level knobs."""
 
 from typing import get_args
 
-from pydantic import SerializeAsAny, model_validator
+from pydantic import Field, SerializeAsAny, model_validator
 from pydantic_config import BaseConfig
 
 from verifiers.v1.configs.agent import AgentConfig
@@ -48,9 +48,16 @@ class EnvConfig(BaseConfig):
     retries: RetryConfig = RetryConfig()
     """Whole-EPISODE retries — the coarse fallback for faults no agent owns; a
     retried episode reruns whole (a half-played sibling context isn't reproducible)."""
-    max_concurrent: int | None = None
-    """Bounds concurrent agent runs on a SERVED env, per worker (None = no limit);
-    the in-process eval CLI gates with its run-level `--max-concurrent` instead."""
+    max_concurrent_agents: int | None = Field(1, ge=1)
+    """How many of ONE episode's agent runs may be active at once (None = no limit).
+    One at a time by default, so the bound above — `--max-concurrent` episodes, a
+    dispatched training episode — is also one live agent run, whatever `run()` fans
+    out to internally. Raise it where per-episode latency matters and the
+    multiplication is wanted: `--env.max-concurrent-agents None` plays an episode's
+    `best-of-n` attempts together, so `-c` episodes carry `-c * n` live runs. Not
+    spelled `max_concurrent`: that key used to bound a served worker's agent runs
+    across episodes, and taking it as this one silently multiplies it by the episodes
+    in flight."""
     interception: InterceptionConfig = ElasticInterceptionPoolConfig()
     """The interception shape: `elastic` (default), `server`, or `static`."""
 

verifiers-0.2.2.dev43/verifiers/v1/configs/legacy.py

@@ -0,0 +1,24 @@
+"""The `[legacy]` block: running a classic (v0) environment through the bridge.
+
+Quarantined in its own block, not mixed into `[env]` — a v0 env is a different
+thing to run, not a variant of a v1 env's config."""
+
+from pydantic import Field
+from pydantic_config import BaseConfig
+
+from verifiers.v1.types import ID
+
+
+class LegacyEnvConfig(BaseConfig):
+    """A classic (v0) `verifiers` environment, loaded via `verifiers.load_environment`
+    and run through the legacy bridge. Set `id` *instead of* a v1 `env.taskset`."""
+
+    id: ID | None = None
+    """v0 env id: `name`, `org/name`, or `org/name@version` — installed from the hub on
+    demand."""
+    args: dict = Field(default_factory=dict)
+    """Construction kwargs forwarded to `load_environment(id, **args)`."""
+    extra_env_kwargs: dict = Field(default_factory=dict)
+    """Post-load kwargs applied via `env.set_kwargs(**extra_env_kwargs)` (e.g.
+    `max_total_completion_tokens`, `max_seq_len`, `timeout_seconds`) — typically
+    auto-populated by a trainer, distinct from the `args` passed at construction."""

verifiers-0.2.2.dev43/verifiers/v1/configs/serve.py

@@ -0,0 +1,63 @@
+"""How an env is served: the worker pool, where it binds, and each worker's bound.
+
+Serving is its own axis. `[env]` says what runs; this says how it's hosted, so an
+eval, a `serve` process, and a trainer configure it identically instead of each
+flattening pool knobs onto its own config."""
+
+from typing import Annotated, Literal
+
+from pydantic import Field
+from pydantic_config import BaseConfig
+
+
+class StaticPoolConfig(BaseConfig):
+    """Fixed env-server pool: pre-spawn `num_workers` workers up front."""
+
+    type: Literal["static"] = "static"
+    num_workers: int = Field(4, ge=1)
+    """Worker processes to pre-spawn (1 = a single in-process server, no pool)."""
+
+
+class ElasticPoolConfig(BaseConfig):
+    """Elastic env-server pool: start at one worker and scale up on demand."""
+
+    type: Literal["elastic"] = "elastic"
+    max_workers: int | None = None
+    """Upper bound on workers (None = unbounded)."""
+    multiplex: int = Field(128, ge=1)
+    """Episodes per worker for the scale-up trigger: add a worker once in-flight episodes
+    reach 90% of `workers * multiplex`."""
+
+
+# Discriminated on `type` so the CLI selects with `--serve.pool.type static|elastic`.
+PoolConfig = Annotated[
+    StaticPoolConfig | ElasticPoolConfig, Field(discriminator="type")
+]
+
+
+class ServingConfig(BaseConfig):
+    """The `[serve]` block: the worker pool, the ZMQ address, and each worker's
+    episode bound. Read by whoever hosts the env — the `serve` CLI, a server-backed
+    eval, a trainer's orchestrator."""
+
+    pool: PoolConfig = Field(default_factory=ElasticPoolConfig)
+    """Worker-pool sizing. `elastic` (default) starts at one worker and scales up on
+    demand; `static` pre-spawns a fixed `num_workers`."""
+    address: str = "tcp://127.0.0.1:5000"
+    """ZMQ address the ROUTER binds (and clients connect to)."""
+    max_concurrent: int | None = Field(None, ge=1)
+    """Episodes in flight per worker (None = take the run's own bound, e.g. an eval's
+    `--max-concurrent`). Pin it to hold a worker below what the run asks for; how many
+    agent runs one episode carries is the env's own
+    (`--env.max-concurrent-agents`, one at a time by default)."""
+
+
+def pool_serve_kwargs(pool: StaticPoolConfig | ElasticPoolConfig) -> dict:
+    """Unpack a pool config into `serve_env` kwargs (`max_workers` / `multiplex` / `elastic`)."""
+    if isinstance(pool, ElasticPoolConfig):
+        return {
+            "max_workers": pool.max_workers,
+            "multiplex": pool.multiplex,
+            "elastic": True,
+        }
+    return {"max_workers": pool.num_workers, "elastic": False}