Upload 520 files

.gitattributes

@@ -33,3 +33,38 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/checks-passed.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/deploy/dark_deploy_python.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/deploy/dark_deploy_ts.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/deploy/light_deploy_python.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/deploy/light_deploy_ts.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/evals/evals.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/0_dark.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/0_light.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/1_dark.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/1_light.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/3_dark.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/3_light.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/4_dark.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/4_light.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/5_dark.gif filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/5_light.gif filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/6_dark.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/6_light.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/7_dark.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/7_light.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/8_dark.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/8_light.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/9_dark.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/example_walkthrough/9_light.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/hero-dark.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/hero-light.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/hero.png filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/rag/rag1.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/rag/rag2.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/docs/images/rag/rag3.mp4 filter=lfs diff=lfs merge=lfs -text
+pyspur/frontend/public/images/firecrawl.png filter=lfs diff=lfs merge=lfs -text
+pyspur/frontend/public/images/google_sheets.png filter=lfs diff=lfs merge=lfs -text
+pyspur/frontend/public/images/meta.png filter=lfs diff=lfs merge=lfs -text
+pyspur/frontend/public/images/slack.png filter=lfs diff=lfs merge=lfs -text
+pyspur/frontend/public/pyspur-black.png filter=lfs diff=lfs merge=lfs -text

pyspur/.cursor/rules/frontend-api-calls.mdc

@@ -0,0 +1,6 @@
+---
+description: API calls in frontend
+globs: 
+alwaysApply: false
+---
+API calls inside the frontend should always be stored inside [api.ts](mdc:frontend/src/utils/api.ts) and use the API_BASE_URL defined there

pyspur/.devcontainer/.bashrc

@@ -0,0 +1,21 @@
+# Enable bash completion
+if [ -f /etc/bash_completion ]; then
+    . /etc/bash_completion
+fi
+
+# Docker compose aliases
+alias dcup='docker compose -f docker-compose.dev.yml up --build -d'
+alias dlogb='docker logs -f pyspur-backend-1 --since 5m'
+alias dlogf='docker logs -f pyspur-frontend-1 --since 5m'
+alias dlogn='docker logs -f pyspur-nginx-1 --since 5m'
+alias dlogs='docker compose logs -f --since 5m'
+
+# Test frontend build in temporary container
+alias tfeb='docker build --target production -f Dockerfile.frontend \
+  --no-cache -t temp-frontend-build . && \
+  echo "✅ Frontend build successful!" && \
+  docker rmi temp-frontend-build || \
+  echo "❌ Frontend build failed!"'
+
+# Add color to the terminal
+export PS1='\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ '

pyspur/.devcontainer/Dockerfile

@@ -0,0 +1,28 @@
+# Base stage
+FROM python:3.12 as base
+WORKDIR /pyspur
+
+# Install bash completion
+RUN apt-get update && apt-get install -y \
+    bash-completion \
+    nano \
+    vim \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip install uv
+
+COPY backend/ backend/
+RUN uv pip install --system -e "/pyspur/backend/[dev]"
+
+# Install Node.js for frontend development
+RUN curl -fsSL https://deb.nodesource.com/setup_23.x | bash - \
+    && apt-get install -y nodejs \
+    && npm install -g npm@latest
+
+# Development stage
+FROM base as development
+WORKDIR /pyspur/frontend
+COPY frontend/package*.json ./
+RUN npm install
+
+WORKDIR /pyspur

pyspur/.devcontainer/README.md

@@ -0,0 +1,130 @@
+# Development Container Configuration
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/pyspur-dev/pyspur)
+
+This directory contains configuration files for Visual Studio Code Dev Containers / GitHub Codespaces. Dev containers provide a consistent, isolated development environment for this project.
+
+## Contents
+
+- `devcontainer.json` - The main configuration file that defines the development container settings
+- `Dockerfile` - Defines the container image and development environment
+
+## Usage
+
+### Prerequisites
+
+- Visual Studio Code
+- Docker installation:
+  - Docker Desktop (Windows/macOS)
+  - Docker Engine (Linux)
+- [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension for VS Code
+
+### Getting Started
+
+1. Open this project in Visual Studio Code
+2. When prompted, click "Reopen in Container"
+   - Alternatively, press `F1` and select "Remote-Containers: Reopen in Container"
+3. Wait for the container to build and initialize
+4. Launch the application using:
+   ```bash
+   dcup
+   ```
+5. Access the application (assuming the ports are forwarded as is to the host machine)
+   - Main application: http://localhost:6080
+   - Frontend development server: http://localhost:3000
+   - Backend API: http://localhost:8000
+
+The development environment will be automatically configured with all necessary tools and extensions.
+
+### Viewing Logs
+
+You can monitor the application logs using these commands:
+
+- View all container logs:
+  ```bash
+  dlogs
+  ```
+- View backend logs only:
+  ```bash
+  dlogb
+  ```
+- View frontend logs only:
+  ```bash
+  dlogf
+  ```
+- View nginx logs only:
+  ```bash
+  dlogn
+  ```
+
+All log commands show the last 5 minutes of logs and continue to tail new entries.
+
+### Modifying the database schemas
+
+
+1. **Stop Containers**
+   ```bash
+   docker compose down
+   ```
+
+2. **Generate a Migration**
+   ```bash
+   ./generate_migrations.sh 002 <short_description_in_snake_case>
+   ```
+   - Migration file appears in `./backend/app/models/management/alembic/versions/` with prefix `002_...`.
+
+3. **Review the Generated Script**
+   - Open the file to ensure it has the intended changes.
+
+4. **Apply the Migration**
+   ```bash
+   docker compose down
+   docker compose up --build
+   ```
+   - Alembic applies the new migration automatically on startup.
+
+5. **Test the App**
+   - Confirm new tables/columns work as expected.
+
+6. **Commit & Push**
+   ```bash
+   git add .
+   git commit -m "Add migration 002 <description>"
+   git push origin <branch>
+   ```
+
+### Troubleshooting DBs issues
+
+When modifying the DB models, one needs to be careful to not destroy the local DB due to lacking migrations.
+
+Sometimes the local dev DB gets corrupted. In such cases, assuming it does not contain production data, the quickest fix is to simply delete it and let the backend rebuild it the next time you run `docker compose up` (or `dcup`).
+
+You can do so via running
+
+```bash
+docker volume rm pyspur_postgres_data
+```
+
+## Customization
+
+You can customize the development environment by:
+
+- Modifying `devcontainer.json` to:
+  - Add VS Code extensions
+  - Set container-specific settings
+  - Configure environment variables
+- Updating the `Dockerfile` to:
+  - Install additional packages
+  - Configure system settings
+  - Add development tools
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Rebuild the container: `F1` → "Remote-Containers: Rebuild Container"
+2. Check Docker logs for build errors
+3. Verify Docker Desktop is running
+4. Ensure all prerequisites are installed
+
+For more information, see the [VS Code Remote Development documentation](https://code.visualstudio.com/docs/remote/containers).

pyspur/.devcontainer/devcontainer.json

@@ -0,0 +1,146 @@
+{
+	"name": "PySpur Development",
+
+	"dockerComposeFile": [
+		"./docker-compose.yml"
+	],
+
+	"service": "devdocker",
+
+    "runServices": ["devdocker"],
+
+	"workspaceFolder": "/pyspur",
+
+	"features": {
+		"ghcr.io/devcontainers/features/docker-in-docker:2": {
+			"version": "latest",
+			"moby": true
+		}
+	},
+
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "github.copilot",
+                "github.copilot-chat",
+                // Backend extensions
+                "ms-python.python",
+                "charliermarsh.ruff",
+                "tamasfe.even-better-toml",
+                // Frontend extensions
+                "dbaeumer.vscode-eslint",
+                "esbenp.prettier-vscode",
+                "ms-vscode.vscode-typescript-next"
+            ],
+            "settings": {
+                // Git settings
+                // bypass pre-commit hooks not allowed
+                "git.allowNoVerifyCommit": false,
+                
+                // Python analysis settings
+                "python.analysis.autoImportCompletions": true,
+                "python.analysis.autoImportUserSymbols": true,
+                "python.analysis.importFormat": "relative",
+                "python.analysis.typeCheckingMode": "strict",
+                "python.defaultInterpreterPath": "/usr/local/bin/python",
+                
+                // Python linting and formatting
+                "python.linting.enabled": true,
+                "python.linting.mypyEnabled": false,
+                "python.linting.ruffEnabled": true,
+
+                // TypeScript settings
+                "typescript.tsdk": "/pyspur/frontend/node_modules/typescript/lib",
+                "typescript.preferences.importModuleSpecifier": "non-relative",
+                "typescript.preferences.projectRoot": "/pyspur/frontend",
+                "npm.packageManager": "npm",
+
+                // Editor formatting settings
+                "editor.formatOnSave": true,
+                "editor.defaultFormatter": "esbenp.prettier-vscode",
+
+                // Language specific editor settings
+                "[python]": {
+                    "editor.formatOnType": true,
+                    "editor.formatOnSave": true,
+                    "editor.defaultFormatter": "charliermarsh.ruff",
+                    "editor.codeActionsOnSave": {
+                        "source.organizeImports": "always",
+                        "source.fixAll.ruff": "always"
+                    }
+                },
+                "[typescript]": {
+                    "editor.defaultFormatter": "esbenp.prettier-vscode",
+                    "editor.formatOnSave": true,
+                    "editor.codeActionsOnSave": {
+                        "source.fixAll.eslint": "explicit",
+                        "source.organizeImports": "explicit"
+                    }
+                },
+                "[typescriptreact]": {
+                    "editor.defaultFormatter": "esbenp.prettier-vscode",
+                    "editor.formatOnSave": true,
+                    "editor.codeActionsOnSave": {
+                        "source.fixAll.eslint": "explicit",
+                        "source.organizeImports": "explicit"
+                    }
+                },
+                "[javascript]": {
+                    "editor.defaultFormatter": "esbenp.prettier-vscode",
+                    "editor.formatOnSave": true,
+                    "editor.codeActionsOnSave": {
+                        "source.fixAll.eslint": "explicit",
+                        "source.organizeImports": "explicit"
+                    }
+                },
+                "[javascriptreact]": {
+                    "editor.defaultFormatter": "esbenp.prettier-vscode",
+                    "editor.formatOnSave": true,
+                    "editor.codeActionsOnSave": {
+                        "source.fixAll.eslint": "explicit",
+                        "source.organizeImports": "explicit"
+                    }
+                },
+                "[json]": {
+                    "editor.quickSuggestions": {
+                        "strings": true
+                    },
+                    "editor.suggest.insertMode": "replace",
+                    "editor.formatOnSave": true,
+                    "editor.defaultFormatter": "esbenp.prettier-vscode"
+                },
+                "[shellscript]": {
+                    "editor.formatOnSave": true,
+                    "editor.defaultFormatter": "esbenp.prettier-vscode"
+                },
+                "[yaml]": {
+                    "editor.insertSpaces": true,
+                    "editor.tabSize": 2,
+                    "editor.autoIndent": "advanced",
+                    "diffEditor.ignoreTrimWhitespace": false,
+                    "editor.formatOnSave": true,
+                    "editor.defaultFormatter": "esbenp.prettier-vscode"
+                },
+                "prettier.configPath": "/pyspur/frontend/.prettierrc"
+            }
+        }
+    },
+    "remoteUser": "root",
+    "shutdownAction": "none",
+	"forwardPorts": [6080, "backend:8000", "frontend:3000"],
+    "portsAttributes": {
+        "frontend:3000" :{
+            "label": "frontend",
+            "onAutoForward": "silent"
+        },
+        "backend:8000" :{
+            "label": "backend",
+            "onAutoForward": "silent"
+        },
+        "6080" :{
+            "label": "app",
+            "onAutoForward": "silent"
+        }
+    },
+    "postCreateCommand": "chmod +x .devcontainer/post-create.sh && .devcontainer/post-create.sh"
+}

pyspur/.devcontainer/docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  devdocker:
+    build:
+      context: ..
+      dockerfile: .devcontainer/Dockerfile
+      target: development
+    volumes:
+      # Project files
+      - ../:/pyspur:cached
+      - ../.env:/pyspur/backend/.env:cached
+      - /pyspur/frontend/node_modules
+    environment:
+      - PYTHONPATH=/pyspur/backend
+    command: sleep infinity

pyspur/.devcontainer/post-create.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# Install pre-commit hooks
+uv pip install --system pre-commit==4.1.0
+pre-commit install
+
+# Check if package.json has changed and reinstall if needed
+if [ -f /pyspur/frontend/package.json ]; then
+    cd /pyspur/frontend && npm install
+fi
+
+# Add source command to main bashrc
+echo '
+# Source custom settings
+# Source custom bashrc settings if the file exists
+if [ -f /pyspur/.devcontainer/.bashrc ]; then
+    source /pyspur/.devcontainer/.bashrc
+fi' >> ~/.bashrc 

pyspur/.dockerignore

@@ -0,0 +1,88 @@
+# Version control
+.git
+.gitignore
+
+# Dependencies
+**/node_modules
+**/__pycache__
+**/*.pyc
+**/*.pyo
+**/*.pyd
+**/*.so
+**/.Python
+**/env
+**/venv
+**/.env
+**/.env.local
+**/.env.development.local
+**/.env.test.local
+**/.env.production.local
+
+# Python specific
+**/develop-eggs
+**/eggs
+**/.eggs
+**/parts
+**/sdist
+**/var
+**/wheels
+**/*.egg-info
+**/.installed.cfg
+**/*.egg
+
+# Build outputs
+**/dist
+**/build
+**/.next
+**/out
+**/*.egg-info
+
+# Development/IDE files
+**/.idea
+**/.vscode
+**/.DS_Store
+**/*.swp
+**/*.swo
+
+# Docker files
+**/Dockerfile*
+**/.dockerignore
+docker-compose*.yml
+
+# Test files
+**/__tests__
+**/test
+**/*.test.js
+**/*.spec.js
+**/*.test.py
+**/*.spec.py
+**/coverage
+**/htmlcov
+
+# Documentation
+**/*.md
+**/docs
+
+# Logs
+**/logs
+**/*.log
+**/npm-debug.log*
+**/yarn-debug.log*
+**/yarn-error.log*
+
+# Cache
+**/.cache
+**/.npm
+**/.eslintcache
+**/.pytest_cache
+**/__pycache__
+**/.coverage
+
+# Data directories
+**/data
+**/uploads
+**/downloads
+
+# Databases
+**/*.db
+**/sqlite/*.db 

pyspur/.env.example

@@ -0,0 +1,127 @@
+# ======================
+# Core Configuration
+# ======================
+
+# Environment
+# ENVIRONMENT=development
+ENVIRONMENT=production
+PYTHONUNBUFFERED=1 # This is to prevent Python from buffering stdout and stderr
+OAUTHLIB_INSECURE_TRANSPORT=1 # This is to allow OAuth2 to work with http
+
+# Version tag for Docker images in production
+VERSION=latest
+
+# GitHub repository (username/repo-name)
+GITHUB_REPOSITORY=pyspur-dev/pyspur
+
+
+# ======================
+# Application Configuration
+# ======================
+
+# Application Host Configuration
+# This is the host that the application will be running on
+# By default, the application will be running on
+
+PYSPUR_HOST=0.0.0.0
+PYSPUR_PORT=6080
+
+
+# Backend Configuration
+DEBUG=False
+
+
+# ======================
+# Database Settings
+# ======================
+# PySpur uses PostgreSQL as the database. By default, the database is hosted in a separate container.
+# If you want to use an external database, you can provide the connection details here.
+# PostgreSQL Configuration
+POSTGRES_DB=pyspur
+POSTGRES_USER=pyspur
+POSTGRES_PASSWORD=pyspur
+POSTGRES_HOST=db
+POSTGRES_PORT=5432
+
+
+# ======================
+# Model Provider API Keys
+# ======================
+
+# OPENAI_API_KEY=your_openai_api_key
+# GEMINI_API_KEY=your_gemini_api_key
+# ANTHROPIC_API_KEY=your_anthropic_api_key
+
+# ======================
+# OpenAI API URL Configuration
+# ======================
+# In case you are using OpenAI-compatible API service, you can specify the base URL of the API here
+# OPENAI_API_BASE=https://api.openai.com/v1
+
+# ======================
+# Ollama Configuration
+# ======================
+
+# NOTE:
+# if the ollama service is running on port 11434 of the host machine,
+# then use http://host.docker.internal:11434 as the base url
+# if the ollama service is running on a different host, use the ip address or domain name of the host
+
+# Also make sure the ollama service is configured to accept requests.
+# This can be done setting OLLAMA_HOST=0.0.0.0 environment variable before launching the ollama service.
+
+# OLLAMA_BASE_URL=http://host.docker.internal:11434
+
+
+# ======================
+# Azure OpenAI Configuration
+# ======================
+
+# AZURE_OPENAI_API_KEY=your_azure_openai_api_key
+# AZURE_OPENAI_API_BASE=https://your-resource-name.openai.azure.com
+# AZURE_OPENAI_API_VERSION=your_azure_openai_api_version
+# AZURE_OPENAI_DEPLOYMENT_NAME=your_azure_openai_deployment_name
+# ======================
+
+# ======================
+# Google configuration
+# ======================
+
+# NEXT_PUBLIC_GOOGLE_CLIENT_ID=your_google_client_id # Google OAuth Client ID
+# # This environment variable is used to configure Google OAuth for your application.
+# # It should be set to the client id obtained from the Google Developer Console.
+# # The prefix 'NEXT_PUBLIC_' is used to expose this variable to the frontend,
+# # allowing client-side code to access it.
+
+# ======================
+
+# ======================
+# GitHub configuration
+# ======================
+
+# GITHUB_ACCESS_TOKEN=your_github_access_token # GitHub Personal Access Token
+# # This environment variable is used to configure GitHub OAuth for your application.
+# # It should be set to the personal access token obtained from the GitHub Developer Settings.
+
+# ======================
+
+# ======================
+# Firecrawl configuration
+# ======================
+
+# FIRECRAWL_API_KEY=your_firecrawl_api_key # Firecrawl API Key
+# # This environment variable is used to configure Firecrawl API for your application.
+# # It should be set to the API key obtained from the Firecrawl Developer Console.
+
+# ======================
+
+# Frontend Configuration
+# ======================
+# Usage Data
+# ======================
+# We use PostHog to collect anonymous usage data for the PySpur UI.
+# This helps us understand how our users are interacting with the application
+# and improve the user experience.
+# If you want to disable usage data collection, uncomment the following line:
+# DISABLE_ANONYMOUS_TELEMETRY=true
+# ======================

pyspur/.github/dependabot.yml

@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+ - package-ecosystem: "devcontainers"
+   directory: "/"
+   schedule:
+     interval: weekly

pyspur/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Release
+
+on:
+  release:
+    types: [created]
+
+env:
+  REGISTRY: ghcr.io
+  BACKEND_IMAGE_NAME: ${{ github.repository }}-backend
+
+jobs:
+  build-and-push-docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      id-token: write  # needed for PyPI publishing
+    outputs:
+      image_name: ${{ steps.meta-backend.outputs.tags }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
+      
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Backend
+        id: meta-backend
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+
+      - name: Build and push Backend image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile.backend
+          push: true
+          platforms: linux/amd64,linux/arm64
+          target: production
+          tags: ${{ steps.meta-backend.outputs.tags }}
+          labels: ${{ steps.meta-backend.outputs.labels }}
+
+      - name: Build Python package
+        run: |
+          # Create dist directory
+          mkdir -p dist
+          
+          # Build package using the container we just built - use first tag
+          DOCKER_TAG=$(echo "${{ steps.meta-backend.outputs.tags }}" | head -n1)
+          docker run --rm -v "$(pwd)/dist:/dist" "$DOCKER_TAG" sh -c "cd /pyspur/backend && uv build && cp dist/* /dist/"
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/ 

pyspur/.gitignore

@@ -0,0 +1,178 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+.DS_Store
+.vscode
+
+# Ruff cache
+**/.ruff_cache/
+
+
+# node_modules
+**/node_modules/
+**/node_modules
+
+prd/
+
+# package* in docs
+docs/package*

