synth-ai 0.2.8.dev4__py3-none-any.whl → 0.2.23.dev3__py3-none-any.whl

synth_ai/learning/rl/client.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from contextlib import suppress
+from typing import Any
+
+from synth_ai.api.models.supported import (
+    UnsupportedModelError,
+    normalize_model_identifier,
+)
+
+from ..._utils.http import AsyncHttpClient, HTTPError, sleep
+
+
+def _api_base(b: str) -> str:
+    b = (b or "").rstrip("/")
+    return b if b.endswith("/api") else f"{b}/api"
+
+
+class RlClient:
+    """Lightweight RL client for provider-agnostic job control."""
+
+    def __init__(self, base_url: str, api_key: str, *, timeout: float = 600.0) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+
+    async def resolve_trainer_start_url(self, trainer_id: str) -> str:
+        path = f"/api/rl/services/{trainer_id}"
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=30.0) as http:
+            js = await http.get(path)
+        if not isinstance(js, dict):
+            raise HTTPError(
+                status=500,
+                url=path,
+                message="invalid_service_response",
+                body_snippet=str(js)[:200],
+            )
+        start_url = js.get("training_start_url")
+        if not isinstance(start_url, str) or not start_url:
+            raise HTTPError(
+                status=500,
+                url=path,
+                message="missing_training_start_url",
+                body_snippet=str(js)[:200],
+            )
+        return start_url
+
+    async def create_job(
+        self,
+        *,
+        model: str,
+        task_app_url: str,
+        trainer: dict[str, Any],
+        trainer_id: str | None = None,
+        job_config_id: str | None = None,
+        inline_config: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        try:
+            normalized_model = normalize_model_identifier(model)
+        except UnsupportedModelError as exc:
+            raise ValueError(str(exc)) from exc
+
+        body = {
+            "job_type": "rl",
+            "data": {
+                "model": normalized_model,
+                "endpoint_base_url": task_app_url,
+                **({"job_config_id": job_config_id} if job_config_id else {}),
+                **({"config": inline_config} if inline_config else {}),
+                "trainer": {
+                    "batch_size": int(trainer.get("batch_size", 1)),
+                    "group_size": max(2, int(trainer.get("group_size", 2))),
+                },
+            },
+        }
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=self._timeout) as http:
+            js = await http.post_json(f"{_api_base(self._base_url)}/rl/jobs", json=body)
+        if not isinstance(js, dict):
+            raise HTTPError(
+                status=500,
+                url="/api/rl/jobs",
+                message="invalid_create_response",
+                body_snippet=str(js)[:200],
+            )
+        return js
+
+    async def start_job_if_supported(self, job_id: str) -> dict[str, Any] | None:
+        path = f"{_api_base(self._base_url)}/rl/jobs/{job_id}/start"
+        try:
+            async with AsyncHttpClient(self._base_url, self._api_key, timeout=30.0) as http:
+                return await http.post_json(path, json={})
+        except HTTPError as he:  # noqa: PERF203
+            if he.status == 404:
+                return None
+            raise
+
+    async def get_job(self, job_id: str) -> dict[str, Any]:
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=30.0) as http:
+            return await http.get(f"{_api_base(self._base_url)}/learning/jobs/{job_id}")
+
+    async def get_events(
+        self, job_id: str, *, since_seq: int = 0, limit: int = 200
+    ) -> list[dict[str, Any]]:
+        params = {"since_seq": since_seq, "limit": limit}
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=30.0) as http:
+            try:
+                js = await http.get(
+                    f"{_api_base(self._base_url)}/learning/jobs/{job_id}/events",
+                    params=params,
+                    headers={"accept": "application/json"},
+                )
+            except HTTPError as he:
+                with suppress(Exception):
+                    print(
+                        f"[poll] events HTTPError status={he.status} url={he.url} since_seq={since_seq} body={(he.body_snippet or '')[:200]}"
+                    )
+                raise
+        if isinstance(js, dict):
+            evs = js.get("events") or js.get("data")
+            if isinstance(evs, list):
+                return evs
+        return []
+
+    async def get_metrics(
+        self, job_id: str, *, after_step: int = -1, limit: int = 200
+    ) -> list[dict[str, Any]]:
+        params = {"after_step": after_step, "limit": limit}
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=30.0) as http:
+            js = await http.get(
+                f"{_api_base(self._base_url)}/learning/jobs/{job_id}/metrics", params=params
+            )
+        if isinstance(js, dict) and isinstance(js.get("points"), list):
+            return js["points"]
+        return []
+
+    async def poll_until_terminal(
+        self,
+        job_id: str,
+        *,
+        interval_seconds: float = 2.0,
+        max_seconds: float | None = None,
+        empty_polls_threshold: int = 5,
+        startup_deadline_s: int = 45,
+        on_event: Callable[[dict[str, Any]], None] | None = None,
+        on_metric: Callable[[dict[str, Any]], None] | None = None,
+    ) -> dict[str, Any]:
+        last_seq_by_stream: dict[str, int] = {}
+        events_job_id: str | None = None
+        last_status: str | None = None
+        last_step_by_name: dict[str, int] = {}
+        empty_polls = 0
+        saw_any_event = False
+        start_t = time.time()
+        terminal = {"succeeded", "failed", "cancelled", "canceled", "error", "completed"}
+
+        while True:
+            status_data: dict[str, Any] | None = None
+            try:
+                status_data = await self.get_job(job_id)
+            except Exception:
+                status_data = None
+            if status_data is None:
+                with suppress(Exception):
+                    print(f"[poll] get_job returned None base={self._base_url} job_id={job_id}")
+            status = str((status_data or {}).get("status") or "").lower()
+            if status_data:
+                linked = status_data.get("linked_job_id")
+                if isinstance(linked, str) and linked and linked != events_job_id:
+                    events_job_id = linked
+                    with suppress(Exception):
+                        print(f"[poll] discovered linked_job_id stream={events_job_id}")
+            if status and status != last_status:
+                last_status = status
+                if on_event:
+                    with suppress(Exception):
+                        on_event({"type": "rl.status", "message": status})
+
+            stream_ids = [job_id]
+            if events_job_id and events_job_id not in stream_ids:
+                stream_ids.append(events_job_id)
+            with suppress(Exception):
+                print(
+                    f"[poll] streams={stream_ids} intervals={interval_seconds}s since_map={last_seq_by_stream} empty_polls={empty_polls}"
+                )
+            total_events_this_cycle = 0
+            terminal_event_seen = False
+            terminal_event_status: str | None = None
+            for ev_id in stream_ids:
+                since = last_seq_by_stream.get(ev_id, 0)
+                try:
+                    events = await self.get_events(ev_id, since_seq=since, limit=200)
+                except HTTPError as he:
+                    with suppress(Exception):
+                        print(
+                            f"[poll] get_events error status={he.status} url={he.url} since={since} body={(he.body_snippet or '')[:200]}"
+                        )
+                    events = []
+                except Exception as e:
+                    with suppress(Exception):
+                        print(
+                            f"[poll] get_events unexpected error ev_id={ev_id} since={since} err={type(e).__name__}: {e}"
+                        )
+                    events = []
+                total_events_this_cycle += len(events)
+                if events:
+                    saw_any_event = True
+                for e in events:
+                    seq_val = int(e.get("seq") or 0)
+                    if seq_val <= last_seq_by_stream.get(ev_id, 0):
+                        continue
+                    last_seq_by_stream[ev_id] = seq_val
+                    if on_event:
+                        with suppress(Exception):
+                            on_event(e)
+                    et = str(e.get("type") or e.get("event_type") or "").lower()
+                    if et in ("rl.job.completed", "workflow.completed", "rl.train.completed"):
+                        terminal_event_seen = True
+                        terminal_event_status = "succeeded"
+                    elif et in ("rl.job.failed", "workflow.failed"):
+                        terminal_event_seen = True
+                        terminal_event_status = "failed"
+
+            try:
+                after = max(last_step_by_name.values()) if last_step_by_name else -1
+                points = await self.get_metrics(job_id, after_step=after, limit=200)
+                for p in points:
+                    name = str(p.get("name") or "")
+                    step = int(p.get("step") or -1)
+                    if step <= last_step_by_name.get(name, -1):
+                        continue
+                    last_step_by_name[name] = step
+                    if on_metric:
+                        with suppress(Exception):
+                            on_metric(p)
+            except Exception:
+                pass
+
+            if terminal_event_seen:
+                return {"status": terminal_event_status or status or "completed", "job_id": job_id}
+            if status and status in terminal:
+                return {"status": status, "job_id": job_id}
+
+            if total_events_this_cycle == 0:
+                empty_polls += 1
+            else:
+                empty_polls = 0
+            if empty_polls >= max(1, int(empty_polls_threshold)):
+                with suppress(Exception):
+                    print(
+                        f"[poll] threshold hit: empty_polls={empty_polls} >= {empty_polls_threshold} streams={stream_ids} last_seq_map={last_seq_by_stream}"
+                    )
+                raise AssertionError(
+                    f"No new events detected for {empty_polls_threshold} consecutive polls. Check event ingestion."
+                )
+
+            if not saw_any_event and (time.time() - start_t) > int(startup_deadline_s):
+                with suppress(Exception):
+                    print(
+                        f"[poll] startup window exceeded: {startup_deadline_s}s base={self._base_url} job={job_id} streams={stream_ids} last_seq_map={last_seq_by_stream}"
+                    )
+                raise AssertionError(
+                    f"No events observed within startup window ({startup_deadline_s}s). Investigate event streaming."
+                )
+
+            await sleep(interval_seconds)
+            if max_seconds is not None and (time.time() - start_t) >= max_seconds:
+                raise TimeoutError(f"Polling timed out after {max_seconds}s for job {job_id}")

