synth-ai 0.2.9.dev11__py3-none-any.whl → 0.4.1__py3-none-any.whl

synth_ai/sdk/learning/client.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextlib import suppress
+from pathlib import Path
+from typing import Any, TypedDict
+
+from synth_ai.core._utils.http import AsyncHttpClient, HTTPError, sleep
+from synth_ai.sdk.api.models.supported import (
+    UnsupportedModelError,
+    normalize_model_identifier,
+)
+from synth_ai.sdk.learning.sft.config import prepare_sft_job_payload
+
+
+class LearningClient:
+    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)
+        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_job(
+        self,
+        *,
+        training_type: str,
+        model: str,
+        training_file_id: str,
+        hyperparameters: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+        validation_file: str | None = None,
+    ) -> dict[str, Any]:
+        lower_type = (training_type or "").strip().lower()
+        require_base = (
+            lower_type.startswith("sft")
+            or lower_type.startswith("fft")
+            or lower_type.startswith("qft")
+        )
+        try:
+            normalized_model = normalize_model_identifier(
+                model, allow_finetuned_prefixes=not require_base
+            )
+        except UnsupportedModelError as exc:
+            raise ValueError(str(exc)) from exc
+
+        if lower_type.startswith("sft") or lower_type in {"fft", "qft"}:
+            body = prepare_sft_job_payload(
+                model=model,
+                training_file=training_file_id,
+                hyperparameters=hyperparameters,
+                metadata=metadata,
+                training_type=training_type or "sft_offline",
+                validation_file=validation_file,
+                training_file_field="training_file_id",
+                require_training_file=True,
+            )
+        else:
+            body = {
+                "training_type": training_type,
+                "model": normalized_model,
+                "training_file_id": training_file_id,
+                "hyperparameters": hyperparameters or {},
+                "metadata": metadata or {},
+            }
+        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(self, job_id: str) -> dict[str, Any]:
+        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 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=self._timeout) as http:
+            js = await http.get(f"/api/learning/jobs/{job_id}/events", params=params)
+        if isinstance(js, dict) and isinstance(js.get("events"), list):
+            return js["events"]
+        return []
+
+    async def get_metrics(
+        self,
+        job_id: str,
+        *,
+        name: str | None = None,
+        after_step: int | None = None,
+        limit: int = 500,
+        run_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {"limit": limit}
+        if name is not None:
+            params["name"] = name
+        if after_step is not None:
+            params["after_step"] = after_step
+        if run_id is not None:
+            params["run_id"] = run_id
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=self._timeout) as http:
+            js = await http.get(f"/api/learning/jobs/{job_id}/metrics", params=params)
+        if isinstance(js, dict) and isinstance(js.get("points"), list):
+            return js["points"]
+        return []
+
+    async def get_timeline(self, job_id: str, *, limit: int = 200) -> list[dict[str, Any]]:
+        params = {"limit": limit}
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=self._timeout) as http:
+            js = await http.get(f"/api/learning/jobs/{job_id}/timeline", params=params)
+        if isinstance(js, dict) and isinstance(js.get("events"), list):
+            return js["events"]
+        return []
+
+    async def poll_until_terminal(
+        self,
+        job_id: str,
+        *,
+        interval_seconds: float = 2.0,
+        max_seconds: float | None = 3600,
+        on_event: Callable[[dict[str, Any]], None] | None = None,
+    ) -> dict[str, Any]:
+        last_seq = 0
+        elapsed = 0.0
+        while True:
+            # Events
+            events = await self.get_events(job_id, since_seq=last_seq, limit=200)
+            for e in events:
+                if isinstance(e, dict) and isinstance(e.get("seq"), int):
+                    last_seq = max(last_seq, int(e["seq"]))
+                if on_event:
+                    with suppress(Exception):
+                        on_event(e)
+
+            # Status
+            job = await self.get_job(job_id)
+            status = str(job.get("status") or "").lower()
+            if status in {"succeeded", "failed", "canceled", "cancelled"}:
+                return job
+
+            # Sleep and time budget
+            await sleep(interval_seconds)
+            elapsed += interval_seconds
+            if max_seconds is not None and elapsed >= max_seconds:
+                raise TimeoutError(f"Polling timed out after {elapsed} seconds for job {job_id}")
+
+    # --- Optional diagnostics ---
+    async def pricing_preflight(
+        self, *, job_type: str, gpu_type: str, estimated_seconds: float, container_count: int
+    ) -> dict[str, Any]:
+        body = {
+            "job_type": job_type,
+            "gpu_type": gpu_type,
+            "estimated_seconds": float(estimated_seconds or 0.0),
+            "container_count": int(container_count or 1),
+        }
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=self._timeout) as http:
+            js = await http.post_json("/api/v1/pricing/preflight", json=body)
+        if not isinstance(js, dict):
+            raise HTTPError(
+                status=500,
+                url="/api/v1/pricing/preflight",
+                message="invalid_preflight_response",
+                body_snippet=str(js)[:200],
+            )
+        return js
+
+    async def balance_autumn_normalized(self) -> dict[str, Any]:
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=self._timeout) as http:
+            js = await http.get("/api/v1/balance/autumn-normalized")
+        if not isinstance(js, dict):
+            raise HTTPError(
+                status=500,
+                url="/api/v1/balance/autumn-normalized",
+                message="invalid_balance_response",
+                body_snippet=str(js)[:200],
+            )
+        return js
+
+
+class FineTunedModelInfo(TypedDict, total=False):
+    id: str
+    base_model: str | None
+    created_at: int | None
+    job_id: str | None
+    status: str | None
+
+
+class LearningClient(LearningClient):  # type: ignore[misc]
+    async def list_fine_tuned_models(self) -> list[FineTunedModelInfo]:
+        """Return completed fine‑tuned models for the caller's organization.
+
+        Calls backend route `/api/learning/models` and returns a compact list.
+        """
+        async with AsyncHttpClient(self._base_url, self._api_key, timeout=self._timeout) as http:
+            js = await http.get("/api/learning/models")
+        if isinstance(js, dict) and isinstance(js.get("data"), list):
+            out: list[FineTunedModelInfo] = []
+            for item in js["data"]:
+                if not isinstance(item, dict):
+                    continue
+                rec: FineTunedModelInfo = {
+                    "id": str(item.get("id")),
+                    "base_model": item.get("base_model"),
+                    "created_at": item.get("created_at"),
+                    "job_id": item.get("job_id"),
+                    "status": item.get("status"),
+                }
+                if rec.get("id"):
+                    out.append(rec)
+            return out
+        # Fallback: empty list on unexpected shape
+        return []
+
+
+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"

