Pinecone Python SDK

The Pinecone Python SDK (published on PyPI as pinecone-client, with newer releases under the pinecone package name) is the officially maintained client for Pinecone’s managed vector database. It provides synchronous and asyncio interfaces for creating and managing indexes, upserting and querying vector embeddings, and running inference operations directly from Python.

Maintained by Pinecone, Inc., the SDK is a common dependency in retrieval-augmented-generation (RAG) and semantic search stacks, wrapping Pinecone’s REST/gRPC control and data planes behind a typed, ergonomic API.

What You Get

• Synchronous (Pinecone) and asyncio (AsyncPinecone) client classes sharing the same API surface
• Serverless and pod-based index creation/management via ServerlessSpec/PodSpec
• Vector upsert, query, fetch, and delete operations with batching and namespace support
• Built-in inference client for embedding generation and reranking through Pinecone’s hosted models
• Automatic retry logic with adaptive concurrency (AIMD) tuned against Pinecone’s rate limits

Common Use Cases

• Building retrieval-augmented-generation (RAG) pipelines backed by Pinecone vector search
• Storing and querying embeddings for semantic search or recommendation systems
• Managing serverless Pinecone indexes programmatically as part of a data pipeline
• Using the async client inside FastAPI or other asyncio-based services for non-blocking vector queries

Under The Hood

Architecture - The SDK layers a Python control-plane/data-plane client (pinecone/control, pinecone/data, pinecone/db_control, pinecone/db_data) over generated REST/OpenAPI models, with an internal adaptive-concurrency module (pinecone._internal.adaptive) implementing AIMD-style throttling to stay within Pinecone’s live API rate limits, plus an optional Rust extension (rust/, via Cargo) for performance-critical paths. Tech Stack - Modern Python packaging via uv and pyproject.toml, a small Rust component built with Cargo, mypy strict type checking, and Ruff for linting/formatting; the package supports Python 3.10+. Code Quality - The repo separates fast, mocked unit tests (tests/unit) from opt-in live-API integration/retry-smoke tests (tests/integration/test_retry_smoke.py) that validate real rate-limit behavior before releases touching the HTTP transport, reflecting a mature, release-conscious testing discipline. API Design - The client exposes a small, discoverable surface (Pinecone(api_key=...), pc.indexes.create(...), index.upsert(...), index.query(...)) with near-identical sync/async variants, environment-variable API key support, and configurable timeouts, giving it a low learning curve for a service-specific SDK.