feat: add IndexModel compatibility shims for alpha API (#590)

## Summary

This PR adds backward compatibility properties to `IndexModel` that map
old-style accessor patterns to the new alpha API structure, ensuring
existing code continues to work with the new API.

## Problem

The alpha API (2026-01.alpha) has a different response structure than
the previous API (2025-10):

- **Old structure**: `spec` (with `serverless`/`pod`/`byoc` nested),
`dimension`, `metric`, `vector_type` at the top level
- **New structure**: `deployment` (with `deployment_type`, `cloud`,
`region`, etc.), `schema` (with `fields` containing vector field
configurations)

Existing user code that accesses `index.spec.serverless.cloud` or
`index.dimension` would break with the new API.

## Solution

Add compatibility shims to `IndexModel` that provide the old-style
access patterns:

1. **`spec` property**: Returns a `CompatibilitySpec` that builds the
old `.spec.serverless`/`.spec.pod`/`.spec.byoc` access patterns from the
new `deployment` data
2. **`dimension` property**: Extracts dimension from `schema.fields`
(finds dense vector field)
3. **`metric` property**: Extracts metric from `schema.fields` (finds
vector field with metric)
4. **`vector_type` property**: Returns "dense" or "sparse" based on
vector field type, or None for FTS-only indexes

## Usage Examples

```python
# New alpha API format with schema and deployment
index = pc.describe_index("my-index")

# Old-style access still works via compatibility shims
print(index.spec.serverless.cloud)  # "aws" - via CompatibilitySpec
print(index.spec.serverless.region) # "us-east-1"
print(index.dimension)              # 1536 - extracted from schema.fields
print(index.metric)                 # "cosine" - extracted from schema.fields
print(index.vector_type)            # "dense" - derived from field type

# New-style access also works directly
print(index.deployment.cloud)       # "aws"
print(index.schema.fields)          # Field configurations
```

## Handling FTS-Only Indexes

Indexes with only text fields (no vectors) return `None` for vector
properties:

```python
fts_index = pc.describe_index("fts-only-index")
print(fts_index.dimension)    # None
print(fts_index.metric)       # None
print(fts_index.vector_type)  # None
print(fts_index.spec.serverless.cloud)  # "aws" - spec still works
```

## Test Plan

- [x] Unit tests for `CompatibilitySpec` with serverless/pod/byoc
deployments
- [x] Unit tests for `IndexModel` dimension/metric/vector_type
extraction
- [x] Unit tests for FTS-only indexes returning None for vector
properties
- [x] Unit tests for dict-style access (`index["dimension"]`)
- [x] Mypy type checking passes

## Related Issues

- Linear: SDK-107

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes `IndexModel` attribute resolution for
`spec`/`dimension`/`metric`/`vector_type`, which may affect callers
depending on prior `spec` parsing behavior when `deployment`/`schema`
are missing or shaped differently. The logic is straightforward and
covered by new unit tests, but it touches a commonly used wrapper.
> 
> **Overview**
> Adds a new `CompatibilitySpec` wrapper (plus
`ServerlessSpecCompat`/`PodSpecCompat`/`ByocSpecCompat`) to recreate
legacy `.spec.serverless`/`.spec.pod`/`.spec.byoc` access from the alpha
API’s `deployment` object.
> 
> Updates `IndexModel` to provide backward-compatible `dimension`,
`metric`, and `vector_type` by extracting vector field info from
`schema.fields` (including sparse-vector and FTS-only cases), and
replaces the previous complex `spec` deserialization logic with the new
deployment-based shim.
> 
> Exports the new compatibility classes from
`pinecone.db_control.models` and expands unit tests to cover
serverless/pod/byoc deployments, sparse vectors, FTS-only indexes, and
dict-style access.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
8b4b59d. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: jhamon

pinecone/db_control/models/__init__.py

@@ -22,6 +22,12 @@
 )
 from .schema_builder import SchemaBuilder
 from .deployment import ServerlessDeployment, ByocDeployment, PodDeployment, Deployment
+from .compatibility_spec import (
+    CompatibilitySpec,
+    ServerlessSpecCompat,
+    PodSpecCompat,
+    ByocSpecCompat,
+)
 
 
 __all__ = [
@@ -51,4 +57,8 @@
     "ByocDeployment",
     "PodDeployment",
     "Deployment",
+    "CompatibilitySpec",
+    "ServerlessSpecCompat",
+    "PodSpecCompat",
+    "ByocSpecCompat",
 ]

