langsat 0.1.0__py3-none-any.whl

langsat/__init__.py

@@ -0,0 +1,33 @@
+"""Langsat SDK.
+
+    from langsat import Langsat, login
+    login()                     # once: paste the key from Settings → API keys
+    ls = Langsat()
+    p = ls.projects.create("demo"); p.sources.upload("orders.csv"); p.schema.detect().wait()
+"""
+from ._version import __version__
+from .auth import login, logout, whoami
+from .client import Langsat
+from .errors import (
+                     AuthError,
+                     Conflict,
+                     Forbidden,
+                     InsufficientCredits,
+                     Invalid,
+                     JobFailed,
+                     JobTimeout,
+                     LangsatError,
+                     MissingScope,
+                     NeedsUserSession,
+                     NotFound,
+                     ProjectBusy,
+                     QuotaExceeded,
+                     RateLimited,
+                     Refused,
+                     RowCapExceeded,
+)
+from .jobs import Job
+
+__all__ = ["Langsat", "login", "logout", "whoami", "Job", "__version__",
+           "LangsatError", "AuthError", "MissingScope", "NeedsUserSession", "Forbidden", "NotFound", "InsufficientCredits",
+           "QuotaExceeded", "RateLimited", "ProjectBusy", "Conflict", "RowCapExceeded", "Invalid", "Refused", "JobFailed", "JobTimeout"]

langsat/_http.py

