needle-python

What it is and what it does

needle-python is a client library that wraps the Needle API, a service for indexing documents and performing semantic search. It abstracts the REST API into Python objects and methods, allowing you to create collections, upload files (from URLs), wait for indexing, and retrieve semantically relevant context from your documents. The library is designed to integrate into RAG pipelines—you use it to extract relevant passages from your indexed documents, then feed those passages as context to an LLM (like OpenAI's GPT) to generate grounded answers.

The library depends only on requests for HTTP communication and supports Python 3.8 through 3.13. It reads your Needle API key from the NEEDLE_API_KEY environment variable by default, though you can pass it explicitly. The fact sheet shows the library is in Beta status, with modest but stable maintenance; it has not been updated recently but has no known vulnerabilities and a permissive MIT license.

Use it for

• Build a RAG system that indexes PDFs or web documents and retrieves relevant passages to answer user questions grounded in those documents.
• Create a knowledge base where users can upload files to a collection and search across them semantically without writing custom indexing logic.
• Prototype LLM applications that need to augment prompts with real document context, reducing hallucination by grounding answers in indexed material.
• Integrate document search into an existing Python application without managing your own vector database or embedding infrastructure.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

needle-python on PyPI

Before you install

Low install friction with a single runtime dependency (requests). Maintenance status is aging—last commit was 2025-07-27, roughly 383 days after initial release, with modest repository activity (45 stars). No recent updates suggest the library is stable but not actively developed.

Requires NEEDLE_API_KEY environment variable or explicit API key parameter; Python >=3.8 required.

License in practice

MIT license (permissive) means you can use, modify, and distribute this library with minimal restrictions, provided you retain the license notice.

Quickstart

pip install needle-python

from needle.v1 import NeedleClient
from needle.v1.models import FileToAdd

ndl = NeedleClient()
collection = ndl.collections.create(name="My Collection")
files = ndl.collections.files.add(
    collection_id=collection.id,
    files=[FileToAdd(name="doc.pdf", url="https://example.com/doc.pdf")]
)
results = ndl.collections.search(collection.id, text="query")

Package facts

Evidence: needle_python-0.6.0-py3-none-any.whl

Tags

More Python Modules packages

See also h2ogpte · llama-index-core · langchain-graph-retriever · agent-framework-azure-ai-search · llama-index-vector-stores-lancedb · lightrag-hku · graph-retriever · llama-index-embeddings-azure-openai · ragstack-ai-knowledge-store · pyvespa