Python SDK

3 min read

We provide a Python SDK for the pure Pythonista's out there. Our package needle-python is available on PyPI and can be installed like so:

pip install needle-python

or if you are using uv for your project:

uv add needle-python

Quickstart

To get started, get your API key in Needle Settings. Note that your key will be valid until you revoke it. Set the following env variable before you run your code:

export NEEDLE_API_KEY=<your-api-key>

NeedleClient reads the API key from the environment by default. If you like to override this behaviour you can pass it in as a parameter.

Retrieve context from Needle

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


needle = NeedleClient()
collection = needle.collections.create(name="AI platforms")

# add file to collection
files = needle.collections.files.add(
    collection_id=collection.id,
    files=[
        FileToAdd(
            name="Needle Website",
            url="https://needle-ai.com",
        )
    ],
)

# retrieve relevant context
prompt = "What files types are supported in Needle?"
results = needle.collections.search(collection.id, text=prompt)

Needle instantly extracts key points from your files.

Complete your RAG pipeline

Naturally, to compose a human friendly answer use an LLM provider of your choice. For the demo purposes, we used OpenAI in this example:

from openai import OpenAI

system_messages = [{"role": "system", "content": r.content} for r in results] # results from Needle
user_message = {
    "role": "system",
    "content": f"""
        Only answer the question based on the provided results data.
        If there is no data in the provided data for the question, do not try to generate an answer.
        This is the question: {prompt}
    """,
}

openai_client = OpenAI()
answer = openai_client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        *system_messages,
        user_message,
    ],
)

print(answer.choices[0].message.content)

This is one basic example of a RAG pipeline you can quickly implement using Needle and OpenAI. Feel free to engineer more precise prompts and explore other prompting techniques such as chain-of-thoughts (CoT), graph of thoughts (GoT) etc.

Needle API helps you with hassle-free contextualization however does not limit you to a certain RAG technique. Let us know what you build in our Discord channel.

Exceptions

If a request to Needle API fails, needle.v1.models.Error object will be thrown. There you can see a message and more details about the error.

Additional Resources

See our API Reference for the extensive list of supported functionality.

Support

If you have questions you can contact us in our Discord channel.

License

needle-python is distributed under the terms of the MIT license.