synth_ai/sdk/learning/ft_client.py

@@ -0,0 +1,7 @@
+"""Backward-compatible shim for FtClient (moved to synth_ai.sdk.learning.sft.client)."""
+
+from __future__ import annotations
+
+from .sft.client import FtClient
+
+__all__ = ["FtClient"]

synth_ai/sdk/learning/health.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any
+
+from synth_ai.core._utils.http import AsyncHttpClient
+
+
+def _api_base(b: str) -> str:
+    b = (b or "").rstrip("/")
+    return b if b.endswith("/api") else f"{b}/api"
+
+
+async def backend_health(base_url: str, api_key: str) -> dict[str, Any]:
+    async with AsyncHttpClient(base_url, api_key, timeout=15.0) as http:
+        js = await http.get(f"{_api_base(base_url)}/health")
+    return {"ok": True, "raw": js}
+
+
+async def task_app_health(task_app_url: str) -> dict[str, Any]:
+    # Delegate to central task module for consistency
+    from synth_ai.sdk.task.health import task_app_health as _th
+
+    return await _th(task_app_url)
+
+
+async def pricing_preflight(
+    base_url: str,
+    api_key: str,
+    *,
+    job_type: str,
+    gpu_type: str,
+    estimated_seconds: float,
+    container_count: int,
+) -> dict[str, Any]:
+    body = {
+        "job_type": job_type,
+        "gpu_type": gpu_type,
+        "estimated_seconds": float(estimated_seconds or 0.0),
+        "container_count": int(container_count or 1),
+    }
+    async with AsyncHttpClient(base_url, api_key, timeout=30.0) as http:
+        js = await http.post_json(f"{_api_base(base_url)}/v1/pricing/preflight", json=body)
+    return js if isinstance(js, dict) else {"raw": js}
+
+
+async def balance_autumn_normalized(base_url: str, api_key: str) -> dict[str, Any]:
+    async with AsyncHttpClient(base_url, api_key, timeout=30.0) as http:
+        js = await http.get(f"{_api_base(base_url)}/v1/balance/autumn-normalized")
+    return js if isinstance(js, dict) else {"raw": js}

synth_ai/sdk/learning/jobs.py

