hotdata-framework 0.9.0__tar.gz → 0.11.0__tar.gz

{hotdata_framework-0.9.0 → hotdata_framework-0.11.0}/CHANGELOG.md

@@ -7,6 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-08-11
+
+### Changed
+
+- Cap the `hotdata` dependency to the current minor (`>=0.8.0,<0.9`). This
+  package wraps a *generated* client, so an SDK minor can remove a model field
+  or a `Configuration` keyword this wrapper passes, and there is no regeneration
+  step here to surface it — an uncapped floor turns an SDK release into a break
+  in this package, in versions already published. Raise the cap deliberately
+  after running the suite against the new minor.
+
+### Removed
+
+- **Breaking:** session/sandbox support is gone. `HotdataClient` no longer accepts
+  `session_id=`, `HotdataClient.session_id` is removed, `default_session_id()` and
+  the `HOTDATA_SANDBOX` read are gone, and `list_workspaces()`,
+  `resolve_workspace_selection()` and `pick_workspace()` lose their `session_id`
+  parameter — note that loss is **positional**, so a three-argument call raises an
+  arity `TypeError` rather than an unexpected-keyword one.
+  `workspace_health_lines()` no longer emits a `sandbox` line.
+
+  **Why now.** The server stopped enforcing session scoping some time ago, so the
+  value already reached nothing. What makes removal urgent rather than tidy is
+  that the SDK is dropping the `SessionId` security scheme: against that release
+  `Configuration(session_id=...)` raises `TypeError` instead of setting a header,
+  and this package passed it unconditionally — so every `HotdataClient(...)`
+  would fail at construction. This package still pins `hotdata<0.9`, so nothing
+  is broken today; the change is what lets the cap be raised later without a
+  second breaking release.
+
+  **Migrating.** Drop `session_id=` from `HotdataClient(...)`, stop reading
+  `client.session_id`, stop setting `HOTDATA_SANDBOX`, and pass two arguments to
+  the workspace helpers. Adapters that re-export session context in their own
+  signatures — a `session_id=` parameter, a `session_id` metadata key — need to
+  remove it from theirs too, which makes their own release breaking in turn.
+
+- `hotdata_framework.http` and `default_http_retries()`. The module existed only
+  to build the `retries=` policy removed under Fixed below, and had no other
+  callers. It predates `hotdata._retry`, which supersedes it.
+
+### Fixed
+
+- A `POST` is no longer replayed because of a response status. `HotdataClient`
+  passed its own `retries=` into `Configuration`, which replaced the generated
+  SDK's policy wholesale with one listing `POST` in `allowed_methods` alongside
+  a `(502, 503, 504)` forcelist — so an intermediary timing out a long request
+  produced a silent, identical re-`POST` while the server was still working on
+  the first one. For a load that is not idempotent: the duplicate collides with
+  the write lock the original holds and is refused.
+
+  The override is removed and the SDK's own default now applies. It is the
+  policy this wrapper was reaching for — `hotdata._retry` retries a
+  *pre-response* connection reset (the stale pooled socket case, where the
+  server did no work) on any method, while leaving read timeouts and status
+  retries idempotent-only.
+
+## [0.10.0] - 2026-08-07
+
+### Added
+
+- `create_index(database, table, columns=..., index_type=...)` builds a `bm25`,
+  `vector`, or `sorted` index on a managed table, matching `hotdata indexes create`
+  in the CLI. The build is a background job whose submit call reports success even
+  when the build later fails, so this polls the job and raises `RuntimeError` with
+  its error message; `wait=False` returns as soon as the job is accepted. Returns
+  `CreateIndexResult`, also exported.
 
 ## [0.9.0] - 2026-07-23
 

{hotdata_framework-0.9.0 → hotdata_framework-0.11.0}/CONTRACT.md

@@ -21,7 +21,6 @@ The supported import surface is:
 - `workspace_health_lines`
 - `default_api_key`
 - `default_host`
-- `default_session_id`
 - `explicit_workspace_id`
 - `list_workspaces`
 - `normalize_host`
@@ -33,6 +32,7 @@ The supported import surface is:
 - `ManagedDatabase`
 - `ManagedTable`
 - `LoadManagedTableResult`
+- `CreateIndexResult`
 - `DEFAULT_SCHEMA`
 - `is_parquet_path`
 
