predictabl 0.1.0__py3-none-any.whl

predictabl/__init__.py

@@ -0,0 +1,105 @@
+"""Predictabl from Python.
+
+    import predictabl as pb
+
+    pb.login("pk_...")                      # or set PREDICTABL_API_KEY
+    data  = pb.upload("orders.csv")
+    model = data.predict("Will an order arrive late?")
+    model.report()
+    model.predict(rows=new_orders)
+
+Module-level functions use one shared client, configured by `login()` or the
+PREDICTABL_API_KEY / PREDICTABL_BASE_URL environment variables. For several
+accounts or instances at once, create `predictabl.Client` objects instead.
+"""
+
+from __future__ import annotations
+
+from ._progress import Update
+from ._version import __version__
+from .client import Client, Data, Model, Plan, Predictions
+from .errors import (
+    ApiError,
+    AuthenticationError,
+    BuildFailed,
+    InvalidRequest,
+    LimitReached,
+    NotFound,
+    PermissionDenied,
+    PredictablError,
+)
+
+__all__ = [
+    "__version__",
+    "login",
+    "client",
+    "account",
+    "upload",
+    "data",
+    "datasets",
+    "plan",
+    "model",
+    "models",
+    "Client",
+    "Data",
+    "Plan",
+    "Model",
+    "Predictions",
+    "Update",
+    "PredictablError",
+    "AuthenticationError",
+    "PermissionDenied",
+    "NotFound",
+    "LimitReached",
+    "InvalidRequest",
+    "BuildFailed",
+    "ApiError",
+]
+
+_default: Client | None = None
+
+
+def login(api_key: str | None = None, base_url: str | None = None, **kw) -> Client:
+    """Configure the shared client. Without arguments, reads
+    PREDICTABL_API_KEY (and PREDICTABL_BASE_URL) from the environment."""
+    global _default
+    if _default is not None:
+        _default.close()
+    _default = Client(api_key=api_key, base_url=base_url, **kw)
+    return _default
+
+
+def client() -> Client:
+    """The shared client, created from the environment on first use."""
+    global _default
+    if _default is None:
+        _default = Client()
+    return _default
+
+
+def account() -> dict:
+    return client().account()
+
+
+def upload(source, name: str | None = None, **kw) -> Data:
+    return client().upload(source, name, **kw)
+
+
+def data(data_id: str) -> Data:
+    return client().data(data_id)
+
+
+def datasets() -> list[Data]:
+    return client().datasets()
+
+
+def plan(question_id: str) -> Plan:
+    return client().plan(question_id)
+
+
+def model(model_id: str) -> Model:
+    return client().model(model_id)
+
+
+def models(limit: int = 50) -> list[Model]:
+    return client().models(limit)

predictabl/__main__.py

@@ -0,0 +1,52 @@
+"""Command line: `predictabl whoami`, `predictabl models`, `predictabl mcp`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import errors
+from ._version import __version__
+from .client import Client
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="predictabl", description="Predictabl from the shell."
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"predictabl {__version__}"
+    )
+    parser.add_argument(
+        "--base-url", help="default: PREDICTABL_BASE_URL or the hosted app"
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("whoami", help="your account, plan and builds left")
+    sub.add_parser("models", help="your models")
+    sub.add_parser(
+        "mcp", help="run the MCP server over stdio (for Claude and other agents)"
+    )
+    args = parser.parse_args(argv)
+
+    if args.cmd == "mcp":
+        from .mcp import serve
+
+        serve(base_url=args.base_url)
+        return 0
+
+    try:
+        with Client(base_url=args.base_url) as c:
+            if args.cmd == "whoami":
+                print(json.dumps(c.account(), indent=2))
+            elif args.cmd == "models":
+                for m in c.models():
+                    print(f"{m.id}  {m.state:<10} {m.title or ''}")
+    except errors.PredictablError as exc:
+        print(f"predictabl: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

predictabl/_http.py

@@ -0,0 +1,129 @@
+"""The one place that talks HTTP.
+
+Unwraps the API's `{data, error}` envelope, turns refusals into typed errors,
+and retries what is safe to retry (connection failures and 502/503/504 on
+reads). Everything else in the package goes through `Transport`.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+import httpx
+
+from . import errors
+from ._version import __version__
+
+HOSTED_URL = "https://app.predictabl.tech/pub/v1"
+LOCAL_URL = "http://localhost:8000/api/v1"
+
+_RETRY_STATUS = {502, 503, 504}
+
+
+def resolve_base_url(base_url: str | None) -> str:
+    url = base_url or os.environ.get("PREDICTABL_BASE_URL") or HOSTED_URL
+    return url.rstrip("/")
+
+
+class Transport:
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str,
+        *,
+        timeout: float = 120.0,
+        client_tag: str | None = None,
+        http: httpx.Client | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        agent = f"predictabl-python/{__version__}"
+        if client_tag:
+            agent += f" ({client_tag})"
+        headers = {"User-Agent": agent, "Accept": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self._http = http or httpx.Client(timeout=timeout)
+        self._headers = headers
+
+    def close(self) -> None:
+        self._http.close()
+
+    # ------------------------------------------------------------------ calls
+
+    def get(self, path: str, **params: Any) -> Any:
+        params = {k: v for k, v in params.items() if v is not None}
+        return self._request("GET", path, params=params or None, retry=True)
+
+    def post(self, path: str, json: Any = None, **kw: Any) -> Any:
+        return self._request("POST", path, json=json, **kw)
+
+    def put(self, path: str, json: Any = None) -> Any:
+        return self._request("PUT", path, json=json)
+
+    def patch(self, path: str, json: Any = None) -> Any:
+        return self._request("PATCH", path, json=json)
+
+    def delete(self, path: str) -> Any:
+        return self._request("DELETE", path)
+
+    def _request(self, method: str, path: str, *, retry: bool = False, **kw: Any) -> Any:
+        url = f"{self.base_url}{path}"
+        attempts = 4 if retry else 1
+        last: Exception | None = None
+        for i in range(attempts):
+            try:
+                resp = self._http.request(method, url, headers=self._headers, **kw)
+            except httpx.TransportError as exc:
+                last = exc
+                if i + 1 < attempts:
+                    time.sleep(min(2**i, 8))
+                    continue
+                raise errors.ApiError(
+                    f"Could not reach Predictabl at {self.base_url} ({exc})."
+                ) from exc
+            if resp.status_code in _RETRY_STATUS and i + 1 < attempts:
+                time.sleep(min(2**i, 8))
+                continue
+            return _unwrap(resp)
+        raise errors.ApiError(str(last))  # pragma: no cover - loop always returns
+
+
+def _unwrap(resp: httpx.Response) -> Any:
+    try:
+        body = resp.json()
+    except ValueError:
+        body = None
+    if resp.is_success and isinstance(body, dict) and body.get("error") is None:
+        return body.get("data") if "data" in body else body
+    code, message = _error_of(body, resp)
+    status = resp.status_code
+    cls = {
+        401: errors.AuthenticationError,
+        402: errors.LimitReached,
+        403: errors.PermissionDenied,
+        404: errors.NotFound,
+    }.get(status)
+    if cls is None:
+        cls = errors.InvalidRequest if 400 <= status < 500 else errors.ApiError
+    if status == 401 and not message:
+        message = "Missing or invalid API key. Set PREDICTABL_API_KEY or call login()."
+    raise cls(message or f"HTTP {status}", code=code, status=status)
+
+
+def _error_of(body: Any, resp: httpx.Response) -> tuple[str | None, str]:
+    """The API answers `{data: null, error: {code, message}}`; FastAPI's own
+    refusals (auth, scope) answer `{detail: ...}`. Accept both."""
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):
+            return err.get("code"), str(err.get("message") or "")
+        detail = body.get("detail")
+        if isinstance(detail, str):
+            return None, detail
+        if detail is not None:
+            return None, str(detail)
+    text = (resp.text or "").strip()
+    return None, text[:500]

