polnor 0.1.0__py3-none-any.whl

polnor/__init__.py

@@ -0,0 +1,25 @@
+"""Polnor Python SDK.
+
+Today this exposes the MLflow-compatible tracking surface
+(:mod:`polnor.mlflow`). More modules — auth, jobs, runs, datasets —
+land here as the API stabilises.
+
+The SDK is auto-configured from environment variables when running
+inside a Polnor job. Outside a job, set them yourself::
+
+    export POLNOR_API_URL=https://api.polnor.net
+    export POLNOR_TOKEN=<personal access token>
+    export POLNOR_EXPERIMENT_ID=<uuid of an experiment>
+
+Then::
+
+    from polnor import mlflow
+    with mlflow.start_run() as run:
+        mlflow.log_param("lr", 0.01)
+        mlflow.log_metric("accuracy", 0.93)
+"""
+
+from . import mlflow
+
+__all__ = ["mlflow"]
+__version__ = "0.1.0"

polnor/_client.py

@@ -0,0 +1,132 @@
+"""Thin HTTP client used by polnor.mlflow.
+
+Kept separate so future SDK modules (jobs, datasets) can share the
+same auth + retry plumbing without dragging the MLflow surface in.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import urllib.parse
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+try:
+    import requests
+except ImportError as e:  # pragma: no cover — caught early in install
+    raise ImportError(
+        "polnor SDK requires the 'requests' package. "
+        "Install with `pip install polnor` or `pip install requests`."
+    ) from e
+
+
+class PolnorAPIError(RuntimeError):
+    """Raised on a non-2xx API response with the body verbatim."""
+
+    def __init__(self, status: int, body: str, *, method: str, url: str):
+        super().__init__(f"{method} {url} → {status}: {body}")
+        self.status = status
+        self.body = body
+
+
+@dataclass
+class Config:
+    """SDK configuration. Read from env by default; override for tests."""
+
+    api_url: str
+    token: str
+    workspace_slug: str | None = None
+    timeout: float = 30.0
+    max_retries: int = 3
+    backoff_base: float = 0.5
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        api_url = os.environ.get("POLNOR_API_URL", "").rstrip("/")
+        token = os.environ.get("POLNOR_TOKEN", "")
+        workspace = os.environ.get("POLNOR_WORKSPACE_SLUG") or None
+        if not api_url:
+            raise RuntimeError(
+                "POLNOR_API_URL is not set — point it at https://api.polnor.net "
+                "(or your self-hosted control plane)."
+            )
+        if not token:
+            raise RuntimeError(
+                "POLNOR_TOKEN is not set — generate a personal access token "
+                "from /settings/tokens and export POLNOR_TOKEN."
+            )
+        return cls(api_url=api_url, token=token, workspace_slug=workspace)
+
+
+class Client:
+    """HTTP client with token auth + retry on 5xx / connection errors.
+
+    Idempotency: every method here is safe to retry — they're either
+    pure GETs or POST/PATCH endpoints that the server side already
+    handles idempotently (start_run with the same body would create a
+    second run, but that's a deliberate design — MLflow does the same).
+    """
+
+    def __init__(self, cfg: Config | None = None):
+        self.cfg = cfg or Config.from_env()
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {self.cfg.token}",
+            "Content-Type": "application/json",
+            "User-Agent": "polnor-sdk-python/0.1.0",
+        })
+        if self.cfg.workspace_slug:
+            self._session.headers["X-Workspace-Slug"] = self.cfg.workspace_slug
+
+    # --- low-level ---
+
+    def request(self, method: str, path: str, *, json: Any | None = None,
+                params: Mapping[str, Any] | None = None) -> Any:
+        url = self._build_url(path, params)
+        last_err: Exception | None = None
+        for attempt in range(self.cfg.max_retries):
+            try:
+                resp = self._session.request(
+                    method, url, json=json, timeout=self.cfg.timeout
+                )
+            except requests.RequestException as e:
+                last_err = e
+                self._sleep(attempt)
+                continue
+
+            if resp.status_code >= 500:
+                last_err = PolnorAPIError(resp.status_code, resp.text, method=method, url=url)
+                self._sleep(attempt)
+                continue
+            if resp.status_code >= 400:
+                raise PolnorAPIError(resp.status_code, resp.text, method=method, url=url)
+
+            if resp.status_code == 204 or not resp.content:
+                return None
+            return resp.json()
+
+        if last_err:
+            raise last_err
+        return None
+
+    def _build_url(self, path: str, params: Mapping[str, Any] | None) -> str:
+        base = f"{self.cfg.api_url}/api/v1{path}"
+        if not params:
+            return base
+        return f"{base}?{urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})}"
+
+    def _sleep(self, attempt: int) -> None:
+        delay = self.cfg.backoff_base * (2 ** attempt)
+        time.sleep(delay)
+
+    # --- convenience wrappers ---
+
+    def post(self, path: str, json: Any | None = None) -> Any:
+        return self.request("POST", path, json=json)
+
+    def patch(self, path: str, json: Any | None = None) -> Any:
+        return self.request("PATCH", path, json=json)
+
+    def get(self, path: str, params: Mapping[str, Any] | None = None) -> Any:
+        return self.request("GET", path, params=params)

polnor/mlflow.py

@@ -0,0 +1,300 @@
+"""MLflow-compatible tracking surface for Polnor.
+
+Drop-in shim for the bits of MLflow most jobs use::
+
+    from polnor import mlflow
+
+    with mlflow.start_run() as run:
+        mlflow.log_param("learning_rate", 0.01)
+        mlflow.log_param("optimizer", "adam")
+
+        for epoch in range(10):
+            mlflow.log_metric("loss", train_loss, step=epoch)
+            mlflow.log_metric("accuracy", val_acc, step=epoch)
+
+        mlflow.set_tag("git_commit", os.environ["CI_COMMIT_SHA"])
+
+The active run is stored in a thread-local so nested calls in the
+same job don't fight over a global; calling ``start_run`` twice
+without ``end_run`` between them stacks runs the way MLflow's nested
+runs do.
+
+The following MLflow API is *not* implemented yet and will raise
+``NotImplementedError``:
+
+* ``log_artifact`` — needs a presigned-URL upload flow
+* ``log_image`` / ``log_dict`` — derived from artifacts
+* ``mlflow.search_runs`` — read-side, use the REST API directly
+
+Server-side, metrics are stored as the *latest* value per key (JSONB
+merge). A full time-series of ``(step, value, timestamp)`` per metric
+is tracked separately in a future migration; until then,
+``log_metric(..., step=...)`` records the value but not the step.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import threading
+from dataclasses import dataclass
+from typing import Any, Iterator, Mapping
+
+from ._client import Client
+
+
+# Thread-local stack of active runs; supports the nested-run pattern
+# used by frameworks that spawn child runs per CV fold.
+_local = threading.local()
+
+
+def _stack() -> list["ActiveRun"]:
+    if not hasattr(_local, "runs"):
+        _local.runs = []
+    return _local.runs
+
+
+def _client() -> Client:
+    """Single Client per thread, lazily constructed.
+
+    Reusing the same Session across calls means TLS handshakes and
+    auth resolution amortize across log_metric calls in a tight loop.
+    """
+    if not hasattr(_local, "client"):
+        _local.client = Client()
+    return _local.client
+
+
+@dataclass
+class ActiveRun:
+    """Handle to a running experiment_run on the server.
+
+    Returned by :func:`start_run`; usable as a context manager so the
+    run is finalized on scope exit even when an exception escapes.
+    """
+
+    experiment_id: str
+    run_id: str
+    name: str
+
+    def __enter__(self) -> "ActiveRun":
+        _stack().append(self)
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        # End with status='failed' when an exception escaped, otherwise
+        # 'completed'. Errors in end_run itself are swallowed so they
+        # don't replace the user's exception.
+        status = "failed" if exc_type is not None else "completed"
+        try:
+            end_run(status=status)
+        except Exception:
+            pass
+
+
+def _experiment_id_from_env() -> str:
+    exp_id = os.environ.get("POLNOR_EXPERIMENT_ID")
+    if not exp_id:
+        raise RuntimeError(
+            "No active experiment. Either:\n"
+            "  - export POLNOR_EXPERIMENT_ID=<uuid>, or\n"
+            "  - call mlflow.start_run(experiment_id=...)."
+        )
+    return exp_id
+
+
+def start_run(
+    *,
+    experiment_id: str | None = None,
+    run_name: str | None = None,
+    params: Mapping[str, Any] | None = None,
+    tags: Mapping[str, str] | None = None,
+) -> ActiveRun:
+    """Start a new run and make it the active one.
+
+    The returned :class:`ActiveRun` is usable as a context manager. If
+    ``experiment_id`` is omitted, ``POLNOR_EXPERIMENT_ID`` is used.
+    """
+    exp_id = experiment_id or _experiment_id_from_env()
+    body: dict[str, Any] = {}
+    if run_name:
+        body["name"] = run_name
+    if params:
+        body["params"] = dict(params)
+    if tags:
+        body["tags"] = dict(tags)
+    resp = _client().post(f"/experiments/{exp_id}/runs", body)
+    run = ActiveRun(experiment_id=exp_id, run_id=resp["id"], name=resp.get("name", ""))
+    _stack().append(run)
+    return run
+
+
+def active_run() -> ActiveRun | None:
+    """Return the run on top of the active stack, or None."""
+    s = _stack()
+    return s[-1] if s else None
+
+
+def _require_active() -> ActiveRun:
+    run = active_run()
+    if run is None:
+        raise RuntimeError("No active run. Call start_run() first.")
+    return run
+
+
+def end_run(status: str = "completed") -> None:
+    """Finish the active run with the given status.
+
+    Pops the top of the active stack — nested runs continue to use the
+    next-outer parent.
+    """
+    s = _stack()
+    if not s:
+        return  # no-op when called outside a run
+    run = s.pop()
+    _client().patch(
+        f"/experiments/{run.experiment_id}/runs/{run.run_id}",
+        {"status": status},
+    )
+
+
+def log_metric(key: str, value: float, step: int | None = None) -> None:
+    """Record a single metric value on the active run.
+
+    ``step`` is accepted for MLflow API compatibility but currently
+    ignored server-side (latest-value-wins). The server will track
+    full history once the per-step migration lands.
+    """
+    run = _require_active()
+    body: dict[str, Any] = {"key": key, "value": float(value)}
+    if step is not None:
+        body["step"] = int(step)
+    _client().post(
+        f"/experiments/{run.experiment_id}/runs/{run.run_id}/metrics",
+        body,
+    )
+
+
+def log_metrics(metrics: Mapping[str, float], step: int | None = None) -> None:
+    """Batch variant — single round-trip per dict."""
+    run = _require_active()
+    _client().post(
+        f"/experiments/{run.experiment_id}/runs/{run.run_id}/metrics/batch",
+        {"metrics": {k: float(v) for k, v in metrics.items()}},
+    )
+    _ = step  # see log_metric for why we accept-and-ignore
+
+
+def log_param(key: str, value: Any) -> None:
+    """Record a hyperparameter on the active run."""
+    run = _require_active()
+    _client().post(
+        f"/experiments/{run.experiment_id}/runs/{run.run_id}/params",
+        {"key": key, "value": value},
+    )
+
+
+def log_params(params: Mapping[str, Any]) -> None:
+    """Convenience: log_param in a loop."""
+    for k, v in params.items():
+        log_param(k, v)
+
+
+def set_tag(key: str, value: str) -> None:
+    run = _require_active()
+    _client().post(
+        f"/experiments/{run.experiment_id}/runs/{run.run_id}/tags",
+        {"key": key, "value": str(value)},
+    )
+
+
+def set_tags(tags: Mapping[str, str]) -> None:
+    for k, v in tags.items():
+        set_tag(k, v)
+
+
+def log_artifact(local_path: str, artifact_path: str | None = None) -> None:
+    """Upload a local file as an artifact of the active run.
+
+    Two-step flow: ask the server for a presigned PUT URL, then
+    stream the file to S3 directly. The server records the artifact
+    path in the run's JSONB ``artifacts`` list. Files larger than
+    ~100 MB should ideally be chunked; we send a single PUT here and
+    let the underlying TLS connection take care of the streaming.
+    """
+    import os
+    if not os.path.isfile(local_path):
+        raise FileNotFoundError(local_path)
+    target = artifact_path or os.path.basename(local_path)
+    run = _require_active()
+    presign = _client().post(
+        f"/experiments/{run.experiment_id}/runs/{run.run_id}/artifacts/presigned-url",
+        {"path": target, "content_type": "application/octet-stream"},
+    )
+    upload_url = presign["upload_url"]
+
+    # We bypass the SDK's auth-bearing Session for the actual PUT —
+    # presigned URLs carry their own signature and don't accept the
+    # Polnor Bearer header. Use a stripped-down requests call.
+    import requests
+    with open(local_path, "rb") as f:
+        resp = requests.put(upload_url, data=f, timeout=300)
+    if resp.status_code >= 400:
+        raise RuntimeError(
+            f"artifact upload failed ({resp.status_code}): {resp.text[:200]}"
+        )
+
+
+def get_metric_history(key: str) -> list[dict]:
+    """Return every (step, value, timestamp) observation for a metric
+    on the active run. Useful for building local plots or comparing
+    across runs.
+    """
+    run = _require_active()
+    resp = _client().get(
+        f"/experiments/{run.experiment_id}/runs/{run.run_id}/metrics/{key}"
+    )
+    return resp.get("data", [])
+
+
+@contextlib.contextmanager
+def autolog(framework: str | None = None) -> Iterator[None]:
+    """Lightweight autolog: open a run on enter, close on exit.
+
+    The full MLflow autolog hooks (sklearn estimator inspection, etc.)
+    aren't here yet. This context just gives users the convenient
+    ``with mlflow.autolog():`` shape that frameworks tend to wrap.
+    """
+    run = start_run()
+    if framework:
+        try:
+            set_tag("autolog.framework", framework)
+        except Exception:
+            pass
+    try:
+        yield
+    finally:
+        try:
+            end_run("completed")
+        except Exception:
+            # Make sure the stack stays clean even if the network call fails.
+            s = _stack()
+            if s and s[-1] is run:
+                s.pop()
+
+
+__all__ = [
+    "ActiveRun",
+    "start_run",
+    "end_run",
+    "active_run",
+    "log_metric",
+    "log_metrics",
+    "log_param",
+    "log_params",
+    "set_tag",
+    "set_tags",
+    "log_artifact",
+    "get_metric_history",
+    "autolog",
+]

polnor-0.1.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: polnor
+Version: 0.1.0
+Summary: Polnor Python SDK — query Iceberg lakehouses, manage notebooks/jobs/models, MLflow-compatible tracking.
+Author-email: Polnor <contact@polnor.net>
+License: Apache-2.0
+Project-URL: Homepage, https://polnor.net
+Project-URL: Documentation, https://docs.polnor.net/sdk/python
+Project-URL: Source, https://github.com/polnor/polnor
+Keywords: polnor,lakehouse,iceberg,sql,mlflow,data-platform
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: responses>=0.24; extra == "test"
+
+# Polnor Python SDK
+
+MLflow-compatible tracking for jobs running on the Polnor lakehouse.
+
+## Install
+
+```bash
+pip install polnor
+```
+
+Or, from a local checkout (contributors / pre-release):
+
+```bash
+pip install -e ./sdk/python
+```
+
+## Configure
+
+Set three environment variables before importing the SDK:
+
+| Variable | Required | Notes |
+|---|---|---|
+| `POLNOR_API_URL` | yes | e.g. `https://api.polnor.net` |
+| `POLNOR_TOKEN` | yes | Personal access token from `/settings/tokens` |
+| `POLNOR_EXPERIMENT_ID` | optional | Default experiment for `start_run()` |
+| `POLNOR_WORKSPACE_SLUG` | optional | When the token isn't workspace-scoped |
+
+Inside a Polnor job these are injected automatically.
+
+## Quickstart
+
+```python
+from polnor import mlflow
+
+with mlflow.start_run(run_name="train-resnet50") as run:
+    mlflow.log_params({"lr": 0.01, "batch_size": 32, "optimizer": "adam"})
+
+    for epoch in range(10):
+        loss, acc = train_one_epoch()
+        mlflow.log_metrics({"loss": loss, "accuracy": acc}, step=epoch)
+
+    mlflow.set_tag("git_commit", os.environ.get("CI_COMMIT_SHA", "dev"))
+```
+
+The run handle is also usable without the `with` block:
+
+```python
+run = mlflow.start_run()
+try:
+    mlflow.log_metric("score", 0.93)
+finally:
+    mlflow.end_run("completed")
+```
+
+## What's supported
+
+| API | Status |
+|---|---|
+| `start_run` / `end_run` / `active_run` | ✅ |
+| `log_metric` / `log_metrics` (latest value wins) | ✅ |
+| `log_param` / `log_params` | ✅ |
+| `set_tag` / `set_tags` | ✅ |
+| `autolog()` context manager | ✅ |
+| Per-step metric history (time series) | ⏳ planned |
+| `log_artifact` (presigned-URL upload) | ⏳ planned |
+| Sklearn / PyTorch / TF auto-instrumentation | ⏳ planned |
+
+## How it differs from upstream MLflow
+
+* Server-side, metrics merge into a single JSONB blob — the latest
+  value per key wins. The full `(step, value, timestamp)` history is
+  in scope for a follow-up migration.
+* No server-side parameter immutability check yet — calling
+  `log_param("lr", 0.02)` after `log_param("lr", 0.01)` overwrites
+  silently. Upstream MLflow rejects with 400.
+* No `mlflow.search_runs()` — use the REST API
+  (`GET /api/v1/experiments/:id/runs`) directly until we wrap it.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Tests use [responses](https://github.com/getsentry/responses) to mock
+HTTP — no live API needed.

polnor-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+polnor/__init__.py,sha256=3M_AsT8n2SOftHXlVK_wCFAXXRFkDfwDibakOCXZPZk,690
+polnor/_client.py,sha256=SNKx-MFPnECcD8AopAql3jbjqIklrF1boDDLoosQSCY,4641
+polnor/mlflow.py,sha256=e4HjrA7i_Hi2PXK7z-ct2Z21FQAT6u3lqlwq-82vcOI,9180
+polnor-0.1.0.dist-info/METADATA,sha256=obC3mNnV6I2YHCysBVzC_CuryTkcJaM3kGykhUquEWo,3493
+polnor-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+polnor-0.1.0.dist-info/top_level.txt,sha256=SRaiPv1RjbeCmlsA5dXXw-gsS_oTbIvbD90RgdJm0EU,7
+polnor-0.1.0.dist-info/RECORD,,

polnor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

polnor-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+polnor