Home

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.

🚀 What’s in the box¶

• 🤖 Agents: Production-ready patterns for ReAct, SQL, RAG, Router etc. think → act → observe → answer
• 🧠 Models: Unified interface for OpenAI-style and local backends like Transformers/Unsloth, vLLM, Llama.cpp etc.
• 📚 RAG: Simple, swappable retrieval core: embed → search → format → token-aware trimming
• ⚙️ FastAPI Server: OpenAI-compatible endpoints for chat + tools — custom endpoints, chat handlers, RAG etc.
• 🖥️ NeurowebUI: React chat UI (GPT-style) that communicates with the server out-of-the-box
• 🧪 CLI: neurosurfer serve to run server/UI — custom backend app and UI support

🎓 Tutorials

#	Tutorial	Link	Description
1	Neurosurfer Quickstart		Learn how to load local and OpenAI models, stream responses, and build your first RAG and tool-based agents directly in Jupyter or Colab.

More tutorials coming soon — covering RAG, Custom Tools, More on Agents, FastAPI integration and more.

🗞️ News¶

• Agents: ReAct & SQLAgent upgraded with bounded retries, spec-aware input validation, and better final-answer streaming; new ToolsRouterAgent for quick one-shot tool picks.
• Models: Cleaner OpenAI-style responses across backends; smarter token budgeting + fallbacks when tokenizer isn’t available.
• Server: Faster startup, better logging/health endpoints, and safer tool execution paths; OpenAI-compatible routes refined for streaming/tool-calling.
• CLI: serve now runs backend-only or UI-only and auto-injects VITE_BACKEND_URL; new subcommands for ingest/traces to standardize local workflows.

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

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¶

📦 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 naumanhsa965@gmail.com.

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