langsat 0.1.0__tar.gz

langsat-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: langsat
+Version: 0.1.0
+Summary: Langsat SDK — the same user, the same rights, the same prices, with no screen.
+Author-email: Langsat <team@langsat.ai>
+License: Proprietary
+Project-URL: Homepage, https://langsat.ai
+Project-URL: Documentation, https://langsat.ai/resources/learn/getting-started/sdk
+Project-URL: API contract, https://langsat.ai/sdk/langsat-v1.json
+Project-URL: Changelog, https://langsat.ai/resources/learn/getting-started/sdk#changelog
+Keywords: langsat,sdk,relational deep learning,analytics,dashboards,forecasting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == "pandas"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: pandas>=1.5; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+
+# Langsat SDK (Python)
+
+The same user, the same rights, the same prices — with no screen. Everything the Langsat web app
+does goes through the same REST API; this package wraps the public part of it.
+
+## Install
+
+```bash
+pip install langsat              # Python 3.9+
+pip install "langsat[pandas]"    # optional: .to_pandas()
+```
+
+## Login — the Hugging Face way
+
+1. In the web app: **Settings → API keys → Generate new key**. Pick its **permissions** (presets:
+   *Predict only*, *Read only*, *Full SDK*), optionally the projects it may touch and an expiry.
+   The key (`rdl_…`) is shown **once**.
+2. Then:
+
+```bash
+langsat login          # paste the key → verified → saved to ~/.langsat/token (0600)
+langsat whoami         # who it acts as, its scopes, its projects
+```
+
+or `export LANGSAT_API_KEY=rdl_…` (the environment wins over the saved file), or `Langsat(token="rdl_…")`.
+There is no password login: a script should never hold one, and a Google-SSO account has none.
+
+A key acts **as you**: your tier limits, credits, quotas and team role apply exactly as in the app.
+Billing, account changes and hand-written SQL are never available to a key (`NeedsUserSession`).
+
+## 15-minute quickstart
+
+```python
+from langsat import Langsat
+
+ls = Langsat()
+me = ls.me()                                     # tier, teams, the key's scopes
+
+p = ls.projects.create("churn-q3")               # data_analysis; kind="data_science" adds modeling
+p.sources.upload("orders.csv", "customers.csv")  # presign → S3 → confirm; the tier row cap applies
+p.schema.detect().wait()
+print(p.schema.result()["schema_data"]["foreign_keys"])      # orders.customer_id → customers
+
+print(p.estimates())                             # what clean / refresh / train / ask / report would cost
+p.cleaning.clean().wait()                        # ≤500K rows: 0 credits
+
+paid = p.table("orders").rows(filters=[("status", "eq", "paid")], sort=[("amount", "desc")], page_size=100)
+df = p.table("customers").to_pandas()
+
+tab = p.dashboards.create("Sales")
+chart = tab.add_chart({"tables": ["orders", "customers"], "chart_type": "bar",
+                       "group_by": [{"column": "region"}], "measure": {"agg": "sum", "column": "amount"},
+                       "joins": [{"table": "customers", "left_column": "customer_id", "right_column": "customer_id"}]},
+                      title="Amount by region")                 # deterministic, free, no AI
+tab.generate_cards()                                            # 6 AI charts (dashboard quota)
+view = tab.save_view("Paid only", {"filters": [{"column": "status", "op": "eq", "value": "paid"}]})
+link = tab.share(mode="published", view_id=view["view_id"])    # a frozen link; numbers follow refreshes
+
+a = p.ask("Which region's revenue fell most last month, and why?")   # 1 AI question
+print(a.text, a.chart_specs, a.execution_kind)
+tab.add_chart_spec(a.chart_specs[0])
+
+# the data-model workspace: Save is free and pending; Refresh applies and re-cleans at the lane price
+p.data_model.save_pending(foreign_keys={"orders": {"customer_id": "customers"}},
+                          cell_overrides=[{"table": "customers", "key_column": "customer_id",
+                                           "key_value": "1", "column": "segment", "value": "VIP"}])
+p.data_model.refresh().wait()
+
+# modeling (data_science projects)
+p.tasks.define("predict which customers churn in the next 30 days").wait()
+job = p.train(max_training_min=60).wait()        # credits reserved from the estimate
+model_id = p.models.list()[0]["model_id"]
+ls.predict.predict(model_id=model_id, entity_id=4711)                  # 50 credits
+ls.predict.forecast(project_id=p.id, target="amount", window="day", length=14)
+```
+
+## Conventions
+
+- **Jobs.** Long work returns a `Job`; `job.wait(poll=3, timeout=…)` raises `JobFailed` / `JobTimeout`.
+  `project.jobs()` lists recent jobs in one shape; `job.result()` fetches the lane's rich result.
+- **Money.** Nothing charges without an API call that the web app would also charge. Ask first:
+  `project.estimates()`. Set a monthly spend cap in Settings before letting a cron job train.
+- **Idempotency.** The replayable lanes (clean, refresh, train, generate-cards, report export,
+  predict, ask, add chart…) get an `Idempotency-Key` automatically: a retry after a timeout replays
+  the first response, it never re-runs or re-charges. Pass `idempotency_key=` to control it.
+- **Retries.** 429 (rate / quota) and 503 back off and retry; 409 *project busy* is raised unless you
+  pass `wait_if_busy=<seconds>`.
+- **Errors** are typed by the API's `X-Error-Code`: `AuthError`, `MissingScope` (`.scope`),
+  `NeedsUserSession`, `Forbidden`, `NotFound`, `InsufficientCredits`, `QuotaExceeded`, `RateLimited`,
+  `ProjectBusy`, `Conflict`, `RowCapExceeded`, `Invalid`, `Refused`, `JobFailed`, `JobTimeout`.
+- **Scopes** (what a key may do): `projects:read|write`, `sources:write`, `data:read|write`,
+  `dashboards:read|write`, `chat`, `train`, `predict`, `monitoring:read|write`, `hosting:write`
+  (owner/admin — a cost lever), `credits:read`, `teams:read`, `keys:read`.
+
+## Contract and versioning
+
+The public surface is the OpenAPI document at <https://langsat.ai/sdk/langsat-v1.json> (generated
+from the server, `x-scope` per operation). `/api/v1` is frozen for that set: fields are only added;
+a removal means `v2` with six months of `Deprecation` headers.
+
+## Docs and support
+
+Guide: <https://langsat.ai/resources/learn/getting-started/sdk> · questions: team@langsat.ai

