Pinecone Plugin

Managed cloud vector database with serverless and pod-based deployment options. Built on pinecone.

Installation

pip install pinecone

Quick Start

from daita import SubstrateAgent
from daita.plugins import pinecone
import os

# Create plugin
vector_db = pinecone(
    api_key=os.getenv("PINECONE_API_KEY"),
    index="embeddings"
)

# Agent uses vector database tools autonomously
agent = SubstrateAgent(
    name="Vector Search Agent",
    prompt="You are a semantic search assistant. Help users find relevant information.",
    tools=[vector_db]
)

await agent.start()
result = await agent.run("Find documents similar to 'machine learning'")

Direct Usage

The plugin can be used directly without agents for programmatic access. For comprehensive Pinecone API documentation, see the official Pinecone docs. The main value of this plugin is agent integration - enabling LLMs to autonomously perform semantic search operations.

Connection Parameters

pinecone(
    api_key: str,
    index: str,
    namespace: str = "",
    host: Optional[str] = None,
    **kwargs
)

Parameters

• api_key (str, required): Pinecone API key
• index (str, required): Index name to use
• namespace (str): Optional namespace for multi-tenancy (default: "")
• host (str, optional): Optional host URL for serverless Pinecone
• ****kwargs**: Additional Pinecone configuration

Using with Agents

Pinecone plugin exposes vector operations as tools that agents can use autonomously:

from daita import SubstrateAgent
from daita.plugins import pinecone
import os

# Create Pinecone plugin
vector_db = pinecone(
    api_key=os.getenv("PINECONE_API_KEY"),
    index="knowledge_base",
    namespace="production"
)

# Pass plugin to agent - agent can now use Pinecone tools autonomously
agent = SubstrateAgent(
    name="Semantic Search Agent",
    prompt="You are a semantic search assistant. Help users find relevant documents.",
    llm_provider="openai",
    model="gpt-4",
    tools=[vector_db]
)

await agent.start()

# Agent autonomously uses Pinecone tools to answer questions
result = await agent.run("Find documents about machine learning")

# The agent will autonomously:
# 1. Use pinecone_search to find relevant vectors
# 2. Analyze and present results in natural language

await agent.stop()

Available Tools

The Pinecone plugin exposes these tools to LLM agents:

Tool	Description	Parameters
pinecone_search	Search for similar vectors	vector (required), top_k (int), filter (object), namespace (string)
pinecone_upsert	Insert or update vectors	ids (required), vectors (required), metadata (array), namespace (string)
pinecone_delete	Delete vectors	ids (array), filter (object), namespace (string), delete_all (boolean)
pinecone_stats	Get index statistics	None

Tool Categories: vector_db Tool Source: plugin Filter Format: Pinecone filter dict (e.g., {"category": {"$eq": "tech"}})

Tool Usage Example

from daita import SubstrateAgent
from daita.plugins import pinecone
import os

# Setup Pinecone with tool integration
vector_db = pinecone(
    api_key=os.getenv("PINECONE_API_KEY"),
    index="articles"
)

agent = SubstrateAgent(
    name="Research Assistant",
    prompt="You are a research assistant. Help users find and organize information.",
    llm_provider="openai",
    model="gpt-4",
    tools=[vector_db]
)

await agent.start()

# Natural language command - agent uses tools autonomously
result = await agent.run("""
Search for articles about:
1. Neural networks
2. Deep learning
3. Computer vision
Return the top 5 most relevant results.
""")

# Agent orchestrates Pinecone tool calls to fulfill the request
print(result)
await agent.stop()

Error Handling

try:
    async with pinecone(
        api_key=os.getenv("PINECONE_API_KEY"),
        index="documents"
    ) as db:
        results = await db.query(
            vector=[0.1, 0.2, 0.3],
            top_k=5
        )
except ImportError as e:
    if "pinecone" in str(e):
        print("Install pinecone: pip install pinecone")
except Exception as e:
    print(f"Pinecone error: {e}")

Best Practices

Connection Management:

• Use context managers (async with) for automatic cleanup
• Store API keys in environment variables, never hardcode
• Use namespaces to isolate different use cases or tenants
• Monitor index statistics to track usage

Performance:

• Batch upsert operations when inserting multiple vectors
• Use metadata filters to narrow search scope
• Limit top_k to only what you need
• Use namespaces instead of multiple indexes when possible

Data Organization:

• Use meaningful index names for different use cases
• Leverage namespaces for multi-tenant applications
• Include descriptive metadata for better filtering
• Ensure consistent vector dimensions within an index

Security:

• Protect API keys with environment variables or secret management
• Use separate indexes for different environments (dev/staging/prod)
• Apply least privilege principles to API keys
• Rotate API keys periodically

Filtering

Pinecone supports advanced metadata filtering with operators:

async with pinecone(
    api_key=os.getenv("PINECONE_API_KEY"),
    index="documents"
) as db:
    # Equality
    results = await db.query(
        vector=[0.1, 0.2, 0.3],
        top_k=10,
        filter={"category": {"$eq": "tech"}}
    )

    # Greater than
    results = await db.query(
        vector=[0.1, 0.2, 0.3],
        top_k=10,
        filter={"year": {"$gte": 2024}}
    )

    # Multiple conditions
    results = await db.query(
        vector=[0.1, 0.2, 0.3],
        top_k=10,
        filter={
            "$and": [
                {"category": {"$eq": "tech"}},
                {"year": {"$gte": 2024}}
            ]
        }
    )

Troubleshooting

Issue	Solution
pinecone not installed	pip install pinecone
Authentication failed	Verify API key is correct
Index not found	Check index name, ensure index exists in Pinecone console
Dimension mismatch	Ensure all vectors match index dimension
Rate limit exceeded	Implement exponential backoff, upgrade plan
Namespace not found	Namespaces are created automatically on first upsert

Common Patterns

Semantic search with filters:

async with pinecone(
    api_key=os.getenv("PINECONE_API_KEY"),
    index="docs"
) as db:
    results = await db.query(
        vector=query_embedding,
        top_k=10,
        filter={"category": {"$eq": "tech"}, "published": {"$gte": "2024"}}
    )

Multi-tenant search:

async with pinecone(
    api_key=os.getenv("PINECONE_API_KEY"),
    index="shared"
) as db:
    results = await db.query(
        vector=query_embedding,
        top_k=5,
        namespace=f"user_{user_id}"
    )

Index monitoring:

async with pinecone(
    api_key=os.getenv("PINECONE_API_KEY"),
    index="docs"
) as db:
    stats = await db.describe_index_stats()
    if stats['index_fullness'] > 0.8:
        print("Warning: Index nearly full")

Next Steps

• Plugin Overview - All available plugins
• ChromaDB Plugin - Embeddable vector database
• Qdrant Plugin - Self-hosted vector database