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

synth_ai/sdk/learning/rl/client.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from contextlib import suppress
+from typing import Any
+
+from synth_ai.core._utils.http import AsyncHttpClient, HTTPError, sleep
+from synth_ai.sdk.api.models.supported import (
+    UnsupportedModelError,
+    normalize_model_identifier,
+)
+
+
+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/sdk/learning/rl/contracts.py

@@ -0,0 +1,23 @@
+"""Compatibility re-export for rollout contracts used by RL tooling."""
+
+from __future__ import annotations
+
+from synth_ai.sdk.task.contracts import (
+    RolloutEnvSpec,
+    RolloutMetrics,
+    RolloutPolicySpec,
+    RolloutRecordConfig,
+    RolloutRequest,
+    RolloutResponse,
+    RolloutSafetyConfig,
+)
+
+__all__ = [
+    "RolloutEnvSpec",
+    "RolloutPolicySpec",
+    "RolloutRecordConfig",
+    "RolloutSafetyConfig",
+    "RolloutRequest",
+    "RolloutMetrics",
+    "RolloutResponse",
+]

synth_ai/sdk/learning/rl/env_keys.py

@@ -0,0 +1,166 @@
+"""Helpers for uploading Environment credentials to the backend."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import os
+from typing import Any
+
+import requests
+from nacl.public import PublicKey, SealedBox
+
+__all__ = ["encrypt_for_backend", "setup_environment_api_key", "MAX_ENVIRONMENT_API_KEY_BYTES"]
+
+MAX_ENVIRONMENT_API_KEY_BYTES = 8 * 1024
+_ALGORITHM = "libsodium.sealedbox.v1"
+
+
+def encrypt_for_backend(pubkey_b64: str, secret: str | bytes) -> str:
+    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:
+        raise ValueError("public key must be base64-encoded") from exc
+
+    if len(key_bytes) != 32:
+        raise ValueError("public key must be 32 bytes for X25519")
+
+    if isinstance(secret, str):
+        secret_bytes = secret.encode("utf-8")
+    elif isinstance(secret, bytes):
+        secret_bytes = secret
+    else:
+        raise TypeError("secret must be str or bytes")
+
+    if not secret_bytes:
+        raise ValueError("secret must not be empty")
+
+    box = SealedBox(PublicKey(key_bytes))
+    ciphertext = box.encrypt(secret_bytes)
+    return base64.b64encode(ciphertext).decode("ascii")
+
+
+def setup_environment_api_key(
+    backend_base: str,
+    synth_api_key: str,
+    token: str | None = None,
+    *,
+    timeout: float = 15.0,
+) -> 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")
+
+    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):
+        raise TypeError("token must be a string")
+
+    token_bytes = plaintext.encode("utf-8")
+    if not token_bytes:
+        raise ValueError("ENVIRONMENT_API_KEY token must not be empty")
+    if len(token_bytes) > MAX_ENVIRONMENT_API_KEY_BYTES:
+        raise ValueError("ENVIRONMENT_API_KEY token exceeds 8 KiB limit")
+
+    headers = {"Authorization": f"Bearer {synth_api_key}"}
+    pub_url = f"{backend}/api/v1/crypto/public-key"
+    response = requests.get(pub_url, headers=headers, timeout=timeout)
+    _raise_with_detail(response)
+
+    try:
+        doc = response.json()
+    except ValueError as exc:
+        raise RuntimeError("backend returned invalid JSON for public key") from exc
+
+    if not isinstance(doc, dict):
+        raise RuntimeError("backend public key response must be an object")
+
+    pubkey = doc.get("public_key")
+    if not isinstance(pubkey, str) or not pubkey:
+        raise RuntimeError("backend response missing public_key")
+
+    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"
+    # 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:
+        upload_doc = response2.json()
+    except ValueError:
+        upload_doc = {}
+
+    if not isinstance(upload_doc, dict):
+        upload_doc = {}
+
+    return {
+        "stored": True,
+        "id": upload_doc.get("id"),
+        "name": upload_doc.get("name"),
+        "updated_at": upload_doc.get("updated_at"),
+    }
+
+
+def _raise_with_detail(response: requests.Response) -> None:
+    try:
+        response.raise_for_status()
+    except requests.HTTPError as exc:
+        detail_snippet: str | None = None
+        try:
+            detail = response.json()
+            detail_snippet = json.dumps(detail, separators=(",", ":"))[:200]
+        except Exception:
+            body = response.text if response.text is not None else ""
+            detail_snippet = body[:200] if body else None
+        message = str(exc)
+        if detail_snippet:
+            message = f"{message} | body={detail_snippet}"
+        raise requests.HTTPError(message, request=exc.request, response=exc.response) from None

synth_ai/sdk/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)

synth_ai/sdk/learning/sft/client.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from synth_ai.core._utils.http import AsyncHttpClient, HTTPError
+
+from .config import prepare_sft_job_payload
+from .data import validate_jsonl_or_raise
+
+
+class FtClient:
+    def __init__(self, base_url: str, api_key: str, *, timeout: float = 30.0) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+
+    async def upload_training_file(self, path: str | Path, *, purpose: str = "fine-tune") -> str:
+        p = Path(path)
+        if p.suffix.lower() == ".jsonl" and purpose == "fine-tune":
+            validate_jsonl_or_raise(p, min_messages=2)
+        content = p.read_bytes()
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=self._timeout) as http:
+            data = {"purpose": purpose}
+            files = {"file": (p.name, content, _infer_content_type(p.name))}
+            js = await http.post_multipart("/api/learning/files", data=data, files=files)
+        if not isinstance(js, dict) or "id" not in js:
+            raise HTTPError(
+                status=500,
+                url="/api/learning/files",
+                message="invalid_upload_response",
+                body_snippet=str(js)[:200],
+            )
+        return str(js["id"])
+
+    async def create_sft_job(
+        self,
+        *,
+        model: str,
+        training_file_id: str,
+        hyperparameters: dict[str, Any],
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body = prepare_sft_job_payload(
+            model=model,
+            training_file=training_file_id,
+            hyperparameters=hyperparameters,
+            metadata=metadata,
+            training_type="sft_offline",
+            training_file_field="training_file_id",
+            require_training_file=True,
+        )
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=self._timeout) as http:
+            return await http.post_json("/api/learning/jobs", json=body)
+
+    async def start_job(self, job_id: str) -> dict[str, Any]:
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=self._timeout) as http:
+            return await http.post_json(f"/api/learning/jobs/{job_id}/start", json={})
+
+    async def get_job_status(self, job_id: str) -> dict[str, Any]:
+        """Get the status and details of an SFT job.
+        
+        Args:
+            job_id: The job ID to check
+            
+        Returns:
+            Job details including status, progress, etc.
+        """
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=self._timeout) as http:
+            return await http.get(f"/api/learning/jobs/{job_id}")
+
+    async def list_jobs(self, *, limit: int = 50, offset: int = 0) -> list[dict[str, Any]]:
+        """List SFT jobs.
+        
+        Args:
+            limit: Max number of jobs to return
+            offset: Pagination offset
+            
+        Returns:
+            List of job objects
+        """
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=self._timeout) as http:
+            result = await http.get(f"/api/learning/jobs?limit={limit}&offset={offset}")
+            return result if isinstance(result, list) else result.get("jobs", [])
+
+
+def _infer_content_type(filename: str) -> str:
+    name = filename.lower()
+    if name.endswith(".jsonl"):
+        return "application/jsonl"
+    if name.endswith(".json"):
+        return "application/json"
+    if name.endswith(".txt"):
+        return "text/plain"
+    return "application/octet-stream"