neurosurfer 0.1.0

Neurosurfer: production-ready AI agent framework with multi-LLM, RAG, tools, and FastAPI server

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.
• Model registry & RAG hooks — easier wiring for multi-model setups. See Example App.
• Optional LLM stack — install heavy deps only when you need them:

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

pip install -U neurosurfer

Or full LLM stack (torch, transformers, bnb, unsloth):

pip install -U "neurosurfer[torch]"

Run the dev server (backend + UI):

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:

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

Neurosurfer Architecture

✨ Key Features

• Production API — FastAPI backend with auth, chat APIs, and OpenAI-compatible endpoints → Server setup

• Intelligent Agents — Build ReAct, SQL, and RAG agents with minimal code, optimized for specific tasks → Learn about agents

• Rich Tool Ecosystem — Built-in tools (calculator, web calls, files) plus easy custom tools → Explore tools

• RAG System — Ingest, chunk, and retrieve relevant context for your LLMs → RAG System

• Vector Databases — Built-in ChromaDB with an extensible interface for other stores → Vector stores

• Multi-LLM Support — OpenAI, Transformers/Unsloth, vLLM, Llama.cpp, and OpenAI-compatible APIs → Model docs

📦 Install Options

pip (recommended)

pip install -U neurosurfer

pip + full LLM stack

pip install -U "neurosurfer[torch]"

From source

git clone https://github.com/NaumanHSA/neurosurfer.git
cd neurosurfer && pip install -e ".[torch]"

CUDA notes (Linux x86_64):

# 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.

🌟 Support

• ⭐ Star the project on GitHub.
• 💬 Ask & share in Discussions: Discussions.
• 🧠 Read the Docs.
• 🐛 File Issues.
• 🔒 Security: report privately to [e-mail].

📚 Citation

If you use Neurosurfer in your work, please cite:

@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}
}

---

_{Built with ❤️ by the Neurosurfer team}