pyspur/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: local
+    hooks:
+      - id: backend-hooks
+        name: Backend Hooks
+        entry: pre-commit run --config backend/.pre-commit-config.yaml
+        language: system
+        pass_filenames: false
+        always_run: true
+        files: ^backend/
+
+      - id: frontend-hooks
+        name: Frontend Hooks
+        entry: bash -c 'cd frontend && npx lint-staged'
+        language: system
+        pass_filenames: false
+        always_run: true
+        files: ^frontend/
+      
+      - id: frontend-hooks-cleanup
+        name: Cleanup files created by frontend hooks
+        entry: bash -c 'cd frontend && rm -f tsconfig.*.tsbuildinfo'
+        language: system
+        pass_filenames: false
+        always_run: true
+        files: ^frontend/

pyspur/Dockerfile.backend

@@ -0,0 +1,38 @@
+FROM python:3.12-slim AS base
+RUN apt-get update && apt-get install -y \
+    libpq-dev \
+    gcc \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip install uv
+WORKDIR /pyspur/backend
+COPY backend/pyproject.toml .
+RUN uv pip compile pyproject.toml > requirements.txt && \
+    uv pip install --system --no-cache-dir -r requirements.txt && \
+    rm requirements.txt
+
+
+# Development stage
+FROM base AS development
+ENV PYTHONPATH=/pyspur/backend
+# Development-specific instructions here
+
+# Frontend build stage
+FROM node:23-slim AS frontend-builder
+WORKDIR /pyspur/frontend
+COPY frontend/package*.json ./
+RUN npm ci
+COPY frontend/ .
+RUN npm run build
+
+# Production stage
+FROM base AS production
+ENV PYTHONPATH=/pyspur/backend
+COPY backend/ .
+# Copy frontend static files from frontend build stage
+RUN mkdir -p /pyspur/backend/pyspur/static
+RUN rm -rf /pyspur/backend/pyspur/static/*
+COPY --from=frontend-builder /pyspur/frontend/out/ /pyspur/backend/pyspur/static/
+COPY .env.example /pyspur/backend/pyspur/templates/.env.example
+# Production-specific instructions here

pyspur/Dockerfile.frontend

@@ -0,0 +1,15 @@
+FROM node:23-slim AS base
+WORKDIR /pyspur/frontend
+COPY frontend/package*.json ./
+
+# Development stage
+FROM base AS development
+RUN npm install
+# Development-specific instructions here
+
+# Production stage
+FROM base AS production
+RUN npm ci --only=production
+COPY frontend/ .
+RUN npm run build
+# Production-specific instructions here 

pyspur/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pyspur/README.md

@@ -0,0 +1,187 @@
+![PySpur](./docs/images/hero.png)
+
+<p align="center"><strong>Iterate over your agents 10x faster. AI engineers use PySpur to iterate over AI agents visually without reinventing the wheel.</strong></p>
+
+<p align="center">
+  <a href="./README.md"><img alt="README in English" src="https://img.shields.io/badge/English-blue"></a>
+  <a href="./README_CN.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-blue"></a>
+  <a href="./README_JA.md"><img alt="日本語のREADME" src="https://img.shields.io/badge/日本語-blue"></a>
+  <a href="./README_KR.md"><img alt="README in Korean" src="https://img.shields.io/badge/한국어-blue"></a>
+  <a href="./README_DE.md"><img alt="Deutsche Version der README" src="https://img.shields.io/badge/Deutsch-blue"></a>
+<a href="./README_FR.md"><img alt="Version française du README" src="https://img.shields.io/badge/Français-blue"></a>
+<a href="./README_ES.md"><img alt="Versión en español del README" src="https://img.shields.io/badge/Español-blue"></a>
+</p>
+
+<p align="center">
+<a href="https://docs.pyspur.dev/" target="_blank">
+  <img alt="Docs" src="https://img.shields.io/badge/Docs-green.svg?style=for-the-badge&logo=readthedocs&logoColor=white">
+</a>
+<a href="https://calendly.com/d/cnf9-57m-bv3/pyspur-founders" target="_blank">
+  <img alt="Meet us" src="https://img.shields.io/badge/Meet%20us-blue.svg?style=for-the-badge&logo=calendly&logoColor=white">
+</a>
+<a href="https://forms.gle/5wHRctedMpgfNGah7" target="_blank">
+  <img alt="Cloud" src="https://img.shields.io/badge/Cloud-orange.svg?style=for-the-badge&logo=cloud&logoColor=white">
+</a>
+  <a href="https://discord.gg/7Spn7C8A5F">
+    <img alt="Join Our Discord" src="https://img.shields.io/badge/Discord-7289DA.svg?style=for-the-badge&logo=discord&logoColor=white">
+  </a>
+</p>
+
+https://github.com/user-attachments/assets/54d0619f-22fd-476c-bf19-9be083d7e710
+
+# 🕸️ Why PySpur?
+
+## Problem: It takes a 1,000 tiny paper cuts to make AI reliable
+
+AI engineers today face three problems of building agents: 
+
+* **Prompt Hell**: Hours of prompt tweaking and trial-and-error frustration.
+* **Workflow Blindspots**: Lack of visibility into step interactions causing hidden failures and confusion.
+* **Terminal Testing Nightmare** Squinting at raw outputs and manually parsing JSON.
+
+We've been there ourselves, too. We launched a graphic design agent early 2024 and quickly reached thousands of users, yet, struggled with the lack of its reliability and existing debugging tools. 
+
+## Solution: A playground for agents that saves time
+
+### Step 1: Define Test Cases
+
+https://github.com/user-attachments/assets/ed9ca45f-7346-463f-b8a4-205bf2c4588f
+ 
+### Step 2: Build the agent in Python code or via UI
+
+https://github.com/user-attachments/assets/7043aae4-fad1-42bd-953a-80c94fce8253
+
+### Step 3: Iterate obsessively
+
+https://github.com/user-attachments/assets/72c9901d-a39c-4f80-85a5-f6f76e55f473
+
+### Step 4: Deploy
+
+https://github.com/user-attachments/assets/b14f34b2-9f16-4bd0-8a0f-1c26e690af93
+
+# ✨ 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:**
+    ```sh
+    pip install pyspur
+    ```
+
+2. **Initialize a new project:**
+    ```sh
+    pyspur init my-project
+    cd my-project
+    ```
+    This will create a new directory with a `.env` file.
+
+3. **Start the server:**
+    ```sh
+    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`
+
+
+# 😎 Feature Reel
+
+## 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.
+
+https://github.com/user-attachments/assets/98cb2b4e-207c-4d97-965b-4fee47c94ce8
+
+## 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
+
+<img width="1919" alt="Loops" src="https://github.com/user-attachments/assets/3aea63dc-f46f-46e9-bddd-e2af9c2a56bf" />
+
+## 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 ]
+
+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](https://www.cursor.com/)/[VS Code](https://code.visualstudio.com/) and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+2. Clone and open the repository
+3. Click "Reopen in Container" when prompted
+
+**Option 2: Manual Setup**
+1. **Clone the repository:**
+    ```sh
+    git clone https://github.com/PySpur-com/pyspur.git
+    cd pyspur
+    ```
+
+2. **Launch using docker-compose.dev.yml:**
+    ```sh
+    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!
+
+![star](https://github.com/user-attachments/assets/71f65273-6755-469d-be44-087bb89d5e76)
+
+Your feedback will be massively appreciated.
+Please [tell us](mailto:founders@pyspur.dev?subject=Feature%20Request&body=I%20want%20this%20feature%3Ai) which features on that list you like to see next or request entirely new ones.

pyspur/README_CN.md

@@ -0,0 +1,156 @@
+![PySpur](./docs/images/hero.png)
+
+<p align="center"><strong>PySpur 是一个基于 Python 编写的 AI 智能体构建器。AI 工程师使用它来构建智能体，逐步执行并检查过去的运行记录。</strong></p>
+
+<p align="center">
+  <a href="./README.md"><img alt="README in English" src="https://img.shields.io/badge/English-blue"></a>
+  <a href="./README_CN.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-blue"></a>
+  <a href="./README_JA.md"><img alt="日本語のREADME" src="https://img.shields.io/badge/日本語-blue"></a>
+  <a href="./README_KR.md"><img alt="README in Korean" src="https://img.shields.io/badge/한국어-blue"></a>
+  <a href="./README_DE.md"><img alt="Deutsche Version der README" src="https://img.shields.io/badge/Deutsch-blue"></a>
+  <a href="./README_FR.md"><img alt="Version française du README" src="https://img.shields.io/badge/Français-blue"></a>
+  <a href="./README_ES.md"><img alt="Versión en español del README" src="https://img.shields.io/badge/Español-blue"></a>
+</p>
+
+<p align="center">
+  <a href="https://docs.pyspur.dev/" target="_blank">
+    <img alt="Docs" src="https://img.shields.io/badge/Docs-green.svg?style=for-the-badge&logo=readthedocs&logoColor=white">
+  </a>
+  <a href="https://calendly.com/d/cnf9-57m-bv3/pyspur-founders" target="_blank">
+    <img alt="Meet us" src="https://img.shields.io/badge/Meet%20us-blue.svg?style=for-the-badge&logo=calendly&logoColor=white">
+  </a>
+  <a href="https://forms.gle/5wHRctedMpgfNGah7" target="_blank">
+    <img alt="Cloud" src="https://img.shields.io/badge/Cloud-orange.svg?style=for-the-badge&logo=cloud&logoColor=white">
+  </a>
+  <a href="https://discord.gg/7Spn7C8A5F">
+    <img alt="Join Our Discord" src="https://img.shields.io/badge/Discord-7289DA.svg?style=for-the-badge&logo=discord&logoColor=white">
+  </a>
+</p>
+
+https://github.com/user-attachments/assets/1ebf78c9-94b2-468d-bbbb-566311df16fe
+
+# 🕸️ 为什么选择 PySpur?
+
+- ✅ **测试驱动**：构建工作流，运行测试用例，并进行迭代。
+- 👤 **人在环路中**：持久化工作流，等待人工批准或拒绝。
+- 🔄 **循环**：具有记忆功能的迭代工具调用。
+- 📤 **文件上传**：上传文件或粘贴 URL 来处理文档。
+- 📋 **结构化输出**：JSON Schema UI 编辑器。
+- 🗃️ **RAG**：解析、分块、嵌入并将数据更新到向量数据库。
+- 🖼️ **多模态**：支持视频、图像、音频、文本、代码。
+- 🧰 **工具**：Slack、Firecrawl.dev、Google Sheets、GitHub 等。
+- 🧪 **评估**：在真实数据集上评估代理。
+- 🚀 **一键部署**：发布为 API 并在任意地方集成。
+- 🐍 **基于 Python**：通过创建单个 Python 文件来添加新节点。
+- 🎛️ **供应商支持**：支持超过 100 个 LLM 供应商、嵌入器和向量数据库。
+
+# ⚡ 快速开始
+
+这是入门的最快方式。需要 Python 3.11 或更高版本。
+
+1. **安装 PySpur:**
+    ```sh
+    pip install pyspur
+    ```
+
+2. **初始化新项目:**
+    ```sh
+    pyspur init my-project
+    cd my-project
+    ```
+    这将创建一个包含 `.env` 文件的新目录。
+
+3. **启动服务器:**
+    ```sh
+    pyspur serve --sqlite
+    ```
+    默认情况下，这将使用 SQLite 数据库在 `http://localhost:6080` 启动 PySpur 应用。
+    我们建议你在 `.env` 文件中配置 Postgres 实例的 URL，以获得更稳定的体验。
+
+4. **[可选] 配置环境和添加 API 密钥:**
+    - **应用界面**: 导航至 API 密钥标签页添加供应商密钥（OpenAI、Anthropic 等）
+    - **手动配置**: 编辑 `.env` 文件（推荐：配置 postgres）并使用 `pyspur serve` 重启
+
+# ✨ 核心优势
+
+## 人在环路中断点:
+
+这些断点在达到时会暂停工作流，并在人工批准后恢复。
+它们为需要质量保证的工作流提供人工监督：在工作流继续之前验证关键输出。
+
+https://github.com/user-attachments/assets/98cb2b4e-207c-4d97-965b-4fee47c94ce8
+
+## 节点级调试：
+
+https://github.com/user-attachments/assets/6e82ad25-2a46-4c50-b030-415ea9994690
+
+## 多模态（上传文件或粘贴 URL）
+
+支持 PDF、视频、音频、图像等……
+
+https://github.com/user-attachments/assets/83ed9a22-1ec1-4d86-9dd6-5d945588fd0b
+
+## 循环
+
+<img width="1919" alt="Loops" src="https://github.com/user-attachments/assets/3aea63dc-f46f-46e9-bddd-e2af9c2a56bf" />
+
+## RAG
+
+### 步骤 1) 创建文档集合（分块 + 解析）
+
+https://github.com/user-attachments/assets/c77723b1-c076-4a64-a01d-6d6677e9c60e
+
+### 步骤 2) 创建向量索引（嵌入 + 向量数据库插入）
+
+https://github.com/user-attachments/assets/50e5c711-dd01-4d92-bb23-181a1c5bba25
+
+## 模块化构建块
+
+https://github.com/user-attachments/assets/6442f0ad-86d8-43d9-aa70-e5c01e55e876
+
+## 评估最终性能
+
+https://github.com/user-attachments/assets/4dc2abc3-c6e6-4d6d-a5c3-787d518de7ae
+
+## 即将推出：自我提升
+
+https://github.com/user-attachments/assets/5bef7a16-ef9f-4650-b385-4ea70fa54c8a
+
+# 🛠️ PySpur 开发环境设置
+#### [ Unix 类系统开发指南。Windows/PC 开发不支持。 ]
+
+我们推荐使用 Cursor/VS Code 和我们的开发容器（`.devcontainer/devcontainer.json`），它提供：
+- 预配置工具和扩展的一致开发环境
+- 针对 Python 和 TypeScript 开发的优化设置
+- 自动热重载和端口转发
+
+**选项 1：Cursor/VS Code 开发容器（推荐）**
+1. 安装 [Cursor](https://www.cursor.com/)/[VS Code](https://code.visualstudio.com/) 和 [Dev Containers 扩展](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+2. 克隆并打开仓库
+3. 当提示时点击"在容器中重新打开"
+
+**选项 2：手动设置**
+1. **克隆仓库:**
+    ```sh
+    git clone https://github.com/PySpur-com/pyspur.git
+    cd pyspur
+    ```
+
+2. **使用 docker-compose.dev.yml 启动:**
+    ```sh
+    docker compose -f docker-compose.dev.yml up --build -d
+    ```
+
+3. **自定义设置:**
+    编辑 `.env` 配置环境（例如：PostgreSQL 设置）。
+
+注意：手动设置需要额外配置，可能无法包含开发容器提供的所有功能。
+
+# ⭐ 支持我们
+
+你可以通过给我们项目 Star 来支持我们的工作！谢谢！
+
+![star](https://github.com/user-attachments/assets/71f65273-6755-469d-be44-087bb89d5e76)
+
+我们非常重视你的反馈。
+请 [告诉我们](mailto:founders@pyspur.dev?subject=Feature%20Request&body=I%20want%20this%20feature%3Ai) 你想在下一次看到列表中的哪些功能或全新的功能。

pyspur/README_DE.md

@@ -0,0 +1,146 @@
+![PySpur](./docs/images/hero.png)
+
+<p align="center"><strong>PySpur ist ein KI-Agenten-Builder in Python. KI-Entwickler nutzen ihn, um Agenten zu erstellen, sie Schritt für Schritt auszuführen und vergangene Durchläufe zu analysieren.</strong></p>
+
+<p align="center">
+  <a href="./README.md"><img alt="README auf Englisch" src="https://img.shields.io/badge/English-blue"></a>
+  <a href="./README_CN.md"><img alt="README auf vereinfachtem Chinesisch" src="https://img.shields.io/badge/简体中文-blue"></a>
+  <a href="./README_JA.md"><img alt="README auf Japanisch" src="https://img.shields.io/badge/日本語-blue"></a>
+  <a href="./README_KR.md"><img alt="README auf Koreanisch" src="https://img.shields.io/badge/한국어-blue"></a>
+  <a href="./README_DE.md"><img alt="Deutsche Version der README" src="https://img.shields.io/badge/Deutsch-blue"></a>
+  <a href="./README_FR.md"><img alt="README auf Französisch" src="https://img.shields.io/badge/Français-blue"></a>
+  <a href="./README_ES.md"><img alt="README auf Spanisch" src="https://img.shields.io/badge/Español-blue"></a>
+</p>
+
+<p align="center">
+  <a href="https://docs.pyspur.dev/" target="_blank">
+    <img alt="Dokumentation" src="https://img.shields.io/badge/Docs-green.svg?style=for-the-badge&logo=readthedocs&logoColor=white">
+  </a>
+  <a href="https://calendly.com/d/cnf9-57m-bv3/pyspur-founders" target="_blank">
+    <img alt="Treffen Sie uns" src="https://img.shields.io/badge/Meet%20us-blue.svg?style=for-the-badge&logo=calendly&logoColor=white">
+  </a>
+  <a href="https://forms.gle/5wHRctedMpgfNGah7" target="_blank">
+    <img alt="Cloud" src="https://img.shields.io/badge/Cloud-orange.svg?style=for-the-badge&logo=cloud&logoColor=white">
+  </a>
+  <a href="https://discord.gg/7Spn7C8A5F">
+    <img alt="Discord beitreten" src="https://img.shields.io/badge/Discord-7289DA.svg?style=for-the-badge&logo=discord&logoColor=white">
+  </a>
+</p>
+
+https://github.com/user-attachments/assets/1ebf78c9-94b2-468d-bbbb-566311df16fe
+
+# 🕸️ Warum PySpur?
+
+- ✅ **Testgetrieben**: Erstellen Sie Workflows, führen Sie Testfälle aus und iterieren Sie.
+- 👤 **Human in the Loop**: Persistente Workflows, die auf Genehmigung oder Ablehnung des Users warten.
+- 🔄 **Loops**: Wiederholte Toolaufrufe mit Zwischenspeicherung.
+- 📤 **Datei-Upload**: Laden Sie Dateien hoch oder fügen Sie URLs ein, um Dokumente zu verarbeiten.
+- 📋 **Strukturierte Outputs**: UI-Editor für JSON-Schemata.
+- 🗃️ **RAG**: Daten parsen, in Abschnitte unterteilen, einbetten und in eine Vektor-Datenbank einfügen/aktualisieren.
+- 🖼️ **Multimodal**: Unterstützung für Video, Bilder, Audio, Texte, Code.
+- 🧰 **Tools**: Slack, Firecrawl.dev, Google Sheets, GitHub und mehr.
+- 🧪 **Evaluierungen**: Bewerten Sie Agenten anhand von realen Datensätzen.
+- 🚀 **One-Click Deploy**: Veröffentlichen Sie Ihre Lösung als API und integrieren Sie sie überall.
+- 🐍 **Python-basiert**: Fügen Sie neue Knoten hinzu, indem Sie eine einzige Python-Datei erstellen.
+- 🎛️ **Support für jeden Anbieter**: Über 100 LLM-Anbieter, Einbettungslösungen und Vektor-Datenbanken.
+
+# ⚡ Schnellstart
+
+Dies ist der schnellste Weg, um loszulegen. Python 3.11 oder höher wird benötigt.
+
+1. **PySpur installieren:**
+    ```sh
+    pip install pyspur
+    ```
+
+2. **Ein neues Projekt initialisieren:**
+    ```sh
+    pyspur init my-project
+    cd my-project
+    ```
+    Dadurch wird ein neues Verzeichnis mit einer `.env`-Datei erstellt.
+
+3. **Den Server starten:**
+    ```sh
+    pyspur serve --sqlite
+    ```
+    Standardmäßig startet dies die PySpur-App unter `http://localhost:6080` mit einer SQLite-Datenbank.
+    Wir empfehlen, in der `.env`-Datei eine PostgreSQL-Instanz-URL zu konfigurieren, um eine stabilere Erfahrung zu gewährleisten.
+
+4. **[Optional] Umgebung konfigurieren und API-Schlüssel hinzufügen:**
+    - **App-Oberfläche**: Navigieren Sie zum Tab „API Keys", um Anbieter-Schlüssel hinzuzufügen (OpenAI, Anthropic usw.)
+    - **Manuelle Konfiguration**: Bearbeiten Sie die `.env`-Datei (empfohlen: PostgreSQL konfigurieren) und starten Sie mit `pyspur serve` neu
+
+# ✨ Kernvorteile
+
+## Mensch-im-Regelkreis-Haltepunkte:
+
+Diese Haltepunkte pausieren den Workflow, wenn sie erreicht werden, und setzen ihn fort, sobald ein Mensch ihn genehmigt.
+Sie ermöglichen menschliche Aufsicht für Workflows, die Qualitätssicherung erfordern: Überprüfen Sie kritische Ausgaben, bevor der Workflow fortgesetzt wird.
+
+https://github.com/user-attachments/assets/98cb2b4e-207c-4d97-965b-4fee47c94ce8
+
+## Debuggen auf Node-Ebene:
+
+https://github.com/user-attachments/assets/6e82ad25-2a46-4c50-b030-415ea9994690
+
+## Multimodal (Dateien hochladen oder URLs einfügen)
+
+PDFs, Videos, Audio, Bilder, ...
+
+https://github.com/user-attachments/assets/83ed9a22-1ec1-4d86-9dd6-5d945588fd0b
+
+## Loops
+
+<img width="1919" alt="Loops" src="https://github.com/user-attachments/assets/3aea63dc-f46f-46e9-bddd-e2af9c2a56bf" />
+
+## RAG
+
+### Schritt 1) Erstellen einer Dokumentensammlung (Chunking + Parsing)
+
+https://github.com/user-attachments/assets/c77723b1-c076-4a64-a01d-6d6677e9c60e
+
+### Schritt 2) Erstellen eines Vektorindex (Einbettung + Einfügen/Aktualisieren in der Vektor-Datenbank)
+
+https://github.com/user-attachments/assets/50e5c711-dd01-4d92-bb23-181a1c5bba25
+
+## Modulare Bausteine
+
+https://github.com/user-attachments/assets/6442f0ad-86d8-43d9-aa70-e5c01e55e876
+
+## Endgültige Leistung bewerten
+
+https://github.com/user-attachments/assets/4dc2abc3-c6e6-4d6d-a5c3-787d518de7ae
+
+## Demnächst: Selbstverbesserung
+
+https://github.com/user-attachments/assets/5bef7a16-ef9f-4650-b385-4ea70fa54c8a
+
+# 🛠️ PySpur Entwicklungs-Setup
+#### [ Anweisungen für die Entwicklung auf Unix-ähnlichen Systemen. Entwicklung auf Windows/PC wird nicht unterstützt ]
+
+Für die Entwicklung folgen Sie diesen Schritten:
+
+1. **Das Repository klonen:**
+    ```sh
+    git clone https://github.com/PySpur-com/pyspur.git
+    cd pyspur
+    ```
+
+2. **Mit docker-compose.dev.yml starten:**
+    ```sh
+    docker compose -f docker-compose.dev.yml up --build -d
+    ```
+    Dadurch wird eine lokale Instanz von PySpur mit aktiviertem Hot-Reloading für die Entwicklung gestartet.
+
+3. **Ihre Einrichtung anpassen:**
+    Bearbeiten Sie die `.env`-Datei, um Ihre Umgebung zu konfigurieren. Standardmäßig verwendet PySpur eine lokale PostgreSQL-Datenbank. Um eine externe Datenbank zu nutzen, ändern Sie die `POSTGRES_*`-Variablen in der `.env`.
+
+# ⭐ Unterstützen Sie uns
+
+Sie können uns bei unserer Arbeit unterstützen, indem Sie einen Stern hinterlassen! Vielen Dank!
+
+![star](https://github.com/user-attachments/assets/71f65273-6755-469d-be44-087bb89d5e76)
+
+Ihr Feedback wird sehr geschätzt.
+Bitte [sagen Sie uns](mailto:founders@pyspur.dev?subject=Feature%20Request&body=I%20want%20this%20feature%3Ai), welche Funktionen aus dieser Liste Sie als Nächstes sehen möchten oder schlagen Sie ganz neue vor.

pyspur/README_ES.md

@@ -0,0 +1,148 @@
+![PySpur](./docs/images/hero.png)
+
+<p align="center"><strong>PySpur es un constructor de agentes de IA en Python. Los ingenieros de IA lo utilizan para crear agentes, ejecutarlos paso a paso e inspeccionar ejecuciones anteriores.</strong></p>
+
+<p align="center">
+  <a href="./README.md"><img alt="README en inglés" src="https://img.shields.io/badge/English-blue"></a>
+  <a href="./README_CN.md"><img alt="Versión en chino simplificado" src="https://img.shields.io/badge/简体中文-blue"></a>
+  <a href="./README_JA.md"><img alt="README en japonés" src="https://img.shields.io/badge/日本語-blue"></a>
+  <a href="./README_KR.md"><img alt="README en coreano" src="https://img.shields.io/badge/한국어-blue"></a>
+  <a href="./README_DE.md"><img alt="Versión en alemán del README" src="https://img.shields.io/badge/Deutsch-blue"></a>
+  <a href="./README_FR.md"><img alt="Versión en francés del README" src="https://img.shields.io/badge/Français-blue"></a>
+  <a href="./README_ES.md"><img alt="Versión en español del README" src="https://img.shields.io/badge/Español-blue"></a>
+</p>
+
+<p align="center">
+  <a href="https://docs.pyspur.dev/" target="_blank">
+    <img alt="Docs" src="https://img.shields.io/badge/Docs-green.svg?style=for-the-badge&logo=readthedocs&logoColor=white">
+  </a>
+  <a href="https://calendly.com/d/cnf9-57m-bv3/pyspur-founders" target="_blank">
+    <img alt="Conócenos" src="https://img.shields.io/badge/Meet%20us-blue.svg?style=for-the-badge&logo=calendly&logoColor=white">
+  </a>
+  <a href="https://forms.gle/5wHRctedMpgfNGah7" target="_blank">
+    <img alt="Cloud" src="https://img.shields.io/badge/Cloud-orange.svg?style=for-the-badge&logo=cloud&logoColor=white">
+  </a>
+  <a href="https://discord.gg/7Spn7C8A5F">
+    <img alt="Únete a nuestro Discord" src="https://img.shields.io/badge/Discord-7289DA.svg?style=for-the-badge&logo=discord&logoColor=white">
+  </a>
+</p>
+
+https://github.com/user-attachments/assets/1ebf78c9-94b2-468d-bbbb-566311df16fe
+
+# 🕸️ ¿Por qué PySpur?
+
+- ✅ **Desarrollo Guiado por Pruebas**: Construye flujos de trabajo, ejecuta casos de prueba e itera.
+- 👤 **Humano en el Bucle**: Flujos de trabajo persistentes que esperan aprobación o rechazo humano.
+- 🔄 **Bucles**: Llamadas iterativas a herramientas con memoria.
+- 📤 **Carga de Archivos**: Sube archivos o pega URLs para procesar documentos.
+- 📋 **Salidas Estructuradas**: Editor de interfaz para esquemas JSON.
+- 🗃️ **RAG**: Analiza, segmenta, incrusta y actualiza datos en una base de datos vectorial.
+- 🖼️ **Multimodal**: Soporte para video, imágenes, audio, textos y código.
+- 🧰 **Herramientas**: Slack, Firecrawl.dev, Google Sheets, GitHub y más.
+- 🧪 **Evaluaciones**: Evalúa agentes en conjuntos de datos del mundo real.
+- 🚀 **Despliegue con un clic**: Publica como una API e intégrala donde desees.
+- 🐍 **Basado en Python**: Agrega nuevos nodos creando un solo archivo Python.
+- 🎛️ **Soporte para Cualquier Proveedor**: Más de 100 proveedores de LLM, embedders y bases de datos vectoriales.
+
+# ⚡ Inicio Rápido
+
+Esta es la forma más rápida de comenzar. Se requiere Python 3.11 o superior.
+
+1. **Instala PySpur:**
+    ```sh
+    pip install pyspur
+    ```
+
+2. **Inicializa un nuevo proyecto:**
+    ```sh
+    pyspur init my-project
+    cd my-project
+    ```
+    Esto creará un nuevo directorio con un archivo `.env`.
+
+3. **Inicia el servidor:**
+    ```sh
+    pyspur serve --sqlite
+    ```
+    Por defecto, esto iniciará la aplicación PySpur en `http://localhost:6080` utilizando una base de datos SQLite.
+    Se recomienda configurar una URL de instancia de Postgres en el archivo `.env` para obtener una experiencia más estable.
+
+4. **[Opcional] Configura tu entorno y añade claves API:**
+    - **A través de la interfaz de la aplicación**: Navega a la pestaña de API Keys para añadir claves de proveedores (OpenAI, Anthropic, etc.)
+    - **Configuración manual**: Edita el archivo `.env` (recomendado: configura postgres) y reinicia con `pyspur serve`
+
+¡Eso es todo! Haz clic en "New Spur" para crear un flujo de trabajo, o comienza con una de las plantillas predefinidas.
+
+# ✨ Beneficios Principales
+
+## Puntos de Interrupción con Humano en el Bucle:
+
+Estos puntos de interrupción pausan el flujo de trabajo cuando se alcanzan y lo reanudan tan pronto como un humano lo aprueba.
+Permiten la supervisión humana para flujos de trabajo que requieren garantía de calidad: verifique las salidas críticas antes de que el flujo de trabajo continúe.
+
+https://github.com/user-attachments/assets/98cb2b4e-207c-4d97-965b-4fee47c94ce8
+
+## Depuración a Nivel de Nodo:
+
+https://github.com/user-attachments/assets/6e82ad25-2a46-4c50-b030-415ea9994690
+
+## Multimodal (Sube archivos o pega URLs)
+
+PDFs, Videos, Audio, Imágenes, ...
+
+https://github.com/user-attachments/assets/83ed9a22-1ec1-4d86-9dd6-5d945588fd0b
+
+## Bucles
+
+<img width="1919" alt="Bucles" src="https://github.com/user-attachments/assets/3aea63dc-f46f-46e9-bddd-e2af9c2a56bf" />
+
+## RAG
+
+### Paso 1) Crear Colección de Documentos (Segmentación + Análisis)
+
+https://github.com/user-attachments/assets/c77723b1-c076-4a64-a01d-6d6677e9c60e
+
+### Paso 2) Crear Índice Vectorial (Incrustación + Actualización en DB Vectorial)
+
+https://github.com/user-attachments/assets/50e5c711-dd01-4d92-bb23-181a1c5bba25
+
+## Bloques Modulares
+
+https://github.com/user-attachments/assets/6442f0ad-86d8-43d9-aa70-e5c01e55e876
+
+## Evaluar el Rendimiento Final
+
+https://github.com/user-attachments/assets/4dc2abc3-c6e6-4d6d-a5c3-787d518de7ae
+
+## Próximamente: Auto-mejora
+
+https://github.com/user-attachments/assets/5bef7a16-ef9f-4650-b385-4ea70fa54c8a
+
+# 🛠️ Configuración de Desarrollo de PySpur
+#### [ Instrucciones para el desarrollo en sistemas tipo Unix. Desarrollo en Windows/PC no es soportado ]
+
+Para el desarrollo, sigue estos pasos:
+
+1. **Clona el repositorio:**
+    ```sh
+    git clone https://github.com/PySpur-com/pyspur.git
+    cd pyspur
+    ```
+
+2. **Inicia utilizando docker-compose.dev.yml:**
+    ```sh
+    docker compose -f docker-compose.dev.yml up --build -d
+    ```
+    Esto iniciará una instancia local de PySpur con recarga en caliente habilitada para el desarrollo.
+
+3. **Personaliza tu configuración:**
+    Edita el archivo `.env` para configurar tu entorno. Por defecto, PySpur utiliza una base de datos PostgreSQL local. Para usar una base de datos externa, modifica las variables `POSTGRES_*` en el archivo `.env`.
+
+# ⭐ Apóyanos
+
+¡Puedes apoyarnos en nuestro trabajo dándonos una estrella! ¡Gracias!
+
+![star](https://github.com/user-attachments/assets/71f65273-6755-469d-be44-087bb89d5e76)
+
+Tu retroalimentación será enormemente apreciada.
+Por favor [dinos](mailto:founders@pyspur.dev?subject=Feature%20Request&body=I%20want%20this%20feature%3Ai) qué características de esa lista te gustaría ver a continuación o solicita nuevas funcionalidades.

pyspur/README_FR.md

@@ -0,0 +1,148 @@
+![PySpur](./docs/images/hero.png)
+
+<p align="center"><strong>PySpur est un créateur d'agents d'IA en Python. Les ingénieurs en IA l'utilisent pour créer des agents, les exécuter étape par étape et inspecter les exécutions passées.</strong></p>
+
+<p align="center">
+  <a href="./README.md"><img alt="README in English" src="https://img.shields.io/badge/English-blue"></a>
+  <a href="./README_CN.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-blue"></a>
+  <a href="./README_JA.md"><img alt="日本語のREADME" src="https://img.shields.io/badge/日本語-blue"></a>
+  <a href="./README_KR.md"><img alt="README in Korean" src="https://img.shields.io/badge/한국어-blue"></a>
+  <a href="./README_DE.md"><img alt="Deutsche Version der README" src="https://img.shields.io/badge/Deutsch-blue"></a>
+  <a href="./README_FR.md"><img alt="Version française du README" src="https://img.shields.io/badge/Français-blue"></a>
+  <a href="./README_ES.md"><img alt="Versión en español del README" src="https://img.shields.io/badge/Español-blue"></a>
+</p>
+
+<p align="center">
+<a href="https://docs.pyspur.dev/" target="_blank">
+  <img alt="Documentation" src="https://img.shields.io/badge/Docs-green.svg?style=for-the-badge&logo=readthedocs&logoColor=white">
+</a>
+<a href="https://calendly.com/d/cnf9-57m-bv3/pyspur-founders" target="_blank">
+  <img alt="Rencontrez-nous" src="https://img.shields.io/badge/Meet%20us-blue.svg?style=for-the-badge&logo=calendly&logoColor=white">
+</a>
+<a href="https://forms.gle/5wHRctedMpgfNGah7" target="_blank">
+  <img alt="Cloud" src="https://img.shields.io/badge/Cloud-orange.svg?style=for-the-badge&logo=cloud&logoColor=white">
+</a>
+<a href="https://discord.gg/7Spn7C8A5F">
+  <img alt="Rejoignez notre Discord" src="https://img.shields.io/badge/Discord-7289DA.svg?style=for-the-badge&logo=discord&logoColor=white">
+</a>
+</p>
+
+https://github.com/user-attachments/assets/1ebf78c9-94b2-468d-bbbb-566311df16fe
+
+# 🕸️ Pourquoi PySpur ?
+
+- ✅ **Piloté par les tests** : Construisez des workflows, exécutez des cas de test et itérez.
+- 👤 **Humain dans la boucle** : Workflows persistants qui attendent l'approbation ou le rejet humain.
+- 🔄 **Boucles** : Appels d'outils itératifs avec mémoire.
+- 📤 **Téléversement de fichiers** : Téléchargez des fichiers ou collez des URL pour traiter des documents.
+- 📋 **Sorties structurées** : Éditeur d'interface utilisateur pour les schémas JSON.
+- 🗃️ **RAG** : Analyser, découper, intégrer et insérer ou mettre à jour des données dans une base de données vectorielle.
+- 🖼️ **Multimodal** : Support pour vidéos, images, audio, textes, code.
+- 🧰 **Outils** : Slack, Firecrawl.dev, Google Sheets, GitHub, et plus encore.
+- 🧪 **Évaluations** : Évaluez les agents sur des ensembles de données réelles.
+- 🚀 **Déploiement en un clic** : Publiez en tant qu'API et intégrez-le où vous le souhaitez.
+- 🐍 **Basé sur Python** : Ajoutez de nouveaux nœuds en créant un seul fichier Python.
+- 🎛️ **Support multi-fournisseurs** : >100 fournisseurs de LLM, intégrateurs et bases de données vectorielles.
+
+# ⚡ Démarrage rapide
+
+C'est la manière la plus rapide de commencer. Python 3.11 ou une version supérieure est requis.
+
+1. **Installer PySpur :**
+    ```sh
+    pip install pyspur
+    ```
+
+2. **Initialiser un nouveau projet :**
+    ```sh
+    pyspur init my-project
+    cd my-project
+    ```
+    Cela va créer un nouveau répertoire avec un fichier `.env`.
+
+3. **Démarrer le serveur :**
+    ```sh
+    pyspur serve --sqlite
+    ```
+    Par défaut, cela démarrera l'application PySpur sur `http://localhost:6080` en utilisant une base de données SQLite.
+    Nous vous recommandons de configurer une URL d'instance Postgres dans le fichier `.env` pour une expérience plus stable.
+
+4. **[Optionnel] Configurer votre environnement et ajouter des clés API :**
+    - **Via l'interface de l'application** : Naviguez vers l'onglet des clés API pour ajouter des clés de fournisseurs (OpenAI, Anthropic, etc.)
+    - **Configuration manuelle** : Éditez le fichier `.env` (recommandé : configurez postgres) et redémarrez avec `pyspur serve`
+
+C'est tout ! Cliquez sur « New Spur » pour créer un workflow, ou commencez avec l'un des modèles de base.
+
+# ✨ Avantages principaux
+
+## Points d'arrêt avec humain dans la boucle :
+
+Ces points d'arrêt mettent en pause le flux de travail lorsqu'ils sont atteints et le reprennent dès qu'un humain l'approuve.
+Ils permettent une supervision humaine pour les flux de travail nécessitant une assurance qualité : vérifiez les sorties critiques avant que le flux de travail ne continue.
+
+https://github.com/user-attachments/assets/98cb2b4e-207c-4d97-965b-4fee47c94ce8
+
+## Déboguer au niveau des nœuds :
+
+https://github.com/user-attachments/assets/6e82ad25-2a46-4c50-b030-415ea9994690
+
+## Multimodal (tél��verser des fichiers ou coller des URL)
+
+PDF, vidéos, audio, images, ...
+
+https://github.com/user-attachments/assets/83ed9a22-1ec1-4d86-9dd6-5d945588fd0b
+
+## Boucles
+
+<img width="1919" alt="Loops" src="https://github.com/user-attachments/assets/3aea63dc-f46f-46e9-bddd-e2af9c2a56bf" />
+
+## RAG
+
+### Étape 1) Créer une collection de documents (découpage + analyse)
+
+https://github.com/user-attachments/assets/c77723b1-c076-4a64-a01d-6d6677e9c60e
+
+### Étape 2) Créer un index vectoriel (intégration + insertion/mise à jour dans la base de données vectorielle)
+
+https://github.com/user-attachments/assets/50e5c711-dd01-4d92-bb23-181a1c5bba25
+
+## Blocs modulaires
+
+https://github.com/user-attachments/assets/6442f0ad-86d8-43d9-aa70-e5c01e55e876
+
+## Évaluer la performance finale
+
+https://github.com/user-attachments/assets/4dc2abc3-c6e6-4d6d-a5c3-787d518de7ae
+
+## Bientôt : Auto-amélioration
+
+https://github.com/user-attachments/assets/5bef7a16-ef9f-4650-b385-4ea70fa54c8a
+
+# 🛠️ Configuration de développement de PySpur
+#### [ Instructions pour le développement sur des systèmes de type Unix. Le développement sur Windows/PC n'est pas supporté ]
+
+Pour le développement, suivez ces étapes :
+
+1. **Cloner le dépôt :**
+    ```sh
+    git clone https://github.com/PySpur-com/pyspur.git
+    cd pyspur
+    ```
+
+2. **Lancer en utilisant docker-compose.dev.yml :**
+    ```sh
+    docker compose -f docker-compose.dev.yml up --build -d
+    ```
+    Cela démarrera une instance locale de PySpur avec le rechargement à chaud activé pour le développement.
+
+3. **Personnaliser votre configuration :**
+    Modifiez le fichier `.env` pour configurer votre environnement. Par défaut, PySpur utilise une base de données PostgreSQL locale. Pour utiliser une base de données externe, modifiez les variables `POSTGRES_*` dans le fichier `.env`.
+
+# ⭐ Soutenez-nous
+
+Vous pouvez nous soutenir en laissant une étoile ! Merci !
+
+![star](https://github.com/user-attachments/assets/71f65273-6755-469d-be44-087bb89d5e76)
+
+Vos retours seront grandement appréciés.
+Veuillez nous [faire part](mailto:founders@pyspur.dev?subject=Feature%20Request&body=I%20want%20this%20feature%3Ai) des fonctionnalités de cette liste que vous souhaitez voir prochainement ou proposer de toutes nouvelles fonctionnalités.

pyspur/README_JA.md

@@ -0,0 +1,145 @@
+![PySpur](./docs/images/hero.png)
+
+<p align="center"><strong>PySpurはPython製のAIエージェントビルダーです。AIエンジニアはこれを利用してエージェントを構築し、ステップバイステップで実行し、過去の実行結果を検証します。</strong></p>
+
+<p align="center">
+  <a href="./README.md"><img alt="英語版README" src="https://img.shields.io/badge/English-blue"></a>
+  <a href="./README_CN.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-blue"></a>
+  <a href="./README_JA.md"><img alt="日本語のREADME" src="https://img.shields.io/badge/日本語-blue"></a>
+  <a href="./README_KR.md"><img alt="韓国語版README" src="https://img.shields.io/badge/한국어-blue"></a>
+  <a href="./README_DE.md"><img alt="ドイツ語版README" src="https://img.shields.io/badge/Deutsch-blue"></a>
+  <a href="./README_FR.md"><img alt="フランス語版README" src="https://img.shields.io/badge/Français-blue"></a>
+  <a href="./README_ES.md"><img alt="スペイン語版README" src="https://img.shields.io/badge/Español-blue"></a>
+</p>
+
+<p align="center">
+  <a href="https://docs.pyspur.dev/" target="_blank">
+    <img alt="ドキュメント" src="https://img.shields.io/badge/Docs-green.svg?style=for-the-badge&logo=readthedocs&logoColor=white">
+  </a>
+  <a href="https://calendly.com/d/cnf9-57m-bv3/pyspur-founders" target="_blank">
+    <img alt="お会いしましょう" src="https://img.shields.io/badge/Meet%20us-blue.svg?style=for-the-badge&logo=calendly&logoColor=white">
+  </a>
+  <a href="https://forms.gle/5wHRctedMpgfNGah7" target="_blank">
+    <img alt="クラウド" src="https://img.shields.io/badge/Cloud-orange.svg?style=for-the-badge&logo=cloud&logoColor=white">
+  </a>
+  <a href="https://discord.gg/7Spn7C8A5F">
+    <img alt="Discordに参加する" src="https://img.shields.io/badge/Discord-7289DA.svg?style=for-the-badge&logo=discord&logoColor=white">
+  </a>
+</p>
+
+https://github.com/user-attachments/assets/1ebf78c9-94b2-468d-bbbb-566311df16fe
+
+# 🕸️ なぜ PySpur なのか？
+
+- ✅ **テスト駆動型**: ワークフローを構築し、テストケースを実行し、反復します。
+- 👤 **ヒューマンインザループ**: 人間の承認または拒否を待つ永続的なワークフロー。
+- 🔄 **ループ**: メモリを活用した反復的なツール呼び出し。
+- 📤 **ファイルアップロード**: ファイルのアップロードやURLの貼り付けによりドキュメントを処理します。
+- 📋 **構造化された出力**: JSONスキーマ用のUIエディタ。
+- 🗃️ **RAG**: データを解析、分割、埋め込み、そしてVector DBにアップサートします。
+- 🖼️ **マルチモーダル**: ビデオ、画像、オーディオ、テキスト、コードに対応。
+- 🧰 **ツール**: Slack、Firecrawl.dev、Google Sheets、GitHubなど多数。
+- 🧪 **評価**: 実際のデータセットでエージェントを評価します。
+- 🚀 **ワンクリックデプロイ**: APIとして公開し、どこにでも統合可能。
+- 🐍 **Pythonベース**: 単一のPythonファイルを作成するだけで新しいノードを追加できます。
+- 🎛️ **どのベンダーにも対応**: 100以上のLLMプロバイダー、エンベッダー、Vector DBに対応。
+
+# ⚡ クイックスタート
+
+これは最も迅速なスタート方法です。Python 3.11以上が必要です。
+
+1. **PySpurのインストール:**
+    ```sh
+    pip install pyspur
+    ```
+
+2. **新しいプロジェクトの初期化:**
+    ```sh
+    pyspur init my-project
+    cd my-project
+    ```
+    これにより、`.env`ファイルを含む新しいディレクトリが作成されます。
+
+3. **サーバーの起動:**
+    ```sh
+    pyspur serve --sqlite
+    ```
+    デフォルトでは、SQLiteデータベースを使用して `http://localhost:6080` でPySpurアプリが起動します。より安定した動作を求める場合は、`.env`ファイルにPostgresのインスタンスURLを設定することを推奨します。
+
+4. **[オプション] 環境設定とAPIキーの追加:**
+    - **アプリUI**: APIキータブに移動して各プロバイダーのキー（OpenAI、Anthropicなど）を追加
+    - **手動設定**: `.env`ファイルを編集（推奨：postgresを設定）し、`pyspur serve`で再起動
+
+# ✨ 主な利点
+
+## ヒューマンインザループブレークポイント:
+
+これらのブレークポイントは到達時にワークフローを一時停止し、人間が承認するとすぐに再開します。
+品質保証が必要なワークフローに人間の監視を可能にします：ワークフローが進む前に重要な出力を検証します。
+
+https://github.com/user-attachments/assets/98cb2b4e-207c-4d97-965b-4fee47c94ce8
+
+## ノードレベルでのデバッ���:
+
+https://github.com/user-attachments/assets/6e82ad25-2a46-4c50-b030-415ea9994690
+
+## マルチモーダル（ファイルアップロードまたはURL貼り付け）
+
+PDF、ビデオ、オーディオ、画像、…
+
+https://github.com/user-attachments/assets/83ed9a22-1ec1-4d86-9dd6-5d945588fd0b
+
+## ループ
+
+<img width="1919" alt="Loops" src="https://github.com/user-attachments/assets/3aea63dc-f46f-46e9-bddd-e2af9c2a56bf" />
+
+## RAG
+
+### ステップ 1) ドキュメントコレクションの作成（チャンク分割＋解析）
+
+https://github.com/user-attachments/assets/c77723b1-c076-4a64-a01d-6d6677e9c60e
+
+### ステップ 2) ベクターインデックスの作成（埋め込み＋Vector DBアップサート）
+
+https://github.com/user-attachments/assets/50e5c711-dd01-4d92-bb23-181a1c5bba25
+
+## モジュール式ビルディングブロック
+
+https://github.com/user-attachments/assets/6442f0ad-86d8-43d9-aa70-e5c01e55e876
+
+## 最終パフォーマンスの評価
+
+https://github.com/user-attachments/assets/4dc2abc3-c6e6-4d6d-a5c3-787d518de7ae
+
+## 近日公開予定：自己改善
+
+https://github.com/user-attachments/assets/5bef7a16-ef9f-4650-b385-4ea70fa54c8a
+
+# 🛠️ PySpur 開発環境セットアップ
+#### [ Unix系システムでの開発向けの手順です。Windows/PCでの開発はサポートされていません ]
+
+開発のためには、以下の手順に従ってください：
+
+1. **リポジトリのクローン:**
+    ```sh
+    git clone https://github.com/PySpur-com/pyspur.git
+    cd pyspur
+    ```
+
+2. **docker-compose.dev.ymlを使用して起動:**
+    ```sh
+    docker compose -f docker-compose.dev.yml up --build -d
+    ```
+    これにより、開発用にホットリロードが有効なPySpurのローカルインスタンスが起動します。
+
+3. **セットアップのカスタマイズ:**
+    環境設定のために `.env` ファイルを編集してください。デフォルトでは、PySpurはローカルのPostgreSQLデータベースを使用しています。外部データベースを使用する場合は、`.env` 内の `POSTGRES_*` 変数を変更してください.
+
+# ⭐ サポート
+
+スターを押していただくことで、私たちの活動をサポートしていただけます。ありがとうございます！
+
+![star](https://github.com/user-attachments/assets/71f65273-6755-469d-be44-087bb89d5e76)
+
+皆様のフィードバックを大変ありがたく思います。
+次にどの機能を見たいか、または全く新しい機能のリクエストがあれば、ぜひ[お知らせください](mailto:founders@pyspur.dev?subject=Feature%20Request&body=I%20want%20this%20feature%3Ai).

pyspur/README_KR.md

@@ -0,0 +1,146 @@
+![PySpur](./docs/images/hero.png)
+
+<p align="center"><strong>PySpur은 파이썬 기반의 AI 에이전트 빌더입니다. AI 엔지니어들은 이를 사용해 에이전트를 구축하고, 단계별로 실행하며 과거 실행 기록을 검토합니다.</strong></p>
+
+<p align="center">
+  <a href="./README.md"><img alt="영문 README" src="https://img.shields.io/badge/English-blue"></a>
+  <a href="./README_CN.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-blue"></a>
+  <a href="./README_JA.md"><img alt="日本語のREADME" src="https://img.shields.io/badge/日本語-blue"></a>
+  <a href="./README_KR.md"><img alt="한국어 README" src="https://img.shields.io/badge/한국어-blue"></a>
+  <a href="./README_DE.md"><img alt="독일어 README" src="https://img.shields.io/badge/Deutsch-blue"></a>
+  <a href="./README_FR.md"><img alt="프랑스어 README" src="https://img.shields.io/badge/Français-blue"></a>
+  <a href="./README_ES.md"><img alt="스페인어 README" src="https://img.shields.io/badge/Español-blue"></a>
+</p>
+
+<p align="center">
+  <a href="https://docs.pyspur.dev/" target="_blank">
+    <img alt="문서" src="https://img.shields.io/badge/Docs-green.svg?style=for-the-badge&logo=readthedocs&logoColor=white">
+  </a>
+  <a href="https://calendly.com/d/cnf9-57m-bv3/pyspur-founders" target="_blank">
+    <img alt="만나기" src="https://img.shields.io/badge/Meet%20us-blue.svg?style=for-the-badge&logo=calendly&logoColor=white">
+  </a>
+  <a href="https://forms.gle/5wHRctedMpgfNGah7" target="_blank">
+    <img alt="클라우드" src="https://img.shields.io/badge/Cloud-orange.svg?style=for-the-badge&logo=cloud&logoColor=white">
+  </a>
+  <a href="https://discord.gg/7Spn7C8A5F">
+    <img alt="디스코드 참여" src="https://img.shields.io/badge/Discord-7289DA.svg?style=for-the-badge&logo=discord&logoColor=white">
+  </a>
+</p>
+
+https://github.com/user-attachments/assets/1ebf78c9-94b2-468d-bbbb-566311df16fe
+
+# 🕸️ 왜 PySpur인가?
+
+- ✅ **테스트 주도**: 워크플로우를 구축하고, 테스트 케이스를 실행하며, 반복합니다.
+- 👤 **인간 참여 루프**: 인간의 승인 또는 거부를 기다리는 지속적인 워크플로우.
+- 🔄 **루프**: 메모리를 활용한 반복적 도구 호출.
+- 📤 **파일 업로드**: 파일을 업로드하거나 URL을 붙여넣어 문서를 처리.
+- 📋 **구조화된 출력**: JSON 스키마용 UI 편집기.
+- 🗃️ **RAG**: 데이터를 파싱, 청킹, 임베딩 및 벡터 DB에 업서트.
+- 🖼️ **멀티모달**: 비디오, 이미지, 오디오, 텍스트, 코드 지원.
+- 🧰 **도구**: Slack, Firecrawl.dev, Google Sheets, GitHub 등.
+- 🧪 **평가**: 실제 데이터셋에서 에이전트 평가.
+- 🚀 **원클릭 배포**: API로 발행하여 원하는 곳에 통합.
+- 🐍 **파이썬 기반**: 단일 파이썬 파일 생성으로 새 노드 추가.
+- 🎛️ **모든 벤더 지원**: 100개 이상의 LLM 제공업체, 임베더, 벡터 DB 지원.
+
+# ⚡ 빠른 시작
+
+시작하는 가장 빠른 방법입니다. 파이썬 3.11 이상이 필요합니다.
+
+1. **PySpur 설치:**
+    ```sh
+    pip install pyspur
+    ```
+
+2. **새 프로젝트 초기화:**
+    ```sh
+    pyspur init my-project
+    cd my-project
+    ```
+    새 디렉토리와 함께 `.env` 파일이 생성됩니다.
+
+3. **서버 시작:**
+    ```sh
+    pyspur serve --sqlite
+    ```
+    기본적으로 SQLite 데이터베이스를 사용하여 `http://localhost:6080`에서 PySpur 앱이 시작됩니다.
+    보다 안정적인 사용을 위해 `.env` 파일에 PostgreSQL 인스턴스 URL을 설정하는 것을 권장합니다.
+
+4. **[선택 사항] 환경 구성 및 API 키 추가:**
+    - **앱 UI**: API 키 탭으로 이동하여 공급자 키(OpenAI, Anthropic 등) 추가
+    - **수동 구성**: `.env` 파일 편집(권장: postgres 구성) 후 `pyspur serve`로 재시작
+
+# ✨ 핵심 이점
+
+## 인간 참여 중단점:
+
+이러한 중단점은 도달했을 때 워크플로우를 일시 중지하고 인간이 승인하면 재개됩니다.
+품질 보증이 필요한 워크플로우에 인간의 감독을 가능하게 합니다: 워크플로우가 진행되기 전에 중요한 출력을 검증합니다.
+
+https://github.com/user-attachments/assets/98cb2b4e-207c-4d97-965b-4fee47c94ce8
+
+## 노드 레벨에서 디버그:
+
+https://github.com/user-attachments/assets/6e82ad25-2a46-4c50-b030-415ea9994690
+
+## 멀티모달 (파일 업로드 또는 URL 붙여넣기)
+
+PDF, 비디오, 오디오, 이미지, ...
+
+https://github.com/user-attachments/assets/83ed9a22-1ec1-4d86-9dd6-5d945588fd0b
+
+## 루프
+
+<img width="1919" alt="Loops" src="https://github.com/user-attachments/assets/3aea63dc-f46f-46e9-bddd-e2af9c2a56bf" />
+
+## RAG
+
+### 1단계) 문서 컬렉션 생성 (청킹 + 파싱)
+
+https://github.com/user-attachments/assets/c77723b1-c076-4a64-a01d-6d6677e9c60e
+
+### 2단계) 벡터 인덱스 생성 (임베딩 + 벡터 DB 업서트)
+
+https://github.com/user-attachments/assets/50e5c711-dd01-4d92-bb23-181a1c5bba25
+
+## 모듈형 빌딩 블록
+
+https://github.com/user-attachments/assets/6442f0ad-86d8-43d9-aa70-e5c01e55e876
+
+## 최종 성능 평가
+
+https://github.com/user-attachments/assets/4dc2abc3-c6e6-4d6d-a5c3-787d518de7ae
+
+## 곧 추가될 기능: 자기 개선
+
+https://github.com/user-attachments/assets/5bef7a16-ef9f-4650-b385-4ea70fa54c8a
+
+# 🛠️ PySpur 개발 환경 설정
+#### [ 유닉스 계열 시스템 개발 지침. Windows/PC 개발은 지원되지 않음 ]
+
+개발을 위해 아래 단계를 따르세요:
+
+1. **리포지토리 클론:**
+    ```sh
+    git clone https://github.com/PySpur-com/pyspur.git
+    cd pyspur
+    ```
+
+2. **docker-compose.dev.yml 사용하여 실행:**
+    ```sh
+    docker compose -f docker-compose.dev.yml up --build -d
+    ```
+    이 명령어는 개발용 핫 리로딩이 활성화된 로컬 PySpur 인스턴스를 시작합니다.
+
+3. **환경 설정 맞춤:**
+    환경 구성을 위해 `.env` 파일을 수정합니다. 기본적으로 PySpur는 로컬 PostgreSQL 데이터베이스를 사용합니다. 외부 데이터베이스를 사용하려면 `.env` 파일의 `POSTGRES_*` 변수를 수정하세요.
+
+# ⭐ 지원해 주세요
+
+별을 남겨 주셔서 저희의 작업을 지원하실 수 있습니다! 감사합니다!
+
+![star](https://github.com/user-attachments/assets/71f65273-6755-469d-be44-087bb89d5e76)
+
+여러분의 피드백은 큰 힘이 됩니다.
+다음에 보고 싶은 기능이나 완전히 새로운 기능 요청이 있다면 [알려주세요](mailto:founders@pyspur.dev?subject=Feature%20Request&body=I%20want%20this%20feature%3Ai).

pyspur/backend/.gitignore

@@ -0,0 +1,7 @@
+# ignore the test database file
+test.db
+/app/integrations/google/token.json
+data/
+/secure_tokens/
+/.bolt-app-installation/
+pyspur/openapi_specs/

pyspur/backend/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        name: ruff
+        entry: ruff check
+        args: [--fix, --exit-non-zero-on-fix, --quiet]
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: ruff-format
+        name: ruff-format
+        entry: ruff format
+        args: [--quiet]
+        language: system
+        types_or: [python, pyi]
+        require_serial: true

pyspur/backend/alembic.ini

@@ -0,0 +1,117 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts
+# Use forward slashes (/) also on windows to provide an os agnostic path
+script_location = pyspur/models/management/alembic/
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.
+prepend_sys_path = .
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python>=3.9 or backports.zoneinfo library.
+# Any required deps can installed by adding `alembic[tz]` to the pip requirements
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to app/models/management/alembic//versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "version_path_separator" below.
+# version_locations = %(here)s/bar:%(here)s/bat:app/models/management/alembic//versions
+
+# version path separator; As mentioned above, this is the character used to split
+# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+# Valid values for version_path_separator are:
+#
+# version_path_separator = :
+# version_path_separator = ;
+# version_path_separator = space
+# version_path_separator = newline
+version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+sqlalchemy.url = postgresql://%(POSTGRES_USER)s:%(POSTGRES_PASSWORD)s@%(POSTGRES_HOST)s:%(POSTGRES_PORT)s/%(POSTGRES_DB)s
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the exec runner, execute a binary
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = %(here)s/.venv/bin/ruff
+# ruff.options = --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

pyspur/backend/entrypoint.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# First test Ollama connection if URL is provided
+if [ -f "test_ollama.sh" ]; then
+    chmod +x test_ollama.sh
+    ./test_ollama.sh
+fi
+
+set -e 
+mkdir -p /pyspur/backend/pyspur/models/management/alembic/versions/
+start_server() {
+    cd /pyspur/backend
+    uvicorn "pyspur.api.main:app" --reload --reload-include ./log_conf.yaml --reload-include "**/*.py" --log-config=log_conf.yaml --host 0.0.0.0 --port 8000
+}
+
+main() {
+    alembic upgrade head
+    start_server
+}
+
+main

