{"id":9182,"library":"pinecone-text","title":"Pinecone Text Client","description":"The Pinecone Text Client is a Python package that provides text utilities for generating sparse, dense, and hybrid vector embeddings. It is designed for seamless integration with Pinecone's vector database to facilitate sparse-dense (hybrid) semantic search. Currently, it is a public preview ('Beta') version, with the latest release being 0.11.0. Release cadence is infrequent, focusing on feature additions and improvements within its beta phase.","status":"active","version":"0.11.0","language":"en","source_language":"en","source_url":"https://github.com/pinecone-io/pinecone-text-python","tags":["text processing","embeddings","vector search","sparse vectors","dense vectors","hybrid search","pinecone","nlp"],"install":[{"cmd":"pip install pinecone-text","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for interacting with the Pinecone vector database, as pinecone-text provides embedding utilities that are typically used to prepare data for Pinecone indexes.","package":"pinecone","optional":false},{"reason":"Required if using the `OpenAIEncoder` for dense vector generation.","package":"openai","optional":true},{"reason":"Underlying dependency for SPLADE and Sentence Transformer models; incompatibility issues exist with Python 3.12.","package":"torch","optional":true}],"imports":[{"symbol":"OpenAIEncoder","correct":"from pinecone_text.dense import OpenAIEncoder"},{"symbol":"AzureOpenAIEncoder","correct":"from pinecone_text.dense import AzureOpenAIEncoder"},{"symbol":"SpladeEncoder","correct":"from pinecone_text.sparse import SpladeEncoder"},{"symbol":"BM25Encoder","correct":"from pinecone_text.sparse import BM25Encoder"},{"symbol":"hybrid_convex_scale","correct":"from pinecone_text.hybrid import hybrid_convex_scale"}],"quickstart":{"code":"import os\nfrom pinecone_text.dense import OpenAIEncoder\n\n# Ensure OPENAI_API_KEY is set in your environment\n# For quick testing, you can uncomment and set it directly, but prefer environment variables\n# os.environ[\"OPENAI_API_KEY\"] = \"YOUR_OPENAI_API_KEY\"\n\nif not os.environ.get(\"OPENAI_API_KEY\"):\n    print(\"Error: OPENAI_API_KEY environment variable not set.\")\n    print(\"Please set it or uncomment the line above for testing.\")\nelse:\n    try:\n        encoder = OpenAIEncoder() # Defaults to 'text-embedding-3-small'\n        documents = [\n            \"The quick brown fox jumps over the lazy dog\",\n            \"Artificial intelligence is transforming industries\"\n        ]\n        queries = [\n            \"Who jumped over the lazy dog?\",\n            \"What is AI doing?\"\n        ]\n\n        document_vectors = encoder.encode_documents(documents)\n        query_vectors = encoder.encode_queries(queries)\n\n        print(f\"Encoded document 1 vector (first 5 elements): {document_vectors[0][:5]}...\")\n        print(f\"Encoded query 1 vector (first 5 elements): {query_vectors[0][:5]}...\")\n    except Exception as e:\n        print(f\"An error occurred during encoding: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize the `OpenAIEncoder` and use it to generate dense vector embeddings for both documents and queries. It highlights the necessity of setting the `OPENAI_API_KEY` environment variable."},"warnings":[{"fix":"Monitor official documentation and release notes for breaking changes and updates. Test thoroughly when upgrading.","message":"The `pinecone-text` library is currently in 'public preview' ('Beta'). This means its API or behavior may change in future updates.","severity":"gotcha","affected_versions":"0.1.0 - 0.11.0"},{"fix":"Remove `pinecone-client` from your `requirements.txt` or `pyproject.toml` and add `pinecone` instead. For example, `pip uninstall pinecone-client && pip install pinecone`.","message":"The main Pinecone Python SDK was renamed from `pinecone-client` to `pinecone` in version 5.1.0. If you are migrating or have existing projects, ensure you update your dependencies to `pinecone` to get the latest features and avoid conflicts.","severity":"breaking","affected_versions":"pinecone-client < 5.1.0"},{"fix":"Be aware of this limitation when building systems where document frequencies are expected to change frequently. Consider re-fitting the BM25 model if the corpus changes significantly, or use alternative sparse encoding methods.","message":"The `BM25Encoder` currently supports only static document frequency. This means precomputed document frequency values are fixed and do not dynamically update when new documents are added to a collection.","severity":"gotcha","affected_versions":"0.1.0 - 0.11.0"},{"fix":"Use Python versions 3.9, 3.10, or 3.11 if you need to use SPLADE or Sentence Transformer models. Check `pinecone-text` release notes for future Python 3.12 compatibility updates.","message":"Using SPLADE and Sentence Transformer models with `pinecone-text` is not currently supported on Python 3.12 due to compatibility issues with PyTorch.","severity":"breaking","affected_versions":"0.1.0 - 0.11.0 with Python 3.12"},{"fix":"Set the `OPENAI_API_KEY` (or `AZURE_OPENAI_API_KEY` and other Azure-specific variables for `AzureOpenAIEncoder`) environment variable before importing and instantiating the encoder class.","message":"When using `OpenAIEncoder` or `AzureOpenAIEncoder`, the corresponding API key (e.g., `OPENAI_API_KEY`) must be set as an environment variable before the encoder is initialized.","severity":"gotcha","affected_versions":"0.1.0 - 0.11.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Set the environment variable: `export OPENAI_API_KEY='your_api_key'` in your shell, or `os.environ['OPENAI_API_KEY'] = 'your_api_key'` in your Python script before initializing `OpenAIEncoder`.","cause":"The `OpenAIEncoder` requires the `OPENAI_API_KEY` environment variable to be set, but it was not found.","error":"KeyError: 'OPENAI_API_KEY'"},{"fix":"Update your imports from `pinecone_client` to `pinecone`. Also, ensure you have `pinecone` installed: `pip install pinecone` and `pip uninstall pinecone-client` if it's still present.","cause":"You are trying to import `pinecone_client` which is the old name for the main Pinecone Python SDK. The package was renamed to `pinecone`.","error":"ModuleNotFoundError: No module named 'pinecone_client'"},{"fix":"Downgrade your Python environment to version 3.9, 3.10, or 3.11 if you need to use these specific encoders. Monitor `pinecone-text` release notes for updates on Python 3.12 compatibility.","cause":"You are attempting to use SPLADE or Sentence Transformer encoders with Python 3.12, which currently has known compatibility issues due to PyTorch.","error":"RuntimeError: 'Unsupported Python version for SPLADE/Sentence Transformers'"}]}