@@ -42,7 +42,7 @@ Adapters should import from `hotdata_framework` and treat this surface as the st
 
 ### `HotdataClient`
 
-- Represents runtime context: API key, host, workspace, optional session.
+- Represents runtime context: API key, host, workspace.
 - `from_env()` resolves runtime context from env vars and selected workspace.
 - `execute_sql(sql)` returns `QueryResult` or raises `RuntimeError`/`TimeoutError`.
 - `get_result(result_id)` returns a ready `QueryResult` and waits for readiness when needed.
@@ -63,7 +63,8 @@ Adapters should import from `hotdata_framework` and treat this surface as the st
 - `upload_parquet(path)` uploads a local parquet file and returns an upload id.
 - `load_managed_table(database, table, schema=..., upload_id=..., file=...)` publishes parquet data into a declared managed table.
 - `delete_managed_table(database, table, schema=...)` deletes a managed table.
-- The `database` argument of `list_managed_tables`, `load_managed_table`, `add_managed_table`, `delete_managed_table`, `delete_managed_database`, and `execute_sql` accepts a name/id **or** an already-resolved `ManagedDatabase`. Passing a `ManagedDatabase` skips the name/id read probe, so a create-scoped key that cannot read `/databases` can load into a database it just created.
+- `create_index(database, table, schema=..., columns=..., index_type=..., index_name=...)` builds a `"sorted"`, `"bm25"`, or `"vector"` index on a managed table and returns a `CreateIndexResult`. It is the framework-side equivalent of the CLI's `hotdata indexes create`; indexing a table on a plain (non-managed) connection is out of scope. `index_name` defaults to `{table}_{columns}_{index_type}`, matching the CLI's derivation when `--name` is omitted. `index_type` is required rather than defaulting to the API's `"sorted"`. The build runs as a background job; the call polls it to a terminal state and raises `RuntimeError` with the job's `error_message` when it fails, because the submit call reports success regardless. `wait=False` returns as soon as the job is accepted, with `status="pending"` and a `job_id` for the caller to poll. For `index_type="vector"`, omitting `embedding_provider_id` indexes an existing vector column and `metric` (`"l2"`, `"cosine"`, `"dot"`) selects the distance function the index accelerates — a query using a different function silently falls back to a full scan; setting `embedding_provider_id` indexes a source *text* column instead, and the returned `source_column` names the column to pass to `vector_distance`. Argument combinations the server would silently ignore raise `ValueError` before any request is sent.
+- The `database` argument of `list_managed_tables`, `load_managed_table`, `add_managed_table`, `delete_managed_table`, `delete_managed_database`, `create_index`, and `execute_sql` accepts a name/id **or** an already-resolved `ManagedDatabase`. Passing a `ManagedDatabase` skips the name/id read probe, so a create-scoped key that cannot read `/databases` can load into a database it just created.
 
 ### `QueryResult`
 
@@ -77,7 +78,6 @@ Adapters should import from `hotdata_framework` and treat this surface as the st
 
 - `default_api_key()` reads `HOTDATA_API_KEY`.
 - `default_host()` reads `HOTDATA_API_URL` (default: `https://api.hotdata.dev`) and normalizes it.
-- `default_session_id()` reads `HOTDATA_SANDBOX`.
 - `explicit_workspace_id()` reads `HOTDATA_WORKSPACE` (workspace public id).
 - `pick_workspace()` prefers explicit env workspace, then active workspace, then first workspace.
 - `resolve_workspace_selection()` is the canonical workspace selection algorithm. It returns `WorkspaceSelection` with selected workspace id, selection source, and discovered workspaces when auto-selected.

{hotdata_framework-0.9.0 → hotdata_framework-0.11.0}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hotdata-framework
-Version: 0.9.0
-Summary: Python framework for building Hotdata integrations: workspace/session runtime, query execution, and managed databases
+Version: 0.11.0
+Summary: Python framework for building Hotdata integrations: workspace runtime, query execution, and managed databases
 Project-URL: Homepage, https://www.hotdata.dev
 Project-URL: Documentation, https://www.hotdata.dev/docs
 Project-URL: Repository, https://github.com/hotdata-dev/sdk-python-framework
@@ -21,7 +21,7 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: hotdata>=0.8.0
+Requires-Dist: hotdata<0.9,>=0.8.0
 Requires-Dist: pandas>=2.0
 Requires-Dist: pyarrow>=14.0
 Description-Content-Type: text/markdown