pyspur/backend/log_conf.yaml

@@ -0,0 +1,54 @@
+version: 1
+disable_existing_loggers: True
+formatters:
+  default:
+    # "()": uvicorn.logging.DefaultFormatter
+    format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+  access:
+    # "()": uvicorn.logging.AccessFormatter
+    format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+handlers:
+  default:
+    formatter: default
+    class: logging.StreamHandler
+    stream: ext://sys.stderr
+  access:
+    formatter: access
+    class: logging.StreamHandler
+    stream: ext://sys.stdout
+loggers:
+  uvicorn.error:
+    level: INFO
+    handlers:
+      - default
+    propagate: no
+  uvicorn.access:
+    level: INFO
+    handlers:
+      - access
+    propagate: no
+  httpx:
+    level: ERROR
+    handlers:
+      - default
+  httpcore:
+    level: ERROR
+    handlers:
+      - default
+  watchfiles.main:
+    level: INFO
+    handlers:
+      - default
+  LiteLLM:
+    level: INFO
+    handlers:
+      - default
+  openai._base_client:
+    level: INFO
+    handlers:
+      - default
+root:
+  level: DEBUG
+  handlers:
+    - default
+  propagate: no

pyspur/backend/output_files/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

pyspur/backend/pyproject.toml

@@ -0,0 +1,142 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyspur"
+version = "0.1.18"
+description = "PySpur is a Graph UI for building AI Agents in Python"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+classifiers = [
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Unix",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+maintainers = [
+    {name = "Srijan Patel", email = "srijan@pyspur.dev"},
+    {name = "Jean Kaddour", email = "jean@pyspur.dev"},
+    {name = "Parshva Bhadra", email = "parshva.bhadra@pyspur.dev"},
+]
+dependencies = [
+    "alembic==1.14.0",
+    "arrow==1.3.0",
+    "asyncio==3.4.3",
+    "attrs==24.3.0",
+    "backend==0.2.4.1",
+    "chromadb==0.6.2",
+    "datasets==3.2.0",
+    "docx2txt==0.8",
+    "docx2python==3.3.0",
+    "exa-py==1.9.0",
+    "fastapi==0.115.6",
+    "genanki==0.13.1",
+    "google-api-python-client==2.159.0",
+    "grpcio==1.69.0",
+    "Jinja2==3.1.6",
+    "litellm==1.61.15",
+    "loguru==0.7.3",
+    "numpy==2.2.1",
+    "ollama==0.4.5",
+    "pandas==2.2.3",
+    "pinecone==5.4.2",
+    "praw==7.8.1",
+    "psycopg2-binary==2.9.10",
+    "pydantic==2.10.5",
+    "pypdf==5.1.0",
+    "python-dotenv==1.0.1",
+    "python-multipart==0.0.20",
+    "python-pptx==1.0.2",
+    "PyYAML==6.0.2",
+    "py-zerox==0.0.7",
+    "qdrant_client==1.12.2",
+    "redis==5.2.1",
+    "regex==2024.11.6",
+    "requests==2.32.3",
+    "requests-file==2.1.0",
+    "requests-oauthlib==1.3.1",
+    "retrying==1.3.4",
+    "slack_sdk==3.35.0",
+    "slack_bolt==1.23.0",
+    "SQLAlchemy==2.0.36",
+    "supabase==2.11.0",
+    "six==1.17.0",
+    "tenacity==8.3.0",
+    "tiktoken==0.7.0",
+    "tqdm==4.67.1",
+    "weaviate_client==4.10.2",
+    "itsdangerous==2.2.0",
+    "phidata==2.7.8",
+    "youtube_transcript_api==0.6.3",
+    "PyGithub==2.5.0",
+    "firecrawl-py==1.10.2",
+    "httpx[http2]==0.27.2",
+    "sendgrid==6.11.0",
+    "resend==2.6.0",
+    "typer[all]==0.9.0",
+    "psutil>=7.0.0",
+]
+
+[project.urls]
+Repository = "https://github.com/pyspur-dev/pyspur"
+Documentation = "https://docs.pyspur.dev"
+
+[project.scripts]
+pyspur = "pyspur.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1.0",
+]
+
+[tool.hatch.build.targets.wheel]
+universal = false
+packages = ["pyspur"]
+zip-safe = false
+
+[tool.hatch.build.targets.wheel.force-include]
+"pyspur/templates" = "pyspur/templates/"
+"pyspur/static" = "pyspur/static/"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "B", "C", "D", "PYI"]
+ignore = [
+    "B006",  # Do not use mutable default arguments
+    "B008",  # Do not perform function call `Depends` in argument defaults
+    "C901",  # Function is too complex
+    "D100",  # Missing docstring in public module
+    "D101",  # Missing docstring in public class
+    "D102",  # Missing docstring in public method
+    "D103",  # Missing docstring in public function
+    "D104",  # Missing docstring in public package
+    "D105",  # Missing docstring in magic method
+    "D106",  # Missing docstring in public nested class
+    "D107",  # Missing docstring in __init__
+    "I001",  # Import block is un-sorted or un-formatted
+    "E402",  # Module level import not at top of file
+]
+
+[tool.black]
+line-length = 100
+target-version = ["py312"]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

