Daita Logo

Pinecone Plugin

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

#Installation

bash
pip install pinecone

#Quick Start

python
from daita import Agent
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 = Agent(
    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

python
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:

python
from daita import Agent
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 = Agent(
    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:

ToolDescriptionParameters
pinecone_searchSearch for similar vectorsvector (required), top_k (int), filter (object), namespace (string)
pinecone_upsertInsert or update vectorsids (required), vectors (required), metadata (array), namespace (string)
pinecone_deleteDelete vectorsids (array), filter (object), namespace (string), delete_all (boolean)
pinecone_statsGet index statisticsNone

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

#Tool Usage Example

python
from daita import Agent
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 = Agent(
    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

python
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:

python
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

IssueSolution
pinecone not installedpip install pinecone
Authentication failedVerify API key is correct
Index not foundCheck index name, ensure index exists in Pinecone console
Dimension mismatchEnsure all vectors match index dimension
Rate limit exceededImplement exponential backoff, upgrade plan
Namespace not foundNamespaces are created automatically on first upsert

#Common Patterns

Semantic search with filters:

python
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:

python
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:

python
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