Pinecone Plugin Interface

Warnings

• breaking As a 0.0.x series library, the API is subject to rapid change. Expect potential breaking changes to class signatures, method names, and model structures without major version bumps.
  Fix: Always pin the exact minor version (e.g., `pinecone-plugin-interface==0.0.7`) and thoroughly review release notes upon upgrading.
• gotcha This library provides interfaces, not pre-built plugins. Users must implement the specific logic for their desired plugins by subclassing `TextPlugin` or `FilterPlugin`.
  Fix: Understand that the library defines the contract; you are responsible for writing the plugin's `run` method logic.
• gotcha Requires `pinecone-client>=3.0.0`. Older versions of the Pinecone client do not support the plugin registration mechanism and will raise errors.
  Fix: Ensure `pinecone-client` is updated to version 3.0.0 or higher (`pip install 'pinecone-client>=3.0.0'`).
• gotcha Plugins must be explicitly registered with a Pinecone index instance (e.g., `index.register_plugin(my_plugin_instance)`) before they can be used. Forgetting this step will mean the plugin is not active.
  Fix: After instantiating your plugin, call the `register_plugin` method on your `pinecone.Index` object.

Install

• pip install pinecone-plugin-interface Install pinecone-plugin-interface

Imports

• Plugin

  from pinecone_plugin_interface.plugin import Plugin

  Base class for all Pinecone plugins.
• TextPlugin

  from pinecone_plugin_interface.plugin import TextPlugin

  Interface for plugins that modify or enrich query text before embedding or indexing.
• FilterPlugin

  from pinecone_plugin_interface.plugin import FilterPlugin

  Interface for plugins that modify or generate filters for Pinecone queries.
• FilterPluginRequest

  from pinecone_plugin_interface.models import FilterPluginRequest

  Pydantic model for incoming filter plugin requests.
• FilterPluginResponse

  from pinecone_plugin_interface.models import FilterPluginResponse

  Pydantic model for outgoing filter plugin responses.

Quickstart

This quickstart demonstrates how to define a simple `FilterPlugin` that intercepts and modifies a filter parameter. The core idea is to subclass `FilterPlugin` (or `TextPlugin`) and implement the `run` asynchronous method. The example shows capitalizing a 'category' filter value. To activate such a plugin, you must instantiate it and then register it with a specific `Pinecone` index instance using `index.register_plugin(plugin_instance)`.

from pinecone_plugin_interface.plugin import FilterPlugin
from pinecone_plugin_interface.models import FilterPluginRequest, FilterPluginResponse
from typing import Dict, Any
import os

class CapitalizeCategoryFilterPlugin(FilterPlugin):
    """
    An example filter plugin that adds a simple metadata filter to capitalize
    the 'category' field for demonstration purposes, effectively applying
    a filter like {'category': {'$eq': 'DOCS'}}.
    """
    def __init__(self, name: str = "capitalize-category-filter", description: str = "Capitalizes category for filtering"):
        super().__init__(name=name, description=description)

    async def run(self, request: FilterPluginRequest) -> FilterPluginResponse:
        # Assume a 'category' key exists in request.metadata or is expected in the filter
        if request.filter and 'category' in request.filter:
            # This example demonstrates modification; in a real scenario,
            # you might look for specific filter patterns to modify.
            # Here, we just illustrate returning a modified filter.
            modified_filter = {"category": {"$eq": request.filter['category'].upper()}}
        else:
            # If no category filter is present, we could add a default or pass through
            modified_filter = request.filter

        return FilterPluginResponse(filter=modified_filter)

# To use this plugin, you would typically register it with a Pinecone index:
# from pinecone import Pinecone
# # Ensure PINECONE_API_KEY and PINECONE_ENVIRONMENT are set in your environment
# pc = Pinecone(api_key=os.environ.get('PINECONE_API_KEY', 'TEST_API_KEY'),
#               environment=os.environ.get('PINECONE_ENVIRONMENT', 'us-west-2'))
# index = pc.Index("my-index") # Replace with your index name
# 
# plugin_instance = CapitalizeCategoryFilterPlugin()
# index.register_plugin(plugin_instance)
# 
# print(f"Plugin '{plugin_instance.name}' registered. Its description is: '{plugin_instance.description}'")
# # You can then call index.query with the plugin applied through a 'plugin_params' argument:
# # query_results = index.query(vector=[0.1, ...], top_k=5, plugin_params={'my-plugin-name': {'category': 'docs'}})