synth_ai/learning/rl/config.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+def _ensure_positive(value: Any, *, name: str) -> int:
+    try:
+        ivalue = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be an integer") from exc
+    if ivalue < 1:
+        raise ValueError(f"{name} must be >= 1")
+    return ivalue
+
+
+@dataclass(slots=True)
+class RLJobConfig:
+    model: str
+    task_app_url: str
+    trainer_id: str
+    batch_size: int = 1
+    group_size: int = 2
+    job_config_id: str | None = None
+    inline_config: dict[str, Any] | None = None
+
+    def trainer_dict(self) -> dict[str, Any]:
+        return {
+            "batch_size": _ensure_positive(self.batch_size, name="trainer.batch_size"),
+            "group_size": _ensure_positive(self.group_size, name="trainer.group_size"),
+        }

synth_ai/{rl → learning/rl}/contracts.py

@@ -1,20 +1,17 @@
-from __future__ import annotations
+"""Compatibility re-export for rollout contracts used by RL tooling."""
 
-"""
-Compatibility layer: re-export Task App rollout contracts from synth_ai.task.contracts
-so existing imports continue to work while consolidating under synth_ai.task.
-"""
+from __future__ import annotations
 
 from synth_ai.task.contracts import (
     RolloutEnvSpec,
+    RolloutMetrics,
     RolloutPolicySpec,
     RolloutRecordConfig,
-    RolloutSafetyConfig,
     RolloutRequest,
+    RolloutResponse,
+    RolloutSafetyConfig,
     RolloutStep,
     RolloutTrajectory,
-    RolloutMetrics,
-    RolloutResponse,
 )
 
 __all__ = [
@@ -28,5 +25,3 @@ __all__ = [
     "RolloutMetrics",
     "RolloutResponse",
 ]
-
-

synth_ai/{rl → learning/rl}/env_keys.py

@@ -1,12 +1,12 @@
-from __future__ import annotations
+"""Helpers for uploading Environment credentials to the backend."""
 
-"""Helpers for uploading RL environment credentials to the backend."""
+from __future__ import annotations
 
 import base64
 import binascii
 import json
-from typing import Any, Dict
 import os
+from typing import Any
 
 import requests
 from nacl.public import PublicKey, SealedBox
@@ -18,14 +18,12 @@ _ALGORITHM = "libsodium.sealedbox.v1"
 
 
 def encrypt_for_backend(pubkey_b64: str, secret: str | bytes) -> str:
-    """Encrypt ``secret`` for storage by the backend using libsodium sealed boxes."""
-
     if not isinstance(pubkey_b64, str) or not pubkey_b64.strip():
         raise ValueError("public key must be a non-empty base64 string")
 
     try:
         key_bytes = base64.b64decode(pubkey_b64, validate=True)
-    except binascii.Error as exc:  # pragma: no cover - defensive guard
+    except binascii.Error as exc:
         raise ValueError("public key must be base64-encoded") from exc
 
     if len(key_bytes) != 32:
@@ -35,7 +33,7 @@ def encrypt_for_backend(pubkey_b64: str, secret: str | bytes) -> str:
         secret_bytes = secret.encode("utf-8")
     elif isinstance(secret, bytes):
         secret_bytes = secret
-    else:  # pragma: no cover - type guard
+    else:
         raise TypeError("secret must be str or bytes")
 
     if not secret_bytes:
@@ -52,20 +50,17 @@ def setup_environment_api_key(
     token: str | None = None,
     *,
     timeout: float = 15.0,
-) -> Dict[str, Any]:
-    """Upload an ENVIRONMENT_API_KEY to the backend."""
-
+) -> dict[str, Any]:
     backend = backend_base.rstrip("/")
     if not backend:
         raise ValueError("backend_base must be provided")
     if not synth_api_key:
         raise ValueError("synth_api_key must be provided")
 