langsat-0.1.0/README.md

@@ -0,0 +1,103 @@
+# Langsat SDK (Python)
+
+The same user, the same rights, the same prices — with no screen. Everything the Langsat web app
+does goes through the same REST API; this package wraps the public part of it.
+
+## Install
+
+```bash
+pip install langsat              # Python 3.9+
+pip install "langsat[pandas]"    # optional: .to_pandas()
+```
+
+## Login — the Hugging Face way
+
+1. In the web app: **Settings → API keys → Generate new key**. Pick its **permissions** (presets:
+   *Predict only*, *Read only*, *Full SDK*), optionally the projects it may touch and an expiry.
+   The key (`rdl_…`) is shown **once**.
+2. Then:
+
+```bash
+langsat login          # paste the key → verified → saved to ~/.langsat/token (0600)
+langsat whoami         # who it acts as, its scopes, its projects
+```
+
+or `export LANGSAT_API_KEY=rdl_…` (the environment wins over the saved file), or `Langsat(token="rdl_…")`.
+There is no password login: a script should never hold one, and a Google-SSO account has none.
+
+A key acts **as you**: your tier limits, credits, quotas and team role apply exactly as in the app.
+Billing, account changes and hand-written SQL are never available to a key (`NeedsUserSession`).
+
+## 15-minute quickstart
+
+```python
+from langsat import Langsat
+
+ls = Langsat()
+me = ls.me()                                     # tier, teams, the key's scopes
+
+p = ls.projects.create("churn-q3")               # data_analysis; kind="data_science" adds modeling
+p.sources.upload("orders.csv", "customers.csv")  # presign → S3 → confirm; the tier row cap applies
+p.schema.detect().wait()
+print(p.schema.result()["schema_data"]["foreign_keys"])      # orders.customer_id → customers
+
+print(p.estimates())                             # what clean / refresh / train / ask / report would cost
+p.cleaning.clean().wait()                        # ≤500K rows: 0 credits
+
+paid = p.table("orders").rows(filters=[("status", "eq", "paid")], sort=[("amount", "desc")], page_size=100)
+df = p.table("customers").to_pandas()
+
+tab = p.dashboards.create("Sales")
+chart = tab.add_chart({"tables": ["orders", "customers"], "chart_type": "bar",
+                       "group_by": [{"column": "region"}], "measure": {"agg": "sum", "column": "amount"},
+                       "joins": [{"table": "customers", "left_column": "customer_id", "right_column": "customer_id"}]},
+                      title="Amount by region")                 # deterministic, free, no AI
+tab.generate_cards()                                            # 6 AI charts (dashboard quota)
+view = tab.save_view("Paid only", {"filters": [{"column": "status", "op": "eq", "value": "paid"}]})
+link = tab.share(mode="published", view_id=view["view_id"])    # a frozen link; numbers follow refreshes
+
+a = p.ask("Which region's revenue fell most last month, and why?")   # 1 AI question
+print(a.text, a.chart_specs, a.execution_kind)
+tab.add_chart_spec(a.chart_specs[0])
+
+# the data-model workspace: Save is free and pending; Refresh applies and re-cleans at the lane price
+p.data_model.save_pending(foreign_keys={"orders": {"customer_id": "customers"}},
+                          cell_overrides=[{"table": "customers", "key_column": "customer_id",
+                                           "key_value": "1", "column": "segment", "value": "VIP"}])
+p.data_model.refresh().wait()
+
+# modeling (data_science projects)
+p.tasks.define("predict which customers churn in the next 30 days").wait()
+job = p.train(max_training_min=60).wait()        # credits reserved from the estimate
+model_id = p.models.list()[0]["model_id"]
+ls.predict.predict(model_id=model_id, entity_id=4711)                  # 50 credits
+ls.predict.forecast(project_id=p.id, target="amount", window="day", length=14)
+```
+
+## Conventions
+
+- **Jobs.** Long work returns a `Job`; `job.wait(poll=3, timeout=…)` raises `JobFailed` / `JobTimeout`.
+  `project.jobs()` lists recent jobs in one shape; `job.result()` fetches the lane's rich result.
+- **Money.** Nothing charges without an API call that the web app would also charge. Ask first:
+  `project.estimates()`. Set a monthly spend cap in Settings before letting a cron job train.
+- **Idempotency.** The replayable lanes (clean, refresh, train, generate-cards, report export,
+  predict, ask, add chart…) get an `Idempotency-Key` automatically: a retry after a timeout replays
+  the first response, it never re-runs or re-charges. Pass `idempotency_key=` to control it.
+- **Retries.** 429 (rate / quota) and 503 back off and retry; 409 *project busy* is raised unless you
+  pass `wait_if_busy=<seconds>`.
+- **Errors** are typed by the API's `X-Error-Code`: `AuthError`, `MissingScope` (`.scope`),
+  `NeedsUserSession`, `Forbidden`, `NotFound`, `InsufficientCredits`, `QuotaExceeded`, `RateLimited`,
+  `ProjectBusy`, `Conflict`, `RowCapExceeded`, `Invalid`, `Refused`, `JobFailed`, `JobTimeout`.
+- **Scopes** (what a key may do): `projects:read|write`, `sources:write`, `data:read|write`,
+  `dashboards:read|write`, `chat`, `train`, `predict`, `monitoring:read|write`, `hosting:write`
+  (owner/admin — a cost lever), `credits:read`, `teams:read`, `keys:read`.
+
+## Contract and versioning
+
+The public surface is the OpenAPI document at <https://langsat.ai/sdk/langsat-v1.json> (generated
+from the server, `x-scope` per operation). `/api/v1` is frozen for that set: fields are only added;
+a removal means `v2` with six months of `Deprecation` headers.
+
+## Docs and support
+
+Guide: <https://langsat.ai/resources/learn/getting-started/sdk> · questions: team@langsat.ai

langsat-0.1.0/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-0.1.0/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-0.1.0/langsat/_version.py

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

langsat-0.1.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-0.1.0/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-0.1.0/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()