feat: add request translator for spec to deployment + schema

[jhamon]

Summary

Adds _translate_legacy_request() method to PineconeDBControlRequestFactory that converts legacy spec-based index creation parameters to the new deployment + schema format required by the alpha API.

Problem

The new Full-Text Search API uses a different structure for index creation:

• Old format: Uses spec (ServerlessSpec/PodSpec/ByocSpec) with top-level dimension and metric parameters
• New format: Uses deployment (with deployment_type) and schema (with field definitions)

To maintain backward compatibility while supporting the new API, we need translation logic that converts the old format to the new format.

Solution

Added _translate_legacy_request() static method that:

1. Converts spec types to deployment:

   • ServerlessSpec(cloud, region) → {"deployment_type": "serverless", "cloud": ..., "region": ...}
   • PodSpec(environment, ...) → {"deployment_type": "pod", "environment": ..., ...}
   • ByocSpec(environment) → {"deployment_type": "byoc", "environment": ...}

2. Converts vector parameters to schema:

   • dimension + metric + vector_type="dense" → schema.fields._values (dense_vector field)
   • vector_type="sparse" → schema.fields._sparse_values (sparse_vector field)

3. Provides sensible defaults:

   • Defaults to "cosine" metric for dense vectors
   • Defaults to "dotproduct" metric for sparse vectors

4. Validates inputs:

   • Requires dimension for dense vector indexes
   • Raises clear errors for invalid spec types

Usage Example

from pinecone.db_control.request_factory import PineconeDBControlRequestFactory
from pinecone import ServerlessSpec

# Translate legacy request format
deployment, schema = PineconeDBControlRequestFactory._translate_legacy_request(
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
    dimension=1536,
    metric="cosine",
    vector_type="dense"
)

# Returns:
# deployment = {"deployment_type": "serverless", "cloud": "aws", "region": "us-east-1"}
# schema = {"fields": {"_values": {"type": "dense_vector", "dimension": 1536, "metric": "cosine"}}}

Testing

Added comprehensive unit tests covering:

• All spec types (Serverless, Pod, BYOC)
• Both object and dict-based spec formats
• Dense and sparse vector translations
• Default metric handling
• Edge cases (missing dimension, invalid spec types)

Related Issues

• Linear: SDK-104
• Part of the Full-Text Search SDK implementation

Value

This translation layer enables backward compatibility by allowing existing code using the legacy spec-based API to work with the new schema-based API. It's a critical building block for the FTS feature set, as it allows the SDK to support both old and new index creation patterns seamlessly.

---

Note

Medium Risk
Medium risk because it introduces new translation/validation logic that will shape index-creation payloads (including defaults and error conditions) and could affect backward-compatibility behavior if edge cases differ from the legacy format.

Overview
Adds PineconeDBControlRequestFactory._translate_legacy_request() to convert legacy index creation inputs (spec plus dimension/metric/vector_type) into the new deployment and schema.fields structures, including enum-to-string normalization, sensible metric defaults (dense→cosine, sparse→dotproduct), and stricter validation (e.g., dense requires dimension, invalid vector_type errors).

Expands unit coverage for the translator across serverless/pod/BYOC (object and dict specs), defaulting behavior, zero-value preservation, and error cases; also simplifies test_deployment.py to import deployment models directly from pinecone instead of dynamically loading the module.

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

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Dict specs with missing required fields return invalid data

Low Severity

When dict-based specs are missing required fields like cloud, region, or environment, the method silently defaults to empty strings instead of failing. This differs from __parse_index_spec which directly accesses these keys (raising KeyError if absent). A dict like {"serverless": {"region": "us-east-1"}} missing cloud would return a deployment with cloud: "", causing a confusing API error later instead of an immediate SDK error.

Additional Locations (2)

• pinecone/db_control/request_factory.py#L428-L430
• pinecone/db_control/request_factory.py#L441-L442