pyspur/backend/pyspur/api/ai_management.py

@@ -0,0 +1,352 @@
+import json
+import re
+from typing import Any, Dict, List, Literal, Optional, cast
+
+from fastapi import APIRouter, HTTPException
+from loguru import logger
+from pydantic import BaseModel
+
+from ..nodes.llm._utils import generate_text
+
+router = APIRouter()
+
+
+class SchemaGenerationRequest(BaseModel):
+    description: str
+    existing_schema: Optional[str] = None
+
+
+class MessageGenerationRequest(BaseModel):
+    description: str
+    message_type: Literal["system", "user"]  # "system" or "user"
+    existing_message: Optional[str] = None
+    context: Optional[str] = None
+    available_variables: Optional[List[str]] = None
+
+
+@router.post("/generate_schema/")
+async def generate_schema(request: SchemaGenerationRequest) -> Dict[str, Any]:
+    response: str = ""
+    try:
+        # Prepare the system message
+        system_message = """You are a JSON Schema expert. Your task is to generate a JSON Schema
+        based on a text description.
+        The schema should:
+        1. Follow JSON Schema standards
+        2. Include appropriate types, required fields, and descriptions
+        3. Be clear and well-structured
+        4. Include type: "object" at the root
+        5. Include a properties object
+        6. Set appropriate required fields
+        7. Include meaningful descriptions for each field
+        8. Return ONLY the JSON schema without any markdown formatting or explanation
+
+        Here are some examples:
+
+        <example>
+        Input: "Create a schema for a person with name, age and optional email"
+        Output: {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "The person's full name"
+                },
+                "age": {
+                    "type": "integer",
+                    "description": "The person's age in years",
+                    "minimum": 0
+                },
+                "email": {
+                    "type": "string",
+                    "description": "The person's email address",
+                    "format": "email"
+                }
+            },
+            "required": ["name", "age"]
+        }
+        </example>
+
+        <example>
+        Input: "Schema for a blog post with title, content, author details and tags"
+        Output: {
+            "type": "object",
+            "properties": {
+                "title": {
+                    "type": "string",
+                    "description": "The title of the blog post"
+                },
+                "content": {
+                    "type": "string",
+                    "description": "The main content of the blog post"
+                },
+                "author": {
+                    "type": "object",
+                    "description": "Details about the post author",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "Author's full name"
+                        },
+                        "bio": {
+                            "type": "string",
+                            "description": "Short biography of the author"
+                        }
+                    },
+                    "required": ["name"]
+                },
+                "tags": {
+                    "type": "array",
+                    "description": "List of tags associated with the post",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            },
+            "required": ["title", "content", "author"]
+        }
+        </example>
+        """
+
+        # Prepare the user message
+        user_message = (
+            f"Generate a JSON Schema for the following description:\n{request.description}"
+        )
+
+        if request.existing_schema:
+            user_message += (
+                f"\n\nPlease consider this existing schema as context:\n{request.existing_schema}"
+            )
+            user_message += (
+                "\nModify it based on the description while preserving any compatible parts."
+            )
+
+        # Call the LLM
+        messages = [
+            {"role": "system", "content": system_message},
+            {"role": "user", "content": user_message},
+        ]
+
+        message_response = await generate_text(
+            messages=messages, model_name="openai/o3-mini", json_mode=True
+        )
+        assert message_response.content, "No response from LLM"
+        response = message_response.content
+
+        # Try to parse the response in different ways
+        try:
+            # First try: direct JSON parse
+            schema = json.loads(response)
+            if isinstance(schema, dict) and "output" in schema:
+                # If we got a wrapper object with an "output" key, extract the schema from it
+                schema_str = cast(str, schema["output"])
+                # Extract JSON from potential markdown code blocks
+                json_match = re.search(r"```json\s*(.*?)\s*```", schema_str, re.DOTALL)
+                if json_match:
+                    schema_str = json_match.group(1)
+                schema = json.loads(schema_str)
+        except json.JSONDecodeError as e:
+            # Second try: Look for JSON in markdown code blocks
+            json_match = re.search(r"```(?:json)?\s*(.*?)\s*```", response, re.DOTALL)
+            if json_match:
+                schema = json.loads(json_match.group(1))
+            else:
+                raise ValueError("Could not extract valid JSON schema from response") from e
+
+        # Validate the schema structure
+        if not isinstance(schema, dict) or "type" not in schema or "properties" not in schema:
+            raise ValueError("Generated schema is not valid - missing required fields")
+
+        return cast(Dict[str, Any], schema)
+
+    except Exception as e:
+        # Log the raw response if it exists and is not empty
+        if response:
+            truncated_response = response[:1000] + "..." if len(response) > 1000 else response
+            logger.error(f"Schema generation failed. response (truncated): {truncated_response}.")
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+
+@router.post("/generate_message/")
+async def generate_message(request: MessageGenerationRequest) -> Dict[str, str]:
+    response: str = ""
+    try:
+        # Prepare the system message based on the message type
+        if request.message_type == "system":
+            system_message = """You are an expert at crafting effective \
+system messages for AI assistants.
+            Your task is to generate a clear, concise, and effective system message based\
+on the provided description.
+
+            # INSTRUCTIONS
+            A good system message should:
+            1. Clearly define the AI's role and purpose
+            2. Set appropriate boundaries and constraints
+            3. Provide necessary context and background information
+            4. Be concise but comprehensive
+            5. Use clear, unambiguous language
+            6. Use XML tags when appropriate to structure information:
+                e.g., <role>...</role>, <constraints>...</constraints>
+
+            # FORMAT REQUIREMENTS
+            Your generated system message MUST include:
+            1. An "# Instructions" section with clearly enumerated instructions (1., 2., 3., etc.)
+            2. Clear organization with appropriate headings and structure
+
+            # EXAMPLES
+            Example 1 (Simple role definition):
+            ```
+            You are a helpful coding assistant that specializes in Python programming.
+
+            # Instructions
+            1. Provide accurate Python code examples when requested
+            2. Explain coding concepts clearly and concisely
+            3. Suggest best practices for Python development
+            ```
+
+            Example 2 (With XML tags):
+            ```
+            <role>You are a data analysis expert specialized in interpreting financial data.</role>
+
+            # Instructions
+            1. Only provide analysis based on the data provided
+            2. Present findings with supporting evidence
+            3. Identify trends and patterns in the data
+            4. Suggest actionable insights when appropriate
+
+            <constraints>Do not make assumptions about data you cannot see.</constraints>
+            <format>Present your analysis with clear sections for Summary, Details, \
+and Recommendations.</format>
+            ```
+
+            Return ONLY the system message text without any additional explanation or formatting.
+            """
+        elif request.message_type == "user":
+            system_message = """You are an expert at crafting effective user prompts for AI \
+assistants.
+            Your task is to generate a clear, specific, and effective user prompt based on the \
+provided description.
+
+            # INSTRUCTIONS
+            A good user prompt should:
+            1. Clearly state what is being asked of the AI
+            2. Provide necessary context and specific details
+            3. Be structured in a way that guides the AI to produce the desired output
+            4. Use clear, unambiguous language
+            5. Include any relevant constraints or requirements
+            6. Use XML tags when appropriate to structure information \
+(e.g., <context>...</context>, <request>...</request>)
+
+            # FORMAT REQUIREMENTS
+            Your generated user prompt MUST include:
+            1. An "# Instructions" section with clearly enumerated instructions (1., 2., 3., etc.)
+            2. Clear organization with appropriate headings and structure
+
+            # EXAMPLES
+            Example 1 (Simple request):
+            ```
+            Explain how JavaScript promises work with code examples.
+
+            # Instructions
+            1. Explain the concept in simple terms first
+            2. Provide practical code examples
+            3. Include error handling patterns
+            ```
+
+            Example 2 (With XML tags):
+            ```
+            <context>I'm building a React application with a complex state management system.\
+</context>
+
+            <request>Review the following code snippet and suggest improvements for performance \
+and readability:</request>
+
+            <code>
+            // Code would go here
+            </code>
+
+            # Instructions
+            1. Identify performance bottlenecks in the code
+            2. Suggest specific refactoring approaches
+            3. Explain the reasoning behind each recommendation
+            4. Provide example code for key improvements
+            ```
+
+            Return ONLY the user prompt text without any additional explanation or formatting.
+            """
+        else:
+            raise ValueError(f"Unsupported message type: {request.message_type}")
+
+        # Prepare the user message
+        user_message = f"Generate a {request.message_type} message based on the following \
+description:\n{request.description}"
+
+        if request.existing_message:
+            user_message += f"\n\nPlease consider this existing message as a starting \
+point:\n{request.existing_message}"
+
+        # Add context if provided
+        if request.context:
+            user_message += f"\n\nAdditional context:\n{request.context}"
+
+        # Add information about available template variables if provided
+        if request.available_variables and len(request.available_variables) > 0:
+            variables_str = "\n".join([f"- {var}" for var in request.available_variables])
+
+            if request.message_type == "system":
+                user_message += f"\n\nThe message should appropriately incorporate the following \
+template variables that the user has specifically selected for this message:\n{variables_str}\n\n\
+These variables will be replaced with actual values at runtime. Use them in the appropriate places \
+to make the message dynamic and context-aware."
+            else:  # user message
+                user_message += f"\n\nThe prompt should appropriately incorporate the following \
+template variables that the user has specifically selected for this message:\n{variables_str}\n\n\
+These variables will be replaced with actual values at runtime. Use them in the appropriate places \
+to make the prompt dynamic and personalized."
+
+            # Additional guidance on template variable usage
+            user_message += "\n\nUse the variables in the format {{ variable_name }}. Only use the \
+variables listed above - do not invent new variables."
+
+        # Prepare messages for the LLM
+        messages = [
+            {"role": "system", "content": system_message},
+            {"role": "user", "content": user_message},
+        ]
+
+        # Generate the message using OpenAI
+        message_response = await generate_text(
+            messages=messages,
+            model_name="openai/o3-mini",
+            temperature=0.7,
+            max_tokens=1000,
+        )
+        response = cast(str, message_response.content)
+
+        # Process the response to extract the message
+        message: str = ""
+        if response.strip().startswith("{") and response.strip().endswith("}"):
+            try:
+                parsed_response = json.loads(response)
+                if isinstance(parsed_response, dict) and "output" in parsed_response:
+                    message = cast(str, parsed_response["output"])
+                else:
+                    message = response
+            except json.JSONDecodeError:
+                message = response
+        else:
+            message = response
+
+        # Remove any markdown code blocks if present
+        if "```" in message:
+            message = re.sub(r"```.*?```", "", message, flags=re.DOTALL).strip()
+        else:
+            # Fallback if response is not a string (shouldn't happen)
+            message = str(response)
+
+        return {"message": message}
+    except Exception as e:
+        logger.error(f"Error generating message: {str(e)}")
+        if response:
+            logger.error(f"Raw response: {response}")
+        raise HTTPException(status_code=500) from e

