feat: add IndexModel compatibility shims for alpha API

[jhamon]

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

# 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:

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

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

Related Issues

• Linear: SDK-107

---

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.

^{Written by Cursor Bugbot for commit 8b4b59d. This will update automatically on new commits. Configure here.}