-    # Require caller-provided plaintext. If not provided, read from ENVIRONMENT_API_KEY.
     plaintext = token if token is not None else os.getenv("ENVIRONMENT_API_KEY", "").strip()
     if not plaintext:
         raise ValueError("ENVIRONMENT_API_KEY must be set (or pass token=...) to upload")
-    if not isinstance(plaintext, str):  # pragma: no cover - defensive guard
+    if not isinstance(plaintext, str):
         raise TypeError("token must be a string")
 
     token_bytes = plaintext.encode("utf-8")
@@ -81,7 +76,7 @@ def setup_environment_api_key(
 
     try:
         doc = response.json()
-    except ValueError as exc:  # pragma: no cover - backend invariant
+    except ValueError as exc:
         raise RuntimeError("backend returned invalid JSON for public key") from exc
 
     if not isinstance(doc, dict):
@@ -91,17 +86,51 @@ def setup_environment_api_key(
     if not isinstance(pubkey, str) or not pubkey:
         raise RuntimeError("backend response missing public_key")
 
-    # The backend currently returns a single algorithm identifier; keep a guard in
-    # case future versions change the value and we need to surface that to callers.
     alg = doc.get("alg")
     if alg is not None and alg != _ALGORITHM:
         raise RuntimeError(f"unsupported sealed box algorithm: {alg}")
 
+    # Diagnostics: safe previews and hashes to correlate with backend logs
+    try:
+        import hashlib as _hash
+
+        pk_bytes = base64.b64decode(pubkey, validate=True)
+        pk_sha256 = _hash.sha256(pk_bytes).hexdigest()
+        print(
+            f"[env-keys] public_key: b64_len={len(pubkey)} sha256={pk_sha256} head={pubkey[:16]} tail={pubkey[-16:]}"
+        )
+        _plen = len(plaintext)
+        _ppref = (plaintext[:6] + "…") if _plen > 10 else plaintext
+        _psuf = ("…" + plaintext[-4:]) if _plen > 10 else ""
+        _has_ws = any(ch.isspace() for ch in plaintext)
+        print(
+            f"[env-keys] plaintext: len={_plen} preview={_ppref}{_psuf} has_ws={bool(_has_ws)}"
+        )
+    except Exception:
+        pass
+
     ciphertext_b64 = encrypt_for_backend(pubkey, token_bytes)
 
     body = {"name": "ENVIRONMENT_API_KEY", "ciphertext_b64": ciphertext_b64}
     post_url = f"{backend}/api/v1/env-keys"
-    response2 = requests.post(post_url, headers={**headers, "Content-Type": "application/json"}, json=body, timeout=timeout)
+    # Ciphertext diagnostics
+    try:
+        import hashlib as _hash
+
+        _ct_bytes = base64.b64decode(ciphertext_b64, validate=True)
+        _ct_sha = _hash.sha256(_ct_bytes).hexdigest()
+        print(
+            f"[env-keys] ciphertext: b64_len={len(ciphertext_b64)} sha256={_ct_sha} head={ciphertext_b64[:16]} tail={ciphertext_b64[-16:]}"
+        )
+    except Exception:
+        pass
+
+    response2 = requests.post(
+        post_url,
+        headers={**headers, "Content-Type": "application/json"},
+        json=body,
+        timeout=timeout,
+    )
     _raise_with_detail(response2)
 
     try:

synth_ai/learning/rl/secrets.py

@@ -0,0 +1,13 @@
+"""Helpers for generating Environment credentials."""
+
+from __future__ import annotations
+
+import secrets
+
+__all__ = ["mint_environment_api_key"]
+
+
+def mint_environment_api_key() -> str:
+    """Mint a random ENVIRONMENT_API_KEY value."""
+
+    return secrets.token_hex(32)