pyspur/backend/pyspur/api/api_app.py

@@ -0,0 +1,53 @@
+from fastapi import FastAPI
+
+from ..nodes.registry import NodeRegistry
+
+NodeRegistry.discover_nodes()
+
+from ..integrations.google.auth import router as google_auth_router
+from .ai_management import router as ai_management_router
+from .dataset_management import router as dataset_management_router
+from .evals_management import router as evals_management_router
+from .file_management import router as file_management_router
+from .key_management import router as key_management_router
+from .node_management import router as node_management_router
+from .openai_compatible_api import router as openai_compatible_api_router
+from .openapi_management import router as openapi_router
+from .output_file_management import router as output_file_management_router
+from .rag_management import router as rag_management_router
+from .run_management import router as run_management_router
+from .session_management import router as session_management_router
+from .slack_management import router as slack_management_router
+from .template_management import router as template_management_router
+from .user_management import router as user_management_router
+from .workflow_code_convert import router as workflow_code_router
+from .workflow_management import router as workflow_management_router
+from .workflow_run import router as workflow_run_router
+
+# Create a sub-application for API routes
+api_app = FastAPI(
+    docs_url="/docs",
+    redoc_url="/redoc",
+    title="PySpur API",
+    version="1.0.0",
+)
+
+api_app.include_router(node_management_router, prefix="/node", tags=["nodes"])
+api_app.include_router(workflow_management_router, prefix="/wf", tags=["workflows"])
+api_app.include_router(workflow_run_router, prefix="/wf", tags=["workflow runs"])
+api_app.include_router(workflow_code_router, prefix="/code_convert", tags=["workflow code (beta)"])
+api_app.include_router(dataset_management_router, prefix="/ds", tags=["datasets"])
+api_app.include_router(run_management_router, prefix="/run", tags=["runs"])
+api_app.include_router(output_file_management_router, prefix="/of", tags=["output files"])
+api_app.include_router(key_management_router, prefix="/env-mgmt", tags=["environment management"])
+api_app.include_router(template_management_router, prefix="/templates", tags=["templates"])
+api_app.include_router(openai_compatible_api_router, prefix="/api", tags=["openai compatible"])
+api_app.include_router(evals_management_router, prefix="/evals", tags=["evaluations"])
+api_app.include_router(google_auth_router, prefix="/google", tags=["google auth"])
+api_app.include_router(rag_management_router, prefix="/rag", tags=["rag"])
+api_app.include_router(file_management_router, prefix="/files", tags=["files"])
+api_app.include_router(ai_management_router, prefix="/ai", tags=["ai"])
+api_app.include_router(user_management_router, prefix="/user", tags=["users"])
+api_app.include_router(session_management_router, prefix="/session", tags=["sessions"])
+api_app.include_router(slack_management_router, prefix="/slack", tags=["slack integration"])
+api_app.include_router(openapi_router, prefix="/openapi", tags=["openapi"])

