---
id: needle-python
version: "0.6.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# needle-python — Needle client library for Python

License: permissive · Maintenance: aging · Downloads: 174.2K/mo

## 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 above — verify before relying.

Python client library for the Needle API, enabling document indexing, collection management, and semantic search to power retrieval-augmented generation (RAG) pipelines.

Yes, if you need semantic search and document indexing for a RAG pipeline and prefer a managed service over self-hosted infrastructure. The library is straightforward to use, has low install friction, and carries no security vulnerabilities. However, the aging maintenance status (no updates in months) and modest adoption (45 repository stars) suggest you should verify that Needle's API remains actively supported before committing to production use. Suitable for prototyping and moderate-scale applications; evaluate alternatives if you need active development or extensive customization.

## Install

pip install needle-python
uv add needle-python
poetry add needle-python

## Installing needle-python

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.

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")

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

Verify before relying:

- Whether the library's search performance scales well with large document collections or many concurrent requests.
- Current state of API stability and whether breaking changes are expected given the aging maintenance status.
- Whether FileToAdd and other model types support additional parameters beyond name and url for file ingestion.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 174.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

needle api python client, rag retrieval augmented generation, document indexing and search, semantic search library, ai context retrieval, information retrieval python, needle document management, rag, semantic-search, document-indexing

[View on SkillFed](https://skillfed.io/packages/needle-python) · [View on PyPI](https://pypi.org/project/needle-python/)