synth-ai 0.4.1__py3-none-any.whl → 0.4.4__py3-none-any.whl

synth_ai/sdk/task/in_process.py

@@ -409,40 +409,51 @@ async def _verify_preconfigured_url_ready(
 
 
 class InProcessTaskApp:
-    """
-    Context manager for running task apps in-process with automatic tunneling.
-    
+    """Context manager for running Local APIs in-process with automatic tunneling.
+
     This class simplifies local development and demos by:
-    1. Starting a task app server in a background thread
+    1. Starting a Local API server in a background thread
     2. Opening a tunnel automatically (Cloudflare by default, or use preconfigured URL)
-    3. Providing the tunnel URL for GEPA/MIPRO jobs
+    3. Providing the tunnel URL for GEPA/MIPRO/RL jobs
     4. Cleaning up everything on exit
-    
+
+    (Alias: also known as "task app" in older documentation)
+
     Supports multiple input methods:
     - FastAPI app instance (most direct)
     - TaskAppConfig object
     - Config factory function (Callable[[], TaskAppConfig])
-    - Task app file path (fallback for compatibility)
-    
+    - Local API file path (fallback for compatibility)
+
     Tunnel modes:
     - "quick": Cloudflare quick tunnel (default for local dev)
     - "named": Cloudflare named/managed tunnel
     - "local": No tunnel, use localhost URL directly
     - "preconfigured": Use externally-provided URL (set via preconfigured_url param or
       SYNTH_TASK_APP_URL env var). Useful for ngrok or other external tunnel providers.
-    
+
+    Attributes:
+        url: The public URL of the running Local API (tunnel URL or localhost).
+            Available after entering the context manager.
+        local_url: The local URL (http://host:port) where the server is running.
+        port: The actual port the server is bound to (may differ from requested
+            port if auto_find_port=True).
+        host: The host the server is bound to.
+        tunnel_mode: The tunnel mode being used.
+        is_running: Whether the server is currently running.
+
     Example:
         ```python
         from synth_ai.sdk.task.in_process import InProcessTaskApp
         from heartdisease_task_app import build_config
-        
+
         # Default: use Cloudflare quick tunnel
         async with InProcessTaskApp(
             config_factory=build_config,
             port=8114,
         ) as task_app:
-            print(f"Task app running at: {task_app.url}")
-        
+            print(f"Local API running at: {task_app.url}")
+
         # Use preconfigured URL (e.g., from ngrok, localtunnel, etc.)
         async with InProcessTaskApp(
             config_factory=build_config,
@@ -450,7 +461,7 @@ class InProcessTaskApp:
             tunnel_mode="preconfigured",
             preconfigured_url="https://abc123.ngrok.io",
         ) as task_app:
-            print(f"Task app running at: {task_app.url}")
+            print(f"Local API running at: {task_app.url}")
         ```
     """
 
@@ -475,14 +486,13 @@ class InProcessTaskApp:
         on_start: Optional[Callable[[InProcessTaskApp], None]] = None,
         on_stop: Optional[Callable[[InProcessTaskApp], None]] = None,
     ):
-        """
-        Initialize in-process task app.
-        
+        """Initialize in-process Local API.
+
         Args:
             app: FastAPI app instance (most direct)
             config: TaskAppConfig object
             config_factory: Callable that returns TaskAppConfig
-            task_app_path: Path to task app .py file (fallback)
+            task_app_path: Path to Local API .py file (fallback, alias: task app)
             port: Local port to run server on
             host: Host to bind to (default: 127.0.0.1, use 0.0.0.0 for external access)
             tunnel_mode: Tunnel mode - "quick", "named", "local", or "preconfigured"
@@ -594,7 +604,7 @@ class InProcessTaskApp:
         else:
             self._prefetched_tunnel_config = None
         
-        logger.info(f"Starting in-process task app on {self.host}:{self.port}")
+        logger.debug(f"Starting in-process task app on {self.host}:{self.port}")
 
         # For named tunnels, the port is baked into the tunnel config - we MUST use it
         tunnel_config = getattr(self, "_prefetched_tunnel_config", None) or {}
@@ -624,7 +634,7 @@ class InProcessTaskApp:
                     f"Port {self.port} is in use, attempting to find available port..."
                 )
                 self.port = _find_available_port(self.host, self.port)
-                logger.info(f"Using port {self.port} instead")
+                logger.debug(f"Using port {self.port} instead")
             else:
                 # Try to kill process on port
                 logger.warning(
@@ -683,7 +693,7 @@ class InProcessTaskApp:
                             f"Task app at {self._task_app_path} must expose either:\n"
                             f"  - An ASGI app via `app = FastAPI(...)` or factory function\n"
                             f"  - A `build_config()` function that returns TaskAppConfig\n"
-                            f"  - Be registered with register_task_app()"
+                            f"  - Be registered with register_local_api() or register_task_app()"
                         ) from None
 
         # 2. Start uvicorn in background thread
@@ -719,7 +729,7 @@ class InProcessTaskApp:
         await wait_for_health_check(
             self.host, self.port, api_key, timeout=self.health_check_timeout
         )
-        logger.info(f"Health check passed for {self.host}:{self.port}")
+        logger.debug(f"Health check passed for {self.host}:{self.port}")
 
         # 4. Determine tunnel mode (env var can override)
         mode = os.getenv("SYNTH_TUNNEL_MODE", self.tunnel_mode)
@@ -774,7 +784,7 @@ class InProcessTaskApp:
             # Local mode: skip tunnel, use localhost
             self.url = f"http://{self.host}:{self.port}"
             self._tunnel_proc = None
-            logger.info(f"Using local mode: {self.url}")
+            logger.debug(f"Using local mode: {self.url}")
         elif mode == "named":
             # Named tunnel mode: fully automatic managed tunnel
             # 1. Check for existing tunnel

synth_ai/sdk/task/in_process_runner.py

@@ -31,7 +31,7 @@ from synth_ai.core.env import get_backend_from_env
 from synth_ai.core.telemetry import log_info
 from synth_ai.sdk.api.train.prompt_learning import PromptLearningJob
 from synth_ai.sdk.api.train.rl import RLJob
-from synth_ai.sdk.api.train.task_app import TaskAppHealth, check_task_app_health
+from synth_ai.sdk.api.train.local_api import LocalAPIHealth, check_local_api_health
 from synth_ai.sdk.api.train.utils import ensure_api_base
 from synth_ai.sdk.task.in_process import InProcessTaskApp
 
@@ -52,7 +52,7 @@ class InProcessJobResult:
     status: Dict[str, Any]
     task_app_url: str
     backend_url: str
-    task_app_health: TaskAppHealth | None = None
+    task_app_health: LocalAPIHealth | None = None
 
 
 def _normalize_base_url(url: str) -> str:
@@ -234,9 +234,14 @@ async def run_in_process_job(
         should_skip_health_check = skip_tunnel_verification or dns_verified_by_backend
         if should_skip_health_check:
             reason = "tunnel verification disabled" if skip_tunnel_verification else "backend verified DNS"
-            health = TaskAppHealth(ok=True, health_status=200, task_info_status=200, detail=f"Skipped ({reason})")
+            health = LocalAPIHealth(
+                ok=True,
+                health_status=200,
+                task_info_status=200,
+                detail=f"Skipped ({reason})",
+            )
         else:
-            health = check_task_app_health(task_url, resolved_task_app_key)
+            health = check_local_api_health(task_url, resolved_task_app_key)
             if not health.ok:
                 raise RuntimeError(f"Task app health check failed for {task_url}: {health.detail}")
 

synth_ai/sdk/task/rubrics/__init__.py

@@ -2,7 +2,7 @@
 
 This module provides:
 - Flexible rubric models (Criterion, Rubric) for general task app use
-- Strict validators (StrictCriterion, StrictRubric) for step-wise judges
+- Strict validators (StrictCriterion, StrictRubric) for step-wise verifiers
 - Loading utilities supporting JSON, YAML, and HTTP sources
 - Blending utilities for composing rubrics
 - Scoring utilities for events and outcomes
@@ -16,7 +16,7 @@ from .models import Criterion, Rubric
 # Scoring
 from .scoring import score_events_against_rubric, score_outcome_against_rubric
 
-# Strict validators (for judge configs)
+# Strict validators (for verifier configs)
 from .strict import (
     StrictCriterion,
     StrictRubric,
@@ -52,4 +52,3 @@ RubricSpec = StrictRubric
 
 
 
-

synth_ai/sdk/task/rubrics/loaders.py

@@ -62,7 +62,7 @@ def load_rubric(source: str | dict[str, Any] | Rubric | None) -> Rubric | None:
         Parsed Rubric instance or None if source is None
         
     Raises:
-        ValueError: If the rubric format is incorrect (e.g., backend judge format)
+        ValueError: If the rubric format is incorrect (e.g., backend verifier format)
         ValidationError: If the rubric fails schema validation
     """
     if source is None:
@@ -77,7 +77,7 @@ def load_rubric(source: str | dict[str, Any] | Rubric | None) -> Rubric | None:
         text, suffix = _load_text(str(source))
         data = _parse_structured(text, suffix)
     
-    # Check if this looks like a backend judge rubric (wrong format)
+    # Check if this looks like a backend verifier rubric (wrong format)
     if (
         isinstance(data, dict)
         and "event" in data
@@ -88,9 +88,9 @@ def load_rubric(source: str | dict[str, Any] | Rubric | None) -> Rubric | None:
     ):
         source_hint = f" ({source})" if isinstance(source, str) else ""
         raise ValueError(
-            f"Rubric appears to be in backend judge format (has 'event'/'outcome' keys){source_hint}. "
+            f"Rubric appears to be in backend verifier format (has 'event'/'outcome' keys){source_hint}. "
             f"Task apps require rubrics with 'version', 'goal_text', and 'criteria' fields. "
-            f"Backend judge rubrics should be named '*_backend_judge.json' and loaded by judge functions."
+            f"Backend verifier rubrics should be named '*_backend_verifier.json' and loaded by verifier functions."
         )
     
     return Rubric.model_validate(data)

synth_ai/sdk/task/rubrics/strict.py

@@ -1,11 +1,11 @@
-"""Strict rubric validators for step-wise judges.
+"""Strict rubric validators for step-wise verifiers.
 
 These validators enforce stricter constraints than the general-purpose rubrics:
 - Weights must be ≤ 1.0 and sum to exactly 1.0
 - Only weighted_sum aggregation is allowed
 - All required fields must be non-empty
 
-Used primarily for validation in judge configurations.
+Used primarily for validation in verifier configurations.
 """
 
 from __future__ import annotations
@@ -53,7 +53,7 @@ class StrictCriterion(pydantic.BaseModel):
 
 
 class StrictRubric(pydantic.BaseModel):
-    """Strict rubric definition for step-wise judges.
+    """Strict rubric definition for step-wise verifiers.
     
     Enforces:
     - Weights must sum to 1.0
@@ -146,4 +146,3 @@ def validate_rubric_files(paths: Iterable[Path]) -> list[StrictRubric]:
     for path in paths:
         validated.append(validate_rubric_file(path))
     return validated
-

synth_ai/sdk/task/server.py

@@ -1,10 +1,15 @@
-"""FastAPI scaffolding for Task Apps (local dev + deployment)."""
+"""FastAPI scaffolding for Task Apps (local dev + deployment).
+
+Prefer synth_ai.sdk.localapi.server moving forward. This module remains for
+backward compatibility during the naming transition.
+"""
 
 from __future__ import annotations
 
 import asyncio
 import inspect
 import os
+import threading
 from collections.abc import Awaitable, Callable, Iterable, Mapping, MutableMapping, Sequence
 from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
@@ -66,7 +71,7 @@ class TaskAppConfig:
     
     A TaskAppConfig defines all the components needed to create a task app:
     - Task information (base_task_info)
-    - Task set description (describe_taskset)
+    - Task set description (provide_taskset_description)
     - Task instance provider (provide_task_instances)
     - Rollout executor (rollout)
     - Optional rubrics, datasets, proxy config, etc.
@@ -76,19 +81,18 @@ class TaskAppConfig:
     
     Example:
         >>> from synth_ai.sdk.task.server import TaskAppConfig, create_task_app
-        >>> from synth_ai.sdk.task.contracts import TaskInfo
-        >>> 
+        >>>
         >>> def build_config() -> TaskAppConfig:
         ...     return TaskAppConfig(
         ...         app_id="my_task",
         ...         name="My Task App",
         ...         description="A simple task app",
-        ...         base_task_info=TaskInfo(...),
-        ...         describe_taskset=lambda: {"splits": ["train", "val"]},
+        ...         provide_taskset_description=lambda: {"splits": ["train", "val"]},
         ...         provide_task_instances=lambda seeds: [...],
         ...         rollout=lambda req, r: {...},
+        ...         # base_task_info is optional - auto-derived from app_id/name
         ...     )
-        >>> 
+        >>>
         >>> app = create_task_app(build_config())
         >>> # app is a FastAPI instance ready to run
     
@@ -96,8 +100,8 @@ class TaskAppConfig:
         app_id: Unique identifier for this task app
         name: Human-readable name
         description: Description of what this task app does
-        base_task_info: Base TaskInfo that all instances inherit from
-        describe_taskset: Function that returns taskset metadata
+        base_task_info: Base TaskInfo (optional - auto-derived from app_id/name if not provided)
+        provide_taskset_description: Function that returns taskset metadata
         provide_task_instances: Function that yields TaskInfo instances for given seeds
         rollout: Function that executes a rollout request and returns response
         dataset_registry: Optional registry for task datasets
@@ -116,10 +120,10 @@ class TaskAppConfig:
     app_id: str
     name: str
     description: str
-    base_task_info: TaskInfo
-    describe_taskset: TasksetDescriptor
+    provide_taskset_description: TasksetDescriptor
     provide_task_instances: InstanceProvider
     rollout: RolloutExecutor
+    base_task_info: TaskInfo | None = None  # Auto-derived from app_id/name if not provided
     dataset_registry: TaskDatasetRegistry | None = None
     rubrics: RubricBundle | None = field(default_factory=RubricBundle)
     proxy: ProxyConfig | None = None
@@ -139,10 +143,10 @@ class TaskAppConfig:
             app_id=self.app_id,
             name=self.name,
             description=self.description,
-            base_task_info=self.base_task_info,
-            describe_taskset=self.describe_taskset,
+            provide_taskset_description=self.provide_taskset_description,
             provide_task_instances=self.provide_task_instances,
             rollout=self.rollout,
+            base_task_info=self.base_task_info,  # May be None - auto-derived in create_task_app
             dataset_registry=self.dataset_registry,
             rubrics=self.rubrics or RubricBundle(),
             proxy=self.proxy,
@@ -157,6 +161,10 @@ class TaskAppConfig:
         )
 
 
+class LocalAPIConfig(TaskAppConfig):
+    """Alias for TaskAppConfig with LocalAPI naming."""
+
+
 def _maybe_await(result: Any) -> Awaitable[Any]:
     if inspect.isawaitable(result):
         return asyncio.ensure_future(result)
@@ -299,10 +307,10 @@ def create_task_app(config: TaskAppConfig) -> FastAPI:
         ...         app_id="my_task",
         ...         name="My Task",
         ...         description="A task app",
-        ...         base_task_info=TaskInfo(...),
-        ...         describe_taskset=lambda: {"splits": ["train"]},
+        ...         provide_taskset_description=lambda: {"splits": ["train"]},
         ...         provide_task_instances=lambda seeds: [...],
         ...         rollout=lambda req, r: {...},
+        ...         # base_task_info is optional - auto-derived from app_id/name
         ...     )
         >>>
         >>> app = create_task_app(build_config())
@@ -312,6 +320,16 @@ def create_task_app(config: TaskAppConfig) -> FastAPI:
     log_info("create_task_app invoked", ctx=ctx)
     cfg = config.clone()
     cfg.rubrics = cfg.rubrics or RubricBundle()
+
+    # Auto-derive base_task_info from app_id/name if not provided
+    if cfg.base_task_info is None:
+        cfg.base_task_info = TaskInfo(
+            task={"id": cfg.app_id, "name": cfg.name},
+            dataset={"id": cfg.app_id},
+            inference={},
+            limits={},
+        )
+
     app = FastAPI(title=cfg.name, description=cfg.description)
 
     for key, value in cfg.app_state.items():
@@ -431,7 +449,7 @@ def create_task_app(config: TaskAppConfig) -> FastAPI:
             all_seeds.extend(_normalise_seeds(seeds))
 
         if not all_seeds:
-            descriptor_result = await _maybe_await(cfg.describe_taskset())
+            descriptor_result = await _maybe_await(cfg.provide_taskset_description())
             return to_jsonable({"taskset": descriptor_result})
 
         instances = await _maybe_await(cfg.provide_task_instances(all_seeds))
@@ -578,3 +596,45 @@ def run_task_app(
             remove_service_record(port)
         except Exception:
             pass
+
+
+def run_server_background(
+    app: Any,
+    port: int,
+    host: str = "0.0.0.0",
+) -> threading.Thread:
+    """Start uvicorn server in a background daemon thread.
+
+    For manual control over task app lifecycle. If you want automatic
+    tunnel management, use InProcessTaskApp instead.
+
+    Args:
+        app: ASGI/FastAPI application
+        port: Port to bind
+        host: Host to bind (default 0.0.0.0 for tunnel access)
+
+    Returns:
+        Daemon thread running the server (stops when main process exits)
+
+    Example:
+        from synth_ai.sdk.task import run_server_background
+        from synth_ai.sdk.tunnels import wait_for_health_check
+
+        thread = run_server_background(my_app, port=8001)
+        await wait_for_health_check("localhost", 8001, api_key)
+    """
+    import asyncio
+    import threading
+
+    import uvicorn
+
+    def serve() -> None:
+        config = uvicorn.Config(app, host=host, port=port, log_level="warning")
+        server = uvicorn.Server(config)
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        loop.run_until_complete(server.serve())
+
+    thread = threading.Thread(target=serve, daemon=True, name=f"uvicorn-{port}")
+    thread.start()
+    return thread