pyspur/backend/pyspur/api/dataset_management.py

@@ -0,0 +1,121 @@
+import os
+from datetime import datetime, timezone
+from typing import List
+
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..models.dataset_model import DatasetModel
+from ..models.run_model import RunModel
+from ..schemas.dataset_schemas import DatasetResponseSchema
+from ..schemas.run_schemas import RunResponseSchema
+
+router = APIRouter()
+
+
+def save_file(file: UploadFile) -> str:
+    filename = file.filename
+    assert filename is not None
+    file_location = os.path.join(os.path.dirname(__file__), "..", "..", "datasets", filename)
+    with open(file_location, "wb+") as file_object:
+        file_object.write(file.file.read())
+    return file_location
+
+
+@router.post("/", description="Upload a new dataset")
+def upload_dataset(
+    name: str,
+    description: str = "",
+    file: UploadFile = File(...),
+    db: Session = Depends(get_db),
+) -> DatasetResponseSchema:
+    file_location = save_file(file)
+    new_dataset = DatasetModel(
+        name=name,
+        description=description,
+        file_path=file_location,
+        uploaded_at=datetime.now(timezone.utc),
+    )
+    db.add(new_dataset)
+    db.commit()
+    db.refresh(new_dataset)
+    return DatasetResponseSchema(
+        id=new_dataset.id,
+        name=new_dataset.name,
+        description=new_dataset.description,
+        filename=new_dataset.file_path,
+        created_at=new_dataset.uploaded_at,
+        updated_at=new_dataset.uploaded_at,
+    )
+
+
+@router.get(
+    "/",
+    response_model=List[DatasetResponseSchema],
+    description="List all datasets",
+)
+def list_datasets(db: Session = Depends(get_db)) -> List[DatasetResponseSchema]:
+    datasets = db.query(DatasetModel).all()
+    dataset_list = [
+        DatasetResponseSchema(
+            id=ds.id,
+            name=ds.name,
+            description=ds.description,
+            filename=ds.file_path,
+            created_at=ds.uploaded_at,
+            updated_at=ds.uploaded_at,
+        )
+        for ds in datasets
+    ]
+    return dataset_list
+
+
+@router.get(
+    "/{dataset_id}/",
+    response_model=DatasetResponseSchema,
+    description="Get a dataset by ID",
+)
+def get_dataset(dataset_id: str, db: Session = Depends(get_db)) -> DatasetResponseSchema:
+    dataset = db.query(DatasetModel).filter(DatasetModel.id == dataset_id).first()
+    if not dataset:
+        raise HTTPException(status_code=404, detail="Dataset not found")
+    return DatasetResponseSchema(
+        id=dataset.id,
+        name=dataset.name,
+        description=dataset.description,
+        filename=dataset.file_path,
+        created_at=dataset.uploaded_at,
+        updated_at=dataset.uploaded_at,
+    )
+
+
+@router.delete(
+    "/{dataset_id}/",
+    description="Delete a dataset by ID",
+)
+def delete_dataset(dataset_id: str, db: Session = Depends(get_db)):
+    dataset = db.query(DatasetModel).filter(DatasetModel.id == dataset_id).first()
+    if not dataset:
+        raise HTTPException(status_code=404, detail="Dataset not found")
+    db.delete(dataset)
+    db.commit()
+    return {"message": "Dataset deleted"}
+
+
+@router.get(
+    "/{dataset_id}/list_runs/",
+    description="List all runs that used this dataset",
+    response_model=List[RunResponseSchema],
+)
+def list_dataset_runs(dataset_id: str, db: Session = Depends(get_db)):
+    dataset = db.query(DatasetModel).filter(DatasetModel.id == dataset_id).first()
+    if not dataset:
+        raise HTTPException(status_code=404, detail="Dataset not found")
+    runs = (
+        db.query(RunModel)
+        .filter(RunModel.input_dataset_id == dataset_id)
+        .order_by(RunModel.created_at.desc())
+        .all()
+    )
+    return runs

pyspur/backend/pyspur/api/evals_management.py

