honeyframeapi 0.1.0__py3-none-any.whl

honeyframeapi/__init__.py

@@ -0,0 +1,63 @@
+"""honeyframeapi — a ``dataikuapi``-style Python client for the Honeyframe platform.
+
+    import honeyframeapi
+    client = honeyframeapi.HoneyframeClient(
+        "https://platform.hubstudio.id",
+        username="you@hubstudio.id", password="…", project_id=1)
+
+    df   = client.sql("SELECT * FROM marts.fact_appointment FETCH FIRST 100 ROWS ONLY")
+    proj = client.get_project(1)
+    df2  = proj.get_dataset("fact_appointment").get_dataframe()
+
+    dash = proj.create_dashboard("Ops Overview")
+    dash.add_card("Total Visits", "kpi", "SELECT COUNT(*) AS n FROM marts.fact_appointment")
+    dash.execute_all()
+"""
+from .client import HoneyframeClient
+from .project import Project
+from .dataset import Dataset
+from .dashboard import Dashboard, Card
+from .connector import Connector
+from .scenario import Scenario
+from .recipe import Recipe
+from .pipeline import JobsAPI
+from .publishing import PublishedAsset, ApiKey
+from .webapp import Webapp
+from .agent import Agent
+from .auth import AuthBase, LoginAuth, TokenAuth
+from .exceptions import (
+    HoneyframeError,
+    HoneyframeConfigError,
+    HoneyframeAPIError,
+    HoneyframeAuthError,
+    HoneyframeNotFoundError,
+    HoneyframeValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HoneyframeClient",
+    "Project",
+    "Dataset",
+    "Dashboard",
+    "Card",
+    "Connector",
+    "Scenario",
+    "Recipe",
+    "JobsAPI",
+    "PublishedAsset",
+    "ApiKey",
+    "Webapp",
+    "Agent",
+    "AuthBase",
+    "LoginAuth",
+    "TokenAuth",
+    "HoneyframeError",
+    "HoneyframeConfigError",
+    "HoneyframeAPIError",
+    "HoneyframeAuthError",
+    "HoneyframeNotFoundError",
+    "HoneyframeValidationError",
+    "__version__",
+]

honeyframeapi/_compat.py

@@ -0,0 +1,20 @@
+"""Optional-pandas plumbing.
+
+The core SDK has no hard pandas dependency. Helpers here return a DataFrame
+when pandas is importable, and otherwise fall back to a plain dict so scripts
+that only need raw rows still work on a bare install.
+"""
+from __future__ import annotations
+
+try:
+    import pandas as _pd  # noqa: F401
+    HAS_PANDAS = True
+except Exception:  # pragma: no cover - exercised only on bare installs
+    HAS_PANDAS = False
+
+
+def rows_to_dataframe(columns, rows):
+    """Build a DataFrame from columns + positional rows, or a dict fallback."""
+    if HAS_PANDAS:
+        return _pd.DataFrame(rows, columns=columns)
+    return {"columns": columns, "rows": rows}

honeyframeapi/_sql.py

@@ -0,0 +1,143 @@
+"""Ad-hoc SQL execution → DataFrame.
+
+Two execution paths, tried in order:
+
+1. **Native** ``POST /api/sql`` — the first-class governed query endpoint
+   (services/query_executor). This is the preferred path: one request, full
+   result set, project-scoped, SELECT-guarded.
+2. **Scratch-card fallback** — on deployments that predate ``/api/sql`` (the
+   endpoint 404s), fall back to executing the SQL through a hidden per-project
+   scratch dashboard card. Same result shape, zero backend dependency, so the
+   SDK keeps working against older servers.
+
+Both return a pandas DataFrame (or a ``{columns, rows}`` dict on a bare,
+pandas-less install).
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ._compat import rows_to_dataframe
+from .exceptions import HoneyframeAPIError, HoneyframeAuthError, HoneyframeNotFoundError
+
+SCRATCH_TITLE = "__honeyframe_sdk_scratch__"
+
+
+def sql_to_dataframe(project, query: str, *, connector_id: Optional[int] = None,
+                     row_limit: int = 10000):
+    """Execute ``query`` and return a DataFrame, preferring POST /api/sql."""
+    try:
+        res = project._req("POST", "/api/sql", json={
+            "sql": query,
+            "connector_id": connector_id,
+            "row_limit": row_limit,
+        })
+    except HoneyframeNotFoundError:
+        # Endpoint not on this deployment yet — use the scratch-card path.
+        return _scratch_card_sql(project, query, connector_id=connector_id, row_limit=row_limit)
+
+    if res.get("error"):
+        raise HoneyframeAPIError(422, res["error"], method="POST", url="/api/sql")
+    columns = res.get("columns", [])
+    dict_rows = res.get("rows", [])
+    rows = [[r.get(c) for c in columns] for r in dict_rows]
+    return rows_to_dataframe(columns, rows)
+
+
+# ── scratch-card fallback ─────────────────────────────────────────────────────
+def _ensure_scratch_dashboard(project) -> tuple[int, bool]:
+    """Return ``(dashboard_id, created_now)`` for this project's scratch dashboard.
+
+    ``created_now`` is True only when this call had to POST a new dashboard, so
+    the caller knows whether it owns the dashboard and must clean it up if the
+    query then fails (otherwise a failed query would leave an orphan scratch
+    dashboard behind — the leak this hardening fixes)."""
+    cached = getattr(project, "_scratch_dashboard_id", None)
+    if cached is not None:
+        return cached, False
+
+    for d in project.list_dashboards():
+        if d.get("title") == SCRATCH_TITLE:
+            project._scratch_dashboard_id = d["dashboard_id"]
+            return project._scratch_dashboard_id, False
+
+    res = project._req("POST", "/api/dashboards", json={
+        "title": SCRATCH_TITLE,
+        "description": "Auto-created by honeyframeapi for ad-hoc SQL. Safe to ignore.",
+        "is_public": False,
+    })
+    project._scratch_dashboard_id = res["dashboard_id"]
+    return project._scratch_dashboard_id, True
+
+
+def _scratch_card_sql(project, query: str, *, connector_id: Optional[int] = None,
+                      row_limit: int = 10000):
+    """Execute ``query`` via a temporary scratch dashboard card.
+
+    Cleanup is total: the temp card is always deleted, and if THIS call created
+    the scratch dashboard, that dashboard is deleted too on any failure (so an
+    under-privileged caller whose query 500s doesn't leave an orphan behind).
+    Auth failures surface as :class:`HoneyframeAuthError` with a hint that
+    ad-hoc SQL needs ``project.edit``."""
+    dash_id, created_dash = _ensure_scratch_dashboard(project)
+    card_id = None
+
+    def _cleanup():
+        if card_id is not None:
+            try:
+                project._req("DELETE", f"/api/dashboards/{dash_id}/cards/{card_id}")
+            except Exception:
+                pass
+
+    def _drop_owned_dashboard():
+        # Only delete the dashboard if we created it this call — never nuke a
+        # pre-existing/shared scratch dashboard out from under a concurrent caller.
+        if created_dash:
+            try:
+                project._req("DELETE", f"/api/dashboards/{dash_id}")
+            except Exception:
+                pass
+            project._scratch_dashboard_id = None
+
+    try:
+        card_config = {}
+        if connector_id is not None:
+            card_config["connector_id"] = connector_id
+
+        card = project._req("POST", f"/api/dashboards/{dash_id}/cards", json={
+            "title": "sdk_query",
+            "card_type": "table",
+            "sql_query": query,
+            "card_config": card_config,
+            "size_x": 24,
+            "size_y": 6,
+        })
+        card_id = card.get("card_id")
+
+        res = project._req(
+            "POST", f"/api/dashboards/{dash_id}/cards/{card_id}/execute", json={},
+        )
+        if res.get("error"):
+            raise HoneyframeAPIError(422, res["error"], method="POST",
+                                     url=f"/api/dashboards/{dash_id}/cards/{card_id}/execute")
+        columns = res.get("columns", [])
+        dict_rows = res.get("rows", [])
+        rows = [[r.get(c) for c in columns] for r in dict_rows]
+        if row_limit is not None:
+            rows = rows[:row_limit]
+        result = rows_to_dataframe(columns, rows)
+        _cleanup()
+        return result
+    except HoneyframeAuthError as e:
+        _cleanup()
+        _drop_owned_dashboard()
+        # Re-raise with a clearer hint than a bare 403.
+        raise HoneyframeAuthError(
+            e.status_code,
+            f"{e.detail} — ad-hoc SQL needs project.edit on this project",
+            method=e.method, url=e.url, response=e.response,
+        ) from None
+    except Exception:
+        _cleanup()
+        _drop_owned_dashboard()
+        raise

honeyframeapi/agent.py

@@ -0,0 +1,49 @@
+"""Agent handle — chat with / run a Honeyframe agent from code.
+
+    agent = client.get_agent(agent_id=42)
+    reply = agent.ask("How many appointments were cancelled last month?")
+    print(reply["answer"])
+
+    # multi-turn: reuse the returned session_id
+    r1 = agent.ask("Top 5 hospitals by volume?")
+    r2 = agent.ask("…and their cancellation rate?", session_id=r1["session_id"])
+
+The platform exposes the agent library at ``GET /api/agents/library`` and
+invokes agents through ``POST /api/chat`` (JWT auth), where ``agent_id`` selects
+a published agent's tools/config.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+
+class Agent:
+    def __init__(self, client, agent_id: int, *, project=None, _data: Optional[dict] = None):
+        self.client = client
+        self.agent_id = agent_id
+        self.project = project
+        self._data = _data or {}
+
+    def __repr__(self) -> str:
+        return f"<Agent id={self.agent_id} {self._data.get('title')!r}>"
+
+    @property
+    def title(self) -> str:
+        return self._data["title"]
+
+    def _req(self, method, path, **kw):
+        if self.project is not None:
+            kw.setdefault("project_id", self.project.project_id)
+        return self.client._request(method, path, **kw)
+
+    def ask(self, message: str, *, session_id: Optional[int] = None,
+            model: Optional[str] = None) -> dict:
+        """Send a message to this agent. Returns the chat response dict
+        (``answer``, ``session_id``, ``sql``, ``rows``, ``follow_ups``, …).
+        Pass ``session_id`` from a prior reply to continue the conversation."""
+        body = {"message": message, "agent_id": self.agent_id}
+        if session_id is not None:
+            body["session_id"] = session_id
+        if model is not None:
+            body["model"] = model
+        return self._req("POST", "/api/chat", json=body)

honeyframeapi/auth.py

@@ -0,0 +1,141 @@
+"""Authentication strategies for the Honeyframe SDK.
+
+Two strategies ship today, both injected into :class:`~honeyframeapi.client.HoneyframeClient`:
+
+* :class:`LoginAuth` — email/password. Exchanges credentials for a short-lived
+  (8h) JWT via ``POST /api/auth/login`` and transparently re-logs-in when the
+  token is rejected with a 401. This is the path that works against any
+  Honeyframe deployment **today**, with zero backend changes.
+* :class:`TokenAuth` — a pre-minted bearer token (a JWT you already have, or a
+  future long-lived control-plane Personal Access Token). No auto-refresh: a
+  401 surfaces to the caller.
+
+The client calls :meth:`AuthBase.token` before every request to obtain the
+current bearer string, and :meth:`AuthBase.refresh` once on a 401 before
+retrying. An auth strategy that cannot refresh returns ``False`` so the client
+stops retrying and raises.
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import httpx
+
+from .exceptions import HoneyframeAuthError, HoneyframeConfigError
+
+
+class AuthBase:
+    """Interface every auth strategy implements."""
+
+    def token(self, http: httpx.Client) -> str:
+        """Return the current bearer token, acquiring one if needed."""
+        raise NotImplementedError
+
+    def refresh(self, http: httpx.Client) -> bool:
+        """Force-acquire a new token after a 401.
+
+        Returns ``True`` if a fresh token was obtained (caller should retry),
+        ``False`` if this strategy cannot refresh (caller should raise).
+        """
+        return False
+
+
+class TokenAuth(AuthBase):
+    """Authenticate with a token you already hold (JWT or future PAT)."""
+
+    def __init__(self, token: str):
+        if not token:
+            raise HoneyframeConfigError("TokenAuth requires a non-empty token")
+        self._token = token
+
+    def token(self, http: httpx.Client) -> str:
+        return self._token
+
+    # No refresh — a static token that 401s is a hard error.
+
+
+class LoginAuth(AuthBase):
+    """Authenticate with email + password, caching the JWT and re-logging-in on 401."""
+
+    def __init__(self, username: str, password: str, *, login_path: str = "/api/auth/login"):
+        if not username or not password:
+            raise HoneyframeConfigError("LoginAuth requires username and password")
+        self.username = username
+        self.password = password
+        self.login_path = login_path
+        self._token: Optional[str] = None
+        self.must_reset_password: bool = False
+
+    def token(self, http: httpx.Client) -> str:
+        if self._token is None:
+            self._login(http)
+        return self._token  # type: ignore[return-value]
+
+    def refresh(self, http: httpx.Client) -> bool:
+        self._token = None
+        self._login(http)
+        return True
+
+    def _login(self, http: httpx.Client) -> None:
+        resp = http.post(self.login_path, json={
+            "username": self.username,
+            "password": self.password,
+        })
+        if resp.status_code != 200:
+            detail = _safe_detail(resp)
+            raise HoneyframeAuthError(
+                resp.status_code, detail,
+                method="POST", url=str(resp.request.url), response=resp,
+            )
+        body = resp.json()
+        self._token = body.get("access_token")
+        self.must_reset_password = bool(body.get("must_reset_password", False))
+        if not self._token:
+            raise HoneyframeAuthError(
+                resp.status_code, "login succeeded but no access_token in response",
+                method="POST", url=str(resp.request.url), response=resp,
+            )
+
+
+def auth_from_kwargs(
+    *,
+    token: Optional[str] = None,
+    username: Optional[str] = None,
+    password: Optional[str] = None,
+    auth: Optional[AuthBase] = None,
+) -> AuthBase:
+    """Resolve the auth strategy from the assorted client kwargs.
+
+    Precedence: explicit ``auth`` object > ``token`` > ``username``/``password``
+    > environment variables (``HONEYFRAME_TOKEN`` then
+    ``HONEYFRAME_USERNAME``/``HONEYFRAME_PASSWORD``, with ``HUB_*`` fallbacks
+    for continuity with existing dwh-adira .env files).
+    """
+    if auth is not None:
+        return auth
+    if token:
+        return TokenAuth(token)
+    if username and password:
+        return LoginAuth(username, password)
+
+    env_token = os.environ.get("HONEYFRAME_TOKEN")
+    if env_token:
+        return TokenAuth(env_token)
+
+    env_user = os.environ.get("HONEYFRAME_USERNAME") or os.environ.get("HUB_USERNAME")
+    env_pass = os.environ.get("HONEYFRAME_PASSWORD") or os.environ.get("HUB_PASSWORD")
+    if env_user and env_pass:
+        return LoginAuth(env_user, env_pass)
+
+    raise HoneyframeConfigError(
+        "No credentials. Pass token=..., username=/password=, or an auth= "
+        "strategy, or set HONEYFRAME_TOKEN / HONEYFRAME_USERNAME+PASSWORD."
+    )
+
+
+def _safe_detail(resp: httpx.Response):
+    try:
+        return resp.json().get("detail", resp.text)
+    except Exception:
+        return resp.text

honeyframeapi/cli.py

@@ -0,0 +1,218 @@
+"""``honeyframe`` — a thin CLI over the SDK for shell use.
+
+Reads connection + credentials from the environment (same vars as
+``HoneyframeClient.from_env``): ``HONEYFRAME_URL`` (or ``HUB_API_BASE``),
+``HONEYFRAME_TOKEN`` (a JWT or ``hf_…`` PAT), or
+``HONEYFRAME_USERNAME``/``HONEYFRAME_PASSWORD``, plus optional
+``HONEYFRAME_ORG_ID`` / ``HONEYFRAME_PROJECT_ID``. Flags override env.
+
+Examples
+--------
+    export HONEYFRAME_URL=https://platform.hubstudio.id
+    export HONEYFRAME_TOKEN=hf_…
+    honeyframe whoami
+    honeyframe projects
+    honeyframe datasets -p 1
+    honeyframe sql "SELECT COUNT(*) FROM marts.fact_appointment" -p 1 -f csv
+    honeyframe pat create --name laptop --expires-days 90
+    honeyframe scenario run daily_pipeline -p 1 --wait
+
+Flags go after the subcommand (kubectl/gh style): `honeyframe <cmd> [flags]`.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import os
+import sys
+
+from . import HoneyframeClient, __version__
+from .exceptions import HoneyframeError
+
+
+def _client(args) -> HoneyframeClient:
+    kw = {}
+    if args.url:
+        kw["base_url"] = args.url
+    if args.token:
+        kw["token"] = args.token
+    if args.org is not None:
+        kw["org_id"] = args.org
+    if args.project is not None:
+        kw["project_id"] = args.project
+    return HoneyframeClient.from_env(**kw)
+
+
+def _emit(obj, fmt: str) -> None:
+    """Print a result as json (default) or csv (for row lists / DataFrames)."""
+    if fmt == "json":
+        print(json.dumps(obj, indent=2, default=str))
+        return
+    # csv: accept a DataFrame, a {columns,rows} dict, or a list of dicts
+    rows, cols = None, None
+    if hasattr(obj, "to_csv"):  # pandas DataFrame
+        sys.stdout.write(obj.to_csv(index=False))
+        return
+    if isinstance(obj, dict) and "columns" in obj and "rows" in obj:
+        cols, rows = obj["columns"], obj["rows"]
+        w = csv.writer(sys.stdout)
+        w.writerow(cols)
+        w.writerows(rows)
+        return
+    if isinstance(obj, list) and obj and isinstance(obj[0], dict):
+        cols = list(obj[0].keys())
+        dw = csv.DictWriter(sys.stdout, fieldnames=cols)
+        dw.writeheader()
+        dw.writerows(obj)
+        return
+    print(json.dumps(obj, indent=2, default=str))
+
+
+# ── command handlers ─────────────────────────────────────────────────────────
+def cmd_whoami(c, args):
+    return c.get_auth_info()
+
+
+def cmd_version(c, args):
+    return c.get_instance_info()
+
+
+def cmd_projects(c, args):
+    return c.list_projects()
+
+
+def cmd_datasets(c, args):
+    return c.list_datasets()
+
+
+def cmd_sql(c, args):
+    df = c.sql(args.query)
+    return df
+
+
+def cmd_pat_create(c, args):
+    return c.create_pat(args.name or "", expires_days=args.expires_days)
+
+
+def cmd_pat_list(c, args):
+    return c.list_pats()
+
+
+def cmd_pat_revoke(c, args):
+    return c.revoke_pat(args.id)
+
+
+def cmd_scenario_list(c, args):
+    return c.get_project(c.project_id).list_scenarios()
+
+
+def cmd_scenario_run(c, args):
+    sc = c.get_project(c.project_id).get_scenario(args.name)
+    return sc.run_and_wait() if args.wait else sc.run()
+
+
+def cmd_engine(c, args):
+    proj = c.get_project(c.project_id)
+    return {"engine": proj.engine(), "uses_dbt": proj.uses_dbt()}
+
+
+def cmd_lineage(c, args):
+    ds = c.get_project(c.project_id).get_dataset(args.dataset)
+    return ds.downstream() if args.down else ds.upstream()
+
+
+def cmd_upload(c, args):
+    ds = c.get_project(c.project_id).upload_file(
+        args.name, args.file, replace=args.replace, materialize=args.materialize,
+    )
+    return {"uploaded": ds.name, "materialized": args.materialize}
+
+
+def cmd_export(c, args):
+    ds = c.get_project(c.project_id).get_dataset(args.dataset)
+    path = str(args.path)
+    out = (ds.to_parquet(path, max_rows=args.max_rows)
+           if path.lower().endswith(".parquet")
+           else ds.to_csv(path, max_rows=args.max_rows))
+    return {"exported": out}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    # Connection + output flags live on a shared parent attached to every
+    # (leaf) subparser, so they go AFTER the subcommand — the kubectl/gh/docker
+    # convention (`honeyframe projects -f csv`, `honeyframe sql "…" -p 1`).
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--url", default=None, help="base URL (or $HONEYFRAME_URL)")
+    common.add_argument("--token", default=None, help="JWT or hf_ PAT (or $HONEYFRAME_TOKEN)")
+    common.add_argument("-o", "--org", type=int, default=None, help="org id (X-Org-Id)")
+    common.add_argument("-p", "--project", type=int, default=None, help="project id (X-Project-Id)")
+    common.add_argument("-f", "--format", choices=["json", "csv"], default="json", help="output format")
+
+    p = argparse.ArgumentParser(prog="honeyframe", description="Honeyframe platform CLI")
+    p.add_argument("--version", action="version", version=f"honeyframeapi {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def add(name, fn, **kw):
+        sp = sub.add_parser(name, parents=[common], **kw)
+        sp.set_defaults(fn=fn)
+        return sp
+
+    add("whoami", cmd_whoami, help="current user")
+    add("version", cmd_version, help="platform version")
+    add("projects", cmd_projects, help="list projects")
+    add("datasets", cmd_datasets, help="list datasets in --project")
+    add("sql", cmd_sql, help="run ad-hoc SQL in --project").add_argument("query")
+    add("engine", cmd_engine, help="show the catalog engine (dbt|native) for --project")
+
+    lin = add("lineage", cmd_lineage, help="upstream (or --down) lineage of a dataset")
+    lin.add_argument("dataset")
+    lin.add_argument("--down", action="store_true", help="downstream dependents instead of upstream")
+
+    up = add("upload", cmd_upload, help="upload a local .csv/.xlsx as a dataset in --project")
+    up.add_argument("name")
+    up.add_argument("file")
+    up.add_argument("--replace", action="store_true", help="overwrite if it already exists")
+    up.add_argument("--materialize", action="store_true", help="materialize after upload")
+
+    exp = add("export", cmd_export, help="export a dataset to a local .csv/.parquet file")
+    exp.add_argument("dataset")
+    exp.add_argument("path")
+    exp.add_argument("--max-rows", type=int, default=None, help="cap the number of rows pulled")
+
+    pat = sub.add_parser("pat", help="personal access tokens").add_subparsers(dest="pat_cmd", required=True)
+    pc = pat.add_parser("create", parents=[common], help="mint a token")
+    pc.add_argument("--name", default="")
+    pc.add_argument("--expires-days", type=int, default=None)
+    pc.set_defaults(fn=cmd_pat_create)
+    pat.add_parser("list", parents=[common], help="list tokens").set_defaults(fn=cmd_pat_list)
+    pr = pat.add_parser("revoke", parents=[common], help="revoke a token")
+    pr.add_argument("id", type=int)
+    pr.set_defaults(fn=cmd_pat_revoke)
+
+    scn = sub.add_parser("scenario", help="scenarios").add_subparsers(dest="scn_cmd", required=True)
+    scn.add_parser("list", parents=[common], help="list scenarios in --project").set_defaults(fn=cmd_scenario_list)
+    sr = scn.add_parser("run", parents=[common], help="run a scenario by id/name")
+    sr.add_argument("name")
+    sr.add_argument("--wait", action="store_true", help="block until the run finishes")
+    sr.set_defaults(fn=cmd_scenario_run)
+
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        c = _client(args)
+        result = args.fn(c, args)
+        _emit(result, args.format)
+        return 0
+    except HoneyframeError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())