{"id":1625,"library":"pinecone-plugin-interface","title":"Pinecone Plugin Interface","description":"The Pinecone Plugin Interface provides base classes and models for developing custom plugins that extend the functionality of the Pinecone Python client. This allows users to implement custom logic for tasks like query pre-processing (text plugins) or result post-processing (filter plugins). The current version is 0.0.7, indicating an early-stage library with potential for frequent updates.","status":"active","version":"0.0.7","language":"en","source_language":"en","source_url":"https://github.com/pinecone-io/python-plugin-interface","tags":["pinecone","plugin","interface","vector database","ai"],"install":[{"cmd":"pip install pinecone-plugin-interface","lang":"bash","label":"Install pinecone-plugin-interface"}],"dependencies":[{"reason":"Required to register and interact with plugins within a Pinecone index instance.","package":"pinecone-client","optional":false}],"imports":[{"note":"Base class for all Pinecone plugins.","symbol":"Plugin","correct":"from pinecone_plugin_interface.plugin import Plugin"},{"note":"Interface for plugins that modify or enrich query text before embedding or indexing.","symbol":"TextPlugin","correct":"from pinecone_plugin_interface.plugin import TextPlugin"},{"note":"Interface for plugins that modify or generate filters for Pinecone queries.","symbol":"FilterPlugin","correct":"from pinecone_plugin_interface.plugin import FilterPlugin"},{"note":"Pydantic model for incoming filter plugin requests.","symbol":"FilterPluginRequest","correct":"from pinecone_plugin_interface.models import FilterPluginRequest"},{"note":"Pydantic model for outgoing filter plugin responses.","symbol":"FilterPluginResponse","correct":"from pinecone_plugin_interface.models import FilterPluginResponse"}],"quickstart":{"code":"from pinecone_plugin_interface.plugin import FilterPlugin\nfrom pinecone_plugin_interface.models import FilterPluginRequest, FilterPluginResponse\nfrom typing import Dict, Any\nimport os\n\nclass CapitalizeCategoryFilterPlugin(FilterPlugin):\n    \"\"\"\n    An example filter plugin that adds a simple metadata filter to capitalize\n    the 'category' field for demonstration purposes, effectively applying\n    a filter like {'category': {'$eq': 'DOCS'}}.\n    \"\"\"\n    def __init__(self, name: str = \"capitalize-category-filter\", description: str = \"Capitalizes category for filtering\"):\n        super().__init__(name=name, description=description)\n\n    async def run(self, request: FilterPluginRequest) -> FilterPluginResponse:\n        # Assume a 'category' key exists in request.metadata or is expected in the filter\n        if request.filter and 'category' in request.filter:\n            # This example demonstrates modification; in a real scenario,\n            # you might look for specific filter patterns to modify.\n            # Here, we just illustrate returning a modified filter.\n            modified_filter = {\"category\": {\"$eq\": request.filter['category'].upper()}}\n        else:\n            # If no category filter is present, we could add a default or pass through\n            modified_filter = request.filter\n\n        return FilterPluginResponse(filter=modified_filter)\n\n# To use this plugin, you would typically register it with a Pinecone index:\n# from pinecone import Pinecone\n# # Ensure PINECONE_API_KEY and PINECONE_ENVIRONMENT are set in your environment\n# pc = Pinecone(api_key=os.environ.get('PINECONE_API_KEY', 'TEST_API_KEY'),\n#               environment=os.environ.get('PINECONE_ENVIRONMENT', 'us-west-2'))\n# index = pc.Index(\"my-index\") # Replace with your index name\n# \n# plugin_instance = CapitalizeCategoryFilterPlugin()\n# index.register_plugin(plugin_instance)\n# \n# print(f\"Plugin '{plugin_instance.name}' registered. Its description is: '{plugin_instance.description}'\")\n# # You can then call index.query with the plugin applied through a 'plugin_params' argument:\n# # query_results = index.query(vector=[0.1, ...], top_k=5, plugin_params={'my-plugin-name': {'category': 'docs'}})","lang":"python","description":"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)`."},"warnings":[{"fix":"Always pin the exact minor version (e.g., `pinecone-plugin-interface==0.0.7`) and thoroughly review release notes upon upgrading.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Understand that the library defines the contract; you are responsible for writing the plugin's `run` method logic.","message":"This library provides interfaces, not pre-built plugins. Users must implement the specific logic for their desired plugins by subclassing `TextPlugin` or `FilterPlugin`.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Ensure `pinecone-client` is updated to version 3.0.0 or higher (`pip install 'pinecone-client>=3.0.0'`).","message":"Requires `pinecone-client>=3.0.0`. Older versions of the Pinecone client do not support the plugin registration mechanism and will raise errors.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"After instantiating your plugin, call the `register_plugin` method on your `pinecone.Index` object.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}