synth-ai 0.2.8.dev2__py3-none-any.whl → 0.4.3__py3-none-any.whl

synth_ai/sdk/tunnels/cleanup.py

@@ -0,0 +1,83 @@
+"""Process tracking with automatic atexit cleanup.
+
+This module provides a simple way to track cloudflared processes and ensure
+they are terminated when Python exits (via atexit) or when cleanup_all() is
+called explicitly.
+
+Example:
+    from synth_ai.sdk.tunnels import open_managed_tunnel, track_process
+
+    # Start a cloudflared process and track it
+    proc = track_process(open_managed_tunnel(tunnel_token))
+
+    # Process will be automatically terminated when Python exits
+    # Or you can clean up early:
+    # cleanup_all()
+"""
+
+from __future__ import annotations
+
+import atexit
+import subprocess
+from typing import List
+
+# Global state - tracked processes for cleanup
+_tracked: List[subprocess.Popen] = []
+_cleanup_registered = False
+
+
+def tracked_processes() -> List[subprocess.Popen]:
+    """Return list of currently tracked processes (read-only copy).
+
+    Returns:
+        List of subprocess.Popen objects being tracked
+    """
+    return list(_tracked)
+
+
+def track_process(proc: subprocess.Popen) -> subprocess.Popen:
+    """Track a cloudflared process for automatic cleanup on exit.
+
+    Args:
+        proc: Process returned by open_managed_tunnel() or similar
+
+    Returns:
+        The same process (for chaining)
+
+    Example:
+        from synth_ai.sdk.tunnels import open_managed_tunnel, track_process
+
+        proc = track_process(open_managed_tunnel(token))
+        # proc will be terminated automatically when Python exits
+    """
+    global _cleanup_registered
+    _tracked.append(proc)
+
+    if not _cleanup_registered:
+        atexit.register(cleanup_all)
+        _cleanup_registered = True
+
+    return proc
+
+
+def cleanup_all() -> None:
+    """Stop all tracked cloudflared processes.
+
+    This is called automatically on Python exit via atexit.
+    You can also call it manually to clean up early.
+
+    Processes are terminated gracefully (SIGTERM), with a fallback
+    to SIGKILL if they don't exit within 5 seconds.
+    """
+    for proc in _tracked:
+        try:
+            if proc.poll() is None:  # Still running
+                proc.terminate()
+                try:
+                    proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+                    proc.wait()
+        except Exception:
+            pass  # Best effort cleanup
+    _tracked.clear()

synth_ai/sdk/tunnels/ports.py