predictabl/_progress.py

@@ -0,0 +1,103 @@
+"""Step-by-step progress for long operations (reading data, planning, training).
+
+In a terminal the current step updates in place with a spinner; elsewhere
+(notebooks, logs, CI) each change is printed once on its own line, so output
+stays readable when it is not a TTY. `quiet=True` prints nothing; a callback
+receives every update either way.
+"""
+
+from __future__ import annotations
+
+import itertools
+import sys
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+
+@dataclass
+class Update:
+    step: str  # e.g. "Training"
+    status: str  # "running" | "done" | "failed"
+    detail: str = ""
+
+
+Callback = Callable[[Update], None]
+
+_SPIN = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+
+class Progress:
+    def __init__(
+        self, *, quiet: bool = False, on_update: Callback | None = None, stream=None
+    ):
+        self.quiet = quiet
+        self.on_update = on_update
+        self.stream = stream or sys.stderr
+        self.tty = bool(getattr(self.stream, "isatty", lambda: False)())
+        self._spin = itertools.cycle(_SPIN)
+        self._current: str | None = None
+        self._last_line = ""
+        self._last_printed: tuple[str, str] | None = None
+        self._started = time.monotonic()
+
+    # ------------------------------------------------------------- reporting
+
+    def running(self, step: str, detail: str = "") -> None:
+        if self._current and self._current != step:
+            self.done(self._current)
+        self._current = step
+        self._emit(Update(step, "running", detail))
+
+    def done(self, step: str | None = None, detail: str = "") -> None:
+        step = step or self._current
+        if step is None:
+            return
+        self._emit(Update(step, "done", detail))
+        if step == self._current:
+            self._current = None
+
+    def failed(self, step: str | None = None, detail: str = "") -> None:
+        step = step or self._current or "Error"
+        self._emit(Update(step, "failed", detail))
+        self._current = None
+
+    def tick(self) -> None:
+        """Advance the spinner while waiting (terminal only)."""
+        if self.tty and not self.quiet and self._last_line:
+            self._write(self._last_line, final=False)
+
+    # ---------------------------------------------------------------- output
+
+    def _emit(self, u: Update) -> None:
+        if self.on_update is not None:
+            try:
+                self.on_update(u)
+            except Exception:  # noqa: BLE001 - a user callback must not break a build
+                pass
+        if self.quiet:
+            return
+        mark = {"done": "✓", "failed": "✗"}.get(u.status)
+        line = f"{u.step:<14} {u.detail}".rstrip()
+        if self.tty:
+            if mark:
+                self._write(f"{mark} {line}", final=True)
+                self._last_line = ""
+            else:
+                self._last_line = line
+                self._write(line, final=False)
+            return
+        # Not a terminal: one line per distinct change, never per poll.
+        key = (u.status, line)
+        if key == self._last_printed:
+            return
+        self._last_printed = key
+        print(f"{mark or '…'} {line}", file=self.stream, flush=True)
+
+    def _write(self, line: str, *, final: bool) -> None:
+        if final:
+            text = f"\r\033[2K{line}\n"
+        else:
+            text = f"\r\033[2K{next(self._spin)} {line}"
+        self.stream.write(text)
+        self.stream.flush()

predictabl/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"