@@ -0,0 +1,197 @@
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..evals.evaluator import load_yaml_config, prepare_and_evaluate_dataset
+from ..models.eval_run_model import EvalRunModel, EvalRunStatus
+from ..models.workflow_model import WorkflowModel
+from ..schemas.eval_schemas import (
+    EvalRunRequest,
+    EvalRunResponse,
+    EvalRunStatusEnum,
+)
+from ..schemas.workflow_schemas import WorkflowDefinitionSchema
+from .workflow_management import get_workflow_output_variables
+
+router = APIRouter()
+
+EVALS_DIR = Path(__file__).parent.parent / "evals" / "tasks"
+
+
+@router.get("/", description="List all available evals")
+def list_evals() -> List[Dict[str, Any]]:
+    """
+    List all available evals by scanning the tasks directory for YAML files.
+    """
+    evals = []
+    if not EVALS_DIR.exists():
+        raise HTTPException(status_code=500, detail="Evals directory not found")
+    for eval_file in EVALS_DIR.glob("*.yaml"):
+        try:
+            eval_content = load_yaml_config(yaml_path=eval_file)
+            metadata = eval_content.get("metadata", {})
+            evals.append(
+                {
+                    "name": metadata.get("name", eval_file.stem),
+                    "description": metadata.get("description", ""),
+                    "type": metadata.get("type", "Unknown"),
+                    "num_samples": metadata.get("num_samples", "N/A"),
+                    "paper_link": metadata.get("paper_link", ""),
+                    "file_name": eval_file.name,
+                }
+            )
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Error parsing {eval_file.name}: {e}")
+    return evals
+
+
+@router.post(
+    "/launch/",
+    response_model=EvalRunResponse,
+    description="Launch an eval job with detailed validation and workflow integration",
+)
+async def launch_eval(
+    request: EvalRunRequest,
+    background_tasks: BackgroundTasks,
+    db: Session = Depends(get_db),
+) -> EvalRunResponse:
+    """
+    Launch an eval job by triggering the evaluator with the specified eval configuration.
+    """
+    # Validate workflow ID
+    workflow = db.query(WorkflowModel).filter(WorkflowModel.id == request.workflow_id).first()
+    if not workflow:
+        raise HTTPException(status_code=404, detail="Workflow not found")
+
+    workflow_definition = WorkflowDefinitionSchema.model_validate(workflow.definition)
+
+    eval_file = EVALS_DIR / f"{request.eval_name}.yaml"
+    if not eval_file.exists():
+        raise HTTPException(status_code=404, detail="Eval configuration not found")
+
+    try:
+        # Load the eval configuration
+        eval_config = load_yaml_config(eval_file)
+
+        # Validate the output variable
+        leaf_node_output_variables = get_workflow_output_variables(
+            workflow_id=request.workflow_id, db=db
+        )
+
+        print(f"Valid output variables: {leaf_node_output_variables}")
+
+        # Extract the list of valid prefixed variables
+        valid_prefixed_variables = [var["prefixed_variable"] for var in leaf_node_output_variables]
+
+        if request.output_variable not in valid_prefixed_variables:
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    f"Invalid output variable '{request.output_variable}'. "
+                    f"Must be one of: {leaf_node_output_variables}"
+                ),
+            )
+
+        # Create a new EvalRunModel instance
+        new_eval_run = EvalRunModel(
+            eval_name=request.eval_name,
+            workflow_id=request.workflow_id,
+            output_variable=request.output_variable,
+            num_samples=request.num_samples,
+            status=EvalRunStatus.PENDING,
+            start_time=datetime.now(timezone.utc),
+        )
+        db.add(new_eval_run)
+        db.commit()
+        db.refresh(new_eval_run)
+
+        async def run_eval_task(eval_run_id: str):
+            with next(get_db()) as session:
+                eval_run = (
+                    session.query(EvalRunModel).filter(EvalRunModel.id == eval_run_id).first()
+                )
+                if not eval_run:
+                    session.close()
+                    return
+
+                eval_run.status = EvalRunStatus.RUNNING
+                session.commit()
+
+                try:
+                    # Run the evaluation asynchronously
+                    results = await prepare_and_evaluate_dataset(
+                        eval_config,
+                        workflow_definition=workflow_definition,
+                        num_samples=eval_run.num_samples,
+                        output_variable=eval_run.output_variable,
+                    )
+                    eval_run.results = results
+                    eval_run.status = EvalRunStatus.COMPLETED
+                    eval_run.end_time = datetime.now(timezone.utc)
+                except Exception as e:
+                    eval_run.status = EvalRunStatus.FAILED
+                    eval_run.end_time = datetime.now(timezone.utc)
+                    session.commit()
+                    raise e
+                finally:
+                    session.commit()
+
+        background_tasks.add_task(run_eval_task, new_eval_run.id)
+
+        # Return all required parameters
+        return EvalRunResponse(
+            run_id=new_eval_run.id,
+            eval_name=new_eval_run.eval_name,
+            workflow_id=new_eval_run.workflow_id,
+            status=EvalRunStatusEnum(new_eval_run.status.value),
+            start_time=new_eval_run.start_time,
+            end_time=new_eval_run.end_time,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error launching eval: {e}")
+
+
+@router.get(
+    "/runs/{eval_run_id}",
+    response_model=EvalRunResponse,
+    description="Get the status of an eval run",
+)
+async def get_eval_run_status(eval_run_id: str, db: Session = Depends(get_db)) -> EvalRunResponse:
+    eval_run = db.query(EvalRunModel).filter(EvalRunModel.id == eval_run_id).first()
+    if not eval_run:
+        raise HTTPException(status_code=404, detail="Eval run not found")
+    return EvalRunResponse(
+        run_id=eval_run.id,
+        eval_name=eval_run.eval_name,
+        workflow_id=eval_run.workflow_id,
+        status=EvalRunStatusEnum(eval_run.status.value),
+        start_time=eval_run.start_time,
+        end_time=eval_run.end_time,
+        results=eval_run.results,
+    )
+
+
+@router.get(
+    "/runs/",
+    response_model=List[EvalRunResponse],
+    description="List all eval runs",
+)
+async def list_eval_runs(
+    db: Session = Depends(get_db),
+) -> List[EvalRunResponse]:
+    eval_runs = db.query(EvalRunModel).order_by(EvalRunModel.start_time.desc()).all()
+    return [
+        EvalRunResponse(
+            run_id=eval_run.id,
+            eval_name=eval_run.eval_name,
+            workflow_id=eval_run.workflow_id,
+            status=EvalRunStatusEnum(eval_run.status.value),
+            start_time=eval_run.start_time,
+            end_time=eval_run.end_time,
+        )
+        for eval_run in eval_runs
+    ]

pyspur/backend/pyspur/api/file_management.py

@@ -0,0 +1,144 @@
+import os
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse
+
+from ..schemas.file_schemas import FileResponseSchema
+
+router = APIRouter()
+
+# Define base data directory
+DATA_DIR = Path("data")
+
+
+@router.get(
+    "/{workflow_id}",
+    response_model=List[FileResponseSchema],
+    description="List all files for a specific workflow",
+)
+async def list_workflow_files(workflow_id: str) -> List[FileResponseSchema]:
+    """
+    List all files in the workflow's directory.
+    Returns a list of dictionaries containing file information.
+    """
+    workflow_dir = DATA_DIR / "run_files" / workflow_id
+
+    if not workflow_dir.exists():
+        return []
+
+    files: List[FileResponseSchema] = []
+    for file_path in workflow_dir.glob("*"):
+        if file_path.is_file():
+            files.append(
+                FileResponseSchema(
+                    name=file_path.name,
+                    path=str(file_path.relative_to(DATA_DIR)),
+                    size=os.path.getsize(file_path),
+                    created=datetime.fromtimestamp(os.path.getctime(file_path), tz=timezone.utc),
+                    workflow_id=workflow_id,
+                )
+            )
+
+    return files
+
+
+@router.get(
+    "/",
+    response_model=List[FileResponseSchema],
+    description="List all files across all workflows",
+)
+async def list_all_files() -> List[FileResponseSchema]:
+    """
+    List all files in the data directory across all workflows.
+    Returns a list of dictionaries containing file information.
+    """
+    test_files_dir = DATA_DIR / "run_files"
+
+    if not test_files_dir.exists():
+        return []
+
+    files: List[FileResponseSchema] = []
+    for workflow_dir in test_files_dir.glob("*"):
+        if workflow_dir.is_dir():
+            workflow_id = workflow_dir.name
+            for file_path in workflow_dir.glob("*"):
+                if file_path.is_file():
+                    files.append(
+                        FileResponseSchema(
+                            name=file_path.name,
+                            workflow_id=workflow_id,
+                            path=str(file_path.relative_to(DATA_DIR)),
+                            size=os.path.getsize(file_path),
+                            created=datetime.fromtimestamp(
+                                os.path.getctime(file_path), tz=timezone.utc
+                            ),
+                        )
+                    )
+
+    return files
+
+
+@router.delete("/{workflow_id}/{filename}", description="Delete a specific file")
+async def delete_file(workflow_id: str, filename: str):
+    """
+    Delete a specific file from a workflow's directory.
+    """
+    file_path = DATA_DIR / "run_files" / workflow_id / filename
+
+    if not file_path.exists():
+        raise HTTPException(status_code=404, detail="File not found")
+
+    try:
+        os.remove(file_path)
+        return {"message": "File deleted successfully"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error deleting file: {str(e)}")
+
+
+@router.delete("/{workflow_id}", description="Delete all files for a workflow")
+async def delete_workflow_files(workflow_id: str):
+    """
+    Delete all files in a workflow's directory.
+    """
+    workflow_dir = DATA_DIR / "run_files" / workflow_id
+
+    if not workflow_dir.exists():
+        raise HTTPException(status_code=404, detail="Workflow directory not found")
+
+    try:
+        shutil.rmtree(workflow_dir)
+        return {"message": "All workflow files deleted successfully"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error deleting workflow files: {str(e)}")
+
+
+@router.get(
+    "/{file_path:path}",
+    description="Get a specific file",
+    response_class=FileResponse,
+)
+async def get_file(file_path: str):
+    """
+    Get a specific file from the data directory.
+    Validates file path to prevent path traversal attacks.
+    """
+    # Validate that file_path doesn't contain path traversal patterns
+    if ".." in file_path or "~" in file_path:
+        raise HTTPException(status_code=400, detail="Invalid file path")
+
+    # Resolve the full path and ensure it's within DATA_DIR
+    try:
+        full_path = (DATA_DIR / file_path).resolve()
+        if not str(full_path).startswith(str(DATA_DIR.resolve())):
+            raise HTTPException(status_code=403, detail="Access denied")
+    except Exception:
+        raise HTTPException(status_code=400, detail="Invalid file path")
+
+    if not full_path.exists():
+        raise HTTPException(status_code=404, detail="File not found")
+
+    return FileResponse(str(full_path))

pyspur/backend/pyspur/api/key_management.py

@@ -0,0 +1,477 @@
+import os
+from typing import Dict, List, Optional
+
+from dotenv import dotenv_values, load_dotenv, set_key, unset_key
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from ..rag.datastore.factory import VectorStoreConfig, get_vector_stores
+from ..rag.embedder import EmbeddingModelConfig, EmbeddingModels
+
+# Load existing environment variables from the .env file
+load_dotenv(".env")
+
+router = APIRouter()
+
+
+class ProviderParameter(BaseModel):
+    name: str
+    description: str
+    required: bool = True
+    type: str = "password"  # password, text, select
+
+
+class ProviderConfig(BaseModel):
+    id: str
+    name: str
+    description: str
+    category: str  # 'llm', 'embedding', 'vectorstore'
+    parameters: List[ProviderParameter]
+    icon: str = "database"  # Default icon for vector stores
+
+
+PROVIDER_CONFIGS = [
+    # LLM Providers
+    ProviderConfig(
+        id="openai",
+        name="OpenAI",
+        description="OpenAI's GPT models",
+        category="llm",
+        icon="openai",
+        parameters=[
+            ProviderParameter(name="OPENAI_API_KEY", description="OpenAI API Key"),
+        ],
+    ),
+    ProviderConfig(
+        id="azure-openai",
+        name="Azure OpenAI",
+        description="Azure-hosted OpenAI models",
+        category="llm",
+        icon="azure",
+        parameters=[
+            ProviderParameter(name="AZURE_OPENAI_API_KEY", description="Azure OpenAI API Key"),
+            ProviderParameter(
+                name="AZURE_OPENAI_ENDPOINT",
+                description="Azure OpenAI Endpoint URL",
+                type="text",
+            ),
+            ProviderParameter(
+                name="AZURE_OPENAI_API_VERSION",
+                description="API Version (e.g. 2023-05-15)",
+                type="text",
+            ),
+        ],
+    ),
+    ProviderConfig(
+        id="anthropic",
+        name="Anthropic",
+        description="Anthropic's Claude models",
+        category="llm",
+        icon="anthropic",
+        parameters=[
+            ProviderParameter(name="ANTHROPIC_API_KEY", description="Anthropic API Key"),
+        ],
+    ),
+    ProviderConfig(
+        id="gemini",
+        name="Google Gemini",
+        description="Google's Gemini models",
+        category="llm",
+        icon="google",
+        parameters=[
+            ProviderParameter(name="GEMINI_API_KEY", description="Google AI API Key"),
+        ],
+    ),
+    ProviderConfig(
+        id="deepseek",
+        name="DeepSeek",
+        description="DeepSeek's code and chat models",
+        category="llm",
+        icon="deepseek",
+        parameters=[
+            ProviderParameter(name="DEEPSEEK_API_KEY", description="DeepSeek API Key"),
+        ],
+    ),
+    ProviderConfig(
+        id="cohere",
+        name="Cohere",
+        description="Cohere's language models",
+        category="llm",
+        icon="cohere",
+        parameters=[
+            ProviderParameter(name="COHERE_API_KEY", description="Cohere API Key"),
+        ],
+    ),
+    ProviderConfig(
+        id="voyage",
+        name="Voyage AI",
+        description="Voyage's language models",
+        category="llm",
+        icon="voyage",
+        parameters=[
+            ProviderParameter(name="VOYAGE_API_KEY", description="Voyage AI API Key"),
+        ],
+    ),
+    ProviderConfig(
+        id="mistral",
+        name="Mistral AI",
+        description="Mistral's language models",
+        category="llm",
+        icon="mistral",
+        parameters=[
+            ProviderParameter(name="MISTRAL_API_KEY", description="Mistral AI API Key"),
+        ],
+    ),
+    # Vector Store Providers
+    ProviderConfig(
+        id="pinecone",
+        name="Pinecone",
+        description="Production-ready vector database",
+        category="vectorstore",
+        icon="pinecone",
+        parameters=[
+            ProviderParameter(name="PINECONE_API_KEY", description="Pinecone API Key"),
+            ProviderParameter(
+                name="PINECONE_ENVIRONMENT",
+                description="Pinecone Environment",
+                type="text",
+            ),
+            ProviderParameter(
+                name="PINECONE_INDEX",
+                description="Pinecone Index Name",
+                type="text",
+            ),
+        ],
+    ),
+    ProviderConfig(
+        id="weaviate",
+        name="Weaviate",
+        description="Multi-modal vector search engine",
+        category="vectorstore",
+        icon="weaviate",
+        parameters=[
+            ProviderParameter(name="WEAVIATE_API_KEY", description="Weaviate API Key"),
+            ProviderParameter(
+                name="WEAVIATE_URL",
+                description="Weaviate Instance URL",
+                type="text",
+            ),
+        ],
+    ),
+    ProviderConfig(
+        id="qdrant",
+        name="Qdrant",
+        description="Vector database for production",
+        category="vectorstore",
+        icon="qdrant",
+        parameters=[
+            ProviderParameter(name="QDRANT_API_KEY", description="Qdrant API Key"),
+            ProviderParameter(
+                name="QDRANT_URL",
+                description="Qdrant Instance URL",
+                type="text",
+            ),
+        ],
+    ),
+    ProviderConfig(
+        id="chroma",
+        name="Chroma",
+        description="Open-source embedding database",
+        category="vectorstore",
+        icon="chroma",
+        parameters=[
+            ProviderParameter(
+                name="CHROMA_IN_MEMORY",
+                description="Run Chroma in memory",
+                type="text",
+            ),
+            ProviderParameter(
+                name="CHROMA_PERSISTENCE_DIR",
+                description="Directory for Chroma persistence",
+                type="text",
+            ),
+            ProviderParameter(
+                name="CHROMA_HOST",
+                description="Chroma server host",
+                type="text",
+            ),
+            ProviderParameter(
+                name="CHROMA_PORT",
+                description="Chroma server port",
+                type="text",
+            ),
+            ProviderParameter(
+                name="CHROMA_COLLECTION",
+                description="Chroma collection name",
+                type="text",
+            ),
+        ],
+    ),
+    ProviderConfig(
+        id="supabase",
+        name="Supabase",
+        description="Open-source vector database",
+        category="vectorstore",
+        icon="supabase",
+        parameters=[
+            ProviderParameter(
+                name="SUPABASE_URL",
+                description="Supabase Project URL",
+                type="text",
+            ),
+            ProviderParameter(
+                name="SUPABASE_ANON_KEY",
+                description="Supabase Anonymous Key",
+                type="password",
+                required=False,
+            ),
+            ProviderParameter(
+                name="SUPABASE_SERVICE_ROLE_KEY",
+                description="Supabase Service Role Key",
+                type="password",
+                required=False,
+            ),
+        ],
+    ),
+    # Add Reddit Provider
+    ProviderConfig(
+        id="reddit",
+        name="Reddit",
+        description="Reddit API integration",
+        category="social",
+        icon="logos:reddit-icon",
+        parameters=[
+            ProviderParameter(name="REDDIT_CLIENT_ID", description="Reddit API Client ID"),
+            ProviderParameter(name="REDDIT_CLIENT_SECRET", description="Reddit API Client Secret"),
+            ProviderParameter(
+                name="REDDIT_USERNAME", description="Reddit Username", type="text", required=False
+            ),
+            ProviderParameter(
+                name="REDDIT_PASSWORD",
+                description="Reddit Password",
+                type="password",
+                required=False,
+            ),
+            ProviderParameter(
+                name="REDDIT_USER_AGENT",
+                description="Reddit API User Agent",
+                type="text",
+                required=False,
+            ),
+        ],
+    ),
+    # Add Firecrawl Provider
+    ProviderConfig(
+        id="firecrawl",
+        name="Firecrawl",
+        description="Web scraping and crawling service",
+        category="scraping",
+        icon="solar:spider-bold",
+        parameters=[
+            ProviderParameter(name="FIRECRAWL_API_KEY", description="Firecrawl API Key"),
+        ],
+    ),
+    # Add Slack Provider
+    ProviderConfig(
+        id="slack",
+        name="Slack",
+        description="Slack messaging and notification service",
+        category="messaging",
+        icon="logos:slack-icon",
+        parameters=[
+            ProviderParameter(
+                name="SLACK_BOT_TOKEN", description="Slack Bot User OAuth Token (starts with xoxb-)"
+            ),
+            ProviderParameter(
+                name="SLACK_USER_TOKEN",
+                description="Slack User OAuth Token (starts with xoxp-)",
+                required=False,
+            ),
+        ],
+    ),
+    # Add Exa Provider
+    ProviderConfig(
+        id="exa",
+        name="Exa",
+        description="Exa web search API",
+        category="search",
+        icon="solar:search-bold",
+        parameters=[
+            ProviderParameter(name="EXA_API_KEY", description="Exa API Key"),
+        ],
+    ),
+]
+
+# For backward compatibility, create a flat list of all parameter names
+MODEL_PROVIDER_KEYS = [
+    {"name": param.name, "value": ""} for config in PROVIDER_CONFIGS for param in config.parameters
+]
+
+
+class APIKey(BaseModel):
+    name: str
+    value: Optional[str] = None
+
+
+def get_all_env_variables() -> Dict[str, str | None]:
+    return dotenv_values(".env")
+
+
+def get_env_variable(name: str) -> Optional[str]:
+    return os.getenv(name)
+
+
+def set_env_variable(name: str, value: str):
+    """Set an environment variable both in the .env file and in the current process.
+
+    Also ensures the value is properly quoted if it contains special characters.
+    """
+    # Ensure the value is properly quoted if it contains spaces or special characters
+    if any(c in value for c in " '\"$&()|<>"):
+        value = f'"{value}"'
+
+    # Update the .env file using set_key
+    set_key(".env", name, value)
+
+    # Update the os.environ dictionary
+    os.environ[name] = value
+
+    # Force reload of environment variables
+    load_dotenv(".env", override=True)
+
+
+def delete_env_variable(name: str):
+    # Remove the key from the .env file
+    unset_key(".env", name)
+    # Remove the key from os.environ
+    os.environ.pop(name, None)
+
+
+def mask_key_value(value: str, param_type: str = "password") -> str:
+    """Mask the key value based on the parameter type.
+
+    For password types, shows only the first and last few characters.
+    For other types, shows the full value.
+    """
+    if param_type != "password":
+        return value
+
+    visible_chars = 4  # Number of characters to show at the start and end
+    min_masked_chars = 4  # Minimum number of masked characters
+    if len(value) <= visible_chars * 2 + min_masked_chars:
+        return "*" * len(value)
+    else:
+        return (
+            value[:visible_chars] + "*" * (len(value) - visible_chars * 2) + value[-visible_chars:]
+        )
+
+
+@router.get("/providers", description="Get all provider configurations")
+async def get_providers():
+    """Return all provider configurations."""
+    return PROVIDER_CONFIGS
+
+
+@router.get("/", description="Get a list of all environment variable names")
+async def list_api_keys():
+    """Return a list of all model provider keys."""
+    return [k["name"] for k in MODEL_PROVIDER_KEYS]
+
+
+@router.get(
+    "/{name}",
+    description="Get the masked value of a specific environment variable",
+)
+async def get_api_key(name: str):
+    """Return the masked value of the specified environment variable.
+
+    Requires authentication.
+    """
+    # Find the parameter configuration
+    param_type = "password"
+    for config in PROVIDER_CONFIGS:
+        for param in config.parameters:
+            if param.name == name:
+                param_type = param.type
+                break
+
+    if name not in [k["name"] for k in MODEL_PROVIDER_KEYS]:
+        raise HTTPException(status_code=404, detail="Key not found")
+    value = get_env_variable(name)
+    if value is None:
+        value = ""
+    masked_value = mask_key_value(value, param_type)
+    return APIKey(name=name, value=masked_value)
+
+
+@router.post("/", description="Add or update an environment variable")
+async def set_api_key(api_key: APIKey):
+    """Add a new environment variable or updates an existing one.
+
+    Requires authentication.
+    """
+    if api_key.name not in [k["name"] for k in MODEL_PROVIDER_KEYS]:
+        raise HTTPException(status_code=404, detail="Key not found")
+    if not api_key.value:
+        raise HTTPException(status_code=400, detail="Value is required")
+    set_env_variable(api_key.name, api_key.value)
+    return {"message": f"Key '{api_key.name}' set successfully"}
+
+
+@router.delete("/{name}", description="Delete an environment variable")
+async def delete_api_key(name: str):
+    """Delete the specified environment variable.
+
+    Requires authentication.
+    """
+    if name not in [k["name"] for k in MODEL_PROVIDER_KEYS]:
+        raise HTTPException(status_code=404, detail="Key not found")
+    if get_env_variable(name) is None:
+        raise HTTPException(status_code=404, detail="Key not found")
+    delete_env_variable(name)
+    return {"message": f"Key '{name}' deleted successfully"}
+
+
+@router.get("/embedding-models/", response_model=Dict[str, EmbeddingModelConfig])
+async def get_embedding_models() -> Dict[str, EmbeddingModelConfig]:
+    """Get all available embedding models and their configurations."""
+    try:
+        models: Dict[str, EmbeddingModelConfig] = {}
+        for model in EmbeddingModels:
+            model_info = EmbeddingModels.get_model_info(model.value)
+            if model_info:
+                # Find the corresponding provider config
+                provider_config = next(
+                    (p for p in PROVIDER_CONFIGS if p.id == model_info.provider.value.lower()),
+                    None,
+                )
+                if provider_config:
+                    # Add required environment variables from the provider config
+                    model_info.required_env_vars = [
+                        p.name for p in provider_config.parameters if p.required
+                    ]
+                models[model.value] = model_info
+        return models
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+@router.get("/vector-stores/", response_model=Dict[str, VectorStoreConfig])
+async def get_vector_stores_endpoint() -> Dict[str, VectorStoreConfig]:
+    """Get all available vector stores and their configurations."""
+    try:
+        stores = get_vector_stores()
+        # Add required environment variables from provider configs
+        for store_id, store in stores.items():
+            provider_config = next((p for p in PROVIDER_CONFIGS if p.id == store_id), None)
+            if provider_config:
+                store.required_env_vars = [p.name for p in provider_config.parameters if p.required]
+        return stores
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+@router.get("/anon-data/", description="Get the status of anonymous telemetry data")
+async def get_anon_data_status() -> bool:
+    """Get the status of anonymous telemetry data."""
+    return os.getenv("DISABLE_ANONYMOUS_TELEMETRY", "false").lower() == "true"

pyspur/backend/pyspur/api/main.py

@@ -0,0 +1,128 @@
+import os
+import shutil
+import tempfile
+import threading
+from contextlib import ExitStack, asynccontextmanager
+from importlib.resources import as_file, files
+from pathlib import Path
+
+from dotenv import load_dotenv
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from loguru import logger
+
+from .api_app import api_app
+
+load_dotenv()
+
+# Create an ExitStack to manage resources
+exit_stack = ExitStack()
+temporary_static_dir = None
+socket_manager = None
+socket_thread = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Manage application lifespan and cleanup."""
+    global temporary_static_dir, socket_manager, socket_thread
+
+    # Setup: Create temporary directory and extract static files
+    temporary_static_dir = Path(tempfile.mkdtemp())
+
+    # Extract static files to temporary directory
+    static_files = files("pyspur").joinpath("static")
+    static_dir = exit_stack.enter_context(as_file(static_files))
+
+    # Copy static files to temporary directory
+    if static_dir.exists():
+        shutil.copytree(static_dir, temporary_static_dir, dirs_exist_ok=True)
+
+
+    yield
+
+    # Cleanup: Stop socket manager and remove temporary directory
+    if socket_manager:
+        logger.info("Stopping socket manager...")
+        socket_manager.stopping = True
+        if socket_thread and socket_thread.is_alive():
+            try:
+                # Give the thread a chance to stop gracefully
+                socket_thread.join(timeout=5)
+            except Exception as e:
+                logger.error(f"Error stopping socket manager thread: {e}")
+
+    exit_stack.close()
+    shutil.rmtree(temporary_static_dir, ignore_errors=True)
+
+
+app = FastAPI(lifespan=lifespan)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Mount the API routes under /api
+app.mount("/api", api_app, name="api")
+
+# Optionally, mount directories for assets that you want served directly:
+if temporary_static_dir and Path.joinpath(temporary_static_dir, "images").exists():
+    app.mount(
+        "/images",
+        StaticFiles(directory=str(temporary_static_dir.joinpath("images"))),
+        name="images",
+    )
+if temporary_static_dir and Path.joinpath(temporary_static_dir, "_next").exists():
+    app.mount(
+        "/_next", StaticFiles(directory=str(temporary_static_dir.joinpath("_next"))), name="_next"
+    )
+
+
+@app.get("/{full_path:path}", include_in_schema=False)
+async def serve_frontend(full_path: str):
+    if not temporary_static_dir:
+        raise RuntimeError("Static directory not initialized")
+
+    # If the request is empty, serve index.html
+    if full_path == "":
+        return FileResponse(temporary_static_dir.joinpath("index.html"))
+
+    # remove trailing slash
+    if full_path[-1] == "/":
+        full_path = full_path[:-1]
+
+    # Build a candidate file path from the request.
+    candidate = temporary_static_dir.joinpath(full_path)
+
+    # If candidate is a directory, try its index.html.
+    if candidate.is_dir():
+        candidate_index = candidate.joinpath("index.html")
+        if candidate_index.exists():
+            return FileResponse(candidate_index)
+
+    # If no direct file, try appending ".html" (for files like dashboard.html)
+    candidate_html = temporary_static_dir.joinpath(full_path + ".html")
+    if candidate_html.exists():
+        return FileResponse(candidate_html)
+
+    # If a file exists at that candidate, serve it.
+    if candidate.exists():
+        return FileResponse(candidate)
+
+    # Check if the parent directory contains a file named "[id].html"
+    parts = full_path.split("/")
+    if len(parts) >= 2:
+        parent = temporary_static_dir.joinpath(*parts[:-1])
+        dynamic_file = parent.joinpath("[id].html")
+        if dynamic_file.exists():
+            return FileResponse(dynamic_file)
+
+    # Fallback: serve the main index.html for client‑side routing.
+    return FileResponse(temporary_static_dir.joinpath("index.html"))

pyspur/backend/pyspur/api/node_management.py

@@ -0,0 +1,69 @@
+from typing import Any, Dict, List
+
+from fastapi import APIRouter
+
+from ..nodes.factory import NodeFactory
+from ..nodes.llm._utils import LLMModels
+
+router = APIRouter()
+
+
+@router.get(
+    "/supported_types/",
+    description="Get the schemas for all available node types",
+)
+async def get_node_types() -> Dict[str, List[Dict[str, Any]]]:
+    """Return the schemas for all available node types."""
+    # get the schemas for each node class
+    node_groups = NodeFactory.get_all_node_types()
+
+    response: Dict[str, List[Dict[str, Any]]] = {}
+    for group_name, node_types in node_groups.items():
+        node_schemas: List[Dict[str, Any]] = []
+        for node_type in node_types:
+            node_class = node_type.node_class
+            try:
+                input_schema = node_class.input_model.model_json_schema()
+            except AttributeError:
+                input_schema = {}
+            try:
+                output_schema = node_class.output_model.model_json_schema()
+            except AttributeError:
+                output_schema = {}
+
+            # Get the config schema and update its title with the display name
+            config_schema = node_class.config_model.model_json_schema()
+            config_schema["title"] = node_type.display_name
+            has_fixed_output = node_class.config_model.model_fields["has_fixed_output"].default
+
+            node_schema: Dict[str, Any] = {
+                "name": node_type.node_type_name,
+                "input": input_schema,
+                "output": output_schema,
+                "config": config_schema,
+                "visual_tag": node_class.get_default_visual_tag().model_dump(),
+                "has_fixed_output": has_fixed_output,
+            }
+
+            # Add model constraints if this is an LLM node
+            if node_type.node_type_name in ["LLMNode", "SingleLLMCallNode"]:
+                model_constraints = {}
+                for model_enum in LLMModels:
+                    model_info = LLMModels.get_model_info(model_enum.value)
+                    if model_info:
+                        model_constraints[model_enum.value] = model_info.constraints.model_dump()
+                node_schema["model_constraints"] = model_constraints
+
+            # Add the logo if available
+            logo = node_type.logo
+            if logo:
+                node_schema["logo"] = logo
+
+            category = node_type.category
+            if category:
+                node_schema["category"] = category
+
+            node_schemas.append(node_schema)
+        response[group_name] = node_schemas
+
+    return response

pyspur/backend/pyspur/api/openai_compatible_api.py

@@ -0,0 +1,107 @@
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Union
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..models.workflow_model import WorkflowModel
+from ..schemas.run_schemas import StartRunRequestSchema
+from .workflow_run import run_workflow_blocking
+
+router = APIRouter()
+
+
+# Define the request schema for OpenAI-compatible chat completions
+class ChatCompletionRequest(BaseModel):
+    model: str
+    messages: List[Dict[str, Any]]
+    functions: Optional[List[Dict[str, Any]]] = None
+    function_call: Optional[Union[Dict[str, Any], str]] = None
+    temperature: float = 0.7
+    top_p: float = 0.9
+    n: int = 1
+    stream: bool = False
+    stop: Optional[Union[str, List[str]]] = None
+    max_tokens: Optional[int] = None
+    presence_penalty: float = 0.0
+    frequency_penalty: float = 0.0
+    logit_bias: Optional[Dict[str, float]] = None
+    user: Optional[str] = None
+
+
+# Define the response schema for OpenAI-compatible chat completions
+class ChatCompletionResponse(BaseModel):
+    id: str
+    object: str
+    created: int
+    model: str
+    choices: List[Dict[str, Any]]
+    usage: Dict[str, int]
+
+
+@router.post(
+    "/v1/chat/completions",
+    response_model=ChatCompletionResponse,
+    description="OpenAI-compatible chat completions endpoint",
+)
+async def chat_completions(
+    request: ChatCompletionRequest,
+    background_tasks: BackgroundTasks,
+    db: Session = Depends(get_db),
+) -> ChatCompletionResponse:
+    """
+    Mimics OpenAI's /v1/chat/completions endpoint for chat-based workflows.
+    """
+    # Fetch the workflow (model maps to workflow_id)
+    workflow = db.query(WorkflowModel).filter(WorkflowModel.id == request.model).first()
+    if not workflow:
+        raise HTTPException(status_code=404, detail="Workflow not found")
+
+    # Get the latest user message
+    latest_user_message = next(
+        (message["content"] for message in reversed(request.messages) if message["role"] == "user"),
+        None,
+    )
+    if not latest_user_message:
+        raise HTTPException(status_code=400, detail="No user message found in messages")
+
+    # Prepare initial inputs with the latest user message
+    initial_inputs = {"message": {"value": latest_user_message}}
+
+    # Start a blocking workflow run with the initial inputs
+    start_run_request = StartRunRequestSchema(
+        initial_inputs=initial_inputs,
+        parent_run_id=None,
+    )
+    outputs = await run_workflow_blocking(
+        workflow_id=request.model,
+        request=start_run_request,
+        db=db,
+        run_type="openai",
+    )
+
+    # Format the response with outputs from the workflow
+    response = ChatCompletionResponse(
+        id=f"chatcmpl-{datetime.now(timezone.utc).timestamp()}",
+        object="chat.completion",
+        created=int(datetime.now(timezone.utc).timestamp()),
+        model=request.model,
+        choices=[
+            {
+                "message": {
+                    "role": "assistant",
+                    "content": outputs.get("response", {}).get("value", ""),
+                },
+                "index": 0,
+                "finish_reason": outputs.get("finish_reason", "stop"),
+            }
+        ],
+        usage={
+            "prompt_tokens": outputs.get("prompt_tokens", 0),
+            "completion_tokens": outputs.get("completion_tokens", 0),
+            "total_tokens": outputs.get("total_tokens", 0),
+        },
+    )
+    return response

pyspur/backend/pyspur/api/openapi_management.py

@@ -0,0 +1,180 @@
+import json
+import os
+from typing import Dict, List, Optional
+from uuid import uuid4
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+router = APIRouter()
+
+# Directory to store OpenAPI specs
+OPENAPI_SPECS_DIR = "pyspur/openapi_specs"
+
+# Ensure the directory exists
+os.makedirs(OPENAPI_SPECS_DIR, exist_ok=True)
+
+class OpenAPIEndpoint(BaseModel):
+    path: str
+    method: str
+    summary: Optional[str] = None
+    operationId: Optional[str] = None
+    description: Optional[str] = None
+    input_schema: Optional[Dict] = None
+    output_schema: Optional[Dict] = None
+
+class OpenAPISpec(BaseModel):
+    id: str
+    name: str
+    description: str
+    version: str
+    endpoints: List[OpenAPIEndpoint]
+    raw_spec: Dict
+
+class CreateSpecRequest(BaseModel):
+    spec: Dict
+
+@router.post("/specs/", response_model=OpenAPISpec)
+async def create_openapi_spec(request: CreateSpecRequest) -> OpenAPISpec:
+    """Store an OpenAPI specification."""
+    try:
+        # Generate a unique ID for this spec
+        spec_id = str(uuid4())
+        
+        # Extract basic info from the spec
+        info = request.spec.get("info", {})
+        
+        # Parse all endpoints from the spec
+        endpoints: List[OpenAPIEndpoint] = []
+        for path, path_item in request.spec.get("paths", {}).items():
+            for method, operation in path_item.items():
+                # Extract input schema
+                input_schema: Dict = {"properties": {}}
+                
+                # Path parameters
+                if operation.get("parameters"):
+                    path_params = [p for p in operation["parameters"] if p.get("in") == "path"]
+                    if path_params:
+                        input_schema["properties"]["pathParameters"] = {
+                            "type": "object",
+                            "properties": {p["name"]: p.get("schema", {}) for p in path_params}
+                        }
+                
+                # Query parameters
+                if operation.get("parameters"):
+                    query_params = [p for p in operation["parameters"] if p.get("in") == "query"]
+                    if query_params:
+                        input_schema["properties"]["queryParameters"] = {
+                            "type": "object",
+                            "properties": {p["name"]: p.get("schema", {}) for p in query_params}
+                        }
+                
+                # Header parameters
+                if operation.get("parameters"):
+                    header_params = [p for p in operation["parameters"] if p.get("in") == "header"]
+                    if header_params:
+                        input_schema["properties"]["headerParameters"] = {
+                            "type": "object",
+                            "properties": {p["name"]: p.get("schema", {}) for p in header_params}
+                        }
+                
+                # Request body
+                if operation.get("requestBody"):
+                    content = operation["requestBody"].get("content", {})
+                    if content:
+                        media_type = next(iter(content))
+                        input_schema["properties"]["requestBody"] = {
+                            "mediaType": media_type,
+                            "schema": content[media_type].get("schema", {})
+                        }
+                
+                # Output schema
+                output_schema: Dict = {"properties": {}}
+                if operation.get("responses"):
+                    for status_code, response in operation["responses"].items():
+                        if response.get("content"):
+                            media_type = next(iter(response["content"]))
+                            output_schema["properties"][status_code] = {
+                                "description": response.get("description", ""),
+                                "mediaType": media_type,
+                                "schema": response["content"][media_type].get("schema", {})
+                            }
+                        else:
+                            output_schema["properties"][status_code] = {
+                                "description": response.get("description", ""),
+                                "mediaType": "application/json",
+                                "schema": {}
+                            }
+                
+                endpoints.append(OpenAPIEndpoint(
+                    path=path,
+                    method=method.upper(),
+                    summary=operation.get("summary"),
+                    operationId=operation.get("operationId"),
+                    description=operation.get("description"),
+                    input_schema=input_schema,
+                    output_schema=output_schema
+                ))
+        
+        spec_data = OpenAPISpec(
+            id=spec_id,
+            name=info.get("title", "Untitled API"),
+            description=info.get("description", ""),
+            version=info.get("version", "1.0.0"),
+            endpoints=endpoints,
+            raw_spec=request.spec
+        )
+        
+        # Save the spec to a file
+        spec_path = os.path.join(OPENAPI_SPECS_DIR, f"{spec_id}.json")
+        with open(spec_path, "w") as f:
+            json.dump(spec_data.dict(), f, indent=2)
+            
+        return spec_data
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.get("/specs/", response_model=List[OpenAPISpec])
+async def list_openapi_specs() -> List[OpenAPISpec]:
+    """List all stored OpenAPI specifications."""
+    try:
+        specs = []
+        for filename in os.listdir(OPENAPI_SPECS_DIR):
+            if filename.endswith(".json"):
+                with open(os.path.join(OPENAPI_SPECS_DIR, filename)) as f:
+                    spec_data = json.load(f)
+                    specs.append(OpenAPISpec(**spec_data))
+        return specs
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.get("/specs/{spec_id}", response_model=OpenAPISpec)
+async def get_openapi_spec(spec_id: str) -> OpenAPISpec:
+    """Get a specific OpenAPI specification by ID."""
+    try:
+        spec_path = os.path.join(OPENAPI_SPECS_DIR, f"{spec_id}.json")
+        if not os.path.exists(spec_path):
+            raise HTTPException(status_code=404, detail="Specification not found")
+            
+        with open(spec_path) as f:
+            spec_data = json.load(f)
+            return OpenAPISpec(**spec_data)
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.delete("/specs/{spec_id}")
+async def delete_openapi_spec(spec_id: str) -> Dict[str, str]:
+    """Delete a specific OpenAPI specification by ID."""
+    try:
+        spec_path = os.path.join(OPENAPI_SPECS_DIR, f"{spec_id}.json")
+        if not os.path.exists(spec_path):
+            raise HTTPException(status_code=404, detail="Specification not found")
+            
+        os.remove(spec_path)
+        return {"message": "Specification deleted successfully"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

pyspur/backend/pyspur/api/output_file_management.py

@@ -0,0 +1,92 @@
+from typing import List
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import FileResponse
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..models.output_file_model import OutputFileModel
+from ..schemas.output_file_schemas import OutputFileResponseSchema
+
+router = APIRouter()
+
+
+@router.get(
+    "/",
+    response_model=List[OutputFileResponseSchema],
+    description="List all output files",
+)
+def list_output_files(
+    db: Session = Depends(get_db),
+) -> List[OutputFileResponseSchema]:
+    output_files = db.query(OutputFileModel).all()
+    output_file_list = [
+        OutputFileResponseSchema(
+            id=of.id,
+            file_name=of.file_name,
+            created_at=of.created_at,
+            updated_at=of.updated_at,
+        )
+        for of in output_files
+    ]
+    return output_file_list
+
+
+@router.get(
+    "/{output_file_id}/",
+    response_model=OutputFileResponseSchema,
+    description="Get an output file by ID",
+)
+def get_output_file(output_file_id: str, db: Session = Depends(get_db)) -> OutputFileResponseSchema:
+    output_file = db.query(OutputFileModel).filter(OutputFileModel.id == output_file_id).first()
+    if not output_file:
+        raise HTTPException(status_code=404, detail="Output file not found")
+    return OutputFileResponseSchema(
+        id=output_file.id,
+        file_name=output_file.file_name,
+        created_at=output_file.created_at,
+        updated_at=output_file.updated_at,
+    )
+
+
+@router.delete(
+    "/{output_file_id}/",
+    description="Delete an output file by ID",
+)
+def delete_output_file(output_file_id: str, db: Session = Depends(get_db)):
+    output_file = db.query(OutputFileModel).filter(OutputFileModel.id == output_file_id).first()
+    if not output_file:
+        raise HTTPException(status_code=404, detail="Output file not found")
+    db.delete(output_file)
+    db.commit()
+    return {"message": "Output file deleted"}
+
+
+# download_output_file endpoint
+@router.get(
+    "/{output_file_id}/download/",
+    description="Download an output file by ID",
+)
+def download_output_file(output_file_id: str, db: Session = Depends(get_db)):
+    output_file = db.query(OutputFileModel).filter(OutputFileModel.id == output_file_id).first()
+    if not output_file:
+        raise HTTPException(status_code=404, detail="Output file not found")
+
+    # get the appropriate media type based on the file extension
+    media_type = "application/octet-stream"
+    if output_file.file_name.endswith(".csv"):
+        media_type = "text/csv"
+    elif output_file.file_name.endswith(".json"):
+        media_type = "application/json"
+    elif output_file.file_name.endswith(".txt"):
+        media_type = "text/plain"
+    elif output_file.file_name.endswith(".jsonl"):
+        media_type = "application/x-ndjson"
+
+    return FileResponse(
+        output_file.file_path,
+        media_type=media_type,
+        filename=output_file.file_name,
+        headers={"Content-Disposition": f"attachment; filename={output_file.file_name}"},
+        content_disposition_type="attachment",
+    )