PySpur is a graph UI for visualizing agent trajectories in Python. AI engineers use it to build agents, execute them step-by-step and inspect past runs.

https://github.com/user-attachments/assets/1ebf78c9-94b2-468d-bbbb-566311df16fe

🕸️ Why PySpur?

• 🖐️ Drag-and-Drop: Build, Test and Iterate in Seconds.
• 🔄 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.
• 🧪 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

Option A: Using pyspur Python Package

This is the quickest way to get started. Python 3.12 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] Customize Your Deployment: You can customize your PySpur deployment in two ways:

   a. Through the app (Recommended): - Navigate to the API Keys tab in the app - Add your API keys for various providers (OpenAI, Anthropic, etc.) - Changes take effect immediately

   b. Manual Configuration: - Edit the .env file in your project directory - It is recommended to configure a postgres database in .env for more reliability - Restart the app with pyspur serve. Add --sqlite if you are not using postgres

Option B: Using Docker (Recommended for Scalable, In-Production Systems)

This is the recommended way for production deployments:

1. Install Docker: First, install Docker by following the official installation guide for your operating system:

   • Docker for Linux
   • Docker Desktop for Mac

2. Create a PySpur Project: Once Docker is installed, create a new PySpur project with:

   curl -fsSL https://raw.githubusercontent.com/PySpur-com/pyspur/main/start_pyspur_docker.sh | bash -s pyspur-project
   

   This will:

   • Start a new PySpur project in a new directory called pyspur-project
   • Set up the necessary configuration files
   • Start PySpur app automatically backed by a local postgres docker instance

3. Access PySpur: Go to http://localhost:6080 in your browser.

4. [Optional] Customize Your Deployment: You can customize your PySpur deployment in two ways:

   a. Through the app (Recommended): - Navigate to the API Keys tab in the app - Add your API keys for various providers (OpenAI, Anthropic, etc.) - Changes take effect immediately

   b. Manual Configuration: - Edit the .env file in your project directory - Restart the services with: sh docker compose up -d

That's it! Click on "New Spur" to create a workflow, or start with one of the stock templates.

✨ Core Benefits

Debug at Node Level:

https://github.com/user-attachments/assets/6e82ad25-2a46-4c50-b030-415ea9994690

Multimodal (Upload files or paste URLs)

PDFs, Videos, Audio, Images, ...

https://github.com/user-attachments/assets/83ed9a22-1ec1-4d86-9dd6-5d945588fd0b

Loops

RAG

Step 1) Create Document Collection (Chunking + Parsing)

https://github.com/user-attachments/assets/c77723b1-c076-4a64-a01d-6d6677e9c60e

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

https://github.com/user-attachments/assets/50e5c711-dd01-4d92-bb23-181a1c5bba25

Modular Building Blocks

https://github.com/user-attachments/assets/6442f0ad-86d8-43d9-aa70-e5c01e55e876

Evaluate Final Performance

https://github.com/user-attachments/assets/4dc2abc3-c6e6-4d6d-a5c3-787d518de7ae

Coming soon: Self-improvement

https://github.com/user-attachments/assets/5bef7a16-ef9f-4650-b385-4ea70fa54c8a

🛠️ PySpur Development Setup

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

For development, follow these steps:

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
   

   This will start a local instance of PySpur with hot-reloading enabled for development.

3. Customize your setup: Edit the .env file to configure your environment. By default, PySpur uses a local PostgreSQL database. To use an external database, modify the POSTGRES_* variables in .env.

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