feat: add deployment model classes (#584)

## Summary

Add deployment model classes for different index deployment
configurations.

Closes SDK-103

## Classes

| Class | Deployment Type | Key Parameters |
|-------|-----------------|----------------|
| `ServerlessDeployment` | `serverless` | `cloud`, `region` |
| `ByocDeployment` | `byoc` | `environment` |
| `PodDeployment` | `pod` | `environment`, `pod_type`, `replicas`,
`shards` |

## Usage Example

```python
from pinecone import ServerlessDeployment, ByocDeployment, PodDeployment

# Serverless deployment
pc.create_index(
    name="my-index",
    schema=schema,
    deployment=ServerlessDeployment(cloud="aws", region="us-east-1"),
)

# BYOC deployment
pc.create_index(
    name="my-index",
    schema=schema,
    deployment=ByocDeployment(environment="aws-us-east-1-b92"),
)

# Pod deployment
pc.create_index(
    name="my-index",
    schema=schema,
    deployment=PodDeployment(
        environment="us-east-1-aws",
        pod_type="p1.x1",
        replicas=2,
    ),
)
```

## Test Plan

- [x] Unit tests for ServerlessDeployment serialization
- [x] Unit tests for ByocDeployment serialization
- [x] Unit tests for PodDeployment with various options
- [x] mypy type checking passes

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: this PR only adds new model/dataclass types and exports
them; it doesn’t change existing request flows, but downstream code may
start relying on the new `to_dict` serialization format.
>
> **Overview**
> Adds new deployment configuration dataclasses (`ServerlessDeployment`,
`ByocDeployment`, `PodDeployment`) with `to_dict()` serialization and a
`Deployment` union type in `db_control/models/deployment.py`.
>
> Exports these types through `pinecone.db_control.models` and top-level
`pinecone` lazy imports, and adds unit tests validating constructor
defaults and `to_dict()` output across deployment variants.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
c2e965d. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: jhamon

codegen/apis

@@ -116,6 +116,11 @@
     "SemanticTextField": ("pinecone.db_control.models", "SemanticTextField"),
     "SchemaField": ("pinecone.db_control.models", "SchemaField"),
     "SchemaBuilder": ("pinecone.db_control.models", "SchemaBuilder"),
+    # Deployment classes
+    "ServerlessDeployment": ("pinecone.db_control.models", "ServerlessDeployment"),
+    "ByocDeployment": ("pinecone.db_control.models", "ByocDeployment"),
+    "PodDeployment": ("pinecone.db_control.models", "PodDeployment"),
+    "Deployment": ("pinecone.db_control.models", "Deployment"),
     # Read capacity TypedDict classes
     "ScalingConfigManualDict": (
         "pinecone.db_control.models.serverless_spec",

pinecone/__init__.py

@@ -21,6 +21,7 @@
     SchemaField,
 )
 from .schema_builder import SchemaBuilder
+from .deployment import ServerlessDeployment, ByocDeployment, PodDeployment, Deployment
 
 
 __all__ = [
@@ -46,4 +47,8 @@
     "SemanticTextField",
     "SchemaField",
     "SchemaBuilder",
+    "ServerlessDeployment",
+    "ByocDeployment",
+    "PodDeployment",
+    "Deployment",
 ]

pinecone/db_control/models/__init__.py

@@ -0,0 +1,134 @@
+"""Deployment model classes for index deployment configurations.
+
+These classes represent different deployment configurations for Pinecone indexes,
+including serverless, BYOC (bring-your-own-cloud), and pod-based deployments.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ServerlessDeployment:
+    """Serverless deployment configuration.
+
+    Serverless indexes are fully managed by Pinecone and automatically scale
+    based on usage.
+
+    :param cloud: The cloud provider ("aws", "gcp", or "azure").
+    :param region: The cloud region (e.g., "us-east-1", "us-central1").
+
+    Example usage::
+
+        from pinecone import ServerlessDeployment
+
+        deployment = ServerlessDeployment(cloud="aws", region="us-east-1")
+
+        pc.create_index(
+            name="my-index",
+            schema=schema,
+            deployment=deployment,
+        )
+    """
+
+    cloud: str
+    region: str
+
+    def to_dict(self) -> dict:
+        """Serialize to API format.
+
+        :returns: Dictionary representation for the API.
+        """
+        return {"deployment_type": "serverless", "cloud": self.cloud, "region": self.region}
+
+
+@dataclass
+class ByocDeployment:
+    """Bring-your-own-cloud (BYOC) deployment configuration.
+
+    BYOC deployments run in your own cloud infrastructure with a
+    Pinecone-managed control plane.
+
+    :param environment: The BYOC environment identifier.
+
+    Example usage::
+
+        from pinecone import ByocDeployment
+
+        deployment = ByocDeployment(environment="aws-us-east-1-b92")
+
+        pc.create_index(
+            name="my-index",
+            schema=schema,
+            deployment=deployment,
+        )
+    """
+
+    environment: str
+
+    def to_dict(self) -> dict:
+        """Serialize to API format.
+
+        :returns: Dictionary representation for the API.
+        """
+        return {"deployment_type": "byoc", "environment": self.environment}
+
+
+@dataclass
+class PodDeployment:
+    """Pod-based deployment configuration.
+
+    Pod deployments provide dedicated compute resources with configurable
+    replicas, shards, and pod types.
+
+    :param environment: The pod environment (e.g., "us-east-1-aws").
+    :param pod_type: The pod type (e.g., "p1.x1", "s1.x1", "p2.x1").
+    :param replicas: Number of replicas (default: 1).
+    :param shards: Number of shards (default: 1).
+    :param pods: Total number of pods (replicas * shards). If not specified,
+        it will be calculated from replicas and shards.
+
+    Example usage::
+
+        from pinecone import PodDeployment
+
+        deployment = PodDeployment(
+            environment="us-east-1-aws",
+            pod_type="p1.x1",
+            replicas=2,
+            shards=1,
+        )
+
+        pc.create_index(
+            name="my-index",
+            schema=schema,
+            deployment=deployment,
+        )
+    """
+
+    environment: str
+    pod_type: str
+    replicas: int = 1
+    shards: int = 1
+    pods: int | None = None
+
+    def to_dict(self) -> dict:
+        """Serialize to API format.
+
+        :returns: Dictionary representation for the API.
+        """
+        result: dict = {
+            "deployment_type": "pod",
+            "environment": self.environment,
+            "pod_type": self.pod_type,
+            "replicas": self.replicas,
+            "shards": self.shards,
+        }
+        if self.pods is not None:
+            result["pods"] = self.pods
+        return result
+
+
+# Type alias for any deployment type
+Deployment = ServerlessDeployment | ByocDeployment | PodDeployment

pinecone/db_control/models/deployment.py

@@ -44,6 +44,12 @@
     CreateIndexFromBackupRequest,
 )
 from pinecone.db_control.models import ServerlessSpec, PodSpec, ByocSpec, IndexModel, IndexEmbed
+from pinecone.db_control.models.deployment import (
+    ServerlessDeployment,
+    PodDeployment,
+    ByocDeployment,
+)
+from pinecone.db_control.models.schema_fields import DenseVectorField, SparseVectorField
 
 from pinecone.db_control.enums import (
     Metric,
@@ -361,6 +367,119 @@ def __parse_index_spec(spec: Dict | ServerlessSpec | PodSpec | ByocSpec) -> Inde
 
         return cast(IndexSpec, index_spec)
 
+    @staticmethod
+    def _translate_legacy_request(
+        spec: Dict | ServerlessSpec | PodSpec | ByocSpec,
+        dimension: int | None = None,
+        metric: (Metric | str) | None = None,
+        vector_type: (VectorType | str) | None = VectorType.DENSE,
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Translate legacy spec-based request to deployment + schema format.
+
+        This method converts legacy index creation parameters (spec, dimension, metric,
+        vector_type) to the new API format using deployment and schema structures.
+
+        :param spec: The legacy spec (ServerlessSpec, PodSpec, ByocSpec, or dict).
+        :param dimension: The vector dimension (for dense vectors).
+        :param metric: The distance metric (cosine, euclidean, dotproduct).
+        :param vector_type: The vector type (dense or sparse).
+        :returns: A tuple of (deployment_dict, schema_dict) for the new API format.
+
+        **Translation Mappings:**
+
+        * `ServerlessSpec(cloud, region)` → `deployment` with `deployment_type="serverless"`
+        * `PodSpec(environment, ...)` → `deployment` with `deployment_type="pod"`
+        * `ByocSpec(environment)` → `deployment` with `deployment_type="byoc"`
+        * `dimension` + `metric` + `vector_type="dense"` → `schema.fields._values` (dense_vector)
+        * `vector_type="sparse"` → `schema.fields._sparse_values` (sparse_vector)
+
+        Example::
+
+            deployment, schema = PineconeDBControlRequestFactory._translate_legacy_request(
+                spec=ServerlessSpec(cloud="aws", region="us-east-1"),
+                dimension=1536,
+                metric="cosine",
+                vector_type="dense"
+            )
+            # Returns:
+            # (
+            #     {"deployment_type": "serverless", "cloud": "aws", "region": "us-east-1"},
+            #     {"fields": {"_values": {"type": "dense_vector", "dimension": 1536, "metric": "cosine"}}}
+            # )
+        """
+        # Convert metric to string if it's an enum
+        if metric is not None:
+            metric = convert_enum_to_string(metric)
+        if vector_type is not None:
+            vector_type = convert_enum_to_string(vector_type)
+
+        # Translate spec to deployment
+        deployment_dict: dict[str, Any]
+        if isinstance(spec, dict):
+            if "serverless" in spec:
+                serverless_spec = spec["serverless"]
+                deployment = ServerlessDeployment(
+                    cloud=serverless_spec.get("cloud", ""), region=serverless_spec.get("region", "")
+                )
+                deployment_dict = deployment.to_dict()
+            elif "pod" in spec:
+                pod_spec = spec["pod"]
+                deployment = PodDeployment(
+                    environment=pod_spec.get("environment", ""),
+                    pod_type=pod_spec.get("pod_type", "p1.x1"),
+                    replicas=pod_spec.get("replicas", 1),
+                    shards=pod_spec.get("shards", 1),
+                    pods=pod_spec.get("pods"),
+                )
+                deployment_dict = deployment.to_dict()
+            elif "byoc" in spec:
+                byoc_spec = spec["byoc"]
+                deployment = ByocDeployment(environment=byoc_spec.get("environment", ""))
+                deployment_dict = deployment.to_dict()
+            else:
+                raise ValueError("spec must contain either 'serverless', 'pod', or 'byoc' key")
+        elif isinstance(spec, ServerlessSpec):
+            deployment = ServerlessDeployment(cloud=spec.cloud, region=spec.region)
+            deployment_dict = deployment.to_dict()
+        elif isinstance(spec, PodSpec):
+            # PodDeployment requires pod_type, but PodSpec defaults to "p1.x1"
+            pod_type = spec.pod_type if spec.pod_type is not None else "p1.x1"
+            deployment = PodDeployment(
+                environment=spec.environment,
+                pod_type=pod_type,
+                replicas=spec.replicas or 1,
+                shards=spec.shards or 1,
+                pods=spec.pods,
+            )
+            deployment_dict = deployment.to_dict()
+        elif isinstance(spec, ByocSpec):
+            deployment = ByocDeployment(environment=spec.environment)
+            deployment_dict = deployment.to_dict()
+        else:
+            raise TypeError("spec must be of type dict, ServerlessSpec, PodSpec, or ByocSpec")
+
+        # Translate dimension/metric/vector_type to schema
+        schema_dict: dict[str, Any] = {"fields": {}}
+        if vector_type == VectorType.SPARSE.value:
+            # Sparse vector: use _sparse_values field
+            if metric is None:
+                metric = "dotproduct"  # Default for sparse vectors
+            sparse_field = SparseVectorField(metric=metric)
+            schema_dict["fields"]["_sparse_values"] = sparse_field.to_dict()
+        elif vector_type == VectorType.DENSE.value:
+            # Dense vector: use _values field
+            if dimension is None:
+                raise ValueError("dimension is required for dense vector indexes")
+            if metric is None:
+                metric = Metric.COSINE.value  # Default for dense vectors
+            dense_field = DenseVectorField(dimension=dimension, metric=metric)
+            schema_dict["fields"]["_values"] = dense_field.to_dict()
+        else:
+            # No vector type specified - return empty schema fields
+            pass
+
+        return deployment_dict, schema_dict
+
     @staticmethod
     def create_index_request(
         name: str,