{"id":9134,"library":"needle-python","title":"Needle Python Client Library","description":"needle-python is the official client library for the Needle API. It simplifies the process of building Retrieval-Augmented Generation (RAG) pipelines, enabling semantic search and efficient contextualization for Large Language Models (LLMs). The library, currently at version 0.6.0, provides tools for managing collections, uploading files, and performing contextual searches. It is actively maintained with a focus on API integration and RAG pipeline development.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/needle-ai/needle-python","tags":["RAG","LLM","AI","semantic search","API client","contextualization","information retrieval"],"install":[{"cmd":"pip install needle-python","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Requires Python 3.8 or newer, but less than 4.0.","package":"python","optional":false}],"imports":[{"note":"The client library is namespaced under 'v1' to indicate the API version. Direct import from 'needle' will fail.","wrong":"from needle import NeedleClient","symbol":"NeedleClient","correct":"from needle.v1 import NeedleClient"},{"note":"Data models, like 'FileToAdd', are located in the 'models' submodule under the 'v1' API namespace.","wrong":"from needle import FileToAdd","symbol":"FileToAdd","correct":"from needle.v1.models import FileToAdd"}],"quickstart":{"code":"import os\nfrom needle.v1 import NeedleClient\nfrom needle.v1.models import FileToAdd\nimport time # For waiting during indexing\n\n# Ensure your API key is set as an environment variable or pass it directly\n# os.environ['NEEDLE_API_KEY'] = 'YOUR_API_KEY_HERE'\nneedle_api_key = os.environ.get('NEEDLE_API_KEY', '')\nif not needle_api_key:\n    print(\"Warning: NEEDLE_API_KEY environment variable not set. Client may fail to authenticate.\")\n\n# Initialize the client\n# You can also pass the api_key directly: needle = NeedleClient(api_key=needle_api_key)\nneedle = NeedleClient()\n\n# Create a new collection\ncollection_name = \"My AI Project Docs\"\nprint(f\"Creating collection: {collection_name}\")\ncollection = needle.collections.create(name=collection_name)\ncollection_id = collection.id\nprint(f\"Collection '{collection.name}' created with ID: {collection_id}\")\n\n# Add files to the collection (e.g., from a URL)\nfile_url = \"https://www.thoughtworks.com/content/dam/thoughtworks/documents/radar/2024/04/tr_technology_radar_vol_30_en.pdf\"\nfile_name = \"tech-radar-30.pdf\"\nprint(f\"Adding file '{file_name}' from {file_url} to collection {collection_id}\")\n\nfiles_to_add = [\n    FileToAdd(name=file_name, url=file_url)\n]\nneedle.collections.files.add(collection_id=collection_id, files=files_to_add)\n\n# Wait for files to be indexed (indexing takes time)\nprint(\"Waiting for files to be indexed...\")\nfor _ in range(10): # Poll for up to 50 seconds\n    current_files = needle.collections.files.list(collection_id)\n    if all(f.status == \"indexed\" for f in current_files):\n        print(\"All files indexed successfully.\")\n        break\n    time.sleep(5)\nelse:\n    print(\"Warning: Not all files indexed within expected time.\")\n\n# Perform a semantic search\nsearch_prompt = \"What techniques moved into adopt in this volume of technology radar?\"\nprint(f\"Searching collection {collection_id} for prompt: '{search_prompt}'\")\nresults = needle.collections.search(collection_id, text=search_prompt)\n\nprint(\"\\nSearch Results (context snippets):\")\nfor r in results:\n    print(f\"- {r.content[:100]}...\")\n\n# Clean up (optional) - delete the collection\n# print(f\"Deleting collection {collection_id}\")\n# needle.collections.delete(collection_id)\n# print(\"Collection deleted.\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the Needle client, create a document collection, add a file via URL, wait for it to be indexed, and then perform a semantic search to retrieve relevant context. It highlights the use of `NEEDLE_API_KEY` for authentication and the typical workflow for building RAG components."},"warnings":[{"fix":"Always use `pip install needle-python` and `from needle.v1 import ...`. Verify the package summary on PyPI if unsure.","message":"There are several unrelated Python libraries also named 'needle' (e.g., for visual testing, deep learning, or threading). Ensure you install `needle-python` and import from `needle.v1` to use the Needle API client library.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set the `NEEDLE_API_KEY` environment variable (e.g., `export NEEDLE_API_KEY='your_key'`) or pass the key directly to the `NeedleClient` constructor: `NeedleClient(api_key='your_key')`.","message":"The client requires an API key for authentication. If `NEEDLE_API_KEY` is not set as an environment variable, API calls will fail with authentication errors.","severity":"breaking","affected_versions":"All versions"},{"fix":"Implement a polling mechanism to check the `status` of files within the collection until they are marked as 'indexed' before performing search operations, as shown in the quickstart example.","message":"After adding files to a collection, Needle processes and indexes them asynchronously. Direct search queries immediately after `add` might not return results until indexing is complete.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor official documentation and release notes for breaking changes related to API version updates. Be prepared to update import paths and client interactions accordingly.","message":"The import path `from needle.v1 import ...` indicates API versioning. Future major API changes might introduce a `v2` or alter the structure under `v1`, potentially requiring updates to import statements and method calls.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `needle-python` is installed using `pip install needle-python`. Confirm your import statement is `from needle.v1 import NeedleClient`.","cause":"The `needle-python` package is either not installed, or an incorrect 'needle' package (not the API client) is installed. Or, the import path is incorrect.","error":"ModuleNotFoundError: No module named 'needle.v1'"},{"fix":"Set the `NEEDLE_API_KEY` environment variable with a valid key obtained from your Needle settings, or pass the key directly to `NeedleClient(api_key='YOUR_KEY')`.","cause":"The Needle API key (`NEEDLE_API_KEY`) is missing or invalid, preventing the client from authenticating with the API.","error":"needle.v1.models.Error: Authentication Failed"},{"fix":"Add error handling and check the return value of API calls before accessing its attributes. For example: `collection = needle.collections.create(...)` then `if collection: collection_id = collection.id`.","cause":"This typically occurs if `needle.collections.create()` or other API calls fail to return a valid object (e.g., due to an API error, network issue, or invalid parameters), and `None` is returned instead of an object with an `id` attribute.","error":"AttributeError: 'NoneType' object has no attribute 'id'"}]}