@@ -0,0 +1,120 @@
+"""Port management utilities.
+
+This module provides utilities for checking port availability and
+killing processes that are using specific ports.
+
+Example:
+    from synth_ai.sdk.tunnels import kill_port, is_port_available, find_available_port
+
+    # Check if port is available
+    if not is_port_available(8001):
+        kill_port(8001)  # Free the port
+
+    # Or find an available port automatically
+    port = find_available_port(8001)
+"""
+
+from __future__ import annotations
+
+import socket
+import subprocess
+import sys
+
+
+def is_port_available(port: int, host: str = "127.0.0.1") -> bool:
+    """Check if a port is available for binding.
+
+    Args:
+        port: Port number to check
+        host: Host to check (default: 127.0.0.1)
+
+    Returns:
+        True if the port is available, False if in use
+    """
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            sock.bind((host, port))
+            return True
+    except OSError:
+        return False
+
+
+def find_available_port(
+    start_port: int, host: str = "127.0.0.1", max_attempts: int = 100
+) -> int:
+    """Find an available port starting from start_port.
+
+    Args:
+        start_port: Port number to start searching from
+        host: Host to check (default: 127.0.0.1)
+        max_attempts: Maximum number of ports to try
+
+    Returns:
+        First available port number
+
+    Raises:
+        RuntimeError: If no available port found within max_attempts
+    """
+    for offset in range(max_attempts):
+        port = start_port + offset
+        if is_port_available(port, host):
+            return port
+    raise RuntimeError(f"No available port found starting from {start_port}")
+
+
+def kill_port(port: int, host: str = "127.0.0.1") -> bool:
+    """Kill any process using the specified port.
+
+    This is a best-effort operation that attempts to free a port by
+    terminating whatever process is using it. Use with caution.
+
+    Args:
+        port: Port number to free
+        host: Host (unused, for API consistency)
+
+    Returns:
+        True if a process was killed, False if port was already free
+
+    Note:
+        This may not work on all systems or require elevated privileges.
+        Prefer using find_available_port() instead when possible.
+    """
+    if is_port_available(port, host):
+        return False  # Already free
+
+    try:
+        if sys.platform == "win32":
+            # Windows: use netstat + taskkill
+            result = subprocess.run(
+                ["netstat", "-ano"], capture_output=True, text=True, check=False
+            )
+            for line in result.stdout.splitlines():
+                if f":{port}" in line and "LISTENING" in line:
+                    parts = line.split()
+                    if len(parts) > 4:
+                        pid = parts[-1]
+                        subprocess.run(
+                            ["taskkill", "/F", "/PID", pid],
+                            capture_output=True,
+                            check=False,
+                        )
+                        return True
+        else:
+            # Unix-like (macOS, Linux): use lsof + kill
+            result = subprocess.run(
+                ["lsof", "-ti", f":{port}"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.stdout.strip():
+                for pid in result.stdout.strip().split():
+                    subprocess.run(
+                        ["kill", "-9", pid], capture_output=True, check=False
+                    )
+                return True
+    except Exception:
+        pass
+
+    return False

synth_ai/utils/__init__.py

@@ -0,0 +1,213 @@
+"""
+Backward compatibility re-exports for synth_ai.utils.
+
+All utilities have been reorganized:
+- Core utilities → synth_ai.core.*
+- CLI utilities → synth_ai.cli.lib.*
+
+This module provides lazy imports to avoid circular import issues.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Direct imports from core (no circular dependency risk)
+from synth_ai.core import task_app_state
+from synth_ai.core.env import PROD_BASE_URL_DEFAULT, get_backend_from_env
+from synth_ai.core.http import AsyncHttpClient, HTTPError, http_request
+from synth_ai.core.json import create_and_write_json, load_json_to_dict, strip_json_comments
+from synth_ai.core.paths import (
+    REPO_ROOT,
+    cleanup_paths,
+    configure_import_paths,
+    find_config_path,
+    get_bin_path,
+    get_env_file_paths,
+    get_home_config_file_paths,
+    is_hidden_path,
+)
+from synth_ai.core.process import (
+    ensure_local_port_available,
+    popen_capture,
+    popen_stream,
+    popen_stream_capture,
+)
+from synth_ai.core.task_app_state import (
+    DEFAULT_TASK_APP_SECRET_NAME,
+    current_task_app_id,
+    load_demo_dir,
+    load_template_id,
+    now_iso,
+    persist_api_key,
+    persist_demo_dir,
+    persist_env_api_key,
+    persist_task_url,
+    persist_template_id,
+    read_task_app_config,
+    record_task_app,
+    resolve_task_app_entry,
+    task_app_config_path,
+    task_app_id_from_path,
+    update_task_app_entry,
+    write_task_app_config,
+)
+from synth_ai.core.telemetry import (
+    flush_logger,
+    log_batch,
+    log_error,
+    log_event,
+    log_info,
+    log_warning,
+)
+from synth_ai.core.user_config import (
+    USER_CONFIG_PATH,
+    load_user_config,
+    load_user_env,
+    save_user_config,
+    update_user_config,
+)
+
+# Lazy imports for CLI utilities to avoid circular imports
+_CLI_IMPORTS = {
+    # From cli.lib.agents
+    "write_agents_md": ("synth_ai.cli.lib.agents", "write_agents_md"),
+    # From core.apps.common
+    "extract_routes_from_app": ("synth_ai.core.apps.common", "extract_routes_from_app"),
+    "get_asgi_app": ("synth_ai.core.apps.common", "get_asgi_app"),
+    "load_module": ("synth_ai.core.apps.common", "load_module"),
+    # From cli.lib.bin
+    "install_bin": ("synth_ai.cli.lib.bin", "install_bin"),
+    "verify_bin": ("synth_ai.cli.lib.bin", "verify_bin"),
+    # From cli.lib.env
+    "mask_str": ("synth_ai.cli.lib.env", "mask_str"),
+    "read_env_var_from_file": ("synth_ai.cli.lib.env", "read_env_var_from_file"),
+    "resolve_env_var": ("synth_ai.cli.lib.env", "resolve_env_var"),
+    "write_env_var_to_dotenv": ("synth_ai.cli.lib.env", "write_env_var_to_dotenv"),
+    "write_env_var_to_json": ("synth_ai.cli.lib.env", "write_env_var_to_json"),
+    # From cli.lib.modal
+    "ensure_modal_installed": ("synth_ai.cli.lib.modal", "ensure_modal_installed"),
+    "ensure_task_app_ready": ("synth_ai.cli.lib.modal", "ensure_task_app_ready"),
+    "find_asgi_apps": ("synth_ai.cli.lib.modal", "find_asgi_apps"),
+    "is_local_demo_url": ("synth_ai.cli.lib.modal", "is_local_demo_url"),
+    "is_modal_public_url": ("synth_ai.cli.lib.modal", "is_modal_public_url"),
+    "normalize_endpoint_url": ("synth_ai.cli.lib.modal", "normalize_endpoint_url"),
+    # From cli.lib.prompts
+    "PromptedChoiceOption": ("synth_ai.cli.lib.prompts", "PromptedChoiceOption"),
+    "PromptedChoiceType": ("synth_ai.cli.lib.prompts", "PromptedChoiceType"),
+    "PromptedPathOption": ("synth_ai.cli.lib.prompts", "PromptedPathOption"),
+    "ctx_print": ("synth_ai.cli.lib.prompts", "ctx_print"),
+    "prompt_choice": ("synth_ai.cli.lib.prompts", "prompt_choice"),
+    "prompt_for_path": ("synth_ai.cli.lib.prompts", "prompt_for_path"),
+    # From cli.lib.sqld
+    "SQLD_VERSION": ("synth_ai.cli.lib.sqld", "SQLD_VERSION"),
+    "find_sqld_binary": ("synth_ai.cli.lib.sqld", "find_sqld_binary"),
+    "install_sqld": ("synth_ai.cli.lib.sqld", "install_sqld"),
+    # From cli.lib.task_app_discovery
+    "AppChoice": ("synth_ai.cli.lib.task_app_discovery", "AppChoice"),
+    "discover_eval_config_paths": ("synth_ai.cli.lib.task_app_discovery", "discover_eval_config_paths"),
+    "select_app_choice": ("synth_ai.cli.lib.task_app_discovery", "select_app_choice"),
+    # From cli.lib.task_app_env
+    "ensure_env_credentials": ("synth_ai.cli.lib.task_app_env", "ensure_env_credentials"),
+    "ensure_port_free": ("synth_ai.cli.lib.task_app_env", "ensure_port_free"),
+    "preflight_env_key": ("synth_ai.cli.lib.task_app_env", "preflight_env_key"),
+    # From core.integrations.mcp.claude
+    "ClaudeConfig": ("synth_ai.core.integrations.mcp.claude", "ClaudeConfig"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _CLI_IMPORTS:
+        module_name, attr_name = _CLI_IMPORTS[name]
+        import importlib
+        module = importlib.import_module(module_name)
+        return getattr(module, attr_name)
+    raise AttributeError(f"module 'synth_ai.utils' has no attribute '{name}'")
+
+
+__all__ = [
+    # Core
+    "AsyncHttpClient",
+    "ClaudeConfig",
+    "DEFAULT_TASK_APP_SECRET_NAME",
+    "HTTPError",
+    "PROD_BASE_URL_DEFAULT",
+    "REPO_ROOT",
+    "USER_CONFIG_PATH",
+    "cleanup_paths",
+    "configure_import_paths",
+    "create_and_write_json",
+    "current_task_app_id",
+    "ensure_local_port_available",
+    "find_config_path",
+    "flush_logger",
+    "get_backend_from_env",
+    "get_bin_path",
+    "get_env_file_paths",
+    "get_home_config_file_paths",
+    "http_request",
+    "is_hidden_path",
+    "load_demo_dir",
+    "load_json_to_dict",
+    "load_template_id",
+    "load_user_config",
+    "load_user_env",
+    "log_batch",
+    "log_error",
+    "log_event",
+    "log_info",
+    "log_warning",
+    "now_iso",
+    "persist_api_key",
+    "persist_demo_dir",
+    "persist_env_api_key",
+    "persist_task_url",
+    "persist_template_id",
+    "popen_capture",
+    "popen_stream",
+    "popen_stream_capture",
+    "read_task_app_config",
+    "record_task_app",
+    "resolve_task_app_entry",
+    "save_user_config",
+    "strip_json_comments",
+    "task_app_config_path",
+    "task_app_id_from_path",
+    "task_app_state",
+    "update_task_app_entry",
+    "update_user_config",
+    "write_task_app_config",
+    # CLI (lazy)
+    "AppChoice",
+    "PromptedChoiceOption",
+    "PromptedChoiceType",
+    "PromptedPathOption",
+    "SQLD_VERSION",
+    "ctx_print",
+    "discover_eval_config_paths",
+    "ensure_env_credentials",
+    "ensure_modal_installed",
+    "ensure_port_free",
+    "ensure_task_app_ready",
+    "extract_routes_from_app",
+    "find_asgi_apps",
+    "find_sqld_binary",
+    "get_asgi_app",
+    "install_bin",
+    "install_sqld",
+    "is_local_demo_url",
+    "is_modal_public_url",
+    "load_module",
+    "mask_str",
+    "normalize_endpoint_url",
+    "preflight_env_key",
+    "prompt_choice",
+    "prompt_for_path",
+    "read_env_var_from_file",
+    "resolve_env_var",
+    "select_app_choice",
+    "verify_bin",
+    "write_agents_md",
+    "write_env_var_to_dotenv",
+    "write_env_var_to_json",
+]

synth_ai-0.4.3.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: synth-ai
+Version: 0.4.3
+Summary: Serverless Posttraining for Agents - Core AI functionality and tracing
+Author-email: Synth AI <josh@usesynth.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/synth-laboratories/synth-ai
+Project-URL: Repository, https://github.com/synth-laboratories/synth-ai
+Project-URL: Issues, https://github.com/synth-laboratories/synth-ai/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: tqdm>=4.66.4
+Requires-Dist: typing_extensions>=4.0.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: openai>=1.99.0
+Requires-Dist: anthropic>=0.42.0
+Requires-Dist: langfuse<3.0.0,>=2.53.9
+Requires-Dist: opentelemetry-api>=1.26.0
+Requires-Dist: opentelemetry-sdk>=1.26.0
+Requires-Dist: groq>=0.30.0
+Requires-Dist: google-genai>=1.26.0
+Requires-Dist: together>=1.5.21
+Requires-Dist: mistralai>=1.9.2
+Requires-Dist: fastapi>=0.115.12
+Requires-Dist: uvicorn>=0.34.2
+Requires-Dist: numpy>=2.2.3
+Requires-Dist: networkx>=3.4.2
+Requires-Dist: sqlalchemy>=2.0.42
+Requires-Dist: celery>=5.4.0
+Requires-Dist: redis>=6.2.0
+Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: libsql>=0.1.8
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: click<8.2,>=8.1.7
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: modal<2.0.0,>=1.1.4
+Requires-Dist: docker>=7.0.0
+Requires-Dist: mcp>=1.21.0
+Requires-Dist: ruff>=0.12.9
+Requires-Dist: tomli_w>=1.0.0
+Requires-Dist: dspy>=3.0.4
+Requires-Dist: setuptools>=80.9.0
+Requires-Dist: gymnasium>=0.26.2
+Requires-Dist: gepa>=0.0.17
+Requires-Dist: datasets>=4.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2.post1; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: keyring>=24.0.0; extra == "dev"
+Requires-Dist: pytest>=8.3.3; extra == "dev"
+Requires-Dist: pytest-xdist>=3.6.1; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pyright>=1.1.350; extra == "dev"
+Requires-Dist: coverage[toml]>=7.3.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: papermill>=2.6.0; extra == "dev"
+Requires-Dist: nest_asyncio>=1.6.0; extra == "dev"
+Provides-Extra: research
+Requires-Dist: crafter>=1.8.3; extra == "research"
+Requires-Dist: datasets>=4.0.0; extra == "research"
+Provides-Extra: swe
+Requires-Dist: morphcloud>=0.1.3; extra == "swe"
+Requires-Dist: swebench>=2.3.0; extra == "swe"
+Provides-Extra: all
+Requires-Dist: crafter>=1.8.3; extra == "all"
+Requires-Dist: datasets>=4.0.0; extra == "all"
+Requires-Dist: morphcloud>=0.1.3; extra == "all"
+Requires-Dist: swebench>=2.3.0; extra == "all"
+Requires-Dist: pyboy>=2.6.0; extra == "all"
+Requires-Dist: transformers>=4.56.1; extra == "all"
+Requires-Dist: redis>=6.2.0; extra == "all"
+Provides-Extra: analytics
+Requires-Dist: pandas>=2.2.3; extra == "analytics"
+Dynamic: license-file
+
+# Synth
+
+[![Python](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/synth-ai.svg)](https://pypi.org/project/synth-ai/)
+[![PyPI Main](https://img.shields.io/badge/main-0.4.1-blue)](https://pypi.org/project/synth-ai/0.4.1/)
+[![PyPI Nightly](https://img.shields.io/badge/nightly-0.4.0-orange)](https://pypi.org/project/synth-ai/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+![Coverage](https://img.shields.io/badge/coverage-28.65%25-yellow)
+![Tests](https://img.shields.io/badge/tests-847%20passing-brightgreen)
+
+Serverless Posttraining APIs for Developers
+
+<p align="center">
+  <picture align="center">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/synth-laboratories/synth-ai/main/assets/langprobe_v2_dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/synth-laboratories/synth-ai/main/assets/langprobe_v2_light.png">
+    <img alt="Shows a bar chart comparing prompt optimization performance across Synth GEPA, Synth MIPRO, GEPA (lib), DSPy MIPRO, and DSPy GEPA with baseline vs optimized." src="https://raw.githubusercontent.com/synth-laboratories/synth-ai/main/assets/langprobe_v2_light.png">
+  </picture>
+</p>
+
+<p align="center">
+  <i>Average accuracy on <a href="https://arxiv.org/abs/2502.20315">LangProBe</a> prompt optimization benchmarks.</i>
+</p>
+
+## Highlights
+
+- 🚀 Train across sft, RL, and prompt opt by standing up a single cloudflared Fastapi wrapper around your code. No production code churn.
+- ⚡️ Parallelize training and achieve 80% GPU util. via PipelineRL
+- 🗂️ Train prompts and models across multiple experiments
+- 🛠️ Spin up experiment queues and datastores locally for dev work
+- 🔩 Run serverless training via cli or programmatically
+- 🏢 Scales gpu-based model training to 64 H100s seemlessly
+- 💾 Use GEPA-calibrated verifiers for fast, accurate rubric scoring
+- 🖥️ Supports HTTP-based training across all programming languages
+- 🤖 CLI utilities tuned for use with Claude Code, Codex, Opencode
+
+## Getting Started
+
+```bash
+# Use with OpenAI Codex
+uvx synth-ai codex
+```
+
+```bash
+# Use with Opencode
+uvx synth-ai opencode
+```
+
+Synth is maintained by devs behind the [MIPROv2](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=jauNVA8AAAAJ&citation_for_view=jauNVA8AAAAJ:u5HHmVD_uO8C) prompt optimizer.
+
+## Documentation
+
+**[docs.usesynth.ai](https://docs.usesynth.ai)**
+
+## In-Process Runner (SDK)
+
+Run GEPA/MIPRO/RL jobs against a tunneled task app without the CLI:
+
+```python
+import asyncio
+import os
+from synth_ai.sdk.task import run_in_process_job
+
+result = asyncio.run(
+    run_in_process_job(
+        job_type="prompt_learning",
+        config_path="configs/style_matching_gepa.toml",
+        task_app_path="task_apps/style_matching_task_app.py",
+        overrides={"prompt_learning.gepa.rollout.budget": 4},
+        backend_url=os.getenv("TARGET_BACKEND_BASE_URL"),  # resolves envs automatically
+    )
+)
+print(result.job_id, result.status.get("status"))
+```
+
+## Zero-Shot Verifiers (SDK)
+
+Run a built-in verifier graph with rubric criteria passed at runtime:
+
+```python
+import asyncio
+import os
+from synth_ai.sdk.graphs import VerifierClient
+
+async def run_verifier():
+    client = VerifierClient(
+        base_url=os.environ["SYNTH_BACKEND_BASE"],
+        api_key=os.environ["SYNTH_API_KEY"],
+    )
+    result = await client.evaluate(
+        job_id="zero_shot_verifier_single",
+        session_trace={"session_id": "s", "event_history": []},
+        rubric={
+            "event": [{"id": "accuracy", "weight": 1.0, "description": "Correctness"}],
+            "outcome": [{"id": "task_completion", "weight": 1.0, "description": "Completed task"}],
+        },
+        options={"event": True, "outcome": True, "model": "gpt-5-nano"},
+        policy_name="my_policy",
+        task_app_id="my_task",
+    )
+    return result
+
+asyncio.run(run_verifier())
+```
+
+You can also call arbitrary graphs directly:
+
+```python
+from synth_ai.sdk.graphs import GraphCompletionsClient
+
+client = GraphCompletionsClient(base_url="https://api.usesynth.ai", api_key="...")
+resp = await client.run(
+    graph={"kind": "zero_shot", "verifier_type": "zero_shot_verifier_mapreduce"},
+    input_data={"session_trace": {"session_id": "s", "event_history": []}, "rubric": {"event": [], "outcome": []}},
+)
+```
+
+## GraphGen: Train Custom Verifier and RLM Graphs
+
+Train custom verifier and RLM graphs using GraphGen:
+
+```python
+from synth_ai.sdk.api.train.graphgen import GraphGenJob
+
+# Train a verifier graph (judge/scorer)
+verifier_job = GraphGenJob.from_dataset(
+    dataset="verifier_dataset.json",
+    graph_type="verifier",
+    policy_models=["gpt-4.1"],
+    proposer_effort="medium",  # Use "medium" (gpt-4.1) or "high" (gpt-5.2)
+    rollout_budget=200,
+)
+verifier_job.submit()
+result = verifier_job.stream_until_complete(timeout=3600.0)
+
+# Run inference with trained verifier
+judgment = verifier_job.run_verifier(
+    session_trace=my_trace,
+    context={"rubric": my_rubric},
+)
+print(f"Score: {judgment.score}, Reasoning: {judgment.reasoning}")
+```
+
+```python
+# Train an RLM graph (massive context via tools)
+rlm_job = GraphGenJob.from_dataset(
+    dataset="rlm_dataset.json",
+    graph_type="rlm",
+    configured_tools=[
+        {"name": "materialize_context", "kind": "rlm_materialize", "stateful": True},
+        {"name": "local_grep", "kind": "rlm_local_grep", "stateful": False},
+        {"name": "codex_exec", "kind": "daytona_exec", "stateful": True},
+    ],
+    policy_models=["gpt-4.1"],
+    proposer_effort="medium",
+    rollout_budget=100,
+)
+rlm_job.submit()
+result = rlm_job.stream_until_complete(timeout=3600.0)
+
+# Run inference with trained RLM graph
+output = rlm_job.run_inference({"query": "Find relevant sections", "context": large_document})
+```
+
+**Graph Types:**
+- **`verifier`**: Trains a judge/scorer that evaluates traces and returns structured rewards
+- **`rlm`**: Trains a graph optimized for massive contexts (1M+ tokens) using tool-based search
+- **`policy`**: Trains a standard input→output graph (default)
+
+**RLM Tools:**
+- `materialize_context` - Store input fields for fast searching (~1ms local)
+- `local_grep` - Regex search on materialized content (~1ms)
+- `local_search` - Substring search (~1ms)
+- `query_lm` - Sub-LM calls for processing chunks
+- `codex_exec` - Shell execution for complex operations
+
+**When to use RLM:**
+- Context exceeds ~100K tokens (too large for prompt)
+- You need to search/filter large datasets
+- RAG-style workflows over massive corpora