> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinecone

> Using Pinecone as a vector database provider

## Overview

Pinecone is a managed vector database service designed for production-scale similarity search. It's cloud-only and supports both dense and sparse vectors with automatic scaling.

**Provider Class:** `PineconeProvider`\
**Config Class:** `PineconeConfig`

## Install

<Note>
  Install the Pinecone optional dependency group:

  ```bash theme={null}
  uv pip install "upsonic[pinecone]"
  ```
</Note>

## Examples

```python theme={null}
from upsonic import Agent, Task, KnowledgeBase
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfig
from upsonic.vectordb import PineconeProvider, PineconeConfig
from pydantic import SecretStr

# Setup embedding provider
embedding = OpenAIEmbedding(OpenAIEmbeddingConfig())

# Create Pinecone configuration
config = PineconeConfig(
    collection_name="my_collection",
    vector_size=1536,
    api_key=SecretStr("your-pinecone-api-key"),
    environment="us-east-1-aws",
    namespace="production"
)
vectordb = PineconeProvider(config)

# Create knowledge base
kb = KnowledgeBase(
    sources="document.pdf",
    embedding_provider=embedding,
    vectordb=vectordb
)

# Use with Agent
agent = Agent("anthropic/claude-sonnet-4-5")
task = Task(
    description="Query the knowledge base",
    context=[kb]
)
result = agent.do(task)
```

## Parameters

### Base Parameters (from BaseVectorDBConfig)

| Parameter                      | Type                                         | Description                                              | Default                | Required |
| ------------------------------ | -------------------------------------------- | -------------------------------------------------------- | ---------------------- | -------- |
| `collection_name`              | `str`                                        | Name of the collection                                   | `"default_collection"` | No       |
| `vector_size`                  | `int`                                        | Dimension of vectors                                     | -                      | **Yes**  |
| `distance_metric`              | `DistanceMetric`                             | Similarity metric (`COSINE`, `EUCLIDEAN`, `DOT_PRODUCT`) | `COSINE`               | No       |
| `recreate_if_exists`           | `bool`                                       | Recreate collection if it exists                         | `False`                | No       |
| `default_top_k`                | `int`                                        | Default number of results                                | `10`                   | No       |
| `default_similarity_threshold` | `Optional[float]`                            | Minimum similarity score (0.0-1.0)                       | `None`                 | No       |
| `dense_search_enabled`         | `bool`                                       | Enable dense vector search                               | `True`                 | No       |
| `full_text_search_enabled`     | `bool`                                       | Enable full-text search                                  | `True`                 | No       |
| `hybrid_search_enabled`        | `bool`                                       | Enable hybrid search                                     | `True`                 | No       |
| `default_hybrid_alpha`         | `float`                                      | Default alpha for hybrid search (0.0-1.0)                | `0.5`                  | No       |
| `default_fusion_method`        | `Literal['rrf', 'weighted']`                 | Default fusion method for hybrid search                  | `'weighted'`           | No       |
| `provider_name`                | `Optional[str]`                              | Provider name                                            | `None`                 | No       |
| `provider_description`         | `Optional[str]`                              | Provider description                                     | `None`                 | No       |
| `provider_id`                  | `Optional[str]`                              | Provider ID                                              | `None`                 | No       |
| `default_metadata`             | `Optional[Dict[str, Any]]`                   | Default metadata for all records                         | `None`                 | No       |
| `indexed_fields`               | `Optional[List[Union[str, Dict[str, Any]]]]` | Fields to index for filtering                            | `None`                 | No       |

### Pinecone-Specific Parameters

| Parameter              | Type                                                       | Description                                                                                       | Default                        | Required |
| ---------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------ | -------- |
| `api_key`              | `SecretStr`                                                | Pinecone API key                                                                                  | -                              | **Yes**  |
| `spec`                 | `Optional[Union[Dict[str, Any], ServerlessSpec, PodSpec]]` | Index specification (ServerlessSpec or PodSpec)                                                   | `None`                         | No       |
| `environment`          | `Optional[str]`                                            | Environment/region for backward compatibility (e.g., "aws-us-east-1")                             | `None`                         | No       |
| `namespace`            | `Optional[str]`                                            | Namespace for data isolation                                                                      | `None`                         | No       |
| `metric`               | `Literal['cosine', 'euclidean', 'dotproduct']`             | Distance metric (auto-mapped from `distance_metric`)                                              | `'cosine'`                     | No       |
| `pods`                 | `Optional[int]`                                            | Number of pods (for PodSpec)                                                                      | `None`                         | No       |
| `pod_type`             | `Optional[str]`                                            | Pod type specification (for PodSpec)                                                              | `None`                         | No       |
| `replicas`             | `Optional[int]`                                            | Number of replicas (for PodSpec)                                                                  | `None`                         | No       |
| `shards`               | `Optional[int]`                                            | Number of shards (for PodSpec)                                                                    | `None`                         | No       |
| `host`                 | `Optional[str]`                                            | Custom Pinecone host                                                                              | `None`                         | No       |
| `additional_headers`   | `Optional[Dict[str, str]]`                                 | Additional HTTP headers                                                                           | `None`                         | No       |
| `pool_threads`         | `Optional[int]`                                            | Thread pool size                                                                                  | `1`                            | No       |
| `index_api`            | `Optional[Any]`                                            | Custom index API instance                                                                         | `None`                         | No       |
| `use_sparse_vectors`   | `bool`                                                     | Enable sparse vector support (requires `hybrid_search_enabled=True`, sets metric to `dotproduct`) | `False`                        | No       |
| `sparse_encoder_model` | `str`                                                      | Model for sparse vector generation                                                                | `"pinecone-sparse-english-v0"` | No       |
| `batch_size`           | `int`                                                      | Batch size for upsert operations                                                                  | `100`                          | No       |
| `show_progress`        | `bool`                                                     | Show progress during batch operations                                                             | `False`                        | No       |
| `timeout`              | `Optional[int]`                                            | Request timeout in seconds                                                                        | `None`                         | No       |
| `reranker`             | `Optional[Any]`                                            | Reranker instance for post-processing results                                                     | `None`                         | No       |