ariapin 1.7.0__tar.gz

ariapin-1.7.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: ariapin
+Version: 1.7.0
+Summary: Python client for the ariapin end-side post-training API (LoRA/QLoRA + RL with SFT/DPO/GRPO)
+Author: aria compute
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/ariacompute/harness
+Keywords: llm,post-training,lora,qlora,dora,grpo,dpo,sft,rl
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"

ariapin-1.7.0/ariapin/__init__.py

@@ -0,0 +1,29 @@
+"""ariapin — Python client for the end-side post-training API."""
+
+from .client import AriaPinClient, DEFAULT_BASE_URL
+from .exceptions import AriaPinConnectionError, AriaPinError
+from .models import (
+    Agent,
+    AutoIntervention,
+    AutoInterventionRule,
+    GPUNode,
+    Hyperparams,
+    Job,
+    LoraConfig,
+)
+
+__all__ = [
+    "AriaPinClient",
+    "DEFAULT_BASE_URL",
+    "AriaPinError",
+    "AriaPinConnectionError",
+    "Job",
+    "LoraConfig",
+    "Hyperparams",
+    "AutoIntervention",
+    "AutoInterventionRule",
+    "GPUNode",
+    "Agent",
+]
+
+__version__ = "1.7.0"

ariapin-1.7.0/ariapin/_http.py

