| Name | neurosurfer JSON |
| Version |
0.1.0.post2
JSON |
| download |
| home_page | None |
| Summary | Neurosurfer: production-ready AI agent framework with multi-LLM, RAG, tools, and FastAPI server |
| upload_time | 2025-11-05 18:49:27 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
llm
agents
rag
transformers
fastapi
chromadb
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img src="https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/banner/neurosurfer_banner_black.png" alt="Neurosurfer — AI Agent Framework" width="50%"/>
<img src="https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/neurosurfer_water_wave.svg" alt="Neurosurfer — AI Agent Framework" width="100%"/>
<a href="https://naumanhsa.github.io/neurosurfer/#quick-start" target="_blank"><img src="https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/buttons/quick_start_button.png" height="40" alt="Quick Start"></a>
<a href="https://naumanhsa.github.io/neurosurfer/examples/" target="_blank"><img src="https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/buttons/examples_button.png" height="40" alt="Examples"></a>
<a href="https://naumanhsa.github.io/neurosurfer/" target="_blank"><img src="https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/buttons/documentation_button.png" height="40" alt="Documentation"></a>
<a href="https://pypi.org/project/neurosurfer/" target="_blank"><img src="https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/buttons/pypi_button.png" height="40" alt="PyPI"></a>
<a href="https://discord.gg/naumanhsa" target="_blank"><img src="https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/buttons/discord_button.png" height="40" alt="Discord"></a>
</div>
**Neurosurfer** helps you build intelligent apps that blend **LLM reasoning**, **tools**, and **retrieval** with a ready-to-run **FastAPI** backend and a **React** dev UI. Start lean, add power as you go — CPU-only or GPU-accelerated.
- 🧩 **OpenAI-style API** with streaming & tool-calling
- 📚 **RAG-ready**: ingest → chunk → retrieve → augment
- 🤖 **Agents** (ReAct, SQL, RAG) + 🔧 **Tools** (calc, web, custom)
- 🧠 **Multi-LLM**: OpenAI, Transformers/Unsloth, vLLM, Llama.cpp, more
- 🖥️ **NeurowebUI** (React) for chat UX, threads, uploads
## 🗞️ News
- **CLI `serve` improvements** — run backend-only or UI-only, inject `VITE_BACKEND_URL` automatically. See [CLI guide](https://naumanhsa.github.io/neurosurfer/cli/).
- **Model registry & RAG hooks** — easier wiring for multi-model setups. See [Example App](https://naumanhsa.github.io/neurosurfer/server/example-app/).
- **Optional LLM stack** — install heavy deps only when you need them:
```bash
pip install "neurosurfer[torch]"
```
> Looking for older updates? Check the repo **Releases** and **Changelog**.
## ⚡ Quick Start
A 60-second path from install → dev server → your first inference.
**Install (minimal core):**
```bash
pip install -U neurosurfer
```
**Or full LLM stack (torch, transformers, bnb, unsloth):**
```bash
pip install -U "neurosurfer[torch]"
```
**Run the dev server (backend + UI):**
```bash
neurosurfer serve
```
- Auto-detects UI; pass `--ui-root` if needed. First run may `npm install`.
- Backend binds to config defaults; override with flags or envs.
**Hello LLM Example:**
```python
from neurosurfer.models.chat_models.transformers import TransformersModel
llm = TransformersModel(
model_name="unsloth/Llama-3.2-1B-Instruct-bnb-4bit",
load_in_4bit=True
)
res = llm.ask(user_prompt="Say hi!", system_prompt="Be concise.", stream=False)
print(res.choices[0].message.content)
```
## 🏗️ High-Level Architecture
<div align="center">
<img alt="Neurosurfer Architecture" src="https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/architecture/neurosurfer_architecture_light.png" width="100%"/>
<p><strong>Neurosurfer Architecture</strong></p>
</div>
## ✨ Key Features
- **Production API** — FastAPI backend with auth, chat APIs, and OpenAI-compatible endpoints → [Server setup](https://naumanhsa.github.io/neurosurfer/server/)
- **Intelligent Agents** — Build ReAct, SQL, and RAG agents with minimal code, optimized for specific tasks → [Learn about agents](https://naumanhsa.github.io/neurosurfer/api-reference/agents/)
- **Rich Tool Ecosystem** — Built-in tools (calculator, web calls, files) plus easy custom tools → [Explore tools](https://naumanhsa.github.io/neurosurfer/api-reference/tools/)
- **RAG System** — Ingest, chunk, and retrieve relevant context for your LLMs → [RAG System](https://naumanhsa.github.io/neurosurfer/api-reference/rag/)
- **Vector Databases** — Built-in ChromaDB with an extensible interface for other stores → [Vector stores](https://naumanhsa.github.io/neurosurfer/api-reference/vectorstores/)
- **Multi-LLM Support** — OpenAI, Transformers/Unsloth, vLLM, Llama.cpp, and OpenAI-compatible APIs → [Model docs](https://naumanhsa.github.io/neurosurfer/api-reference/models/)
## 📦 Install Options
**pip (recommended)**
```bash
pip install -U neurosurfer
```
**pip + full LLM stack**
```bash
pip install -U "neurosurfer[torch]"
```
**From source**
```bash
git clone https://github.com/NaumanHSA/neurosurfer.git
cd neurosurfer && pip install -e ".[torch]"
```
CUDA notes (Linux x86_64):
```bash
# Wheels bundle CUDA; you just need a compatible NVIDIA driver.
pip install -U torch --index-url https://download.pytorch.org/whl/cu124
# or CPU-only:
pip install -U torch --index-url https://download.pytorch.org/whl/cpu
```
## 📝 License
Licensed under **Apache-2.0**. See [`LICENSE`](https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/LICENSE).
## 🌟 Support
- ⭐ Star the project on [GitHub](https://github.com/NaumanHSA/neurosurfer).
- 💬 Ask & share in **Discussions**: [Discussions](https://github.com/NaumanHSA/neurosurfer/discussions).
- 🧠 Read the [Docs](https://naumanhsa.github.io/neurosurfer/).
- 🐛 File [Issues](https://github.com/NaumanHSA/neurosurfer/issues).
- 🔒 Security: report privately to **naumanhsa965@gmail.com**.
## 📚 Citation
If you use **Neurosurfer** in your work, please cite:
```bibtex
@software{neurosurfer,
author = {Nouman Ahsan and Neurosurfer contributors},
title = {Neurosurfer: A Production-Ready AI Agent Framework},
year = {2025},
url = {https://github.com/NaumanHSA/neurosurfer},
version = {0.1.0},
license = {Apache-2.0}
}
```
---
<div align="center">
<sub>Built with ❤️ by the Neurosurfer team
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "neurosurfer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Nouman Ahsan <naumanhsa965@gmail.com>",
"keywords": "LLM, agents, RAG, transformers, FastAPI, ChromaDB",
"author": null,
"author_email": "Nouman Ahsan <naumanhsa965@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9f/1c/d42a37718c8a2fcf336a82ee3a1b422b2ffac70e26fdf886c52d94088552/neurosurfer-0.1.0.post2.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/banner/neurosurfer_banner_black.png\" alt=\"Neurosurfer \u2014 AI Agent Framework\" width=\"50%\"/>\n <img src=\"https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/neurosurfer_water_wave.svg\" alt=\"Neurosurfer \u2014 AI Agent Framework\" width=\"100%\"/>\n \n <a href=\"https://naumanhsa.github.io/neurosurfer/#quick-start\" target=\"_blank\"><img src=\"https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/buttons/quick_start_button.png\" height=\"40\" alt=\"Quick Start\"></a>\n <a href=\"https://naumanhsa.github.io/neurosurfer/examples/\" target=\"_blank\"><img src=\"https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/buttons/examples_button.png\" height=\"40\" alt=\"Examples\"></a>\n <a href=\"https://naumanhsa.github.io/neurosurfer/\" target=\"_blank\"><img src=\"https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/buttons/documentation_button.png\" height=\"40\" alt=\"Documentation\"></a>\n <a href=\"https://pypi.org/project/neurosurfer/\" target=\"_blank\"><img src=\"https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/buttons/pypi_button.png\" height=\"40\" alt=\"PyPI\"></a>\n <a href=\"https://discord.gg/naumanhsa\" target=\"_blank\"><img src=\"https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/buttons/discord_button.png\" height=\"40\" alt=\"Discord\"></a>\n\n\n</div>\n\n**Neurosurfer** helps you build intelligent apps that blend **LLM reasoning**, **tools**, and **retrieval** with a ready-to-run **FastAPI** backend and a **React** dev UI. Start lean, add power as you go \u2014 CPU-only or GPU-accelerated.\n\n- \ud83e\udde9 **OpenAI-style API** with streaming & tool-calling \n- \ud83d\udcda **RAG-ready**: ingest \u2192 chunk \u2192 retrieve \u2192 augment \n- \ud83e\udd16 **Agents** (ReAct, SQL, RAG) + \ud83d\udd27 **Tools** (calc, web, custom) \n- \ud83e\udde0 **Multi-LLM**: OpenAI, Transformers/Unsloth, vLLM, Llama.cpp, more \n- \ud83d\udda5\ufe0f **NeurowebUI** (React) for chat UX, threads, uploads\n\n## \ud83d\uddde\ufe0f News\n\n- **CLI `serve` improvements** \u2014 run backend-only or UI-only, inject `VITE_BACKEND_URL` automatically. See [CLI guide](https://naumanhsa.github.io/neurosurfer/cli/). \n- **Model registry & RAG hooks** \u2014 easier wiring for multi-model setups. See [Example App](https://naumanhsa.github.io/neurosurfer/server/example-app/). \n- **Optional LLM stack** \u2014 install heavy deps only when you need them: \n ```bash\n pip install \"neurosurfer[torch]\"\n ```\n\n> Looking for older updates? Check the repo **Releases** and **Changelog**.\n\n\n## \u26a1 Quick Start\n\nA 60-second path from install \u2192 dev server \u2192 your first inference.\n\n**Install (minimal core):**\n```bash\npip install -U neurosurfer\n```\n\n**Or full LLM stack (torch, transformers, bnb, unsloth):**\n```bash\npip install -U \"neurosurfer[torch]\"\n```\n\n**Run the dev server (backend + UI):**\n```bash\nneurosurfer serve\n```\n- Auto-detects UI; pass `--ui-root` if needed. First run may `npm install`. \n- Backend binds to config defaults; override with flags or envs.\n\n**Hello LLM Example:**\n```python\nfrom neurosurfer.models.chat_models.transformers import TransformersModel\n\nllm = TransformersModel(\n model_name=\"unsloth/Llama-3.2-1B-Instruct-bnb-4bit\",\n load_in_4bit=True\n)\nres = llm.ask(user_prompt=\"Say hi!\", system_prompt=\"Be concise.\", stream=False)\nprint(res.choices[0].message.content)\n```\n\n## \ud83c\udfd7\ufe0f High-Level Architecture\n<div align=\"center\">\n <img alt=\"Neurosurfer Architecture\" src=\"https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/docs/assets/architecture/neurosurfer_architecture_light.png\" width=\"100%\"/>\n <p><strong>Neurosurfer Architecture</strong></p>\n</div>\n\n## \u2728 Key Features\n\n- **Production API** \u2014 FastAPI backend with auth, chat APIs, and OpenAI-compatible endpoints \u2192 [Server setup](https://naumanhsa.github.io/neurosurfer/server/)\n\n- **Intelligent Agents** \u2014 Build ReAct, SQL, and RAG agents with minimal code, optimized for specific tasks \u2192 [Learn about agents](https://naumanhsa.github.io/neurosurfer/api-reference/agents/)\n\n- **Rich Tool Ecosystem** \u2014 Built-in tools (calculator, web calls, files) plus easy custom tools \u2192 [Explore tools](https://naumanhsa.github.io/neurosurfer/api-reference/tools/)\n\n- **RAG System** \u2014 Ingest, chunk, and retrieve relevant context for your LLMs \u2192 [RAG System](https://naumanhsa.github.io/neurosurfer/api-reference/rag/)\n\n- **Vector Databases** \u2014 Built-in ChromaDB with an extensible interface for other stores \u2192 [Vector stores](https://naumanhsa.github.io/neurosurfer/api-reference/vectorstores/)\n\n- **Multi-LLM Support** \u2014 OpenAI, Transformers/Unsloth, vLLM, Llama.cpp, and OpenAI-compatible APIs \u2192 [Model docs](https://naumanhsa.github.io/neurosurfer/api-reference/models/)\n\n## \ud83d\udce6 Install Options\n\n**pip (recommended)**\n```bash\npip install -U neurosurfer\n```\n\n**pip + full LLM stack**\n```bash\npip install -U \"neurosurfer[torch]\"\n```\n\n**From source**\n```bash\ngit clone https://github.com/NaumanHSA/neurosurfer.git\ncd neurosurfer && pip install -e \".[torch]\"\n```\n\nCUDA notes (Linux x86_64):\n```bash\n# Wheels bundle CUDA; you just need a compatible NVIDIA driver.\npip install -U torch --index-url https://download.pytorch.org/whl/cu124\n# or CPU-only:\npip install -U torch --index-url https://download.pytorch.org/whl/cpu\n```\n\n## \ud83d\udcdd License\n\nLicensed under **Apache-2.0**. See [`LICENSE`](https://raw.githubusercontent.com/NaumanHSA/neurosurfer/main/LICENSE).\n\n## \ud83c\udf1f Support\n\n- \u2b50 Star the project on [GitHub](https://github.com/NaumanHSA/neurosurfer).\n- \ud83d\udcac Ask & share in **Discussions**: [Discussions](https://github.com/NaumanHSA/neurosurfer/discussions).\n- \ud83e\udde0 Read the [Docs](https://naumanhsa.github.io/neurosurfer/).\n- \ud83d\udc1b File [Issues](https://github.com/NaumanHSA/neurosurfer/issues).\n- \ud83d\udd12 Security: report privately to **naumanhsa965@gmail.com**.\n\n## \ud83d\udcda Citation\n\nIf you use **Neurosurfer** in your work, please cite:\n\n```bibtex\n@software{neurosurfer,\n author = {Nouman Ahsan and Neurosurfer contributors},\n title = {Neurosurfer: A Production-Ready AI Agent Framework},\n year = {2025},\n url = {https://github.com/NaumanHSA/neurosurfer},\n version = {0.1.0},\n license = {Apache-2.0}\n}\n```\n\n---\n\n<div align=\"center\">\n <sub>Built with \u2764\ufe0f by the Neurosurfer team\n</div>\n",
"bugtrack_url": null,
"license": null,
"summary": "Neurosurfer: production-ready AI agent framework with multi-LLM, RAG, tools, and FastAPI server",
"version": "0.1.0.post2",
"project_urls": {
"Documentation": "https://naumanhsa.github.io/neurosurfer/",
"Homepage": "https://naumanhsa.github.io/neurosurfer/",
"Issues": "https://github.com/NaumanHSA/neurosurfer/issues",
"Repository": "https://github.com/NaumanHSA/neurosurfer"
},
"split_keywords": [
"llm",
" agents",
" rag",
" transformers",
" fastapi",
" chromadb"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e068479a109f7e10738a45ef9f9c3f8d20a7470ec71d62fd1049bcce2af88ad6",
"md5": "fb8bd69f77b0e3371d75482bf886afe8",
"sha256": "74acc218077f254a917df530bb995add6a7d687be92f42406cd16bec54007669"
},
"downloads": -1,
"filename": "neurosurfer-0.1.0.post2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb8bd69f77b0e3371d75482bf886afe8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 601889,
"upload_time": "2025-11-05T18:49:26",
"upload_time_iso_8601": "2025-11-05T18:49:26.397678Z",
"url": "https://files.pythonhosted.org/packages/e0/68/479a109f7e10738a45ef9f9c3f8d20a7470ec71d62fd1049bcce2af88ad6/neurosurfer-0.1.0.post2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9f1cd42a37718c8a2fcf336a82ee3a1b422b2ffac70e26fdf886c52d94088552",
"md5": "2f12ba79eb88f76c670617c41425450a",
"sha256": "f708e196496a74542c2e65f000818d90acc7bb0290500eacd7d60305f6c06a9a"
},
"downloads": -1,
"filename": "neurosurfer-0.1.0.post2.tar.gz",
"has_sig": false,
"md5_digest": "2f12ba79eb88f76c670617c41425450a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 563916,
"upload_time": "2025-11-05T18:49:27",
"upload_time_iso_8601": "2025-11-05T18:49:27.827661Z",
"url": "https://files.pythonhosted.org/packages/9f/1c/d42a37718c8a2fcf336a82ee3a1b422b2ffac70e26fdf886c52d94088552/neurosurfer-0.1.0.post2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-05 18:49:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NaumanHSA",
"github_project": "neurosurfer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "neurosurfer"
}
