fix(preview): accept deprecated field= kwarg on PreviewTextQuery (#665)

## Summary

The rename `PreviewTextQuery.field` (str) → `PreviewTextQuery.fields`
(list[str]) at `fefc4850` is a breaking call-site change for any user
written against pre-rename `PreviewTextQuery`. The preview namespace's
documented SemVer policy permits this, but the cost is small to make it
non-breaking, so this PR does.

- `field=` is reintroduced as a deprecated kwarg/attribute on the
canonical `msgspec.Struct` (no parallel class, per the shim-purity
convention).
- When provided, it migrates to `fields=[field]` in `__post_init__` and
emits a `DeprecationWarning`.
- `omit_defaults=True` keeps the encoded payload free of a `"field":
null` artifact; existing wire-shape tests are unchanged.
- Decoding the legacy single-field backend response variant (`{"type":
"text", "field": "...", "query": "..."}`) now works and routes through
the same migration path.
- Mutually exclusive: passing both `field=` and `fields=` raises
`ValueError`; passing neither raises `ValueError`.

## Why

Avoids breaking callers without forcing a re-design of the preview API.
The backend already accepts both wire forms, so this only restores the
Python-side call signature.

## Test plan

- [x] `uv run pytest tests/unit/preview/models/test_score_by.py` — 21/21
pass, including 6 new tests covering the deprecation path
- [x] `uv run pytest tests/unit/preview/` — 705 passed, 1 xfailed (no
regressions)
- [x] `uv run mypy --strict pinecone/` — clean across 186 source files
- [x] `uv run ruff check` + `ruff format --check` — clean
- [ ] Integration tests in `tests/integration/preview/` — out of scope
for this PR (no behavior change on the wire)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: changes are confined to preview model
initialization/serialization with added validation and tests; main risk
is tightening constructor requirements for callers who passed neither
`fields` nor `field`.
> 
> **Overview**
> Restores backward compatibility for `PreviewTextQuery` by
reintroducing deprecated `field` support that auto-migrates to
`fields=[...]` and emits a `DeprecationWarning`, while enforcing that
callers provide *exactly one* of `field` or `fields`.
> 
> Ensures JSON encoding stays canonical (no `"field": null`) via
`omit_defaults=True`, and adds unit coverage for migration, validation
errors, and decoding the legacy backend `{"field": ...}` variant.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
c559ac0. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: jhamon

pinecone/preview/models/score_by.py

@@ -15,7 +15,7 @@
 ]
 
 
-class PreviewTextQuery(Struct, tag="text", tag_field="type", kw_only=True):
+class PreviewTextQuery(Struct, tag="text", tag_field="type", kw_only=True, omit_defaults=True):
     """Full-text search query for scoring documents.
 
     .. admonition:: Preview
@@ -29,10 +29,33 @@ class PreviewTextQuery(Struct, tag="text", tag_field="type", kw_only=True):
     Attributes:
         fields: One or more text field names to search across.
         query: Search query string.
+        field: Deprecated alias for ``fields``. If provided, it is migrated
+            to ``fields=[field]`` and a ``DeprecationWarning`` is emitted.
+            Cleared to ``None`` after migration; read ``fields`` instead.
     """
 
-    fields: list[str]
     query: str
+    fields: list[str] | None = None
+    field: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.field is not None:
+            if self.fields is not None:
+                raise ValueError(
+                    "PreviewTextQuery accepts `fields=[...]` or the deprecated "
+                    "`field=...`, but not both."
+                )
+            import warnings
+
+            warnings.warn(
+                "PreviewTextQuery `field` is deprecated; use `fields=[...]`.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            self.fields = [self.field]
+            self.field = None
+        elif self.fields is None:
+            raise ValueError("PreviewTextQuery requires `fields=[...]`.")
 
 
 class PreviewQueryStringQuery(Struct, tag="query_string", tag_field="type", kw_only=True):

tests/unit/preview/models/test_score_by.py

@@ -2,7 +2,10 @@
 
 from __future__ import annotations
 
+import warnings
+
 import msgspec
+import pytest
 
 from pinecone.preview.models.score_by import (
     PreviewDenseVectorQuery,
@@ -52,6 +55,55 @@ def test_text_query_no_extra_fields() -> None:
     assert not hasattr(q, "sparse_values")
 
 
+# ---------------------------------------------------------------------------
+# PreviewTextQuery — deprecated `field=` alias
+# ---------------------------------------------------------------------------
+
+
+def test_text_query_deprecated_field_kwarg_migrates_to_fields() -> None:
+    with pytest.warns(DeprecationWarning, match=r"`field` is deprecated"):
+        q = PreviewTextQuery(field="title", query="hello")
+    assert q.fields == ["title"]
+    assert q.field is None
+
+
+def test_text_query_deprecated_field_kwarg_keeps_wire_shape_clean() -> None:
+    with pytest.warns(DeprecationWarning, match=r"`field` is deprecated"):
+        q = PreviewTextQuery(field="title", query="hello")
+    decoded = msgspec.json.decode(msgspec.json.encode(q))
+    assert decoded == {"type": "text", "fields": ["title"], "query": "hello"}
+    assert "field" not in decoded
+
+
+def test_text_query_canonical_fields_emits_no_warning() -> None:
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", DeprecationWarning)
+        q = PreviewTextQuery(fields=["title"], query="hello")
+    assert q.fields == ["title"]
+    assert q.field is None
+
+
+def test_text_query_rejects_both_field_and_fields() -> None:
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        with pytest.raises(ValueError, match="not both"):
+            PreviewTextQuery(field="title", fields=["body"], query="hello")
+
+
+def test_text_query_rejects_neither_field_nor_fields() -> None:
+    with pytest.raises(ValueError, match="requires `fields"):
+        PreviewTextQuery(query="hello")
+
+
+def test_text_query_decodes_backend_field_variant() -> None:
+    """Backend may return the legacy single-field form; decode should migrate."""
+    raw = b'{"type": "text", "field": "body", "query": "hello"}'
+    with pytest.warns(DeprecationWarning, match=r"`field` is deprecated"):
+        result = msgspec.json.decode(raw, type=PreviewTextQuery)
+    assert result.fields == ["body"]
+    assert result.field is None
+
+
 # ---------------------------------------------------------------------------
 # PreviewQueryStringQuery
 # ---------------------------------------------------------------------------