@@ -0,0 +1,202 @@
+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, sleep
+
+from .constants import TERMINAL_EVENT_FAILURE, TERMINAL_EVENT_SUCCESS, TERMINAL_STATUSES
+
+
+def _api_base(b: str) -> str:
+    b = (b or "").rstrip("/")
+    return b if b.endswith("/api") else f"{b}/api"
+
+
+class JobsApiResolver:
+    def __init__(self, base_url: str, *, strict: bool) -> None:
+        self._base = _api_base(base_url)
+        self._strict = strict
+
+    def status_urls(self, job_id: str) -> list[str]:
+        if self._strict:
+            return [f"{self._base}/learning/jobs/{job_id}"]
+        return [
+            f"{self._base}/learning/jobs/{job_id}",
+            f"{self._base}/rl/jobs/{job_id}",
+            f"{self._base}/orchestration/jobs/{job_id}",
+        ]
+
+    def events_urls(self, job_id: str, since: int) -> list[str]:
+        if self._strict:
+            return [f"{self._base}/learning/jobs/{job_id}/events?since_seq={since}&limit=200"]
+        return [
+            f"{self._base}/learning/jobs/{job_id}/events?since_seq={since}&limit=200",
+            f"{self._base}/orchestration/jobs/{job_id}/events?since_seq={since}&limit=200",
+            # RL /jobs/{id}/events is SSE in backend; avoid in JSON poller
+        ]
+
+    def metrics_url(self, job_id: str, after_step: int) -> str:
+        return f"{self._base}/learning/jobs/{job_id}/metrics?after_step={after_step}&limit=200"
+
+
+class JobHandle:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        job_id: str,
+        *,
+        strict: bool = True,
+        timeout: float = 600.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.job_id = job_id
+        self.strict = strict
+        self.timeout = timeout
+
+    async def poll_until_terminal(
+        self,
+        *,
+        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()
+        resolver = JobsApiResolver(self.base_url, strict=self.strict)
+        detected_fine_tuned_model: str | None = None
+
+        async with AsyncHttpClient(self.base_url, self.api_key, timeout=self.timeout) as http:
+            while True:
+                # Status
+                status_data: dict[str, Any] | None = None
+                for su in resolver.status_urls(self.job_id):
+                    try:
+                        status_data = await http.get(su)
+                        if isinstance(status_data, dict):
+                            break
+                    except Exception:
+                        continue
+                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
+                    # Capture fine_tuned_model if already present on status
+                    if not detected_fine_tuned_model:
+                        ftm = status_data.get("fine_tuned_model")
+                        if isinstance(ftm, str) and ftm:
+                            detected_fine_tuned_model = ftm
+                if status and status != last_status:
+                    last_status = status
+                    if on_event:
+                        with suppress(Exception):
+                            on_event({"type": "job.status", "message": status})
+
+                # Events
+                stream_ids = [self.job_id]
+                if events_job_id and events_job_id not in stream_ids:
+                    stream_ids.append(events_job_id)
+                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)
+                    for eu in resolver.events_urls(ev_id, since):
+                        try:
+                            ev_js = await http.get(eu)
+                        except Exception:
+                            continue
+                        events = (ev_js or {}).get("events") or (ev_js or {}).get("data") or []
+                        if not isinstance(events, list):
+                            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()
+                            # Capture fine_tuned_model from event data when available
+                            if not detected_fine_tuned_model:
+                                data_obj = e.get("data") or {}
+                                if isinstance(data_obj, dict):
+                                    ftm = data_obj.get("fine_tuned_model")
+                                    if isinstance(ftm, str) and ftm:
+                                        detected_fine_tuned_model = ftm
+                            if et in TERMINAL_EVENT_SUCCESS:
+                                terminal_event_seen = True
+                                terminal_event_status = "succeeded"
+                            elif et in TERMINAL_EVENT_FAILURE:
+                                terminal_event_seen = True
+                                terminal_event_status = "failed"
+
+                # Metrics
+                try:
+                    after = max(last_step_by_name.values()) if last_step_by_name else -1
+                    mu = resolver.metrics_url(self.job_id, after)
+                    md = await http.get(mu)
+                    for p in (md or {}).get("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
+
+                # Terminal decisions
+                if terminal_event_seen or (status and status in TERMINAL_STATUSES):
+                    # Best-effort enrichment of final result with fine_tuned_model
+                    result_status = terminal_event_status or status or "completed"
+                    final_res: dict[str, Any] = {"status": result_status, "job_id": self.job_id}
+                    if not detected_fine_tuned_model:
+                        # Briefly try to re-fetch status to see if fine_tuned_model is persisted
+                        try:
+                            for su in resolver.status_urls(self.job_id):
+                                final_status = await http.get(su)
+                                if isinstance(final_status, dict):
+                                    ftm2 = final_status.get("fine_tuned_model")
+                                    if isinstance(ftm2, str) and ftm2:
+                                        detected_fine_tuned_model = ftm2
+                                        break
+                        except Exception:
+                            pass
+                    if detected_fine_tuned_model:
+                        final_res["fine_tuned_model"] = detected_fine_tuned_model
+                    return final_res
+
+                # Guards (relaxed): do not abort on consecutive empty polls
+                if total_events_this_cycle == 0:
+                    empty_polls += 1
+                else:
+                    empty_polls = 0
+                if not saw_any_event and (time.time() - start_t) > int(startup_deadline_s):
+                    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 {self.job_id}"
+                    )