@@ -0,0 +1,169 @@
+"""Internal HTTP transport for the ariapin client.
+
+Zero runtime dependencies: uses only the standard library. The envelope is
+the unified ``{"code": int, "data": ..., "message": str}`` shape returned by
+the backend. A non-zero ``code`` (or any non-2xx HTTP status) raises
+``AriaPinError``. Only 5xx / network errors are retried with exponential
+backoff; 4xx responses are surfaced immediately (retrying would waste quota).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+from .exceptions import AriaPinConnectionError, AriaPinError
+
+_DEFAULT_TIMEOUT = 30
+_MAX_RETRIES = 3
+_BACKOFF_BASE = 0.5
+
+
+class _HTTPClient:
+    def __init__(self, api_key: str, base_url: str, timeout: int = _DEFAULT_TIMEOUT):
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    def _url(self, path: str) -> str:
+        if not path.startswith("/"):
+            path = "/" + path
+        return self._base_url + path
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        query: dict[str, Any] | None = None,
+        files: dict[str, tuple[str, bytes, str]] | None = None,
+    ) -> Any:
+        url = self._url(path)
+        if query:
+            from urllib.parse import urlencode
+
+            url += "?" + urlencode({k: v for k, v in query.items() if v is not None})
+
+        last_err: Exception | None = None
+        for attempt in range(1, _MAX_RETRIES + 1):
+            try:
+                data, headers = self._prepare(json_body, files)
+                req = urllib.request.Request(url, data=data, method=method, headers=headers)
+                try:
+                    with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                        return self._parse(resp)
+                except urllib.error.HTTPError as e:
+                    # Server responded with an error status.
+                    body = self._read_bytes(e)
+                    err = self._into_error(e.code, body)
+                    if 400 <= e.code < 500:
+                        # Do not retry client errors, but allow 429 to retry.
+                        if e.code == 429:
+                            last_err = err
+                            time.sleep(_BACKOFF_BASE * attempt)
+                            continue
+                        raise err
+                    last_err = err  # 5xx -> retry
+                except urllib.error.URLError as e:
+                    raise AriaPinConnectionError(
+                        f"cannot reach {url}: {e.reason}"
+                    ) from e
+            except AriaPinConnectionError:
+                last_err = err if (err := last_err) else last_err  # keep last
+                last_err = _wrap_conn_err(url)
+                if attempt < _MAX_RETRIES:
+                    time.sleep(_BACKOFF_BASE * attempt)
+                    continue
+                raise last_err
+            # successful return or 5xx retry
+            if last_err is not None and isinstance(last_err, AriaPinError) and last_err.status >= 500:
+                if attempt < _MAX_RETRIES:
+                    time.sleep(_BACKOFF_BASE * attempt)
+                    continue
+                raise last_err
+        if last_err is not None:
+            raise last_err
+        raise AriaPinError("unknown error")
+
+    # ---- helpers -------------------------------------------------------
+    def _prepare(self, json_body, files):
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+            return json.dumps(json_body).encode("utf-8"), headers
+        if files is not None:
+            boundary = "----ariapin%s" % int(time.time() * 1000)
+            body = _encode_multipart(boundary, files)
+            headers["Content-Type"] = f"multipart/form-data; boundary={boundary}"
+            return body, headers
+        return None, headers
+
+    @staticmethod
+    def _read_bytes(e: urllib.error.HTTPError) -> bytes:
+        try:
+            return e.read()
+        except Exception:  # pragma: no cover - defensive
+            return b""
+
+    def _into_error(self, status: int, raw: bytes) -> AriaPinError:
+        msg = ""
+        code = 0
+        data = None
+        if raw:
+            try:
+                payload = json.loads(raw.decode("utf-8", "replace"))
+                code = int(payload.get("code", 0))
+                msg = str(payload.get("message", ""))
+                data = payload.get("data")
+            except Exception:
+                msg = raw.decode("utf-8", "replace")
+        if not msg:
+            msg = f"HTTP {status}"
+        return AriaPinError(msg, status=status, code=code, data=data)
+
+    @staticmethod
+    def _parse(resp) -> Any:
+        raw = resp.read()
+        if not raw:
+            return None
+        try:
+            payload = json.loads(raw.decode("utf-8", "replace"))
+        except Exception:
+            return raw  # unexpected binary (e.g. download stream) -> caller handles
+        if isinstance(payload, dict) and "code" in payload:
+            if payload.get("code") not in (0, None):
+                raise AriaPinError(
+                    str(payload.get("message", "")),
+                    status=200,
+                    code=int(payload.get("code", 0)),
+                    data=payload.get("data"),
+                )
+            return payload.get("data")
+        return payload
+
+
+def _wrap_conn_err(url: str) -> AriaPinConnectionError:
+    return AriaPinConnectionError(f"cannot reach {url}")
+
+
+def _encode_multipart(boundary: str, files: dict[str, tuple[str, bytes, str]]) -> bytes:
+    """Minimal multipart encoder for the dataset upload endpoint.
+
+    ``files`` maps field name -> (filename, content_bytes, content_type).
+    """
+    crlf = b"\r\n"
+    parts = []
+    for name, (filename, content, ctype) in files.items():
+        parts.append(f"--{boundary}".encode())
+        disp = f'Content-Disposition: form-data; name="{name}"; filename="{filename}"'
+        parts.append(disp.encode())
+        parts.append(f"Content-Type: {ctype}".encode())
+        parts.append(b"")
+        parts.append(content if isinstance(content, bytes) else content.encode("utf-8"))
+    parts.append(f"--{boundary}--".encode())
+    parts.append(b"")
+    return crlf.join(parts)

ariapin-1.7.0/ariapin/client.py

@@ -0,0 +1,282 @@
+"""ariapin Python client.
+
+Drop-in training experience inspired by river-client: submit a LoRA/QLoRA +
+RL job and poll it. Pure standard library, no third-party runtime deps.
+
+Example
+-------
+    from ariapin import AriaPinClient, LoraConfig, Hyperparams
+
+    client = AriaPinClient(api_key="sk-...", base_url="http://localhost:8001")
+    ds = client.create_dataset("my-sft", "sft", "data.jsonl")
+    job = client.train(
+        base_model="Qwen/Qwen2.5-0.5B-Instruct",
+        job_type="grpo",
+        lora=LoraConfig(method="lora", rank=16),
+        dataset_id=ds["dataset_id"],
+        hyperparams=Hyperparams(epochs=1, lr=4e-5, group_size=4, beta=0.04),
+    )
+    job.wait()                       # blocks until terminal
+    print(job.status, job.progress)  # -> "succeeded" {...}
+    model = client.models()[-1]
+    client.export_model(model["model_id"], "gguf")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._http import _HTTPClient
+from .exceptions import AriaPinError
+from .models import AutoIntervention, Hyperparams, Job, LoraConfig
+
+DEFAULT_BASE_URL = "http://localhost:8001"
+
+# 支持的训练方法（对齐 TRL：SFT/DPO/KTO/ORPO/SimPO + RL GRPO/PPO）。
+JOB_TYPES = ("sft", "dpo", "kto", "orpo", "simpo", "grpo", "ppo")
+
+
+class AriaPinClient:
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, timeout: int = 30):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._http = _HTTPClient(api_key, base_url, timeout=timeout)
+
+    # --- capabilities --------------------------------------------------
+    def capabilities(self) -> dict[str, Any]:
+        """``GET /v1/capabilities`` — model/method/LoRA/quota catalog."""
+        return self._http.request("GET", "/v1/capabilities") or {}
+
+    # --- datasets ------------------------------------------------------
+    def create_dataset(self, name: str, fmt: str, file_path: str) -> dict[str, Any]:
+        """``POST /v1/datasets`` multipart upload. Returns dataset metadata."""
+        with open(file_path, "rb") as f:
+            content = f.read()
+        files = {"name": (name, name.encode("utf-8"), "text/plain"),
+                 "format": (fmt, fmt.encode("utf-8"), "text/plain"),
+                 "file": (name, content, "application/octet-stream")}
+        return self._http.request("POST", "/v1/datasets", files=files) or {}
+
+    def list_datasets(self) -> list[dict[str, Any]]:
+        return self._http.request("GET", "/v1/datasets") or []
+
+    def get_dataset(self, dataset_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/datasets/{dataset_id}") or {}
+
+    # --- jobs ----------------------------------------------------------
+    def train(
+        self,
+        base_model: str,
+        job_type: str = "sft",
+        *,
+        lora: LoraConfig | dict[str, Any] | None = None,
+        dataset_id: str | None = None,
+        hyperparams: Hyperparams | dict[str, Any] | None = None,
+        auto_intervention: AutoIntervention | dict[str, Any] | None = None,
+    ) -> Job:
+        """``POST /v1/jobs`` — submit an async training job, return a :class:`Job`.
+
+        Args:
+            base_model: HuggingFace base model id (must be in allow-list).
+            job_type: sft/dpo/kto/orpo/simpo/grpo/ppo.
+            lora_config: LoRA/QLoRA/DoRA config (defaults to rank=16, alpha=32).
+            dataset_id: dataset id from ``create_dataset``.
+            hyperparams: training hyper-params.
+            auto_intervention: optional auto-intervention rules.
+        """
+        if job_type not in JOB_TYPES:
+            raise ValueError(f"job_type must be one of {JOB_TYPES}")
+        body: dict[str, Any] = {"job_type": job_type, "base_model": base_model}
+        if lora is not None:
+            body["lora_config"] = (
+                lora.to_dict() if isinstance(lora, LoraConfig) else lora
+            )
+        if dataset_id is not None:
+            body["dataset_id"] = dataset_id
+        if hyperparams is not None:
+            body["hyperparams"] = (
+                hyperparams.to_dict() if isinstance(hyperparams, Hyperparams) else hyperparams
+            )
+        if auto_intervention is not None:
+            body["auto_intervention"] = (
+                auto_intervention.to_dict()
+                if isinstance(auto_intervention, AutoIntervention)
+                else auto_intervention
+            )
+        data = self._http.request("POST", "/v1/jobs", json_body=body) or {}
+        return Job(self, data.get("job_id", ""), data)
+
+    def list_jobs(self) -> list[dict[str, Any]]:
+        return self._http.request("GET", "/v1/jobs") or []
+
+    def get_job(self, job_id: str) -> Job:
+        return Job(self, job_id, self.get_job_raw(job_id))
+
+    def get_job_raw(self, job_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/jobs/{job_id}") or {}
+
+    def cancel_job(self, job_id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/v1/jobs/{job_id}/cancel") or {}
+
+    # --- job lifecycle (start/pause/resume/stop/delete) -----------------
+    def start_job(self, job_id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/v1/jobs/{job_id}/start") or {}
+
+    def pause_job(self, job_id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/v1/jobs/{job_id}/pause") or {}
+
+    def resume_job(self, job_id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/v1/jobs/{job_id}/resume") or {}
+
+    def stop_job(self, job_id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/v1/jobs/{job_id}/stop") or {}
+
+    def delete_job(self, job_id: str) -> dict[str, Any]:
+        return self._http.request("DELETE", f"/v1/jobs/{job_id}") or {}
+
+    # --- GPU nodes ------------------------------------------------------
+    def list_nodes(self) -> list[dict[str, Any]]:
+        data = self._http.request("GET", "/v1/gpu-nodes") or {}
+        return data.get("items", []) if isinstance(data, dict) else data
+
+    def get_node(self, node_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/gpu-nodes/{node_id}") or {}
+
+    def create_node(self, *, name: str, ip: str, ssh_user: str, ssh_port: int = 22,
+                    ssh_key: str | None = None, ssh_password: str | None = None,
+                    spec: str = "", labels: list[str] | None = None) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "name": name, "ip": ip, "ssh_user": ssh_user, "ssh_port": ssh_port,
+            "spec": spec, "labels": labels or [],
+        }
+        if ssh_key is not None:
+            body["ssh_key"] = ssh_key
+        if ssh_password is not None:
+            body["ssh_password"] = ssh_password
+        return self._http.request("POST", "/v1/gpu-nodes", json_body=body) or {}
+
+    def update_node(self, node_id: str, **fields) -> dict[str, Any]:
+        """Partial update. Supported kwargs: name, ip, ssh_port, ssh_user,
+        ssh_key, ssh_password, spec, labels, status."""
+        body = {k: v for k, v in fields.items() if v is not None}
+        return self._http.request("PUT", f"/v1/gpu-nodes/{node_id}", json_body=body) or {}
+
+    def delete_node(self, node_id: str) -> dict[str, Any]:
+        return self._http.request("DELETE", f"/v1/gpu-nodes/{node_id}") or {}
+
+    # --- agents ---------------------------------------------------------
+    def list_node_agents(self, node_id: str) -> list[dict[str, Any]]:
+        data = self._http.request("GET", f"/v1/gpu-nodes/{node_id}/agents") or {}
+        return data.get("items", []) if isinstance(data, dict) else data
+
+    def deploy_agent(self, node_id: str, name: str | None = None) -> dict[str, Any]:
+        body = {"name": name} if name else {}
+        return self._http.request("POST", f"/v1/gpu-nodes/{node_id}/agents", json_body=body) or {}
+
+    def get_agent(self, agent_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/agents/{agent_id}") or {}
+
+    def update_agent(self, agent_id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/v1/agents/{agent_id}/update") or {}
+
+    def restart_agent(self, agent_id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/v1/agents/{agent_id}/restart") or {}
+
+    def delete_agent(self, agent_id: str) -> dict[str, Any]:
+        return self._http.request("DELETE", f"/v1/agents/{agent_id}") or {}
+
+    # --- interventions -------------------------------------------------
+    def intervene(
+        self,
+        job_id: str,
+        action: str,
+        reason: str = "",
+        hyperparams: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"action": action}
+        if reason:
+            body["reason"] = reason
+        if hyperparams is not None:
+            body["hyperparams"] = hyperparams
+        return self._http.request("POST", f"/v1/jobs/{job_id}/intervene", json_body=body) or {}
+
+    def set_auto_intervention(
+        self, job_id: str, ai: AutoIntervention | dict[str, Any]
+    ) -> dict[str, Any]:
+        body = ai.to_dict() if isinstance(ai, AutoIntervention) else ai
+        return self._http.request("PUT", f"/v1/jobs/{job_id}/auto-intervention", json_body=body) or {}
+
+    def job_interventions(self, job_id: str) -> list[dict[str, Any]]:
+        data = self._http.request("GET", f"/v1/jobs/{job_id}/interventions") or {}
+        if isinstance(data, dict):
+            return data.get("items", [])
+        return data
+
+    def job_analysis(self, job_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/jobs/{job_id}/analysis") or {}
+
+    # --- models --------------------------------------------------------
+    def models(self) -> list[dict[str, Any]]:
+        data = self._http.request("GET", "/v1/models") or {}
+        return data.get("items", []) if isinstance(data, dict) else data
+
+    def get_model(self, model_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/models/{model_id}") or {}
+
+    def merge_model(self, model_id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/v1/models/{model_id}/merge") or {}
+
+    def download(self, model_id: str, artifact: str, dest: str) -> str:
+        """``GET /v1/models/{id}/download?artifact=`` — stream a zip to ``dest``."""
+        url = f"/v1/models/{model_id}/download"
+        from urllib.parse import urlencode
+
+        full = url + "?" + urlencode({"artifact": artifact})
+        raw = self._http.request("GET", full)
+        if isinstance(raw, bytes):
+            with open(dest, "wb") as f:
+                f.write(raw)
+            return dest
+        # If the backend wrapped the response, the binary body is gone; raise.
+        raise AriaPinError("download did not return a binary stream", status=0)
+
+    def export_model(self, model_id: str, fmt: str) -> dict[str, Any]:
+        return self._http.request(
+            "POST", f"/v1/models/{model_id}/export", json_body={"format": fmt}
+        ) or {}
+
+    def exports(self) -> list[dict[str, Any]]:
+        return self._http.request("GET", "/v1/exports") or []
+
+    def get_export(self, export_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/exports/{export_id}") or {}
+
+    # --- evaluation (RL quality regression) ----------------------------
+    def evaluate_model(
+        self, model_id: str, dataset_id: str, baseline: str | None = None
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"dataset_id": dataset_id}
+        if baseline is not None:
+            body["baseline"] = baseline
+        return self._http.request("POST", f"/v1/models/{model_id}/evaluate", json_body=body) or {}
+
+    def model_evaluations(self, model_id: str) -> list[dict[str, Any]]:
+        data = self._http.request("GET", f"/v1/models/{model_id}/evaluations") or {}
+        return data.get("items", []) if isinstance(data, dict) else data
+
+    def get_evaluation(self, eval_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/evaluations/{eval_id}") or {}
+
+    # --- billing -------------------------------------------------------
+    def billing_summary(self) -> dict[str, Any]:
+        return self._http.request("GET", "/v1/billing/summary") or {}
+
+    def billing_usage(self, period: str = "30d", limit: int = 50) -> list[dict[str, Any]]:
+        data = self._http.request(
+            "GET", "/v1/billing/usage", query={"period": period, "limit": limit}
+        ) or {}
+        return data.get("items", []) if isinstance(data, dict) else data
+
+    # --- raw passthrough (for advanced endpoints) ----------------------
+    def raw_request(self, method: str, path: str, **kw) -> Any:
+        return self._http.request(method, path, **kw)

ariapin-1.7.0/ariapin/exceptions.py

@@ -0,0 +1,25 @@
+"""Exceptions for the ariapin Python client."""
+
+
+class AriaPinError(Exception):
+    """Raised for any non-2xx response from the ariapin API.
+
+    Carries the HTTP ``status`` code, the backend ``code`` (from the
+    unified ``{"code", "data", "message"}`` envelope) and ``message``.
+    """
+
+    def __init__(self, message: str, status: int = 0, code: int = 0, data=None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.data = data
+
+    def __str__(self) -> str:
+        if self.status or self.code:
+            return f"[status={self.status} code={self.code}] {self.message}"
+        return self.message
+
+
+class AriaPinConnectionError(AriaPinError):
+    """Raised when the API cannot be reached (DNS, TLS, network)."""

ariapin-1.7.0/ariapin/models.py

@@ -0,0 +1,334 @@
+"""Data transfer objects mirroring the ariapin REST contract.
+
+Field names match the backend JSON tags in ``requirements.md §4.2`` so the
+client can serialize requests without translation. The ``Job`` object is a
+lazy handle returned by ``AriaPinClient.train`` / ``get_job``; its methods
+delegate back to the client.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class LoraConfig:
+    """LoRA / QLoRA / DoRA configuration (requirements.md §4.2)."""
+
+    def __init__(
+        self,
+        method: str = "lora",
+        rank: int = 16,
+        alpha: int = 32,
+        lora_dropout: float = 0.05,
+        target_modules: list[str] | None = None,
+        quantization: str | None = None,
+    ):
+        self.method = method
+        self.rank = rank
+        self.alpha = alpha
+        self.lora_dropout = lora_dropout
+        self.target_modules = target_modules or ["q_proj", "v_proj"]
+        self.quantization = quantization
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "method": self.method,
+            "rank": self.rank,
+            "alpha": self.alpha,
+            "lora_dropout": self.lora_dropout,
+            "target_modules": self.target_modules,
+        }
+        if self.quantization is not None:
+            d["quantization"] = self.quantization
+        return d
+
+
+class Hyperparams:
+    """Training hyper-parameters (whitelist:
+    epochs/lr/max_length/group_size/beta/num_generations/kl_coef/reward_type)."""
+
+    def __init__(
+        self,
+        epochs: int = 1,
+        lr: float = 4e-5,
+        max_length: int = 1024,
+        group_size: int = 4,
+        beta: float = 0.04,
+        num_generations: int = 8,
+        kl_coef: float = 0.05,
+        reward_type: str = "length",
+    ):
+        self.epochs = epochs
+        self.lr = lr
+        self.max_length = max_length
+        self.group_size = group_size
+        self.beta = beta
+        self.num_generations = num_generations
+        self.kl_coef = kl_coef
+        self.reward_type = reward_type
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "epochs": self.epochs,
+            "lr": self.lr,
+            "max_length": self.max_length,
+            "group_size": self.group_size,
+            "beta": self.beta,
+            "num_generations": self.num_generations,
+            "kl_coef": self.kl_coef,
+            "reward_type": self.reward_type,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any] | None) -> "Hyperparams":
+        if not d:
+            return cls()
+        return cls(
+            epochs=d.get("epochs", 1),
+            lr=d.get("lr", 4e-5),
+            max_length=d.get("max_length", 1024),
+            group_size=d.get("group_size", 4),
+            beta=d.get("beta", 0.04),
+            num_generations=d.get("num_generations", 8),
+            kl_coef=d.get("kl_coef", 0.05),
+            reward_type=d.get("reward_type", "length"),
+        )
+
+
+class AutoInterventionRule:
+    """A single reward-hacking detection rule (requirements.md §4.2)."""
+
+    def __init__(
+        self,
+        id: str,
+        metric: str,
+        condition: str,
+        threshold: float,
+        action: str,
+        window_steps: int = 50,
+        min_consecutive: int = 5,
+        hyperparams: dict[str, Any] | None = None,
+    ):
+        self.id = id
+        self.metric = metric
+        self.condition = condition
+        self.threshold = threshold
+        self.action = action
+        self.window_steps = window_steps
+        self.min_consecutive = min_consecutive
+        self.hyperparams = hyperparams
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "id": self.id,
+            "metric": self.metric,
+            "condition": self.condition,
+            "threshold": self.threshold,
+            "action": self.action,
+            "window_steps": self.window_steps,
+            "min_consecutive": self.min_consecutive,
+        }
+        if self.hyperparams is not None:
+            d["hyperparams"] = self.hyperparams
+        return d
+
+
+class AutoIntervention:
+    """Auto-intervention policy attached to a job."""
+
+    def __init__(
+        self,
+        enabled: bool,
+        rules: list[AutoInterventionRule] | None = None,
+        cooldown_seconds: int = 600,
+    ):
+        self.enabled = enabled
+        self.rules = rules or []
+        self.cooldown_seconds = cooldown_seconds
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "enabled": self.enabled,
+            "rules": [r.to_dict() for r in self.rules],
+            "cooldown_seconds": self.cooldown_seconds,
+        }
+
+
+class GPUNode:
+    """A managed GPU node (SSH-deployable host for agents)."""
+
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        ip: str,
+        ssh_user: str,
+        ssh_port: int = 22,
+        spec: str = "",
+        labels: list[str] | None = None,
+        status: str = "active",
+        agent_count: int = 0,
+    ):
+        self.id = id
+        self.name = name
+        self.ip = ip
+        self.ssh_user = ssh_user
+        self.ssh_port = ssh_port
+        self.spec = spec
+        self.labels = labels or []
+        self.status = status
+        self.agent_count = agent_count
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "GPUNode":
+        return cls(
+            id=d.get("id", ""),
+            name=d.get("name", ""),
+            ip=d.get("ip", ""),
+            ssh_user=d.get("ssh_user", ""),
+            ssh_port=d.get("ssh_port", 22),
+            spec=d.get("spec", ""),
+            labels=d.get("labels") or [],
+            status=d.get("status", "active"),
+            agent_count=d.get("agent_count", 0),
+        )
+
+
+class Agent:
+    """A deployed agent on a GPU node."""
+
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        node_id: str = "",
+        version: str = "",
+        deploy_state: str = "",
+        last_error: str = "",
+        status: str = "",
+        gpu_count: int = 0,
+    ):
+        self.id = id
+        self.name = name
+        self.node_id = node_id
+        self.version = version
+        self.deploy_state = deploy_state
+        self.last_error = last_error
+        self.status = status
+        self.gpu_count = gpu_count
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Agent":
+        return cls(
+            id=d.get("id", ""),
+            name=d.get("name", ""),
+            node_id=d.get("node_id", ""),
+            version=d.get("version", ""),
+            deploy_state=d.get("deploy_state", ""),
+            last_error=d.get("last_error", ""),
+            status=d.get("status", ""),
+            gpu_count=d.get("gpu_count", 0),
+        )
+
+
+_TERMINAL = {"succeeded", "failed", "cancelled", "stopped"}
+
+
+class Job:
+    """Lazy handle for a training job returned by ``train`` / ``get_job``.
+
+    Methods delegate back to the owning :class:`AriaPinClient`.
+    """
+
+    def __init__(self, client: "AriaPinClient", job_id: str, raw: dict[str, Any] | None = None):
+        self._client = client
+        self.job_id = job_id
+        self._raw = raw or {}
+
+    # --- introspection -------------------------------------------------
+    def refresh(self) -> "Job":
+        self._raw = self._client.get_job_raw(self.job_id)
+        return self
+
+    @property
+    def status(self) -> str:
+        if not self._raw:
+            self.refresh()
+        return str(self._raw.get("status", ""))
+
+    @property
+    def progress(self) -> dict[str, Any]:
+        if not self._raw:
+            self.refresh()
+        return self._raw.get("progress") or {}
+
+    @property
+    def mlflow_url(self) -> str:
+        if not self._raw:
+            self.refresh()
+        return str(self._raw.get("mlflow_url", "") or "")
+
+    @property
+    def raw(self) -> dict[str, Any]:
+        if not self._raw:
+            self.refresh()
+        return self._raw
+
+    def is_terminal(self) -> bool:
+        return self.status in _TERMINAL
+
+    # --- blocking wait --------------------------------------------------
+    def wait(self, interval: int = 10, timeout: int | None = None) -> "Job":
+        """Poll until the job reaches a terminal state.
+
+        ``interval`` is the sleep seconds between polls; ``timeout`` is the
+        maximum wall-clock seconds (``None`` = wait indefinitely).
+        """
+        import time
+
+        waited = 0
+        self.refresh()
+        while not self.is_terminal():
+            time.sleep(interval)
+            waited += interval
+            if timeout is not None and waited >= timeout:
+                raise TimeoutError(
+                    f"job {self.job_id} did not finish within {timeout}s (status={self.status})"
+                )
+            self.refresh()
+        return self
+
+    # --- actions -------------------------------------------------------
+    def cancel(self) -> dict[str, Any]:
+        return self._client.cancel_job(self.job_id)
+
+    def intervene(self, action: str, reason: str = "", hyperparams: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._client.intervene(self.job_id, action, reason, hyperparams)
+
+    def set_auto_intervention(
+        self, enabled: bool, rules: list[AutoInterventionRule] | None = None, cooldown_seconds: int = 600
+    ) -> dict[str, Any]:
+        ai = AutoIntervention(enabled=enabled, rules=rules or [], cooldown_seconds=cooldown_seconds)
+        return self._client.set_auto_intervention(self.job_id, ai)
+
+    def interventions(self) -> list[dict[str, Any]]:
+        return self._client.job_interventions(self.job_id)
+
+    def analysis(self) -> dict[str, Any]:
+        return self._client.job_analysis(self.job_id)
+
+    # --- lifecycle (start/pause/resume/stop/delete) ---------------------
+    def start(self) -> dict[str, Any]:
+        return self._client.start_job(self.job_id)
+
+    def pause(self) -> dict[str, Any]:
+        return self._client.pause_job(self.job_id)
+
+    def resume(self) -> dict[str, Any]:
+        return self._client.resume_job(self.job_id)
+
+    def stop(self) -> dict[str, Any]:
+        return self._client.stop_job(self.job_id)
+
+    def delete(self) -> dict[str, Any]:
+        return self._client.delete_job(self.job_id)

ariapin-1.7.0/ariapin.egg-info/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: ariapin
+Version: 1.7.0
+Summary: Python client for the ariapin end-side post-training API (LoRA/QLoRA + RL with SFT/DPO/GRPO)
+Author: aria compute
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/ariacompute/harness
+Keywords: llm,post-training,lora,qlora,dora,grpo,dpo,sft,rl
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"

ariapin-1.7.0/ariapin.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+pyproject.toml
+ariapin/__init__.py
+ariapin/_http.py
+ariapin/client.py
+ariapin/exceptions.py
+ariapin/models.py
+ariapin.egg-info/PKG-INFO
+ariapin.egg-info/SOURCES.txt
+ariapin.egg-info/dependency_links.txt
+ariapin.egg-info/requires.txt
+ariapin.egg-info/top_level.txt
+tests/test_client.py

ariapin-1.7.0/ariapin.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ariapin-1.7.0/ariapin.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=7

ariapin-1.7.0/ariapin.egg-info/top_level.txt

@@ -0,0 +1 @@
+ariapin

ariapin-1.7.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ariapin"
+version = "1.7.0"
+description = "Python client for the ariapin end-side post-training API (LoRA/QLoRA + RL with SFT/DPO/GRPO)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "aria compute" }]
+keywords = ["llm", "post-training", "lora", "qlora", "dora", "grpo", "dpo", "sft", "rl"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "License :: OSI Approved :: Apache Software License",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/ariacompute/harness"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["ariapin*"]

ariapin-1.7.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ariapin-1.7.0/tests/test_client.py

@@ -0,0 +1,252 @@
+"""Unit tests for the ariapin Python client.
+
+Uses only stdlib (unittest) and a tiny mock transport so it runs without the
+network, GPU, or the ariapin backend. Verifies request construction, response
+parsing, error mapping, and terminal-state polling.
+"""
+
+import io
+import json
+import time
+import unittest
+from urllib.error import HTTPError
+from urllib.request import Request
+
+from ariapin import (
+    AriaPinClient,
+    AriaPinError,
+    AutoIntervention,
+    AutoInterventionRule,
+    Hyperparams,
+    Job,
+    LoraConfig,
+)
+
+
+class _FakeHTTP:
+    """Replaces _HTTPClient.request with scripted responses.
+
+    Mirrors the real transport's envelope unwrapping: a returned dict with a
+    ``code`` key is unwrapped to its ``data`` field, and a non-zero ``code``
+    raises AriaPinError.
+    """
+
+    def __init__(self):
+        self.calls = []
+        self.handler = None  # callable(method, path, kwargs) -> payload
+
+    @staticmethod
+    def _unwrap(payload):
+        if isinstance(payload, dict) and "code" in payload:
+            if payload.get("code") not in (0, None):
+                raise AriaPinError(
+                    str(payload.get("message", "")), status=200, code=int(payload.get("code", 0))
+                )
+            return payload.get("data")
+        return payload
+
+    def request(self, method, path, **kwargs):
+        self.calls.append((method, path, kwargs))
+        if self.handler is None:
+            return None
+        try:
+            payload = self.handler(method, path, kwargs)
+        except HTTPError as e:
+            # Mimic _HTTPClient: convert HTTPError -> AriaPinError (4xx immediate,
+            # 5xx would retry in real transport; here we surface directly).
+            raw = e.read() if e.fp else b""
+            msg = ""
+            code = 0
+            if raw:
+                try:
+                    p = json.loads(raw.decode("utf-8", "replace"))
+                    msg = str(p.get("message", ""))
+                    code = int(p.get("code", 0))
+                except Exception:
+                    msg = raw.decode("utf-8", "replace")
+            raise AriaPinError(msg or f"HTTP {e.code}", status=e.code, code=code)
+        return self._unwrap(payload)
+
+
+def _envelope(data, code=0, message=""):
+    return {"code": code, "data": data, "message": message}
+
+
+def _make_client():
+    c = AriaPinClient(api_key="sk-test", base_url="http://test")
+    c._http = _FakeHTTP()
+    return c, c._http
+
+
+class TestTrainRequest(unittest.TestCase):
+    def test_train_builds_correct_body_and_returns_job(self):
+        client, http = _make_client()
+
+        def handler(method, path, kwargs):
+            self.assertEqual(method, "POST")
+            self.assertEqual(path, "/v1/jobs")
+            body = kwargs["json_body"]
+            self.assertEqual(body["job_type"], "grpo")
+            self.assertEqual(body["base_model"], "Qwen/Qwen2.5-0.5B-Instruct")
+            self.assertEqual(body["dataset_id"], "ds_x")
+            self.assertEqual(body["lora_config"]["method"], "lora")
+            self.assertEqual(body["lora_config"]["rank"], 16)
+            self.assertEqual(body["hyperparams"]["group_size"], 4)
+            self.assertEqual(body["hyperparams"]["beta"], 0.04)
+            self.assertTrue(body["auto_intervention"]["enabled"])
+            self.assertEqual(len(body["auto_intervention"]["rules"]), 1)
+            return _envelope({"job_id": "jb_1", "status": "queued"})
+
+        http.handler = handler
+        job = client.train(
+            base_model="Qwen/Qwen2.5-0.5B-Instruct",
+            job_type="grpo",
+            lora=LoraConfig(method="lora", rank=16),
+            dataset_id="ds_x",
+            hyperparams=Hyperparams(epochs=1, lr=4e-5, group_size=4, beta=0.04),
+            auto_intervention=AutoIntervention(
+                enabled=True,
+                rules=[
+                    AutoInterventionRule(
+                        id="reward_spike", metric="reward", condition="spike",
+                        threshold=2.0, action="update_hyperparams",
+                        hyperparams={"lr": 2e-5, "beta": 0.08},
+                    )
+                ],
+            ),
+        )
+        self.assertIsInstance(job, Job)
+        self.assertEqual(job.job_id, "jb_1")
+        self.assertEqual(job.status, "queued")
+
+
+class TestErrorMapping(unittest.TestCase):
+    def _raise(self, status, payload):
+        raise HTTPError(
+            url="http://test/v1/jobs",
+            code=status,
+            msg="err",
+            hdrs=None,
+            fp=io.BytesIO(json.dumps(payload).encode()),
+        )
+
+    def test_402_insufficient_balance(self):
+        client, http = _make_client()
+        http.handler = lambda m, p, k: self._raise(
+            402, _envelope(None, code=402, message="insufficient balance")
+        )
+        with self.assertRaises(AriaPinError) as ctx:
+            client.train("m", "sft", dataset_id="d")
+        self.assertEqual(ctx.exception.status, 402)
+
+    def test_422_invalid_lora(self):
+        client, http = _make_client()
+        http.handler = lambda m, p, k: self._raise(
+            422, _envelope(None, code=422, message="rank out of range [1,64]")
+        )
+        with self.assertRaises(AriaPinError) as ctx:
+            client.train("m", "sft", dataset_id="d", lora=LoraConfig(rank=0))
+        self.assertEqual(ctx.exception.status, 422)
+
+    def test_envelope_nonzero_code_raises(self):
+        client, http = _make_client()
+        http.handler = lambda m, p, k: _envelope(None, code=409, message="conflict")
+        with self.assertRaises(AriaPinError) as ctx:
+            client.cancel_job("jb_1")
+        self.assertEqual(ctx.exception.code, 409)
+
+
+class TestJobWait(unittest.TestCase):
+    def test_wait_polls_until_terminal(self):
+        client, http = _make_client()
+        states = iter(["running", "running", "running", "running", "succeeded"])
+
+        def handler(method, path, kwargs):
+            # GET /v1/jobs/{id} returns the next simulated state
+            return _envelope({"job_id": "jb_1", "status": next(states),
+                              "progress": {"step": 10, "loss": 0.3}})
+
+        http.handler = handler
+        # speed up: monkeypatch sleep to no-op
+        real_sleep = time.sleep
+        time.sleep = lambda *_: None
+        try:
+            job = client.get_job("jb_1")
+            final = job.wait()
+        finally:
+            time.sleep = real_sleep
+        self.assertEqual(final.status, "succeeded")
+        self.assertEqual(final.progress["step"], 10)
+        # GET calls: get_job_raw(1) + wait refresh(2) + 3 loop refreshes(3,4,5)
+        self.assertEqual(len(http.calls), 5)
+
+
+class TestInterventionsAndAnalysis(unittest.TestCase):
+    def test_intervene_constructs_body(self):
+        client, http = _make_client()
+        captured = {}
+
+        def handler(method, path, kwargs):
+            captured["method"] = method
+            captured["path"] = path
+            captured["body"] = kwargs.get("json_body")
+            return _envelope({"job_id": "jb_1", "action": "stop", "status": "stopping"})
+
+        http.handler = handler
+        res = client.intervene("jb_1", "stop", reason="reward spike")
+        self.assertEqual(captured["method"], "POST")
+        self.assertEqual(captured["path"], "/v1/jobs/jb_1/intervene")
+        self.assertEqual(captured["body"]["action"], "stop")
+        self.assertEqual(captured["body"]["reason"], "reward spike")
+        self.assertEqual(res["status"], "stopping")
+
+    def test_set_auto_intervention_put(self):
+        client, http = _make_client()
+        captured = {}
+
+        def handler(method, path, kwargs):
+            captured["method"] = method
+            captured["body"] = kwargs.get("json_body")
+            return _envelope({"job_id": "jb_1", "auto_intervention": kwargs.get("json_body")})
+
+        http.handler = handler
+        client.set_auto_intervention(
+            "jb_1", AutoIntervention(enabled=False, cooldown_seconds=300)
+        )
+        self.assertEqual(captured["method"], "PUT")
+        self.assertEqual(captured["body"]["enabled"], False)
+        self.assertEqual(captured["body"]["cooldown_seconds"], 300)
+
+    def test_analysis_and_interventions(self):
+        client, http = _make_client()
+
+        def handler(method, path, kwargs):
+            if path.endswith("/analysis"):
+                return _envelope({"risk": "ok", "reward": {"mean": 0.5}})
+            if path.endswith("/interventions"):
+                return _envelope({"items": [{"action": "stop", "trigger": "auto"}]})
+            return None
+
+        http.handler = handler
+        self.assertEqual(client.job_analysis("jb_1")["risk"], "ok")
+        self.assertEqual(len(client.job_interventions("jb_1")), 1)
+
+
+class TestExportsAndBilling(unittest.TestCase):
+    def test_export_and_billing(self):
+        client, http = _make_client()
+
+        def handler(method, path, kwargs):
+            if path.endswith("/export"):
+                return _envelope({"export_id": "ex_1", "status": "queued"})
+            if path == "/v1/billing/summary":
+                return _envelope({"balance": 9.9, "currency": "USD"})
+            return None
+
+        http.handler = handler
+        self.assertEqual(client.export_model("md_1", "gguf")["export_id"], "ex_1")
+        self.assertEqual(client.billing_summary()["balance"], 9.9)
+
+
+if __name__ == "__main__":
+    unittest.main()