pinecone/db_control/models/compatibility_spec.py

@@ -0,0 +1,131 @@
+"""Compatibility shim classes for backward compatibility with the old spec-based API.
+
+These classes map the new deployment-based API structure to the old spec-based
+access patterns, ensuring existing code continues to work with the new API.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Dict
+
+
+@dataclass
+class ServerlessSpecCompat:
+    """Compatibility shim for serverless spec access.
+
+    Provides the same interface as the old ServerlessSpec response for
+    backward compatibility.
+
+    :param cloud: The cloud provider (e.g., "aws", "gcp", "azure").
+    :param region: The cloud region (e.g., "us-east-1").
+    """
+
+    cloud: str
+    region: str
+
+
+@dataclass
+class PodSpecCompat:
+    """Compatibility shim for pod spec access.
+
+    Provides the same interface as the old PodSpec response for
+    backward compatibility.
+
+    :param environment: The pod environment.
+    :param pod_type: The pod type (e.g., "p1.x1").
+    :param replicas: Number of replicas.
+    :param shards: Number of shards.
+    :param pods: Total number of pods.
+    :param metadata_config: Metadata configuration dict.
+    :param source_collection: Source collection name, if any.
+    """
+
+    environment: str
+    pod_type: str
+    replicas: int
+    shards: int
+    pods: int
+    metadata_config: Dict[str, object] | None = None
+    source_collection: str | None = None
+
+
+@dataclass
+class ByocSpecCompat:
+    """Compatibility shim for BYOC spec access.
+
+    Provides the same interface as the old ByocSpec response for
+    backward compatibility.
+
+    :param environment: The BYOC environment identifier.
+    """
+
+    environment: str
+
+
+class CompatibilitySpec:
+    """Compatibility wrapper that provides old-style spec access from new deployment data.
+
+    This class wraps a deployment object from the alpha API and provides the old
+    `.spec.serverless` / `.spec.pod` / `.spec.byoc` access patterns for backward
+    compatibility.
+
+    :param deployment: The deployment object from the API response.
+    """
+
+    def __init__(self, deployment: object):
+        self._deployment = deployment
+
+    @property
+    def serverless(self) -> ServerlessSpecCompat | None:
+        """Get serverless spec if this is a serverless deployment.
+
+        :returns: ServerlessSpecCompat if serverless deployment, None otherwise.
+        """
+        deployment_type = getattr(self._deployment, "deployment_type", None)
+        if deployment_type == "serverless":
+            cloud = getattr(self._deployment, "cloud", "")
+            region = getattr(self._deployment, "region", "")
+            return ServerlessSpecCompat(cloud=cloud, region=region)
+        return None
+
+    @property
+    def pod(self) -> PodSpecCompat | None:
+        """Get pod spec if this is a pod deployment.
+
+        :returns: PodSpecCompat if pod deployment, None otherwise.
+        """
+        deployment_type = getattr(self._deployment, "deployment_type", None)
+        if deployment_type == "pod":
+            environment = getattr(self._deployment, "environment", "")
+            pod_type = getattr(self._deployment, "pod_type", "p1.x1")
+            replicas = getattr(self._deployment, "replicas", 1)
+            shards = getattr(self._deployment, "shards", 1)
+            pods = getattr(self._deployment, "pods", 1)
+            metadata_config = getattr(self._deployment, "metadata_config", None)
+            source_collection = getattr(self._deployment, "source_collection", None)
+            return PodSpecCompat(
+                environment=environment,
+                pod_type=pod_type,
+                replicas=replicas,
+                shards=shards,
+                pods=pods,
+                metadata_config=metadata_config,
+                source_collection=source_collection,
+            )
+        return None
+
+    @property
+    def byoc(self) -> ByocSpecCompat | None:
+        """Get BYOC spec if this is a BYOC deployment.
+
+        :returns: ByocSpecCompat if BYOC deployment, None otherwise.
+        """
+        deployment_type = getattr(self._deployment, "deployment_type", None)
+        if deployment_type == "byoc":
+            environment = getattr(self._deployment, "environment", "")
+            return ByocSpecCompat(environment=environment)
+        return None