marin-rolloutengine 0.2.160.dev38062449553__tar.gz

marin_rolloutengine-0.2.160.dev38062449553/.gitignore

@@ -0,0 +1,253 @@
+# redundant, but Ray looks for this otherwise.
+.git
+
+logs/
+
+# CPU profiles
+prof/
+
+# Downloaded build tools (zig, etc.)
+.tools/
+
+tests/snapshots/outputs
+tests/snapshots/diffs
+
+# don't log data/MD outputs to git
+data/*
+output/*
+outputs/*
+
+# Snapshot diffs and outputs
+tests/snapshots/*/outputs/*
+tests/snapshots/*/diffs/*
+
+# This is mainly for Ray and using submodule
+*/**/.git
+
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# pypa/gh-action-pypi-publish caches its Docker action manifest here.
+.github/.tmp/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+local_store/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Ruff
+.ruff_cache/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+*.iml
+
+# IDE Config
+.vscode/
+
+# Mac OS
+.DS_Store
+
+# Secrets
+credentials.json
+marin/crawl/bigquery-gcs-key.json
+
+# Archive
+archive/
+
+# Caches and Outputs
+!/scripts/web/output/
+!/output/
+
+# csv
+*.csv
+
+# wandb logs
+wandb
+artifacts
+
+# Ignore generated credentials from google-github-actions/auth
+gha-creds-*.json
+
+.aider*
+.git/*
+
+*.jsonl
+**/*.jsonl
+# Echo's judged search corpus is source, not a run artifact.
+!infra/marina/apps/echo/benchmarks/*.jsonl
+scr/*
+.weaver/
+
+# Local host Marin config
+.marin.yaml
+
+/scratch
+
+.forge
+.claude/*
+!.claude/skills
+!.claude/agents
+!.claude/settings.json
+.agents/tmp/
+.codex
+.entire
+.beads
+
+.worktrees
+.obsidian
+.cw_env
+.localbin/
+
+# Stamped into built artifacts by lib/iris/hatch_build.py; never tracked.
+lib/iris/src/iris/_build_info.py

marin_rolloutengine-0.2.160.dev38062449553/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.5
+Name: marin-rolloutengine
+Version: 0.2.160.dev38062449553
+Summary: Task execution and exact-token rollout records
+Requires-Python: <3.14,>=3.12
+Requires-Dist: marin-shellbox==0.2.160.dev38062449553
+Requires-Dist: marin-taskcompendium==0.2.160.dev38062449553
+Requires-Dist: pydantic>=2

marin_rolloutengine-0.2.160.dev38062449553/README.md

@@ -0,0 +1,27 @@
+# Rollout engine
+
+`marin-rolloutengine` executes one TaskCompendium task through Shellbox and returns
+`RolloutData`: the conversation, exact tokens, loss mask, optional log probabilities, grade, and per-turn records.
+
+Callers supply a model callable, machine factories, and optional `TaskSession`
+factories for task actions and grading.
+The default session handles shell tools.
+For text, number, JSON, and native-action answers, it adds the task's answer-format instruction and tools to the model request.
+For workspace-state tasks, this session adds shell and final-response instructions to the model request.
+Importers retain the task problem without these interface instructions.
+The engine owns model calls, conversation and token accumulation, deadlines, and resource cleanup.
+
+`ShellboxRolloutEngine.run(lowered)` accepts a `LoweredTaskSpec` and asynchronously returns one rollout.
+The lowered record preserves its `TaskSpec` and adds machine selections and session limits.
+The supported scope is single-stage tasks with prebuilt, digest-pinned images, local package-lock environments, or the built-in ShellSim filesystem.
+After the turn loop, the default session grades an in-process `VerifyitGrader` on the host.
+A `ScriptGrader`, or a `VerifyitGrader` with an environment, grades in a separate verifier machine using its digest-pinned image or a local environment built from its package lock.
+A `SessionGrader` requires a registered task session. A `NoGrader` task receives an `unavailable` grade.
+See the [task rollout reference](../../docs/references/task-rollouts.md)
+for the session lifecycle, exact-token contract, failure handling, and backend configuration.
+
+From the Marin repository root:
+
+```bash
+uv run --package marin-rolloutengine --frozen --group test pytest lib/rolloutengine/tests -q
+```

marin_rolloutengine-0.2.160.dev38062449553/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "marin-rolloutengine"
+version = "0.2.160.dev38062449553"
+description = "Task execution and exact-token rollout records"
+requires-python = ">=3.12,<3.14"
+dependencies = [
+    "pydantic>=2",
+    "marin-taskcompendium==0.2.160.dev38062449553",
+    "marin-shellbox==0.2.160.dev38062449553",
+]
+
+[dependency-groups]
+test = [
+    "pytest>=8.3",
+    "pytest-asyncio",
+    "pytest-timeout",
+    "marin-shellbox[daytona,shellsim]",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rolloutengine"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+timeout = 60
+addopts = "--import-mode=importlib -m 'not slow and not integration and not data_integration and not cluster and not requires_cluster and not docker and not manual'"
+markers = [
+    "slow: long-running test",
+    "integration: external service",
+    "data_integration: external data",
+    "cluster: live cluster",
+    "requires_cluster: live cluster",
+    "docker: Docker daemon",
+    "manual: explicit validation",
+]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.ruff.lint.isort]
+known-first-party = ["rolloutengine"]
+
+[tool.pyrefly]
+disable-project-excludes-heuristics = true
+project-includes = ["src"]
+search-path = ["src"]
+python-interpreter = "../../.venv/bin/python"

marin_rolloutengine-0.2.160.dev38062449553/src/rolloutengine/__init__.py

@@ -0,0 +1,2 @@
+# Copyright The Marin Authors
+# SPDX-License-Identifier: Apache-2.0

marin_rolloutengine-0.2.160.dev38062449553/src/rolloutengine/cleanup.py

@@ -0,0 +1,78 @@
+# Copyright The Marin Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Bounded cleanup and ownership of operations that outlive cancellation."""
+
+import asyncio
+import logging
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+_background_tasks: set[asyncio.Task[None]] = set()
+
+
+def _retain_task(task: asyncio.Task[None]) -> None:
+    _background_tasks.add(task)
+    task.add_done_callback(_background_done)
+
+
+def _background_done(task: asyncio.Task[None]) -> None:
+    _background_tasks.discard(task)
+    if not task.cancelled() and (error := task.exception()) is not None:
+        logger.error("Background resource operation failed", exc_info=error)
+
+
+@dataclass(frozen=True)
+class _CleanupError:
+    operation: str
+    exception_type: str
+
+
+@dataclass
+class _Cleanup:
+    timeout: float
+    errors: list[_CleanupError] = field(default_factory=list)
+
+    async def run(self, operation: str, action: Callable[[], Coroutine[Any, Any, None]]) -> Exception | None:
+        pending = asyncio.create_task(action())
+        loop = asyncio.get_running_loop()
+        end = loop.time() + self.timeout
+        cancellation = None
+        failure = None
+        while not pending.done():
+            remaining = end - loop.time()
+            if remaining <= 0:
+                pending.cancel()
+                _retain_task(pending)
+                failure = TimeoutError("Cleanup deadline expired")
+                break
+            try:
+                await asyncio.wait((pending,), timeout=remaining)
+            except asyncio.CancelledError as error:
+                # Repeated cancellation cannot extend the cleanup deadline.
+                cancellation = error
+        if failure is None:
+            try:
+                pending.result()
+            except asyncio.CancelledError as error:
+                failure = RuntimeError("Cleanup operation cancelled")
+                failure.__cause__ = error
+            except Exception as error:
+                failure = error
+        if failure is not None:
+            self.errors.append(_CleanupError(operation, type(failure).__name__))
+            logger.warning("Cleanup failed during %s", operation, exc_info=failure)
+        if cancellation is not None:
+            if failure is not None:
+                raise cancellation from failure
+            raise cancellation
+        return failure
+
+
+async def finish_cleanup(action: Callable[[], Coroutine[Any, Any, None]], *, timeout: float) -> None:
+    """Finish resource cleanup within its deadline and propagate failures or repeated cancellation."""
+    failure = await _Cleanup(timeout).run("resource_close", action)
+    if failure is not None:
+        raise failure

marin_rolloutengine-0.2.160.dev38062449553/src/rolloutengine/contracts.py

@@ -0,0 +1,132 @@
+# Copyright The Marin Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Public rollout protocols, records, and exceptions."""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any, Protocol
+
+from taskcompendium.grading_result import GradeResult
+
+LENGTH_STOP_REASON = "length"
+MAX_TURNS_STOP_REASON = "max_turns"
+TOTAL_TURN_TIMEOUT_STOP_REASON = "total_turn_timeout"
+
+
+@dataclass(frozen=True)
+class ModelRequest:
+    messages: tuple[dict[str, Any], ...]
+    options: dict[str, Any]
+    prefix_token_ids: tuple[int, ...]
+    assistant_message_index: int | None
+
+
+@dataclass(frozen=True)
+class SessionStart:
+    """The initial conversation and model options for one task session."""
+
+    messages: tuple[dict[str, Any], ...]
+    options: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ModelTurn:
+    """Exact tokens and the parsed message from one inference request."""
+
+    message: dict[str, Any]
+    prompt_token_ids: tuple[int, ...]
+    response_token_ids: tuple[int, ...]
+    logprobs: tuple[float, ...] | None
+    stop_reason: str
+    text: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class GenerationLimitReached(Exception):
+    """The rendered prompt leaves no permitted generation budget."""
+
+    def __init__(self, prompt_token_ids: tuple[int, ...]):
+        self.prompt_token_ids = prompt_token_ids
+        super().__init__("The prompt reached the configured generation limit")
+
+
+@dataclass(frozen=True)
+class RolloutFailure:
+    """Safe failure fields for consumers of a rollout record."""
+
+    exception_type: str
+    diagnostics: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RolloutData:
+    task_id: str
+    messages: tuple[dict[str, Any], ...]
+    prompt_token_ids: tuple[int, ...]
+    response_token_ids: tuple[int, ...]
+    loss_mask: tuple[int, ...]
+    logprobs: tuple[float, ...] | None
+    grade: GradeResult
+    stop_reason: str
+    steps: tuple["RolloutStep", ...] = ()
+    metrics: dict[str, Any] = field(default_factory=dict)
+    failure: RolloutFailure | None = None
+
+
+class RolloutOperation(StrEnum):
+    ATTEMPT = "attempt"
+    START = "start"
+    PREPARE = "prepare"
+    MODEL = "model"
+    ADVANCE = "advance"
+    GRADE = "grade"
+    CLEANUP = "cleanup"
+
+
+class RolloutInterrupted(RuntimeError):
+    """An execution failure with the last completed rollout and original exception cause."""
+
+    def __init__(self, rollout: RolloutData, operation: RolloutOperation):
+        self.rollout = rollout
+        self.operation = operation
+        super().__init__(f"Rollout interrupted during {operation}")
+
+
+class RolloutContractError(ValueError):
+    """Rollout evidence violates the exact-token contract."""
+
+
+@dataclass(frozen=True)
+class Transition:
+    """One task transition after a model response."""
+
+    done: bool
+    observations: tuple[dict[str, Any], ...] = ()
+    reset_conversation: tuple[dict[str, Any], ...] | None = None
+    reward: float | None = None
+    token_rewards: tuple[float, ...] | None = None
+    token_credit: tuple[float, ...] | None = None
+    reward_components: dict[str, float] = field(default_factory=dict)
+    grade: GradeResult | None = None
+    metrics: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RolloutStep:
+    turn: ModelTurn
+    transition: Transition
+    response_end: int
+    messages: tuple[dict[str, Any], ...]
+
+
+class TaskSession(Protocol):
+    """Task operations without model inference or token processing."""
+
+    async def prepare(self) -> SessionStart: ...
+
+    async def advance(self, turn: ModelTurn) -> Transition: ...
+
+    async def grade(self, messages: tuple[dict[str, Any], ...]) -> GradeResult: ...
+
+    async def close(self) -> None: ...