synth-ai 0.2.23.dev2__tar.gz → 0.2.23.dev3__tar.gz

{synth_ai-0.2.23.dev2/synth_ai.egg-info → synth_ai-0.2.23.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.2.23.dev2
+Version: 0.2.23.dev3
 Summary: RL as a service SDK - Core AI functionality and tracing
 Author-email: Synth AI <josh@usesynth.ai>
 License-Expression: MIT
@@ -13,11 +13,7 @@ License-File: LICENSE
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: python-dotenv>=1.0.1
 Requires-Dist: requests>=2.32.3
-Requires-Dist: urllib3>=2.3.0
-Requires-Dist: certifi>=2024.8.30
 Requires-Dist: tqdm>=4.66.4
-Requires-Dist: jsonschema>=4.23.0
-Requires-Dist: backoff>=2.0.0
 Requires-Dist: typing_extensions>=4.0.0
 Requires-Dist: rich>=13.9.0
 Requires-Dist: openai>=1.99.0
@@ -25,7 +21,6 @@ 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: diskcache>=5.6.3
 Requires-Dist: groq>=0.30.0
 Requires-Dist: google-genai>=1.26.0
 Requires-Dist: together>=1.5.21
@@ -34,30 +29,16 @@ 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: redis>=6.2.0
-Requires-Dist: duckdb>=1.0.0
-Requires-Dist: ty>=0.0.1a5
-Requires-Dist: toml>=0.10.2
 Requires-Dist: sqlalchemy>=2.0.42
 Requires-Dist: aiosqlite>=0.21.0
-Requires-Dist: greenlet>=3.2.3
 Requires-Dist: libsql>=0.1.8
 Requires-Dist: pynacl>=1.5.0
-Requires-Dist: google-api-core>=2.25.1
-Requires-Dist: google-generativeai>=0.8.5
-Requires-Dist: crafter>=1.8.3
 Requires-Dist: click<8.2,>=8.1.7
-Requires-Dist: openai-harmony>=0.0.1
-Requires-Dist: asyncpg>=0.30.0
 Requires-Dist: aiohttp>=3.8.0
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: datasets>=4.0.0
-Requires-Dist: transformers>=4.56.1
 Requires-Dist: modal<2.0.0,>=1.1.4
-Requires-Dist: pyboy>=2.6.0
-Requires-Dist: setuptools>=80.9.0
-Requires-Dist: libsql-experimental>=0.0.55
 Requires-Dist: mcp>=1.21.0
+Requires-Dist: ruff>=0.12.9
 Provides-Extra: dev
 Requires-Dist: build>=1.2.2.post1; extra == "dev"
 Requires-Dist: twine>=4.0.0; extra == "dev"
@@ -81,6 +62,9 @@ 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
@@ -89,7 +73,7 @@ Dynamic: license-file
 
 [![Python](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![PyPI](https://img.shields.io/badge/PyPI-0.2.22-orange)](https://pypi.org/project/synth-ai/)
+[![PyPI](https://img.shields.io/badge/PyPI-0.2.23.dev2-orange)](https://pypi.org/project/synth-ai/)
 ![Coverage](https://img.shields.io/badge/coverage-28.65%25-yellow)
 ![Tests](https://img.shields.io/badge/tests-847%20passing-brightgreen)
 ![Blacksmith CI](https://img.shields.io/badge/CI-Blacksmith%20Worker-blue)
@@ -99,7 +83,7 @@ Dynamic: license-file
 
 ---
 
-## 🚀 Install version 0.2.22
+## 🚀 Install latest version (0.2.23.dev2)
 
 ```bash
 pip install synth-ai

{synth_ai-0.2.23.dev2 → synth_ai-0.2.23.dev3}/README.md

@@ -2,7 +2,7 @@
 
 [![Python](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![PyPI](https://img.shields.io/badge/PyPI-0.2.22-orange)](https://pypi.org/project/synth-ai/)
+[![PyPI](https://img.shields.io/badge/PyPI-0.2.23.dev2-orange)](https://pypi.org/project/synth-ai/)
 ![Coverage](https://img.shields.io/badge/coverage-28.65%25-yellow)
 ![Tests](https://img.shields.io/badge/tests-847%20passing-brightgreen)
 ![Blacksmith CI](https://img.shields.io/badge/CI-Blacksmith%20Worker-blue)
@@ -12,7 +12,7 @@
 
 ---
 
-## 🚀 Install version 0.2.22
+## 🚀 Install latest version (0.2.23.dev2)
 
 ```bash
 pip install synth-ai

{synth_ai-0.2.23.dev2 → synth_ai-0.2.23.dev3}/examples/swe/task_app/hosted/rollout.py

@@ -10,7 +10,7 @@ from typing import Any
 
 from fastapi import APIRouter, HTTPException, Request, status
 from pydantic import BaseModel
-from synth_ai.lm.vendors.base import BaseLMResponse
+from synth_ai.tracing_v3 import BaseLMResponse
 from synth_ai.task.tracing_utils import unique_sft_path
 from synth_ai.task.contracts import RolloutMode
 from synth_ai.tracing_v3.abstractions import EnvironmentEvent, LMCAISEvent, TimeRecord

{synth_ai-0.2.23.dev2 → synth_ai-0.2.23.dev3}/examples/task_apps/crafter/task_app/synth_envs_hosted/rollout.py

@@ -10,7 +10,7 @@ from typing import Any, Mapping
 
 from fastapi import APIRouter, HTTPException, Request, status
 from pydantic import BaseModel, Field
-from synth_ai.lm.vendors.base import BaseLMResponse
+from synth_ai.tracing_v3 import BaseLMResponse
 from synth_ai.task.tracing_utils import unique_sft_path
 from synth_ai.tracing_v3.abstractions import EnvironmentEvent, LMCAISEvent, TimeRecord
 from synth_ai.task.contracts import RolloutMode

{synth_ai-0.2.23.dev2 → synth_ai-0.2.23.dev3}/examples/warming_up_to_rl/task_app/synth_envs_hosted/rollout.py

@@ -10,7 +10,7 @@ from typing import Any
 
 from fastapi import APIRouter, HTTPException, Request, status
 from pydantic import BaseModel
-from synth_ai.lm.vendors.base import BaseLMResponse
+from synth_ai.tracing_v3 import BaseLMResponse
 from synth_ai.task.tracing_utils import unique_sft_path
 from synth_ai.tracing_v3.abstractions import EnvironmentEvent, LMCAISEvent, TimeRecord
 from synth_ai.tracing_v3.llm_call_record_helpers import create_llm_call_record_from_response

{synth_ai-0.2.23.dev2 → synth_ai-0.2.23.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.2.23.dev2"
+version = "0.2.23.dev3"
 description = "RL as a service SDK - Core AI functionality and tracing"
 authors = [{name = "Synth AI", email = "josh@usesynth.ai"}]
 license = "MIT"
@@ -11,11 +11,7 @@ dependencies = [
     "pydantic>=2.0.0",
     "python-dotenv>=1.0.1",
     "requests>=2.32.3",
-    "urllib3>=2.3.0",
-    "certifi>=2024.8.30",
     "tqdm>=4.66.4",
-    "jsonschema>=4.23.0",
-    "backoff>=2.0.0",
     "typing_extensions>=4.0.0",
     # AI/LLM providers
     "rich>=13.9.0",
@@ -26,7 +22,6 @@ dependencies = [
     "opentelemetry-api>=1.26.0",
     "opentelemetry-sdk>=1.26.0",
     # Storage and caching
-    "diskcache>=5.6.3",
     "groq>=0.30.0",
     "google-genai>=1.26.0",
     "together>=1.5.21",
@@ -36,30 +31,16 @@ dependencies = [
     "uvicorn>=0.34.2",
     "numpy>=2.2.3",
     "networkx>=3.4.2",
-    "redis>=6.2.0",
-    "duckdb>=1.0.0",
-    "ty>=0.0.1a5", # Type annotations helper
-    "toml>=0.10.2",
     "sqlalchemy>=2.0.42",
     "aiosqlite>=0.21.0",
-    "greenlet>=3.2.3",
     "libsql>=0.1.8",
     "pynacl>=1.5.0",
-    "google-api-core>=2.25.1",
-    "google-generativeai>=0.8.5",
-    "crafter>=1.8.3",
     "click>=8.1.7,<8.2", # For CLI (pin to signature compatible with Typer)
-    "openai-harmony>=0.0.1", # For OSS-GPT Harmony encoding support
-    "asyncpg>=0.30.0",
-    "aiohttp>=3.8.0", # For async HTTP requests in Harmony integration
+    "aiohttp>=3.8.0", # For async HTTP requests
     "httpx>=0.28.1", # CLI preflights and HTTP clients (pulls httpcore)
-    "datasets>=4.0.0",
-    "transformers>=4.56.1",
     "modal>=1.1.4,<2.0.0",
-    "pyboy>=2.6.0",
-    "setuptools>=80.9.0",
-    "libsql-experimental>=0.0.55",
     "mcp>=1.21.0",
+    "ruff>=0.12.9",
 ]
 
 [project.scripts]
@@ -94,6 +75,9 @@ all = [
     "datasets>=4.0.0",
     "morphcloud>=0.1.3",
     "swebench>=2.3.0",
+    "pyboy>=2.6.0",
+    "transformers>=4.56.1",
+    "redis>=6.2.0",
 ]
 analytics = [
     "pandas>=2.2.3",
@@ -162,7 +146,7 @@ addopts = "--durations=10"
 
 [tool.coverage.run]
 source = ["synth_ai"]
-omit = ["*/tests/*", "*/test_*", "synth_ai/v0/*"]
+omit = ["*/tests/*", "*/test_*"]
 data_file = "coverage/.coverage"
 
 [tool.coverage.report]
@@ -172,7 +156,7 @@ skip_covered = false
 
 [tool.pyright]
 include = ["synth_ai", "tests"]
-exclude = ["**/__pycache__", "synth_ai/v0"]
+exclude = ["**/__pycache__"]
 pythonVersion = "3.11"
 typeCheckingMode = "standard"
 reportMissingImports = true
@@ -197,7 +181,6 @@ extend-exclude = [
     "traces",
     "traces_*",
     "synth_ai.db",
-    "synth_ai/v0",
     "synth_ai/tracing_v3/tests",
 ]
 

{synth_ai-0.2.23.dev2 → synth_ai-0.2.23.dev3}/synth_ai/__init__.py

@@ -42,51 +42,12 @@ except PackageNotFoundError:  # Fallback to pyproject version for editable insta
     except Exception:
         __version__ = "0.0.0.dev0"
 
-def _optional_import(module_path: str) -> Any | None:
-    try:
-        return importlib.import_module(module_path)
-    except Exception:
-        return None
-
-
-_lm_module = _optional_import("synth_ai.lm.core.main")
-LM = cast(Any, _lm_module).LM if _lm_module and hasattr(_lm_module, "LM") else None  # type: ignore[attr-defined]
-
-_anthropic_module = _optional_import("synth_ai.lm.provider_support.anthropic")
-Anthropic = (
-    cast(Any, _anthropic_module).Anthropic
-    if _anthropic_module and hasattr(_anthropic_module, "Anthropic")
-    else None
-)  # type: ignore[attr-defined]
-AsyncAnthropic = (
-    cast(Any, _anthropic_module).AsyncAnthropic
-    if _anthropic_module and hasattr(_anthropic_module, "AsyncAnthropic")
-    else None
-)  # type: ignore[attr-defined]
-
-_openai_module = _optional_import("synth_ai.lm.provider_support.openai")
-AsyncOpenAI = (
-    cast(Any, _openai_module).AsyncOpenAI
-    if _openai_module and hasattr(_openai_module, "AsyncOpenAI")
-    else None
-)  # type: ignore[attr-defined]
-OpenAI = (
-    cast(Any, _openai_module).OpenAI
-    if _openai_module and hasattr(_openai_module, "OpenAI")
-    else None
-)  # type: ignore[attr-defined]
-
 # Legacy tracing v1 is not required for v3 usage and can be unavailable in minimal envs.
 tracing = None  # type: ignore
 EventPartitionElement = RewardSignal = SystemTrace = TrainingQuestion = None  # type: ignore
 trace_event_async = trace_event_sync = upload = None  # type: ignore
 
 __all__ = [
-    "LM",
-    "OpenAI",
-    "AsyncOpenAI",
-    "Anthropic",
-    "AsyncAnthropic",
     "environments",
     # Judge API contracts
     "JudgeScoreRequest",

{synth_ai-0.2.23.dev2 → synth_ai-0.2.23.dev3}/synth_ai/api/train/builders.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import importlib
+import os
 from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
@@ -33,6 +34,8 @@ try:
 except Exception as exc:  # pragma: no cover - critical dependency
     raise RuntimeError("Unable to load SFT payload helpers") from exc
 
+from synth_ai.utils.config import ConfigResolver
+
 from .configs import PromptLearningConfig, RLConfig, SFTConfig
 from .supported_algos import (
     AlgorithmValidationError,
@@ -116,16 +119,17 @@ def build_rl_payload(
     services = data.get("services") if isinstance(data.get("services"), dict) else {}
     model_cfg = rl_cfg.model
 
-    final_task_url = (
-        overrides.get("task_url")
-        or task_url
-        or (services.get("task_url") if isinstance(services, dict) else None)
-        or ""
-    ).strip()
-    if not final_task_url:
-        raise click.ClickException(
-            "Task app URL required (provide --task-url or set services.task_url in TOML)"
-        )
+    cli_task_url = overrides.get("task_url")
+    env_task_url = task_url or os.environ.get("TASK_APP_URL")
+    config_task_url = services.get("task_url") if isinstance(services, dict) else None
+    final_task_url = ConfigResolver.resolve(
+        "task_app_url",
+        cli_value=cli_task_url,
+        env_value=env_task_url,
+        config_value=config_task_url,
+        required=True,
+    )
+    assert final_task_url is not None  # required=True guarantees non-None
 
     model_source = (model_cfg.source or "").strip() if model_cfg else ""
     model_base = (model_cfg.base or "").strip() if model_cfg else ""
@@ -368,8 +372,6 @@ def build_prompt_learning_payload(
     allow_experimental: bool | None = None,
 ) -> PromptLearningBuildResult:
     """Build payload for prompt learning job (MIPRO or GEPA)."""
-    import os
-
     from pydantic import ValidationError
 
     from .configs.prompt_learning import load_toml
@@ -385,24 +387,29 @@ def build_prompt_learning_payload(
     except ValidationError as exc:
         raise click.ClickException(_format_validation_error(config_path, exc)) from exc
     
-    # Source of truth: TOML only (ignore shell/env and CLI overrides)
-    final_task_url = (pl_cfg.task_app_url or "").strip()
-    
-    if not final_task_url:
-        raise click.ClickException(
-            "Task app URL required (provide --task-url or set prompt_learning.task_app_url in TOML)"
-        )
+    cli_task_url = overrides.get("task_url") or task_url
+    env_task_url = os.environ.get("TASK_APP_URL")
+    config_task_url = (pl_cfg.task_app_url or "").strip() or None
+    final_task_url = ConfigResolver.resolve(
+        "task_app_url",
+        cli_value=cli_task_url,
+        env_value=env_task_url,
+        config_value=config_task_url,
+        required=True,
+    )
+    assert final_task_url is not None  # required=True guarantees non-None
     
     # Get task_app_api_key from config or environment
-    task_app_api_key = (
-        pl_cfg.task_app_api_key
-        or os.environ.get("ENVIRONMENT_API_KEY", "")
-    ).strip()
-    
-    if not task_app_api_key:
-        raise click.ClickException(
-            "Task app API key required (set prompt_learning.task_app_api_key in TOML or ENVIRONMENT_API_KEY env var)"
-        )
+    config_api_key = (pl_cfg.task_app_api_key or "").strip() or None
+    cli_api_key = overrides.get("task_app_api_key")
+    env_api_key = os.environ.get("ENVIRONMENT_API_KEY")
+    task_app_api_key = ConfigResolver.resolve(
+        "task_app_api_key",
+        cli_value=cli_api_key,
+        env_value=env_api_key,
+        config_value=config_api_key,
+        required=True,
+    )
     
     # Build config dict for backend
     config_dict = pl_cfg.to_dict()

{synth_ai-0.2.23.dev2 → synth_ai-0.2.23.dev3}/synth_ai/api/train/cli.py

@@ -5,10 +5,9 @@ import contextlib
 import importlib
 import json
 import os
-import time
 from collections.abc import Callable, Mapping
 from pathlib import Path
-from typing import Any, cast
+from typing import Any, NoReturn, cast
 
 import click
 
@@ -28,13 +27,14 @@ from synth_ai.streaming import (
     StreamEndpoints,
     StreamType,
 )
+from synth_ai.utils.env import load_env_file
+from synth_ai.utils.errors import format_error_message, get_required_value
 
 from .builders import build_prompt_learning_payload, build_rl_payload, build_sft_payload
 from .config_finder import discover_configs, prompt_for_config
 from .env_resolver import KeySpec, resolve_env
 from .task_app import check_task_app_health
 from .utils import (
-    REPO_ROOT,
     TrainError,
     ensure_api_base,
     http_get,
@@ -88,93 +88,6 @@ def _format_text_replacements(obj: dict[str, Any] | None, max_display: int = _MA
     return lines
 
 
-def _discover_dataset_candidates(
-    config_path: Path, limit: int = 50, timeout: float = 10.0
-) -> list[Path]:
-    root = config_path.parent
-    parent = root.parent
-    cwd = Path.cwd()
-
-    search_dirs: list[Path] = [
-        root,
-        root / "datasets",
-        parent,
-        parent / "datasets",
-        parent / "ft_data",
-        cwd,
-        cwd / "datasets",
-        cwd / "ft_data",
-        REPO_ROOT / "datasets",
-        REPO_ROOT / "ft_data",
-        REPO_ROOT / "traces",
-    ]
-
-    candidates: list[Path] = []
-    seen: set[Path] = set()
-    start = time.monotonic()
-    timed_out = False
-    for directory in search_dirs:
-        if timed_out or time.monotonic() - start > timeout:
-            timed_out = True
-            break
-        if not directory.exists() or not directory.is_dir():
-            continue
-        for path in directory.rglob("*.jsonl"):
-            if time.monotonic() - start > timeout:
-                timed_out = True
-                break
-            try:
-                resolved = path.resolve()
-            except OSError:
-                continue
-            if resolved in seen:
-                continue
-            seen.add(resolved)
-            if resolved.stat().st_size == 0:
-                continue
-            candidates.append(resolved)
-            if len(candidates) >= limit:
-                return candidates
-    return candidates
-
-
-def prompt_for_dataset(config_path: Path) -> Path:
-    candidates = _discover_dataset_candidates(config_path)
-    while True:
-        if candidates:
-            click.echo("Select dataset JSONL file:")
-            for idx, candidate in enumerate(candidates, start=1):
-                click.echo(f"  {idx}) {candidate}")
-            click.echo("  m) Enter path manually")
-            click.echo("  0) Abort")
-            choice = click.prompt("Choice", default="m").strip().lower()
-            if choice == "0":
-                raise click.ClickException("Aborted by user")
-            if choice in {"m", "manual"}:
-                selected = _prompt_manual_dataset()
-            else:
-                try:
-                    idx = int(choice)
-                except ValueError:
-                    click.echo("Invalid selection; try again")
-                    continue
-                if idx < 1 or idx > len(candidates):
-                    click.echo("Invalid selection; try again")
-                    continue
-                selected = candidates[idx - 1]
-        else:
-            selected = _prompt_manual_dataset()
-
-        if selected.exists() and selected.suffix == ".jsonl":
-            return selected.resolve()
-        click.echo("File not found or not a .jsonl; please try again.")
-
-
-def _prompt_manual_dataset() -> Path:
-    manual = click.prompt("Enter dataset JSONL path", type=str).strip()
-    return Path(manual).expanduser()
-
-
 def _default_backend() -> str:
     """Resolve backend URL with proper production default."""
     # Check explicit override first
@@ -326,6 +239,7 @@ def train_command(
     examples_limit: int | None,
 ) -> None:
     """Interactive launcher for RL / SFT / Prompt Learning jobs."""
+    load_env_file()
 
     candidates = discover_configs(
         list(config_paths), requested_type=train_type if train_type != "auto" else None
@@ -338,8 +252,18 @@ def train_command(
 
     effective_type = train_type if train_type != "auto" else selection.train_type
     if effective_type not in {"rl", "sft", "prompt_learning"}:
-        effective_type = click.prompt(
-            "Detected config type is ambiguous. Enter type", type=click.Choice(["rl", "sft", "prompt_learning"])
+        raise click.UsageError(
+            format_error_message(
+                summary="Training type required",
+                context="Determining which trainer to invoke",
+                problem="Config metadata did not specify rl / sft / prompt_learning and no --type flag was provided",
+                impact="CLI cannot select the correct builder without a type",
+                solutions=[
+                    ("Pass --type rl|sft|prompt_learning", "Explicitly tell the CLI which workflow to run"),
+                    ("Add algorithm.type metadata to the config", "Include algorithm.type or prompt_learning markers in the TOML"),
+                    ("Use separate config files per training mode", "Keeps intent unambiguous for automation"),
+                ],
+            )
         )
 
     cfg_path = selection.path
@@ -401,9 +325,11 @@ def train_command(
         )
     click.echo(f"Using env file: {env_path}")
 
-    synth_key = env_values.get("SYNTH_API_KEY") or os.environ.get("SYNTH_API_KEY")
-    if not synth_key:
-        raise click.ClickException("SYNTH_API_KEY required")
+    synth_key = get_required_value(
+        "synth_api_key",
+        env_value=env_values.get("SYNTH_API_KEY") or os.environ.get("SYNTH_API_KEY"),
+    )
+    os.environ["SYNTH_API_KEY"] = synth_key
 
     backend_base = ensure_api_base(backend)
     click.echo(f"Backend base: {backend_base} (key {mask_value(synth_key)})")
@@ -605,9 +531,11 @@ def handle_rl(
             # Parsing verification summary failed, but verification itself succeeded
             click.echo("Verification OK")
 
-    env_key = os.environ.get("ENVIRONMENT_API_KEY")
-    if not env_key:
-        raise click.ClickException("ENVIRONMENT_API_KEY required for RL flow")
+    env_key = get_required_value(
+        "environment_api_key",
+        env_value=os.environ.get("ENVIRONMENT_API_KEY"),
+    )
+    os.environ["ENVIRONMENT_API_KEY"] = env_key
 
     click.echo("Performing task app health check…")
     health = check_task_app_health(build.task_url, env_key)
@@ -693,19 +621,14 @@ def handle_sft(
     stream_format: str,
     examples_limit: int | None,
 ) -> None:
-    dataset_path = dataset_override
-
-    while True:
-        try:
-            build = build_sft_payload(
-                config_path=cfg_path,
-                dataset_override=dataset_path,
-                allow_experimental=allow_experimental,
-            )
-            break
-        except TrainError as exc:
-            click.echo(str(exc))
-            dataset_path = prompt_for_dataset(cfg_path)
+    try:
+        build = build_sft_payload(
+            config_path=cfg_path,
+            dataset_override=dataset_override,
+            allow_experimental=allow_experimental,
+        )
+    except TrainError as exc:
+        _raise_sft_usage_error(exc)
 
     limited_path: Path | None = None
 
@@ -847,6 +770,45 @@ def handle_sft(
                 limited_path.parent.rmdir()
 
 
+def _raise_sft_usage_error(exc: TrainError) -> NoReturn:
+    message = str(exc).strip()
+    lower_msg = message.lower()
+    context = "Preparing SFT training job payload"
+    impact = "Cannot submit training job without a valid dataset path"
+
+    if "dataset not specified" in lower_msg:
+        raise click.UsageError(
+            format_error_message(
+                summary="Dataset path required",
+                context=context,
+                problem="No dataset path was provided via config or CLI",
+                impact=impact,
+                solutions=[
+                    ("Add [job].data = \"/path/to/data.jsonl\" to the config", "Persist the dataset path in the TOML file"),
+                    ("Re-run with --dataset /path/to/data.jsonl", "Override the dataset path from the CLI"),
+                    ("Use an absolute path accessible from the current working directory", "Relative paths are resolved from the shell cwd"),
+                ],
+            )
+        ) from exc
+
+    if "dataset not found" in lower_msg:
+        raise click.UsageError(
+            format_error_message(
+                summary="Dataset path not found",
+                context=context,
+                problem=message,
+                impact=impact,
+                solutions=[
+                    ("Verify the dataset path exists on disk", "Double-check spelling and that the file hasn't moved"),
+                    ("Provide an absolute path to the dataset file", "Avoid relying on relative paths that resolve incorrectly"),
+                    ("Sync the dataset to this machine before running the CLI", "Remote paths must be accessible locally"),
+                ],
+            )
+        ) from exc
+
+    raise click.ClickException(message) from exc
+
+
 def _save_prompt_learning_results_locally(
     *,
     backend_base: str,
@@ -1121,23 +1083,24 @@ def handle_prompt_learning(
     stream_format: str,
 ) -> None:
     """Handle prompt learning job creation (MIPRO or GEPA)."""
-    import os
+    env_key = get_required_value(
+        "environment_api_key",
+        env_value=os.environ.get("ENVIRONMENT_API_KEY"),
+    )
+    os.environ["ENVIRONMENT_API_KEY"] = env_key
     
     overrides: dict[str, Any] = {
         "backend": backend_base,
+        "task_url": task_url_override,
     }
     
     build = build_prompt_learning_payload(
         config_path=cfg_path,
-        task_url=None,  # Force using TOML only
+        task_url=task_url_override,
         overrides=overrides,
         allow_experimental=allow_experimental,
     )
     
-    env_key = os.environ.get("ENVIRONMENT_API_KEY")
-    if not env_key:
-        raise click.ClickException("ENVIRONMENT_API_KEY required for prompt learning flow")
-    
     click.echo("Performing task app health check…")
     health = check_task_app_health(build.task_url, env_key)
     if not health.ok: