hotdata-runtime 0.1.0__py3-none-any.whl

hotdata_runtime/__init__.py

@@ -0,0 +1,47 @@
+"""Hotdata runtime primitives for notebook and app integrations."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from hotdata_runtime.client import (
+    HotdataClient,
+    ResultSummary,
+    RunHistoryItem,
+    from_env,
+)
+from hotdata_runtime.env import (
+    default_api_key,
+    default_host,
+    default_session_id,
+    explicit_workspace_id,
+    list_workspaces,
+    normalize_host,
+    pick_workspace,
+    resolve_workspace_selection,
+    WorkspaceSelection,
+)
+from hotdata_runtime.health import workspace_health_lines
+from hotdata_runtime.result import QueryResult
+
+try:
+    __version__ = version("hotdata-runtime")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "__version__",
+    "HotdataClient",
+    "QueryResult",
+    "workspace_health_lines",
+    "default_api_key",
+    "default_host",
+    "default_session_id",
+    "explicit_workspace_id",
+    "from_env",
+    "list_workspaces",
+    "normalize_host",
+    "pick_workspace",
+    "resolve_workspace_selection",
+    "ResultSummary",
+    "RunHistoryItem",
+    "WorkspaceSelection",
+]

hotdata_runtime/client.py

@@ -0,0 +1,341 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import time
+from typing import Any, Iterator
+
+from urllib3.exceptions import HTTPError as Urllib3HTTPError
+from urllib3.exceptions import ProtocolError
+
+from hotdata import ApiClient, Configuration
+from hotdata.api.connections_api import ConnectionsApi
+from hotdata.api.information_schema_api import InformationSchemaApi
+from hotdata.api.query_api import QueryApi
+from hotdata.api.query_runs_api import QueryRunsApi
+from hotdata.api.results_api import ResultsApi
+from hotdata.exceptions import ApiException
+from hotdata.models.async_query_response import AsyncQueryResponse
+from hotdata.models.query_request import QueryRequest
+from hotdata.models.query_response import QueryResponse
+from hotdata.models.table_info import TableInfo
+
+from hotdata_runtime.env import (
+    default_api_key,
+    default_host,
+    default_session_id,
+    normalize_host,
+    pick_workspace,
+)
+from hotdata_runtime.http import default_http_retries
+from hotdata_runtime.result import QueryResult
+
+_TERMINAL = frozenset({"succeeded", "failed", "cancelled"})
+_RESULT_FAILURE = frozenset({"failed", "cancelled"})
+
+
+@dataclass(frozen=True)
+class ResultSummary:
+    result_id: str
+    status: str
+    created_at: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class RunHistoryItem:
+    query_run_id: str
+    status: str
+    created_at: str | None
+    execution_time_ms: int | None
+    result_id: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class HotdataClient:
+    """Thin wrapper around the Hotdata Python SDK with query polling helpers."""
+
+    def __init__(
+        self,
+        api_key: str,
+        workspace_id: str,
+        *,
+        host: str | None = None,
+        session_id: str | None = None,
+    ) -> None:
+        self._host = normalize_host(host) if host else default_host()
+        self._api_key = api_key
+        self._workspace_id = workspace_id
+        self._session_id = session_id
+        self._config = Configuration(
+            host=self._host,
+            api_key=api_key,
+            workspace_id=workspace_id,
+            session_id=session_id,
+            retries=default_http_retries(),
+        )
+        self._api = ApiClient(self._config)
+
+    @classmethod
+    def from_env(cls) -> HotdataClient:
+        api_key = default_api_key()
+        if not api_key:
+            raise RuntimeError("HOTDATA_API_KEY must be set.")
+        host = default_host()
+        session = default_session_id()
+        workspace_id = pick_workspace(api_key, host, session)
+        return cls(api_key, workspace_id, host=host, session_id=session)
+
+    @property
+    def workspace_id(self) -> str:
+        return self._workspace_id
+
+    @property
+    def host(self) -> str:
+        return self._host
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session_id
+
+    @property
+    def api(self) -> ApiClient:
+        return self._api
+
+    def close(self) -> None:
+        self._api.close()
+
+    def __enter__(self) -> HotdataClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def connections(self) -> ConnectionsApi:
+        return ConnectionsApi(self._api)
+
+    def _information_schema(self) -> InformationSchemaApi:
+        return InformationSchemaApi(self._api)
+
+    def _query_api(self) -> QueryApi:
+        return QueryApi(self._api)
+
+    def _query_runs_api(self) -> QueryRunsApi:
+        return QueryRunsApi(self._api)
+
+    def _results_api(self) -> ResultsApi:
+        return ResultsApi(self._api)
+
+    def query_runs(self) -> QueryRunsApi:
+        return self._query_runs_api()
+
+    def results(self) -> ResultsApi:
+        return self._results_api()
+
+    def list_recent_results(
+        self,
+        *,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ResultSummary]:
+        listing = self.results().list_results(limit=limit, offset=offset)
+        return [
+            ResultSummary(
+                result_id=r.id,
+                status=r.status,
+                created_at=r.created_at,
+            )
+            for r in listing.results
+        ]
+
+    def list_run_history(
+        self,
+        *,
+        limit: int = 20,
+    ) -> list[RunHistoryItem]:
+        listing = self.query_runs().list_query_runs(limit=limit)
+        return [
+            RunHistoryItem(
+                query_run_id=r.id,
+                status=r.status,
+                created_at=r.created_at,
+                execution_time_ms=r.execution_time_ms,
+                result_id=r.result_id,
+            )
+            for r in listing.query_runs
+        ]
+
+    def iter_tables(
+        self,
+        *,
+        connection_id: str | None = None,
+        include_columns: bool = False,
+        page_size: int = 200,
+    ) -> Iterator[TableInfo]:
+        cursor: str | None = None
+        while True:
+            resp = self._information_schema().information_schema(
+                connection_id=connection_id,
+                include_columns=include_columns,
+                limit=page_size,
+                cursor=cursor,
+            )
+            yield from resp.tables
+            if not resp.has_more or not resp.next_cursor:
+                break
+            cursor = resp.next_cursor
+
+    def qualified_table_name(self, t: TableInfo) -> str:
+        return f"{t.connection}.{t.var_schema}.{t.table}"
+
+    def list_qualified_table_names(
+        self, *, limit: int = 5000, connection_id: str | None = None
+    ) -> list[str]:
+        out: list[str] = []
+        for t in self.iter_tables(connection_id=connection_id):
+            out.append(self.qualified_table_name(t))
+            if len(out) >= limit:
+                break
+        return sorted(out)
+
+    def connection_id_by_name(self) -> dict[str, str]:
+        listing = self.connections().list_connections()
+        id_map: dict[str, str] = {}
+        duplicate_names: set[str] = set()
+        for c in listing.connections:
+            if c.name in id_map and id_map[c.name] != c.id:
+                duplicate_names.add(c.name)
+            id_map[c.name] = c.id
+        if duplicate_names:
+            names = ", ".join(sorted(duplicate_names))
+            raise RuntimeError(
+                f"Duplicate connection names found: {names}. "
+                "Use an explicit connection_id."
+            )
+        return id_map
+
+    def columns_for_qualified(
+        self,
+        qualified: str,
+        *,
+        connection_id: str | None = None,
+    ) -> list[TableInfo]:
+        parts = qualified.split(".")
+        if len(parts) < 3:
+            raise ValueError(
+                f"Expected connection.schema.table, got {qualified!r}"
+            )
+        conn_name, schema_name, table_name = (
+            parts[0],
+            parts[1],
+            ".".join(parts[2:]),
+        )
+        conn_id = connection_id
+        if conn_id is None:
+            id_map = self.connection_id_by_name()
+            conn_id = id_map.get(conn_name)
+            if not conn_id:
+                raise KeyError(f"Unknown connection {conn_name!r}")
+        resp = self._information_schema().information_schema(
+            connection_id=conn_id,
+            var_schema=schema_name,
+            table=table_name,
+            include_columns=True,
+            limit=10,
+        )
+        if not resp.tables:
+            return []
+        first = resp.tables[0]
+        return first.columns or []
+
+    def _poll_query_run(
+        self,
+        query_run_id: str,
+        *,
+        timeout_s: float = 300.0,
+        interval_s: float = 0.5,
+    ):
+        runs = self._query_runs_api()
+        deadline = time.monotonic() + timeout_s
+        last = None
+        while time.monotonic() < deadline:
+            last = runs.get_query_run(query_run_id)
+            if last.status in _TERMINAL:
+                return last
+            time.sleep(interval_s)
+        raise TimeoutError(
+            f"Query run {query_run_id} did not finish within {timeout_s}s "
+            f"(last status: {getattr(last, 'status', None)})"
+        )
+
+    def _wait_result_ready(
+        self,
+        result_id: str,
+        *,
+        timeout_s: float = 300.0,
+        interval_s: float = 0.5,
+    ):
+        results = self._results_api()
+        deadline = time.monotonic() + timeout_s
+        last = None
+        while time.monotonic() < deadline:
+            last = results.get_result(result_id)
+            if last.status == "ready":
+                return last
+            if last.status in _RESULT_FAILURE:
+                raise RuntimeError(
+                    last.error_message or f"Result {last.status}"
+                )
+            time.sleep(interval_s)
+        raise TimeoutError(
+            f"Result {result_id} not ready within {timeout_s}s "
+            f"(last status: {getattr(last, 'status', None)})"
+        )
+
+    def execute_sql(self, sql: str) -> QueryResult:
+        last_err: BaseException | None = None
+        for attempt in range(3):
+            try:
+                return self._execute_sql_once(sql)
+            except (ProtocolError, ConnectionResetError, Urllib3HTTPError) as e:
+                last_err = e
+                if attempt == 2:
+                    raise
+                time.sleep(0.2 * (2**attempt))
+        raise last_err  # pragma: no cover
+
+    def _execute_sql_once(self, sql: str) -> QueryResult:
+        q = self._query_api()
+        try:
+            raw = q.query(QueryRequest(sql=sql))
+        except ApiException as e:
+            raise RuntimeError(e.reason or str(e)) from e
+
+        if isinstance(raw, AsyncQueryResponse):
+            run = self._poll_query_run(raw.query_run_id)
+            if run.status != "succeeded":
+                raise RuntimeError(
+                    run.error_message or f"Query failed ({run.status})"
+                )
+            if run.result_id:
+                persisted = self._wait_result_ready(run.result_id)
+                return QueryResult.from_get_result(persisted)
+            raise RuntimeError("Query succeeded but no result_id was returned.")
+
+        if isinstance(raw, QueryResponse):
+            return QueryResult.from_query_response(raw)
+
+        raise RuntimeError(f"Unexpected query response type: {type(raw)!r}")
+
+    def get_result(self, result_id: str) -> QueryResult:
+        r = self._results_api().get_result(result_id)
+        if r.status != "ready":
+            r = self._wait_result_ready(result_id)
+        return QueryResult.from_get_result(r)
+
+
+def from_env() -> HotdataClient:
+    return HotdataClient.from_env()

hotdata_runtime/env.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+from hotdata import ApiClient, Configuration
+from hotdata.api.workspaces_api import WorkspacesApi
+
+
+def normalize_host(url: str) -> str:
+    u = url.rstrip("/")
+    if u.endswith("/v1"):
+        u = u[:-3]
+    parsed = urlparse(u)
+    if not parsed.scheme or not parsed.netloc:
+        return u
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+def default_api_key() -> str:
+    return os.environ.get("HOTDATA_API_KEY", "")
+
+
+def explicit_workspace_id() -> str | None:
+    return os.environ.get("HOTDATA_WORKSPACE")
+
+
+def default_host() -> str:
+    raw = os.environ.get("HOTDATA_API_URL", "https://api.hotdata.dev")
+    return normalize_host(raw)
+
+
+def default_session_id() -> str | None:
+    return os.environ.get("HOTDATA_SANDBOX")
+
+
+def list_workspaces(api_key: str, host: str, session_id: str | None):
+    cfg = Configuration(
+        host=host,
+        api_key=api_key,
+        workspace_id=None,
+        session_id=session_id,
+    )
+    with ApiClient(cfg) as api:
+        listing = WorkspacesApi(api).list_workspaces()
+    return listing.workspaces
+
+
+@dataclass(frozen=True)
+class WorkspaceSelection:
+    workspace_id: str
+    source: str
+    workspaces: list
+
+
+def resolve_workspace_selection(
+    api_key: str, host: str, session_id: str | None
+) -> WorkspaceSelection:
+    explicit = explicit_workspace_id()
+    if explicit:
+        return WorkspaceSelection(
+            workspace_id=explicit,
+            source="explicit_env",
+            workspaces=[],
+        )
+    workspaces = list_workspaces(api_key, host, session_id)
+    if not workspaces:
+        raise RuntimeError("No Hotdata workspaces found for this API key.")
+    active = [w for w in workspaces if w.active]
+    chosen = active[0] if active else workspaces[0]
+    return WorkspaceSelection(
+        workspace_id=chosen.public_id,
+        source="active" if active else "first",
+        workspaces=workspaces,
+    )
+
+
+def pick_workspace(api_key: str, host: str, session_id: str | None) -> str:
+    selection = resolve_workspace_selection(api_key, host, session_id)
+    return selection.workspace_id

hotdata_runtime/health.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from hotdata.exceptions import ApiException
+
+from hotdata_runtime.client import HotdataClient
+
+
+def workspace_health_lines(client: HotdataClient) -> tuple[bool, list[str]]:
+    """Return ``(ok, parts)`` where ``parts`` are short markdown fragments.
+
+    On failure, ``ok`` is False and ``parts`` is a single-element list with the error text.
+    """
+    try:
+        listing = client.connections().list_connections()
+        n = len(listing.connections)
+        lines = [
+            "**API** reachable",
+            f"**workspace** `{client.workspace_id}`",
+            f"**connections** {n}",
+        ]
+        if client.session_id:
+            lines.append(f"**sandbox** `{client.session_id}`")
+        return True, lines
+    except ApiException as e:
+        return False, [e.reason or str(e)]
+    except Exception as e:
+        return False, [str(e)]

hotdata_runtime/http.py

@@ -0,0 +1,19 @@
+"""HTTP client defaults for Hotdata SDK :class:`~hotdata.Configuration`."""
+
+from __future__ import annotations
+
+from urllib3.util.retry import Retry
+
+
+def default_http_retries() -> Retry:
+    """Retry transient connection failures (e.g. stale pooled sockets)."""
+    return Retry(
+        total=3,
+        connect=3,
+        read=3,
+        backoff_factor=0.2,
+        status_forcelist=(502, 503, 504),
+        allowed_methods=frozenset(
+            ["GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"]
+        ),
+    )

hotdata_runtime/result.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from hotdata.models.get_result_response import GetResultResponse
+from hotdata.models.query_response import QueryResponse
+
+
+@dataclass
+class QueryResult:
+    """Tabular result from a Hotdata query or stored result id."""
+
+    columns: list[str]
+    rows: list[list[Any]]
+    row_count: int
+    result_id: str | None
+    query_run_id: str | None
+    execution_time_ms: int | None
+    warning: str | None = None
+    error_message: str | None = None
+
+    def to_records(
+        self,
+        *,
+        max_rows: int | None = None,
+    ) -> list[dict[str, Any]]:
+        rows = self.rows if max_rows is None else self.rows[:max_rows]
+        return [dict(zip(self.columns, row)) for row in rows]
+
+    def metadata_dict(self) -> dict[str, Any]:
+        return {
+            "row_count": self.row_count,
+            "column_count": len(self.columns),
+            "result_id": self.result_id,
+            "query_run_id": self.query_run_id,
+            "execution_time_ms": self.execution_time_ms,
+            "warning": self.warning,
+            "error_message": self.error_message,
+        }
+
+    def to_pandas(self):  # type: ignore[no-untyped-def]
+        import pandas as pd
+
+        if not self.columns:
+            return pd.DataFrame()
+        return pd.DataFrame(self.rows, columns=self.columns)
+
+    @classmethod
+    def from_query_response(cls, r: QueryResponse) -> QueryResult:
+        return cls(
+            columns=list(r.columns),
+            rows=[list(row) for row in r.rows],
+            row_count=r.row_count,
+            result_id=r.result_id,
+            query_run_id=r.query_run_id,
+            execution_time_ms=r.execution_time_ms,
+            warning=r.warning,
+            error_message=None,
+        )
+
+    @classmethod
+    def from_get_result(cls, r: GetResultResponse) -> QueryResult:
+        cols = list(r.columns or [])
+        row_data = [list(row) for row in (r.rows or [])]
+        return cls(
+            columns=cols,
+            rows=row_data,
+            row_count=r.row_count or 0,
+            result_id=r.result_id,
+            query_run_id=None,
+            execution_time_ms=None,
+            warning=None,
+            error_message=r.error_message,
+        )

hotdata_runtime-0.1.0.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: hotdata-runtime
+Version: 0.1.0
+Summary: Workspace/session runtime primitives for Hotdata integrations
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: hotdata>=0.1.0
+Requires-Dist: pandas>=2.0
+Description-Content-Type: text/markdown
+
+# hotdata-runtime
+
+Shared runtime primitives for Hotdata integrations: workspace/session semantics, execution context, query state, run history, and replayable result handles. Framework packages (Marimo, Jupyter, Streamlit, LangGraph) depend on this package.
+
+Runtime boundary and guarantees are defined in `CONTRACT.md`.
+
+## Features
+
+- **Environment-driven client setup** — create clients from `HOTDATA_API_KEY`, optional `HOTDATA_API_URL`, `HOTDATA_WORKSPACE`, and `HOTDATA_SANDBOX`.
+- **Workspace resolution** — choose an explicit workspace from env, otherwise discover workspaces and select the active workspace or first available workspace.
+- **Sandbox/session propagation** — pass sandbox session context through the SDK via `X-Session-Id`.
+- **HTTP resilience** — configure SDK retries for transient connection failures and retry SQL execution on stale pooled sockets.
+- **SQL execution helper** — run SQL through `POST /v1/query`, poll async query runs when needed, and return a `QueryResult`.
+- **Result utilities** — convert query results to records, pandas DataFrames, or metadata dictionaries for adapter display layers.
+- **History helpers** — list recent results and query run history with normalized dataclasses.
+- **Health helpers** — build compact API/workspace health summaries for UI integrations.
+
+Install:
+
+```bash
+uv pip install hotdata-runtime
+# or: pip install hotdata-runtime
+```
+
+Example:
+
+```bash
+python examples/basic_usage.py
+```
+
+Development (uses **uv**; creates `.venv/` in this repo):
+
+```bash
+uv sync --locked
+uv run pytest
+```
+
+`uv.lock` is checked in so CI can run `uv sync --locked`. The default **dev** group (pytest) is enabled via `[tool.uv] default-groups`.

hotdata_runtime-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+hotdata_runtime/__init__.py,sha256=fq8XUN9mbHEC78y2a361m0-8EqTdxF9nhpm0d_ylZEA,1094
+hotdata_runtime/client.py,sha256=j3TXMJScBEkuIjWTqe-q_v7w5o5l0Lyvw71-sfHclhs,10611
+hotdata_runtime/env.py,sha256=1gm56sQhJ2rdEtfvAzfXc0P44IodLLmSP15Uax_WnoM,2190
+hotdata_runtime/health.py,sha256=37Gg_R8dHxSssiiLvJCWnW81ND6-IDb3xGsbsXbYdAc,892
+hotdata_runtime/http.py,sha256=9UC4Rbw8-IEQ2sQ_MUTnOSM4KLPj3QKoFEXWUmtjMnE,529
+hotdata_runtime/result.py,sha256=qs2EkdoxYG1H6sLn5gqDFLstBznwBEPkI0FwCeu4f-E,2290
+hotdata_runtime-0.1.0.dist-info/METADATA,sha256=LocMOVRUWbyYwLxyU75RxnnUowU4MlWiAGYv8hj3xLc,1981
+hotdata_runtime-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hotdata_runtime-0.1.0.dist-info/RECORD,,

hotdata_runtime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any