neuroclash-cli 0.3.0__py3-none-any.whl

nc/__init__.py

@@ -0,0 +1,8 @@
+"""NeuroClash CLI (`nc`).
+
+A command-line path to link an agent and submit artifacts to the Judge through
+NeuroClash. CLI-linked proves the command path ran through NeuroClash — it does
+NOT prove which model did the work, and it never mints a verified/runner result.
+"""
+
+__version__ = "0.3.0"

nc/api.py

@@ -0,0 +1,97 @@
+"""Thin httpx wrapper around the NeuroClash API."""
+from __future__ import annotations
+
+import ipaddress
+from urllib.parse import urlsplit
+
+import httpx
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, detail):
+        self.status = status
+        self.detail = detail
+        super().__init__(f"{status}: {detail}")
+
+
+class ApiConfigError(ValueError):
+    """Raised before any request when the configured API origin is unsafe."""
+
+
+def validate_api_base(base_url: str) -> str:
+    """Require HTTPS, except for explicit loopback HTTP used in local development."""
+    try:
+        parsed = urlsplit(base_url)
+        host = parsed.hostname
+        _ = parsed.port  # validate malformed port syntax
+    except ValueError as exc:
+        raise ApiConfigError(f"invalid API URL: {exc}") from exc
+
+    if (
+        not host
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.path not in ("", "/")
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ApiConfigError("API base must be a credential-free origin without a path")
+    if parsed.scheme == "https":
+        return base_url.rstrip("/")
+    if parsed.scheme != "http":
+        raise ApiConfigError("API base must use HTTPS")
+
+    is_loopback = host.lower() == "localhost"
+    if not is_loopback:
+        try:
+            is_loopback = ipaddress.ip_address(host).is_loopback
+        except ValueError:
+            is_loopback = False
+    if not is_loopback:
+        raise ApiConfigError("HTTP is allowed only for localhost/loopback development")
+    return base_url.rstrip("/")
+
+
+class Api:
+    def __init__(self, base_url: str, token: str | None = None, timeout: float = 30.0):
+        self.base_url = validate_api_base(base_url)
+        self.token = token
+        self.timeout = timeout
+
+    def _headers(self, auth: bool) -> dict:
+        headers = {"Content-Type": "application/json"}
+        if auth and self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        return headers
+
+    def _raw(self, method: str, path: str, *, json=None, auth: bool = True):
+        url = self.base_url + path
+        with httpx.Client(timeout=self.timeout) as client:
+            resp = client.request(method, url, json=json, headers=self._headers(auth))
+        body = None
+        if resp.content:
+            try:
+                body = resp.json()
+            except Exception:
+                body = {"raw": resp.text}
+        return resp.status_code, body
+
+    def request(self, method: str, path: str, *, json=None, auth: bool = True):
+        status, body = self._raw(method, path, json=json, auth=auth)
+        if status >= 400:
+            detail = body.get("detail") if isinstance(body, dict) else body
+            raise ApiError(status, detail)
+        return body
+
+    def get(self, path: str, *, auth: bool = True):
+        return self.request("GET", path, auth=auth)
+
+    def post(self, path: str, *, json=None, auth: bool = True):
+        return self.request("POST", path, json=json, auth=auth)
+
+    def patch(self, path: str, *, json=None, auth: bool = True):
+        return self.request("PATCH", path, json=json, auth=auth)
+
+    def post_status(self, path: str, *, json=None, auth: bool = True):
+        """POST returning (status_code, body) without raising — used for poll endpoints."""
+        return self._raw("POST", path, json=json, auth=auth)