PySpur is an AI agent builder in Python. AI engineers use it to build agents, execute them step-by-step and inspect past runs.

hero.mp4

🕸️ Why PySpur?

PySpur's primary purpose is to simplify building reliable agents by making testing and debugging really easy. You can set up test cases, execute them step-by-step, and visually inspect each run. Once an agent is deployed to production, execution traces become automatically available.

Core features:

• 👤 Human in the Loop: Persistent workflows that wait for human approval.
• 🔄 Loops: Iterative tool calling with memory.
• 📤 File Upload: Upload files or paste URLs to process documents.
• 📋 Structured Outputs: UI editor for JSON Schemas.
• 🗃️ RAG: Parse, Chunk, Embed, and Upsert Data into a Vector DB.
• 🖼️ Multimodal: Support for Video, Images, Audio, Texts, Code.
• 🧰 Tools: Slack, Firecrawl.dev, Google Sheets, GitHub, and more.
• 📊 Traces: Automatically capture execution traces of deployed agents.
• 🧪 Evals: Evaluate agents on real-world datasets.
• 🚀 One-Click Deploy: Publish as an API and integrate wherever you want.
• 🐍 Python-Based: Add new nodes by creating a single Python file.
• 🎛️ Any-Vendor-Support: >100 LLM providers, embedders, and vector DBs.

⚡ Quick start

This is the quickest way to get started. Python 3.11 or higher is required.

1. Install PySpur:

   pip install pyspur

2. Initialize a new project:

   pyspur init my-project
   cd my-project

   This will create a new directory with a .env file.

3. Start the server:

   pyspur serve --sqlite

   By default, this will start PySpur app at http://localhost:6080 using a sqlite database. We recommend you configure a postgres instance URL in the .env file to get a more stable experience.

4. [Optional] Configure Your Environment and Add API Keys:

   • App UI: Navigate to API Keys tab to add provider keys (OpenAI, Anthropic, etc.)
   • Manual: Edit .env file (recommended: configure postgres) and restart with pyspur serve

✨ Core Benefits

Human-in-the-loop breakpoints:

These breakpoints pause the workflow when reached and resume whenever a human approves it. They enable human oversight for workflows that require quality assurance: verify critical outputs before the workflow proceeds.

HIL.mp4

Debug at Node Level:

visualization.mp4

Multimodal (Upload files or paste URLs)

PDFs, Videos, Audio, Images, ...

multimodal.mp4

Loops

RAG

Step 1) Create Document Collection (Chunking + Parsing)

RAG_1.mp4

Step 2) Create Vector Index (Embedding + Vector DB Upsert)

RAG_2.mp4

Modular Building Blocks

blocks.mp4

Evaluate Final Performance

evals.mp4

Coming soon: Self-improvement

optimization.mp4

🛠️ PySpur Development Setup

[ Instructions for development on Unix-like systems. Development on Windows/PC not supported ]

We recommend using Cursor/VS Code with our dev container (.devcontainer/devcontainer.json) for:

• Consistent development environment with pre-configured tools and extensions
• Optimized settings for Python and TypeScript development
• Automatic hot-reloading and port forwarding

Option 1: Cursor/VS Code Dev Container (Recommended)

1. Install Cursor/VS Code and the Dev Containers extension
2. Clone and open the repository
3. Click "Reopen in Container" when prompted

Option 2: Manual Setup

1. Clone the repository:

   git clone https://github.com/PySpur-com/pyspur.git
   cd pyspur

2. Launch using docker-compose.dev.yml:

   docker compose -f docker-compose.dev.yml up --build -d

3. Customize your setup: Edit .env to configure your environment (e.g., PostgreSQL settings).

Note: Manual setup requires additional configuration and may not include all dev container features.

⭐ Support us

You can support us in our work by leaving a star! Thank you!

Your feedback will be massively appreciated. Please tell us which features on that list you like to see next or request entirely new ones.