@@ -0,0 +1,124 @@
+"""The one HTTP layer: auth header, User-Agent, retries with backoff, Idempotency-Key, typed errors."""
+from __future__ import annotations
+
+import json
+import random
+import time
+import uuid
+from typing import Any, Iterable, Optional
+
+import httpx
+
+from ._version import __version__
+from .errors import LangsatError, ProjectBusy, RateLimited, from_response
+
+# The lanes the API replays on a repeated Idempotency-Key (mirrors SDK/openapi x-idempotent).
+IDEMPOTENT_SUFFIXES: tuple = (
+    "/train", "/clean", "/refresh", "/data-model/refresh", "/generate-cards", "/dashboard/generate",
+    "/reports/export", "/predict", "/predict/batch", "/predict/forecast", "/inference",
+    "/add-recipe-chart", "/measures", "/task", "/suggestions", "/sources/link",
+)
+
+
+class HttpClient:
+    def __init__(self, base_url: str, token: Optional[str], *, timeout: float = 60.0, max_retries: int = 4,
+                 auto_idempotency: bool = True, transport: Optional[httpx.BaseTransport] = None):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.max_retries = max_retries
+        self.auto_idempotency = auto_idempotency
+        headers = {"User-Agent": f"langsat-python/{__version__}", "Accept": "application/json"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        self._client = httpx.Client(base_url=self.base_url, headers=headers, timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ── the request ──
+    def request(self, method: str, path: str, *, json_body: Any = None, params: Optional[dict] = None,
+                idempotency_key: Optional[str] = None, files: Any = None, data: Any = None,
+                wait_if_busy: float = 0.0, raw: bool = False, headers: Optional[dict] = None) -> Any:
+        """One call, with: automatic `Idempotency-Key` on the replayable lanes (a retry after a
+        timeout then replays, never re-runs), backoff on 429 / 503 honouring `Retry-After`, and
+        — only when `wait_if_busy` > 0 — polite waiting on 409 project_busy up to that many
+        seconds. Every non-2xx becomes a typed `LangsatError`."""
+        hdrs = dict(headers or {})
+        m = method.upper()
+        if m in ("POST", "PUT", "PATCH", "DELETE"):
+            key = idempotency_key
+            if key is None and self.auto_idempotency and any(path.rstrip("/").endswith(s) for s in IDEMPOTENT_SUFFIXES):
+                key = f"sdk-{uuid.uuid4().hex}"
+            if key:
+                hdrs["Idempotency-Key"] = key
+        attempt = 0
+        busy_deadline = time.monotonic() + wait_if_busy if wait_if_busy else None
+        while True:
+            attempt += 1
+            try:
+                resp = self._client.request(m, path, json=json_body, params=params, files=files, data=data, headers=hdrs)
+            except (httpx.TimeoutException, httpx.TransportError) as e:
+                if attempt <= self.max_retries and (m == "GET" or "Idempotency-Key" in hdrs):
+                    time.sleep(self._backoff(attempt))
+                    continue
+                raise LangsatError(0, "network", f"{type(e).__name__}: {e}") from e
+            if 200 <= resp.status_code < 300:
+                if raw:
+                    return resp
+                if not resp.content:
+                    return None
+                ctype = resp.headers.get("content-type", "")
+                return resp.json() if "json" in ctype else resp.content
+            err = from_response(resp.status_code, self._json_or_text(resp), {k.lower(): v for k, v in resp.headers.items()})
+            if isinstance(err, RateLimited) or resp.status_code == 503:
+                if attempt <= self.max_retries:
+                    time.sleep(err.retry_after if isinstance(err, RateLimited) and err.retry_after else self._backoff(attempt))
+                    continue
+            if isinstance(err, ProjectBusy) and busy_deadline and time.monotonic() < busy_deadline:
+                time.sleep(min(5.0, max(1.0, self._backoff(attempt))))
+                continue
+            raise err
+
+    @staticmethod
+    def _json_or_text(resp: httpx.Response) -> Any:
+        try:
+            return resp.json()
+        except (json.JSONDecodeError, ValueError):
+            return resp.text
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        return min(30.0, (2 ** (attempt - 1)) * 0.5 + random.random() * 0.25)
+
+    # ── sugar ──
+    def get(self, path: str, **kw) -> Any:
+        return self.request("GET", path, **kw)
+
+    def post(self, path: str, json_body: Any = None, **kw) -> Any:
+        return self.request("POST", path, json_body=json_body, **kw)
+
+    def put(self, path: str, json_body: Any = None, **kw) -> Any:
+        return self.request("PUT", path, json_body=json_body, **kw)
+
+    def patch(self, path: str, json_body: Any = None, **kw) -> Any:
+        return self.request("PATCH", path, json_body=json_body, **kw)
+
+    def delete(self, path: str, **kw) -> Any:
+        return self.request("DELETE", path, **kw)
+
+    def put_bytes(self, url: str, content: bytes, content_type: str) -> None:
+        """A presigned S3 PUT — no auth header, no base_url."""
+        r = httpx.put(url, content=content, headers={"Content-Type": content_type}, timeout=600)
+        if r.status_code >= 300:
+            raise LangsatError(r.status_code, "upload_failed", f"S3 PUT failed: {r.text[:200]}")
+
+
+def chunked(it: Iterable, n: int):
+    buf = []
+    for x in it:
+        buf.append(x)
+        if len(buf) == n:
+            yield buf
+            buf = []
+    if buf:
+        yield buf

langsat/_version.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.0"
+CONTRACT_VERSION = "1.0.0"

langsat/auth.py

@@ -0,0 +1,91 @@
+"""Login the Hugging Face way.
+
+A token (`rdl_…`) is minted once in the web app (Settings → API keys, with the scopes and
+projects it may touch). Then:
+
+    langsat login                 # paste the token; it is verified and saved to ~/.langsat/token
+    export LANGSAT_API_KEY=rdl_…  # or: the environment wins over the saved file
+    Langsat(token="rdl_…")        # or: pass it explicitly
+
+Resolution order: explicit argument > `LANGSAT_API_KEY` > the token file (`LANGSAT_TOKEN_PATH`
+or `~/.langsat/token`, mode 0600). There is no password login: a Google-SSO account has no
+password and a script should never hold one.
+"""
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+from typing import Optional
+
+ENV_TOKEN = "LANGSAT_API_KEY"
+ENV_TOKEN_PATH = "LANGSAT_TOKEN_PATH"
+ENV_BASE_URL = "LANGSAT_BASE_URL"
+DEFAULT_BASE_URL = "https://api.langsat.ai/api/v1"
+TOKEN_PREFIX = "rdl_"
+
+
+def token_path() -> Path:
+    p = os.environ.get(ENV_TOKEN_PATH)
+    return Path(p).expanduser() if p else Path.home() / ".langsat" / "token"
+
+
+def read_saved_token() -> Optional[str]:
+    try:
+        t = token_path().read_text().strip()
+    except OSError:
+        return None
+    return t or None
+
+
+def save_token(token: str) -> Path:
+    p = token_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(token.strip() + "\n")
+    try:
+        os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)        # 0600 — the token is a credential
+    except OSError:
+        pass
+    return p
+
+
+def delete_saved_token() -> bool:
+    p = token_path()
+    if p.exists():
+        p.unlink()
+        return True
+    return False
+
+
+def resolve_token(explicit: Optional[str] = None) -> Optional[str]:
+    return (explicit or os.environ.get(ENV_TOKEN) or read_saved_token() or None)
+
+
+def resolve_base_url(explicit: Optional[str] = None) -> str:
+    return (explicit or os.environ.get(ENV_BASE_URL) or DEFAULT_BASE_URL).rstrip("/")
+
+
+def login(token: Optional[str] = None, *, base_url: Optional[str] = None, save: bool = True) -> dict:
+    """Verify a token against the API (`GET /auth/me`) and, when it is good, save it for every
+    later `Langsat()`. Returns the whoami payload (who the key acts as, its scopes, its projects).
+    With no `token`, prompts on the terminal (input hidden)."""
+    from .client import Langsat
+    if not token:
+        import getpass
+        token = getpass.getpass("Langsat API key (rdl_…, from Settings → API keys): ").strip()
+    if not token.startswith(TOKEN_PREFIX):
+        raise ValueError(f"A Langsat API key starts with {TOKEN_PREFIX!r}")
+    me = Langsat(token=token, base_url=base_url).me()
+    if save:
+        save_token(token)
+    return me
+
+
+def logout() -> bool:
+    """Forget the saved token (the key itself stays valid until revoked in Settings)."""
+    return delete_saved_token()
+
+
+def whoami(*, token: Optional[str] = None, base_url: Optional[str] = None) -> dict:
+    from .client import Langsat
+    return Langsat(token=token, base_url=base_url).me()

langsat/cli.py

@@ -0,0 +1,47 @@
+"""`langsat login | whoami | logout` — the Hugging Face shape."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import auth
+from .errors import LangsatError
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="langsat", description="Langsat SDK")
+    sub = ap.add_subparsers(dest="cmd")
+    p_login = sub.add_parser("login", help="verify an API key and save it to ~/.langsat/token")
+    p_login.add_argument("--token", help="the rdl_… key (prompted when omitted)")
+    p_login.add_argument("--base-url", help="API base URL (default https://api.langsat.ai/api/v1)")
+    p_login.add_argument("--no-save", action="store_true")
+    p_who = sub.add_parser("whoami", help="who the saved / env key acts as")
+    p_who.add_argument("--base-url")
+    sub.add_parser("logout", help="forget the saved token")
+    args = ap.parse_args(argv)
+    try:
+        if args.cmd == "login":
+            me = auth.login(args.token, base_url=args.base_url, save=not args.no_save)
+            key = me.get("api_key") or {}
+            print(f"Logged in as {me.get('email')} (tier {me.get('tier')})")
+            print(f"  key: {key.get('name')} [{key.get('prefix')}…]  scopes: {', '.join(key.get('scopes') or [])}")
+            print(f"  projects: {key.get('project_ids') or 'all'}  expires: {key.get('expires_at') or 'never'}")
+            if not args.no_save:
+                print(f"  saved to {auth.token_path()}")
+            return 0
+        if args.cmd == "whoami":
+            print(json.dumps(auth.whoami(base_url=args.base_url), indent=2))
+            return 0
+        if args.cmd == "logout":
+            print("token removed" if auth.logout() else "no saved token")
+            return 0
+        ap.print_help()
+        return 1
+    except LangsatError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

langsat/client.py

@@ -0,0 +1,48 @@
+"""`Langsat` — the entry point."""
+from __future__ import annotations
+
+from typing import Optional
+
+from ._http import HttpClient
+from .auth import resolve_base_url, resolve_token
+from .errors import AuthError
+from .resources.models import Predict
+from .resources.ops import Credits
+from .resources.projects import Projects
+
+
+class Langsat:
+    """The same user, the same rights, the same prices, with no screen.
+
+        ls = Langsat()                        # token from LANGSAT_API_KEY or `langsat login`
+        ls = Langsat(token="rdl_…")           # explicit
+        ls.me()                               # who the key acts as, its scopes and projects
+        p = ls.projects.create("churn-q3")
+    """
+
+    def __init__(self, token: Optional[str] = None, *, base_url: Optional[str] = None, timeout: float = 60.0,
+                 max_retries: int = 4, auto_idempotency: bool = True, transport=None):
+        tok = resolve_token(token)
+        if not tok:
+            raise AuthError(401, "no_token", "No API key: run `langsat login`, set LANGSAT_API_KEY, or pass token=…")
+        self.base_url = resolve_base_url(base_url)
+        self._http = HttpClient(self.base_url, tok, timeout=timeout, max_retries=max_retries,
+                                auto_idempotency=auto_idempotency, transport=transport)
+        self.projects = Projects(self._http)
+        self.predict = Predict(self._http)
+        self.credits = Credits(self._http)
+
+    def me(self) -> dict:
+        return self._http.get("/auth/me")
+
+    def tiers(self) -> dict:
+        return self._http.get("/tiers")
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()

langsat/errors.py

@@ -0,0 +1,123 @@
+"""Typed errors — one per `X-Error-Code` the API emits, so a script branches without parsing English."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class LangsatError(Exception):
+    """Base: `status`, `code` (the API's X-Error-Code / detail.code), `message`, raw `detail`."""
+
+    def __init__(self, status: int, code: Optional[str], message: str, detail: Any = None,
+                 headers: Optional[dict] = None):
+        super().__init__(f"[{status}{' ' + code if code else ''}] {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.detail = detail
+        self.headers = headers or {}
+
+
+class AuthError(LangsatError):
+    """401 — no token, a revoked or expired key."""
+
+
+class MissingScope(LangsatError):
+    """403 missing_scope — the key does not carry the scope this call needs (`.scope`)."""
+
+    @property
+    def scope(self) -> Optional[str]:
+        return (self.detail or {}).get("scope") if isinstance(self.detail, dict) else None
+
+
+class NeedsUserSession(LangsatError):
+    """403 needs_user_session — only a signed-in person may do this (billing, account, SQL)."""
+
+
+class Forbidden(LangsatError):
+    """403 — role / tier / frozen project."""
+
+
+class NotFound(LangsatError):
+    """404."""
+
+
+class InsufficientCredits(LangsatError):
+    """402 — the action costs more credits than the account has."""
+
+
+class QuotaExceeded(LangsatError):
+    """429 quota_exhausted / spend_limit_reached — a daily or monthly limit."""
+
+
+class RateLimited(LangsatError):
+    """429 rate_limited — too many requests; `retry_after` seconds when the API says."""
+
+    @property
+    def retry_after(self) -> Optional[float]:
+        v = self.headers.get("retry-after")
+        try:
+            return float(v) if v is not None else None
+        except ValueError:
+            return None
+
+
+class ProjectBusy(LangsatError):
+    """409 project_busy — a clean / refresh / schema detection / training is in progress."""
+
+
+class Conflict(LangsatError):
+    """409 — another conflict (an idempotency key still in flight, a pending edit that would be dropped…)."""
+
+
+class RowCapExceeded(LangsatError):
+    """422 row_cap_exceeded — the tier's row limit."""
+
+
+class Invalid(LangsatError):
+    """422 / 400 — the request was refused; `detail` says why."""
+
+
+class Refused(LangsatError):
+    """200 with a refusal reason (the chart builder, a would-drop edit) — never guessed past."""
+
+
+class JobFailed(LangsatError):
+    """A job ended `failed`; `.job` carries the record."""
+
+    def __init__(self, job: dict):
+        err = job.get("error") or {}
+        super().__init__(200, err.get("code") or "job_failed", err.get("message") or "Job failed", job)
+        self.job = job
+
+
+class JobTimeout(LangsatError):
+    """`wait()` gave up before the job ended."""
+
+
+_BY_CODE = {
+    "unauthorized": AuthError, "missing_scope": MissingScope, "needs_user_session": NeedsUserSession,
+    "forbidden": Forbidden, "forbidden_role": Forbidden, "project_frozen": Forbidden, "read_only": Forbidden,
+    "email_not_verified": Forbidden, "not_found": NotFound, "project_not_found": NotFound,
+    "insufficient_credits": InsufficientCredits, "quota_exhausted": QuotaExceeded,
+    "spend_limit_reached": QuotaExceeded, "rate_limited": RateLimited, "project_busy": ProjectBusy,
+    "conflict": Conflict, "idempotency_in_progress": Conflict, "pending_would_drop": Conflict,
+    "row_cap_exceeded": RowCapExceeded, "invalid": Invalid, "cell_overrides_invalid": Invalid,
+    "unknown_scope": Invalid, "idempotency_key_invalid": Invalid,
+}
+_BY_STATUS = {401: AuthError, 402: InsufficientCredits, 403: Forbidden, 404: NotFound, 409: Conflict,
+              422: Invalid, 400: Invalid, 429: RateLimited}
+
+
+def from_response(status: int, body: Any, headers: dict) -> LangsatError:
+    detail = body.get("detail") if isinstance(body, dict) else body
+    code = headers.get("x-error-code")
+    if not code and isinstance(detail, dict):
+        code = detail.get("code")
+    if isinstance(detail, dict):
+        message = detail.get("message") or detail.get("code") or str(detail)
+    elif isinstance(detail, str):
+        message = detail
+    else:
+        message = f"HTTP {status}"
+    cls = _BY_CODE.get(code or "", None) or _BY_STATUS.get(status, LangsatError)
+    return cls(status, code, message, detail, headers)

langsat/jobs.py

@@ -0,0 +1,72 @@
+"""Every long action is a Job — `wait()` polls the one job shape (`GET /projects/{id}/jobs/{job_id}`)
+or, for the lanes that report through the project (clean / schema / train), `GET …/status`."""
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Optional
+
+from .errors import JobFailed, JobTimeout
+
+BUSY_PROJECT_STATES = ("cleaning", "detecting_schema", "training", "running", "pending", "queued")
+
+
+class Job:
+    def __init__(self, http, project_id: str, job_id: Optional[str], *, kind: str = "", result_route: Optional[str] = None,
+                 status: str = "queued", raw: Any = None):
+        self._http = http
+        self.project_id = project_id
+        self.job_id = job_id
+        self.kind = kind
+        self.status = status
+        self.result_route = result_route
+        self.raw = raw
+        self.record: dict = {}
+
+    def refresh(self) -> dict:
+        if self.job_id:
+            rec = self._http.get(f"/projects/{self.project_id}/jobs/{self.job_id}")
+        else:                                            # a project-status lane (clean / schema / train)
+            st = self._http.get(f"/projects/{self.project_id}/status")
+            ps = str(st.get("status") or "")
+            status = ("running" if ps in BUSY_PROJECT_STATES else
+                      "failed" if ps in ("error", "failed") else
+                      "cancelled" if ps == "cancelled" else "succeeded")
+            rec = {"job_id": None, "kind": self.kind, "status": status, "stage": st.get("progress_stage"),
+                   "progress_pct": st.get("progress_pct"), "error": ({"code": "job_failed", "message": st.get("error_message")} if status == "failed" else None),
+                   "result_route": f"/projects/{self.project_id}/status", "raw": st}
+        self.record = rec
+        self.status = rec.get("status", self.status)
+        self.result_route = rec.get("result_route") or self.result_route
+        return rec
+
+    @property
+    def done(self) -> bool:
+        return self.status in ("succeeded", "failed", "cancelled")
+
+    def wait(self, *, poll: float = 3.0, timeout: Optional[float] = None,
+             on_progress: Optional[Callable[[dict], None]] = None) -> "Job":
+        """Block until the job ends. Raises `JobFailed` on failure, `JobTimeout` after `timeout` s."""
+        t0 = time.monotonic()
+        while True:
+            rec = self.refresh()
+            if on_progress:
+                on_progress(rec)
+            if self.status == "succeeded":
+                return self
+            if self.status in ("failed", "cancelled"):
+                raise JobFailed(rec)
+            if timeout is not None and time.monotonic() - t0 > timeout:
+                raise JobTimeout(0, "job_timeout", f"{self.kind or 'job'} {self.job_id or ''} still {self.status} after {timeout}s", rec)
+            time.sleep(poll)
+
+    def result(self) -> Any:
+        """The lane's own rich result (a task config, a download_url, an answer) from `result_route`."""
+        if not self.result_route:
+            return self.record
+        path = self.result_route
+        if path.startswith("/api/v1"):
+            path = path[len("/api/v1"):]
+        return self._http.get(path)
+
+    def __repr__(self) -> str:
+        return f"Job(kind={self.kind!r}, id={self.job_id!r}, status={self.status!r})"

langsat/resources/_base.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class Resource:
+    def __init__(self, http, project_id: Optional[str] = None):
+        self._http = http
+        self.project_id = project_id
+
+    def _p(self, suffix: str = "") -> str:
+        return f"/projects/{self.project_id}{suffix}"
+
+
+def _clean(d: dict) -> dict:
+    """Drop None values so an omitted field stays 'not mentioned' on the wire."""
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def to_pandas(columns, rows):
+    """Rows + [{name,dtype}] columns → a DataFrame (pandas is an optional extra)."""
+    try:
+        import pandas as pd
+    except ImportError as e:  # pragma: no cover
+        raise ImportError("pip install 'langsat[pandas]' for to_pandas()") from e
+    names = [c["name"] if isinstance(c, dict) else c for c in (columns or [])]
+    return pd.DataFrame(rows or [], columns=names)
+
+
+Any_ = Any

langsat/resources/chat.py

@@ -0,0 +1,79 @@
+"""Ask the data — the same engine as the app's chat."""
+from __future__ import annotations
+
+import time
+from typing import Any, List, Optional
+
+from ..errors import JobFailed, JobTimeout
+from ._base import Resource, _clean
+
+
+class Answer:
+    def __init__(self, data: dict):
+        self.raw = data
+
+    @property
+    def text(self) -> str:
+        return self.raw.get("answer") or ""
+
+    @property
+    def chart_specs(self) -> List[dict]:
+        return self.raw.get("chart_specs") or []
+
+    @property
+    def execution_kind(self) -> Optional[str]:
+        return self.raw.get("execution_kind")
+
+    @property
+    def conversation_id(self) -> Optional[str]:
+        return self.raw.get("conversation_id")
+
+    def __repr__(self) -> str:
+        return f"Answer({self.text[:80]!r}, charts={len(self.chart_specs)}, via={self.execution_kind})"
+
+
+class Chat(Resource):
+    def ask(self, question: str, *, conversation_id: Optional[str] = None, force_chart: bool = False,
+            mode: str = "auto", poll: float = 2.0, timeout: Optional[float] = 600) -> Answer:
+        """1 AI question. Big projects answer asynchronously — this waits for the answer."""
+        out = self._http.post(self._p("/inference"), _clean({"question": question, "mode": mode,
+                                                             "conversation_id": conversation_id, "force_chart": force_chart}))
+        if out.get("status") == "processing" and out.get("inference_id"):
+            t0 = time.monotonic()
+            while True:
+                st = self._http.get(self._p(f"/inference/job/{out['inference_id']}"))
+                s = str(st.get("status", "")).upper()
+                if s == "COMPLETE" or ("answer" in st and s not in ("PROCESSING", "QUEUED")):
+                    return Answer(st)
+                if s == "FAILED":
+                    raise JobFailed({"job_id": out["inference_id"], "status": "failed", "error": {"code": "chat_failed", "message": st.get("error")}})
+                if timeout and time.monotonic() - t0 > timeout:
+                    raise JobTimeout(0, "job_timeout", "the answer did not arrive in time", st)
+                time.sleep(poll)
+        return Answer(out)
+
+    def conversations(self) -> list:
+        out = self._http.get(self._p("/conversations"))
+        return out.get("conversations", out) if isinstance(out, dict) else out
+
+    def new_conversation(self, title: Optional[str] = None) -> dict:
+        return self._http.post(self._p("/conversations"), _clean({"title": title}))
+
+    def history(self) -> Any:
+        return self._http.get(self._p("/inference/history"))
+
+    def clear_history(self) -> Any:
+        return self._http.delete(self._p("/inference/history"))
+
+    def suggestions(self) -> Any:
+        return self._http.get(self._p("/inference/suggestions"))
+
+    def explain_chart(self, chart_title: str, chart_summary: str, **context) -> dict:
+        return self._http.post(self._p("/inference/explain"), _clean({"chart_title": chart_title, "chart_summary": chart_summary, **context}))
+
+    def session(self) -> dict:
+        """The warm inference box for this project (Team; `{active:false}` on Lambda tiers)."""
+        return self._http.get(self._p("/inference/session"))
+
+    def end_session(self) -> dict:
+        return self._http.post(self._p("/inference/session/end"), {})