@@ -30,20 +30,20 @@ Description-Content-Type: text/markdown
 
 **A Python framework for building Hotdata integrations.**
 
-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.
+Shared runtime primitives for Hotdata integrations: workspace 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`.
+- **Environment-driven client setup** — create clients from `HOTDATA_API_KEY`, optional `HOTDATA_API_URL`, and `HOTDATA_WORKSPACE`.
 - **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.
+- **HTTP resilience** — retry SQL execution on stale pooled sockets. Transport-level retries are the SDK's own default, which this package leaves in place so a non-idempotent request is never replayed on a response status.
 - **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.
 - **Managed databases** — create Hotdata-owned catalogs, declare tables, upload parquet, and load managed tables (mirrors `hotdata databases` in the CLI).
+- **Indexes** — build BM25, vector, or sorted indexes on managed tables, mirroring `hotdata indexes create` (managed databases only). Waits on the background build job and surfaces its failure, instead of reporting the phantom success the submit call returns.
 - **Health helpers** — build compact API/workspace health summaries for UI integrations.
 
 Install:

{hotdata_framework-0.9.0 → hotdata_framework-0.11.0}/README.md

@@ -2,20 +2,20 @@
 
 **A Python framework for building Hotdata integrations.**
 
-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.
+Shared runtime primitives for Hotdata integrations: workspace 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`.
+- **Environment-driven client setup** — create clients from `HOTDATA_API_KEY`, optional `HOTDATA_API_URL`, and `HOTDATA_WORKSPACE`.
 - **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.
+- **HTTP resilience** — retry SQL execution on stale pooled sockets. Transport-level retries are the SDK's own default, which this package leaves in place so a non-idempotent request is never replayed on a response status.
 - **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.
 - **Managed databases** — create Hotdata-owned catalogs, declare tables, upload parquet, and load managed tables (mirrors `hotdata databases` in the CLI).
+- **Indexes** — build BM25, vector, or sorted indexes on managed tables, mirroring `hotdata indexes create` (managed databases only). Waits on the background build job and surfaces its failure, instead of reporting the phantom success the submit call returns.
 - **Health helpers** — build compact API/workspace health summaries for UI integrations.
 
 Install:

{hotdata_framework-0.9.0 → hotdata_framework-0.11.0}/hotdata_framework/__init__.py

