refactor: address review nits on create_index

Derive the index-type and metric frozensets from their Literal aliases so
the accepted values have one source of truth. Collapse the two
requested-value CreateIndexResult constructions into a local helper, and
report the server's own status on the wait=False path instead of assuming
"pending". Read the finished job's payload shape-agnostically so a bare
model on `result` does not raise on the success path.

Document `description`, and spell out in CreateIndexResult that
`columns` holds the generated embedding column only when the server
returned the built index — on the echoing paths it is the source text
column.

Author: rohan-hotdata

hotdata_framework/client.py

@@ -4,7 +4,7 @@
 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
@@ -71,8 +71,8 @@
 # the function from the index instead, so it cannot mismatch.
 VectorMetric = Literal["l2", "cosine", "dot"]
 
-_INDEX_TYPES = frozenset({"sorted", "bm25", "vector"})
-_VECTOR_METRICS = frozenset({"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"})
@@ -514,7 +514,10 @@ def create_index(
 
         ``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. A vector index takes exactly one column.
+        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
@@ -593,7 +596,10 @@ def create_index(
             raise RuntimeError(f"Unexpected create_index response type: {type(submitted)!r}")
 
         job_id = submitted.id
-        if not wait:
+
+        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,
@@ -603,31 +609,24 @@ def create_index(
                 columns=list(columns),
                 metric=metric,
                 source_column=columns[0] if embedding_provider_id else None,
-                status="pending",
+                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}")
 
-        built = job.result.actual_instance if job.result is not None else None
+        # `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 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="ready",
-            job_id=job_id,
-        )
+        return requested_result("ready")
 
     @staticmethod
     def _index_result(

hotdata_framework/databases.py

@@ -56,12 +56,16 @@ class CreateIndexResult:
     owns checking the job's outcome.
 
     ``source_column`` is set only for an embedding-backed vector index, where it
-    names the *text* column a query passes to ``vector_distance(col, 'text')``;
-    ``columns`` then holds the generated embedding column instead. It is ``None``
-    for BM25, sorted, and plain (existing-vector-column) indexes.
-
-    ``index_type``, ``columns``, and ``metric`` echo the requested values when
-    the server does not return the built index alongside the finished job.
+    names the *text* column a query passes to ``vector_distance(col, 'text')``.
+    It is ``None`` for BM25, sorted, and plain (existing-vector-column) indexes.
+
+    ``index_type``, ``columns``, and ``metric`` echo the requested values when the
+    server does not return the built index alongside the finished job — that is,
+    on the ``wait=False`` path and when a finished job carries no index payload.
+    Only when the server did return it does ``columns`` hold the *generated*
+    embedding column for an embedding-backed index; on the echoing paths
+    ``columns[0]`` is the source text column, the same value as
+    ``source_column``. Read ``status`` to tell the cases apart.
     """
 
     full_name: str

tests/test_indexes.py

@@ -292,6 +292,53 @@ def test_create_index_wait_false_returns_pending_without_polling():
     assert result.columns == ["body"]
 
 
+def test_wait_false_reports_the_server_status_rather_than_assuming_pending():
+    """The server states the accepted job's status; don't hardcode it."""
+    client = _client()
+    submitted = SubmitJobResponse(id="job_2", status=JobStatus.RUNNING, status_url="/v1/jobs/job_2")
+    indexes = FakeIndexesApi(submitted)
+    jobs = FakeJobsApi([_job(JobStatus.SUCCEEDED)])
+
+    with (
+        patch.object(client, "_indexes_api", return_value=indexes),
+        patch.object(client, "_jobs_api", return_value=jobs),
+    ):
+        result = client.create_index(
+            _db(),
+            "docs",
+            columns=["body"],
+            index_type="bm25",
+            wait=False,
+        )
+
+    assert jobs.calls == 0
+    assert result.status == "running"
+
+
+def test_job_result_carrying_the_index_directly_is_still_read():
+    """`result` is a oneOf wrapper today; a bare model must not raise."""
+    client = _client()
+    indexes = FakeIndexesApi(_submitted())
+    built = _index_info(index_name="docs_body_bm25", index_type="bm25", metric=None)
+    # No `.actual_instance` — the model sits directly on `result`.
+    jobs = FakeJobsApi([_job(JobStatus.SUCCEEDED, result=built)])
+
+    with (
+        patch.object(client, "_indexes_api", return_value=indexes),
+        patch.object(client, "_jobs_api", return_value=jobs),
+    ):
+        result = client.create_index(
+            _db(),
+            "docs",
+            columns=["body"],
+            index_type="bm25",
+            poll_interval_s=0,
+        )
+
+    assert result.status == "ready"
+    assert result.index_name == "docs_body_bm25"
+
+
 def test_create_index_accepts_an_inline_201_response():
     """A build the server finishes inline answers with the index itself, not a job."""
     client = _client()