{"id":50827476,"url":"https://github.com/needle-ai/needle-python","last_synced_at":"2026-06-13T20:27:31.166Z","repository":{"id":251949273,"uuid":"837942019","full_name":"needle-ai/needle-python","owner":"needle-ai","description":"Needle simplifies building RAG pipelines.","archived":false,"fork":false,"pushed_at":"2025-07-27T13:10:44.000Z","size":98,"stargazers_count":26,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-28T21:03:07.117Z","etag":null,"topics":["agents","ai","information-retrieval","machine-learning","needle","python","rag","retrieval-augmented-generation","sdk","transformers"],"latest_commit_sha":null,"homepage":"https://needle.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/needle-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-04T13:59:07.000Z","updated_at":"2025-08-07T05:31:24.000Z","dependencies_parsed_at":"2025-01-13T12:22:09.089Z","dependency_job_id":"f7da96ff-c446-43be-a994-fd3e7b45b96c","html_url":"https://github.com/needle-ai/needle-python","commit_stats":null,"previous_names":["oeken/needle-python","needle-ai/needle-python"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/needle-ai/needle-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-ai%2Fneedle-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-ai%2Fneedle-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-ai%2Fneedle-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-ai%2Fneedle-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/needle-ai","download_url":"https://codeload.github.com/needle-ai/needle-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-ai%2Fneedle-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34300110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","information-retrieval","machine-learning","needle","python","rag","retrieval-augmented-generation","sdk","transformers"],"created_at":"2026-06-13T20:27:30.623Z","updated_at":"2026-06-13T20:27:31.161Z","avatar_url":"https://github.com/needle-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Needle Python Library\n\n[![PyPI - Version](https://img.shields.io/pypi/v/needle-python.svg)](https://pypi.org/project/needle-python)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/needle-python.svg)](https://pypi.org/project/needle-python)\n\nThis Python library provides convenient acccess to Needle API. There are various methods and data types which, we believe will help you explore Needle API quickly. There may be some functionality available in REST API earlier than this Python library. In any case, we recommend to take look the the complete [documentation](https://docs.needle.app). Thank you for flying with us. 🚀\n\n## Installation\n\nThis library requires Python \u003e3.8 and `pip` to use. You don't need the sources unless you want to modify it. Install with:\n\n```\npip install needle-python\n```\n\n## Usage ⚡️\n\nTo get started, generate an API key for your account in developer settings menu at [Needle](https://needle.app). Note that your key will be valid until you revoke it. Set the following env variable before you run your code:\n\n```\nexport NEEDLE_API_KEY=\u003cyour-api-key\u003e\n```\n\n`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. \n\n### Retrieve context from Needle\n\n```python\nfrom needle.v1 import NeedleClient\nfrom needle.v1.models import FileToAdd\n\n\nndl = NeedleClient()\ncollection = ndl.collections.create(name=\"Tech Trends\")\n\n# add file to collection\nfiles = ndl.collections.files.add(\n    collection_id=collection_id,\n    files=[\n        FileToAdd(\n            name=\"tech-radar-30.pdf\",\n            url=\"https://www.thoughtworks.com/content/dam/thoughtworks/documents/radar/2024/04/tr_technology_radar_vol_30_en.pdf\",\n        )\n    ],\n)\n\n# wait until indexing is complete\nfiles = ndl.collections.files.list(collection_id)\nif not all(f.status == \"indexed\" for f in files):\n    time.sleep(5)\n    files = ndl.collections.files.list(collection_id)\n\n# retrieve relevant context\nprompt = \"What techniques moved into adopt in this volume of technology radar?\"\nresults = ndl.collections.search(collection_id, text=prompt)\n```\n\nNeedle instantly extracts key points from your files.\n\n### Complete your RAG pipeline\n\nNaturally, to compose a human friendly answer use an LLM provider of your choice. For the demo purposes, we used OpenAI in this example:\n\n```python\nfrom openai import OpenAI\n\nsystem_messages = [{\"role\": \"system\", \"content\": r.content} for r in results] # results from Needle\nuser_message = {\n    \"role\": \"system\",\n    \"content\": f\"\"\"\n        Only answer the question based on the provided results data. \n        If there is no data in the provided data for the question, do not try to generate an answer.\n        This is the question: {prompt}\n\"\"\",\n}\n\nopenai_client = OpenAI()\nanswer = openai_client.chat.completions.create(\n    model=\"gpt-3.5-turbo\",\n    messages=[\n        *system_messages,\n        user_message,\n    ],\n)\n\nprint(answer.choices[0].message.content)\n# -\u003e Retrieval-Augmented Generation (RAG) is the technique that moved into \"Adopt\" in this volume of the Technology Radar.\n```\n\nThis is one basic example of a RAG pipeline you can quicklu 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. \n\nNeedle 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](https://discord.gg/JzJcHgTyZx) :)\n\n## Exceptions 🧨\n\nIf 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.\n\n## Support 📞\n\nIf you have questions you can contact us in our [Discord channel](https://discord.gg/JzJcHgTyZx). \n\n# License\n\n`needle-python` is distributed under the terms of the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneedle-ai%2Fneedle-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneedle-ai%2Fneedle-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneedle-ai%2Fneedle-python/lists"}