@@ -10,6 +10,7 @@ from hotdata_framework.client import (
 )
 from hotdata_framework.databases import (
     DEFAULT_SCHEMA,
+    CreateIndexResult,
     LoadManagedTableResult,
     ManagedDatabase,
     ManagedTable,
@@ -19,7 +20,6 @@ from hotdata_framework.env import (
     WorkspaceSelection,
     default_api_key,
     default_host,
-    default_session_id,
     explicit_workspace_id,
     list_workspaces,
     normalize_host,
@@ -43,6 +43,7 @@ except PackageNotFoundError:
 
 __all__ = [
     "DEFAULT_SCHEMA",
+    "CreateIndexResult",
     "HotdataClient",
     "HotdataError",
     "HotdataTerminalError",
@@ -59,7 +60,6 @@ __all__ = [
     "classify_sdk_error",
     "default_api_key",
     "default_host",
-    "default_session_id",
     "explicit_workspace_id",
     "from_env",
     "is_parquet_path",

{hotdata_framework-0.9.0 → hotdata_framework-0.11.0}/hotdata_framework/client.py

@@ -4,12 +4,14 @@ import functools
 import time
 from collections.abc import Iterator
 from dataclasses import asdict, dataclass
-from typing import Any, Literal
+from typing import Any, Literal, get_args
 
 from hotdata import ApiClient, Configuration
 from hotdata.api.connections_api import ConnectionsApi
 from hotdata.api.databases_api import DatabasesApi
+from hotdata.api.indexes_api import IndexesApi
 from hotdata.api.information_schema_api import InformationSchemaApi
+from hotdata.api.jobs_api import JobsApi
 from hotdata.api.query_api import QueryApi
 from hotdata.api.query_runs_api import QueryRunsApi
 from hotdata.api.results_api import ResultsApi
@@ -20,40 +22,60 @@ from hotdata.exceptions import ApiException
 from hotdata.models.add_managed_table_request import AddManagedTableRequest
 from hotdata.models.async_query_response import AsyncQueryResponse
 from hotdata.models.create_database_request import CreateDatabaseRequest
+from hotdata.models.create_index_request import CreateIndexRequest
 from hotdata.models.database_default_schema_decl import DatabaseDefaultSchemaDecl
 from hotdata.models.database_default_table_decl import DatabaseDefaultTableDecl
+from hotdata.models.index_info_response import IndexInfoResponse
+from hotdata.models.job_status_response import JobStatusResponse
 from hotdata.models.load_managed_table_request import LoadManagedTableRequest
 from hotdata.models.query_request import QueryRequest
 from hotdata.models.query_response import QueryResponse
+from hotdata.models.submit_job_response import SubmitJobResponse
 from hotdata.models.table_info import TableInfo
 from urllib3.exceptions import HTTPError as Urllib3HTTPError
 from urllib3.exceptions import ProtocolError
 
 from hotdata_framework.databases import (
     DEFAULT_SCHEMA,
+    CreateIndexResult,
     LoadManagedTableResult,
     ManagedDatabase,
     ManagedTable,
     api_error_message,
+    enum_value,
     is_parquet_path,
     managed_database_from_detail,
 )
 from hotdata_framework.env import (
     default_api_key,
     default_host,
-    default_session_id,
     normalize_host,
     pick_workspace,
 )
-from hotdata_framework.http import default_http_retries
 from hotdata_framework.result import QueryResult
 
 # Load modes the managed-table endpoint accepts: replace overwrites, append adds
 # rows, delete/update/upsert match by the table's declared key.
 ManagedLoadMode = Literal["replace", "append", "delete", "update", "upsert"]
 
+# Index kinds the indexes endpoint accepts. "sorted" is the server-side default;
+# "bm25" backs full-text search and "vector" backs nearest-neighbour search.
+IndexType = Literal["sorted", "bm25", "vector"]
+
+# Distance metrics a vector index can be built with. Each one accelerates
+# exactly one query function: cosine -> cosine_distance, l2 -> l2_distance,
+# dot -> negative_dot_product. A hand-written query naming a different function
+# falls back to a full scan; the provider-backed vector_distance path resolves
+# the function from the index instead, so it cannot mismatch.
+VectorMetric = Literal["l2", "cosine", "dot"]
+
+_INDEX_TYPES = frozenset(get_args(IndexType))
+_VECTOR_METRICS = frozenset(get_args(VectorMetric))
+
 _TERMINAL = frozenset({"succeeded", "failed", "cancelled"})
 _RESULT_FAILURE = frozenset({"failed", "cancelled"})
+# Jobs have no "cancelled" state; "partially_succeeded" carries an error_message.
+_JOB_TERMINAL = frozenset({"succeeded", "partially_succeeded", "failed"})
 
 
 @dataclass(frozen=True)
@@ -126,19 +148,21 @@ class HotdataClient:
         workspace_id: str,
         *,
         host: str | None = None,
-        session_id: str | None = None,
         request_timeout: float | tuple[float, float] | 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
+        # No `retries=`: the generated SDK's own default is the correct policy
+        # and passing one here replaces it wholesale. `hotdata._retry` retries a
+        # pre-response connection reset on any method — the stale pooled socket
+        # case this wrapper was reaching for — while leaving read timeouts and
+        # status retries idempotent-only, so a POST that may have reached the
+        # server is never replayed.
         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)
         if request_timeout is not None:
@@ -150,9 +174,8 @@ class HotdataClient:
         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)
+        workspace_id = pick_workspace(api_key, host)
+        return cls(api_key, workspace_id, host=host)
 
     @property
     def workspace_id(self) -> str:
@@ -162,10 +185,6 @@ class HotdataClient:
     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
@@ -188,6 +207,12 @@ class HotdataClient:
     def _information_schema(self) -> InformationSchemaApi:
         return InformationSchemaApi(self._api)
 
+    def _indexes_api(self) -> IndexesApi:
+        return IndexesApi(self._api)
+
+    def _jobs_api(self) -> JobsApi:
+        return JobsApi(self._api)
+
     def _query_api(self) -> QueryApi:
         return QueryApi(self._api)
 
@@ -427,6 +452,199 @@ class HotdataClient:
         except ApiException as e:
             raise RuntimeError(api_error_message(e)) from e
 
+    def create_index(
+        self,
+        database: str | ManagedDatabase,
+        table: str,
+        *,
+        schema: str = DEFAULT_SCHEMA,
+        index_name: str | None = None,
+        columns: list[str],
+        index_type: IndexType,
+        metric: VectorMetric | None = None,
+        dimensions: int | None = None,
+        embedding_provider_id: str | None = None,
+        output_column: str | None = None,
+        description: str | None = None,
+        wait: bool = True,
+        timeout_s: float = 300.0,
+        poll_interval_s: float = 2.0,
+    ) -> CreateIndexResult:
+        """Build an index on a managed table and wait for it to be ready.
+
+        The Python equivalent of ``hotdata indexes create``, scoped to managed
+        databases. Indexing a table on a plain (non-managed) connection is not
+        supported here; the CLI's ``--catalog`` flag covers that case.
+
+        ``index_type`` selects the index kind and is required: ``"bm25"`` for
+        full-text search (queries error outright without one), ``"vector"`` for
+        nearest-neighbour search (queries work without one, but only at
+        full-scan speed), or ``"sorted"``. The API defaults an unspecified kind
+        to ``"sorted"``; this method makes the choice explicit instead, because
+        the wrong kind fails at query time rather than here.
+
+        ``index_name`` defaults to ``{table}_{columns}_{index_type}``, the same
+        derivation the CLI uses when ``--name`` is omitted, so both surfaces
+        name the same index identically.
+
+        There are two kinds of vector index, and they are queried differently:
+
+        * **Plain** — omit ``embedding_provider_id``. ``columns`` is the existing
+          vector column (a float list), and a query passes a literal vector:
+          ``cosine_distance(col, ARRAY[...])``. Here ``metric`` must match the
+          distance function the caller writes — ``cosine`` serves
+          ``cosine_distance``, ``l2`` serves ``l2_distance``, ``dot`` serves
+          ``negative_dot_product``. A mismatch is not an error: the query
+          silently reverts to a full table scan. Omitting ``metric`` lets the
+          server choose (``l2`` for float-array columns), so pass it explicitly
+          whenever the query function is known.
+        * **Provider-backed** — set ``embedding_provider_id`` (e.g. the system
+          provider ``sys_emb_openai``). ``columns`` is then the *source text*
+          column; the provider embeds it into ``output_column`` (default
+          ``{column}_embedding``) and the index is built over that. A query
+          passes text, not a vector — ``vector_distance(source_col, 'query')`` —
+          and the server resolves the matching distance function from the index
+          itself, so the metric-mismatch trap above does not apply. The returned
+          ``source_column`` names the column to query.
+
+        ``dimensions`` picks the output width for providers that support several;
+        it does not apply when indexing an existing vector column, whose width is
+        read from the data. ``description`` is a user-facing label for the
+        embedding (e.g. ``"product descriptions"``), stored alongside it. A vector
+        index takes exactly one column, and every option in this paragraph — plus
+        ``metric`` — is rejected for a non-vector ``index_type``, matching the CLI.
+
+        The server builds the index as a background job. This method polls that
+        job to a terminal state and raises ``RuntimeError`` if it failed, because
+        the submit call itself reports success for builds that later fail. Pass
+        ``wait=False`` to return as soon as the job is accepted — the result then
+        carries ``status="pending"`` and a ``job_id``, and the caller owns
+        checking the outcome (the CLI's ``--async`` plus ``hotdata jobs``).
+
+        Raises ``ValueError`` for an unusable argument combination,
+        ``RuntimeError`` if the API rejects the request or the build fails, and
+        ``TimeoutError`` if the build is still running after ``timeout_s``.
+        """
+        if not columns:
+            raise ValueError("create_index requires at least one column")
+        if index_type not in _INDEX_TYPES:
+            allowed = ", ".join(sorted(_INDEX_TYPES))
+            raise ValueError(f"index_type must be one of {allowed} (got {index_type!r})")
+        if index_type != "vector":
+            vector_only = {
+                "metric": metric,
+                "dimensions": dimensions,
+                "embedding_provider_id": embedding_provider_id,
+                "output_column": output_column,
+                "description": description,
+            }
+            supplied = sorted(k for k, v in vector_only.items() if v is not None)
+            if supplied:
+                raise ValueError(
+                    f"{', '.join(supplied)} appl{'ies' if len(supplied) == 1 else 'y'} to "
+                    f"vector indexes only (index_type={index_type!r})"
+                )
+        else:
+            if len(columns) != 1:
+                raise ValueError(
+                    f"a vector index takes exactly one column (got {len(columns)}); "
+                    "the engine indexes only the first"
+                )
+            if metric is not None and metric not in _VECTOR_METRICS:
+                allowed = ", ".join(sorted(_VECTOR_METRICS))
+                raise ValueError(f"metric must be one of {allowed} (got {metric!r})")
+
+        # Matches the CLI's derivation so both surfaces name the same index
+        # identically: `hotdata indexes create` without --name.
+        resolved_name = index_name or f"{table}_{'_'.join(columns)}_{index_type}"
+
+        db = self._as_managed_database(database)
+        request = CreateIndexRequest(
+            index_name=resolved_name,
+            columns=list(columns),
+            index_type=index_type,
+            metric=metric,
+            dimensions=dimensions,
+            embedding_provider_id=embedding_provider_id,
+            output_column=output_column,
+            description=description,
+            var_async=True,
+        )
+        try:
+            submitted = self._indexes_api().create_index(
+                db.default_connection_id,
+                schema,
+                table,
+                request,
+            )
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+
+        full_name = f"{db.id}.{schema}.{table}"
+
+        # A build the server finished inline answers 201 with the index itself;
+        # the async path answers 202 with a job to poll.
+        if isinstance(submitted, IndexInfoResponse):
+            return self._index_result(submitted, full_name, schema, table, job_id=None)
+
+        if not isinstance(submitted, SubmitJobResponse):
+            raise RuntimeError(f"Unexpected create_index response type: {type(submitted)!r}")
+
+        job_id = submitted.id
+
+        def requested_result(status: str) -> CreateIndexResult:
+            """Echo the requested values, for the paths where the server hands
+            back a job rather than the built index."""
+            return CreateIndexResult(
+                full_name=full_name,
+                schema_name=schema,
+                table_name=table,
+                index_name=resolved_name,
+                index_type=index_type,
+                columns=list(columns),
+                metric=metric,
+                source_column=columns[0] if embedding_provider_id else None,
+                status=status,
+                job_id=job_id,
+            )
+
+        if not wait:
+            return requested_result(enum_value(submitted.status))
+
+        job = self._poll_job(job_id, timeout_s=timeout_s, interval_s=poll_interval_s)
+        status = enum_value(job.status)
+        if status != "succeeded":
+            detail = job.error_message or f"Index build {status}"
+            raise RuntimeError(f"Index {resolved_name!r} on {full_name}: {detail}")
+
+        # `result` is a oneOf wrapper today; tolerate the model arriving directly.
+        built = getattr(job.result, "actual_instance", job.result)
+        if isinstance(built, IndexInfoResponse):
+            return self._index_result(built, full_name, schema, table, job_id=job_id)
+        return requested_result("ready")
+
+    @staticmethod
+    def _index_result(
+        info: IndexInfoResponse,
+        full_name: str,
+        schema: str,
+        table: str,
+        *,
+        job_id: str | None,
+    ) -> CreateIndexResult:
+        return CreateIndexResult(
+            full_name=full_name,
+            schema_name=schema,
+            table_name=table,
+            index_name=info.index_name,
+            index_type=info.index_type,
+            columns=list(info.columns),
+            metric=info.metric,
+            source_column=info.source_column,
+            status=enum_value(info.status),
+            job_id=job_id,
+        )
+
     def list_recent_results(
         self,
         *,
@@ -560,6 +778,29 @@ class HotdataClient:
             f"(last status: {getattr(last, 'status', None)})"
         )
 
+    def _poll_job(
+        self,
+        job_id: str,
+        *,
+        timeout_s: float = 300.0,
+        interval_s: float = 2.0,
+    ) -> JobStatusResponse:
+        jobs = self._jobs_api()
+        deadline = time.monotonic() + timeout_s
+        last: JobStatusResponse | None = None
+        while time.monotonic() < deadline:
+            try:
+                last = jobs.get_job(job_id)
+            except ApiException as e:
+                raise RuntimeError(api_error_message(e)) from e
+            if last.status in _JOB_TERMINAL:
+                return last
+            time.sleep(interval_s)
+        last_status = enum_value(last.status) if last is not None else None
+        raise TimeoutError(
+            f"Job {job_id} did not finish within {timeout_s}s (last status: {last_status})"
+        )
+
     def _wait_result_ready(
         self,
         result_id: str,