A production-grade SaaS platform for AI-powered products: multi-provider chat, prompt marketplace, real-time voice, video generation, and white-label infrastructure.
SPARK is an open-source AI platform that combines multi-provider chat, a prompt marketplace, real-time voice calls, WhatsApp integration, AI video/image generation, and a complete white-label infrastructure into a single deployable application.
Think of it as Poe + Shopify for AI prompts + white-label -- all in one codebase.
| Mode | Description |
|---|---|
| Poe Mode | Public AI aggregator -- users browse and chat with community prompts |
| Enterprise Mode | A manager pays for their team's usage with budget controls and auto-refill |
| Curator Mode | Full white-label deployment with custom branding, domains, and commission splits |
| Freelancer Mode | Creators sell individual AI prompts as paid products to captive users |
Each mode has its own billing logic, user relationships, and access controls -- all running on the same instance.
SPARK integrates 6 providers through a unified streaming interface with native tool calling:
| Provider | Models | Capabilities |
|---|---|---|
| OpenAI | GPT-4o, GPT-5, O1 | Chat, images (DALL-E 3, gpt-image), TTS |
| Anthropic | Claude 3.5/4 Sonnet, Haiku | Chat, thinking tokens, prompt caching |
| Gemini 2.5 | Chat, images, video (VEO-3) | |
| xAI | Grok-2, Grok-4 | Chat |
| OpenRouter | 300+ models | Multi-provider gateway |
| ElevenLabs | ConvAI, TTS, Scribe | Real-time voice, speech synthesis & recognition |
Native Tool Calling across all providers: 8+ built-in tools including image generation, video generation, maps, consciousness analysis, and self-protection mechanisms.
A unique two-layer AI behavior monitoring system that ensures prompts stay on-character and conversations stay safe:
Pre-Watchdog (Synchronous)
- Intercepts every user message before it reaches the AI
- LLM-based evaluation blocks prompt injection, jailbreaks, and off-topic manipulation
- Runs inline -- malicious inputs never reach the AI model
Post-Watchdog (Asynchronous)
- Monitors AI responses after generation via Dramatiq background tasks
- Detects personality drift, role contradictions, and policy violations
- 4-level hint escalation: Steering → Directive → Override → Takeover
- Takeover mode: After N ignored hints, the watchdog replaces the AI entirely
- Force-lock: Permanently locks conversations flagged with "alert" severity
- Role Coherence Module: Detects when the AI contradicts its configured personality
Configurable per prompt with presets for interview, coaching, education, and custom modes. Full admin dashboard with event timeline, filters, and audit trail.
SPARK implements defense-in-depth security with multiple independent layers:
Security Middleware (1,600+ lines)
- 236+ instant-block patterns (scanners, shells, exploit paths, AWS metadata probes, IoT exploits)
- Progressive blocking: accumulated 404s trigger temporary IP bans
- Dual backend: Redis for multi-worker deployments, in-memory fallback for single-process
- Automatic Cloudflare WAF escalation: creates firewall rules for persistent attackers
- Opportunistic cleanup of expired Cloudflare rules
- Smart exemptions for user landing pages
- Admin dashboard with stats, events, and blocked IPs
Security Guard (LLM-Based Content Moderation)
- Pre-execution content analysis using a dedicated LLM evaluator
- 4 threat categories: system info extraction, prompt injection, malicious code, jailbreak attempts
- Supports Claude, GPT, Gemini, and xAI as evaluators
- Temperature 0.0 for deterministic classification
Application Security
- JWT tokens in HTTPOnly cookies with Redis-backed revocation
- bcrypt + pepper password hashing
- Parameterized SQL queries (no string interpolation)
- Path traversal prevention with
Path.is_relative_to() - SSRF protection on all external media URLs
- Decompression bomb protection on file uploads
- Multi-strategy rate limiting across 8+ endpoints (per-IP, per-identifier, per-failure)
- BYOK encryption: AES-128 Fernet with PBKDF2 (100K iterations)
- Admin audit log: every admin action logged with who, what, when, and from where
Every prompt in SPARK is a product with its own identity:
- Custom Landing Pages: Full HTML/CSS/JS per prompt with static assets (images, audio, styles)
- AI Landing Page Wizard: Generate and iterate on landing pages using Claude Code CLI (4 visual styles, multi-language, brand colors)
- Custom Domains: Users can attach their own domain to a prompt (CNAME verification, 4-state lifecycle: unverified → pending → verified → active)
- Categories: 10 categories with age-restriction support and per-user access controls
- Landing Page Analytics: Anonymized visitor tracking (hashed IPs), referrer analysis, return visitor detection, conversion funnels (visit → signup)
- Discount Codes: Configurable coupons with usage limits, expiration dates, and percentage discounts
Stripe Connect Integration
- Creator bank account onboarding via Stripe Express
- Real transfers to creators ($50 minimum payout threshold)
- Per-prompt earnings dashboard with stats
- Webhooks for
account.updatedandtransfer.failed - Commission model: 70% creator / 30% platform (configurable)
Enterprise Billing
- Manager-pays-for-team model with budget caps
- Auto-refill when balance drops below threshold
- Per-user usage tracking and cost attribution
Image Generation -- 5 engines:
- DALL-E 3 and OpenAI gpt-image
- Ideogram V2
- Google Gemini
- POE API (access to multiple image models)
- Up to 16 reference images per request, automatic aspect ratio detection
Video Generation -- Google VEO:
- 3 models: VEO 3.1-fast, VEO 3.1, VEO 2.0
- Negative prompts, configurable aspect ratios
- Async generation with polling and exponential backoff
Text-to-Speech -- Dual engine:
- ElevenLabs + OpenAI TTS
- Intelligent text chunking for long content
- SHA256-based audio caching
- WebSocket streaming for real-time playback
- Multi-key load balancer with health scoring
Speech-to-Text -- Dual engine with auto-fallback:
- Deepgram Nova-2 (primary)
- ElevenLabs Scribe v2 (fallback)
- Automatic engine switching on failure
Export:
- PDF: ReportLab with full Markdown rendering (tables, code blocks, emojis, nested lists), embedded images, document metadata
- MP3: TTS-powered audio export of entire conversations
Live voice conversations with AI through ElevenLabs ConvAI:
- Auto-cached SDK proxy (resilient to CDN outages)
- Multi-key load balancer with performance scoring
- Watchdog integration (voice calls are supervised too)
- Automatic transcript synchronization to chat history
- Audio download for completed calls
- Admin tooling: per-prompt agent/voice configuration
AI chat via WhatsApp through Twilio:
- Twilio webhook signature verification
- SSRF prevention on incoming media URLs
- Text and voice mode switching per user
- Automatic voice note transcription (dual-engine with fallback)
- Configurable response format (text or audio)
Full white-label infrastructure for Curator Mode:
- Custom logo and brand colors
- Complete SPARK branding removal
- Forced theme for sub-users
- Branded transactional emails
- Custom domain attachment ($25 one-time)
- DNS verification with automated CNAME checking
- Alter Egos: Multiple personas per user with custom avatar, name, and description -- injected into system prompts automatically
- BYOK (Bring Your Own Keys): Users supply their own API keys with 3 modes (own only, system only, prefer own). Keys encrypted with AES-128 Fernet (PBKDF2, 100K iterations) and masked in UI
- Chat Folders: Nested folder organization with drag-and-drop, color coding, and custom sort order
- 13 UI Themes: All WCAG AA compliant for contrast. Includes Default, Light, Coder (VS Code), Terminal, Writer, Neumorphism, Frutiger Aero, Memphis, E-ink, Katari Shoji, Halloween, Christmas, Valentine's. Template included for creating new themes
- Usage Dashboard: Personal usage stats at
/my-usagewith daily aggregation charts
Multi-modal authentication system:
| Method | Description |
|---|---|
| Magic Links | Passwordless email login |
| Passwords | bcrypt + pepper hashing |
| Google OAuth | One-click Google account login |
| Combined | Magic link + password (configurable per user) |
- JWT tokens stored in HTTPOnly cookies
- Redis-backed token revocation
- Per-endpoint rate limiting with 12 strategies across 8+ endpoints
- Admin-controlled password change permissions
- User Management: Create, edit, delete users with role assignment (admin/manager/user)
- Prompt Management: Approve, categorize, and configure marketplace prompts
- Watchdog Dashboard: Event timeline, hint history, force-locks, per-conversation audit
- Security Dashboard: Blocked IPs, attack patterns, Cloudflare WAF rule management
- Usage Dashboard: Platform-wide stats with filters, top users, CSV export
- Audit Log: Complete record of every admin action (who, what, when, IP)
- LLM Configuration: Per-model pricing, token limits, and feature flags
- ElevenLabs Agent Config: Map voices and agents to specific prompts
SPARK uses a FastAPI + Flask hybrid architecture:
+-------------------------------------+
| Cloudflare CDN |
+-----------------+-------------------+
|
+-----------------v-------------------+
| Nginx Reverse Proxy |
| (auth_request for file access) |
+-----------------+-------------------+
|
+---------------------------+---------------------------+
| | |
+---------v---------+ +-------------v-------------+ +---------v---------+
| FastAPI | | WebSocket Server | | Background |
| (REST + SSE) | | (Real-time chat + TTS) | | (Dramatiq) |
+---------+---------+ +-------------+-------------+ +---------+---------+
| | |
+---------------------------+---------------------------+
|
+-----------------v-------------------+
| SQLite (WAL mode, pooled) |
+-------------------------------------+
| Layer | Technology |
|---|---|
| Backend | FastAPI + Flask (Jinja2 templating) |
| Database | SQLite with aiosqlite, WAL mode, connection pooling |
| Real-time | WebSockets (chat, TTS streaming), Server-Sent Events |
| Caching | Redis (primary) with in-memory fallback |
| Background Jobs | Dramatiq + Redis (watchdog, video polling, async tasks) |
| File Storage | 3-tier SHA1 hash directories, JWT-authenticated image access |
| CDN | Cloudflare with Redis/Cloudflare/in-memory token modes |
| Payments | Stripe Connect (marketplace payouts, subscriptions) |
| Messaging | Twilio (WhatsApp), SendGrid/SMTP (email) |
SPARK/
├── app.py # Main application (FastAPI + Flask routing)
├── auth.py # Authentication (JWT, magic links, OAuth, rate limiting)
├── database.py # Async SQLite with connection pooling
├── ai_calls.py # Unified AI provider interface + streaming
├── common.py # Configuration, constants, cost calculations
├── prompts.py # Marketplace logic & file management
├── security_guard_llm.py # LLM-based content moderation
├── elevenlabs_service.py # Voice calls, transcripts, agent management
├── whatsapp.py # Twilio WhatsApp integration
├── middleware/
│ ├── security.py # Request filtering, IP blocking, WAF escalation
│ └── custom_domains.py # Custom domain resolution & caching
├── routes/
│ └── custom_domains.py # Custom domain API endpoints
├── tools/
│ ├── watchdog.py # Pre/post watchdog + hint escalation
│ ├── llm_caller.py # Non-streaming LLM caller for background tasks
│ ├── perplexity.py # Web search integration
│ ├── generate_images.py # AI image generation (DALL-E, Ideogram, Gemini)
│ ├── generate_videos.py # AI video generation (Google VEO)
│ ├── download_pdf.py # Conversation export to PDF
│ ├── download_mp3.py # TTS-powered audio export
│ └── tts.py # Text-to-speech with multi-key load balancer
├── data/
│ ├── static/ # CSS themes, JS modules, media
│ │ ├── css/themes/ # 13 unified themes (WCAG AA)
│ │ ├── css/chat/ # Chat-specific theme variants
│ │ └── js/chat/ # Frontend modules (chat, folders, voice, audio)
│ ├── seed/ # Seed data (bot images, landing pages, prompts)
│ └── users/ # Hash-based user directories (prompts, profiles)
├── templates/ # Jinja2 templates (chat, admin, marketplace)
├── tests/ # Test suite (security, watchdog)
└── nginx/ # Production Nginx configs
- Python 3.10+
- Redis (recommended; optional with in-memory fallback)
- Node.js 18+ (only for AI Landing Page Wizard)
# Clone the repository
git clone https://github.com/jordicor/sparkAI.git
cd sparkAI
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# or: venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Copy environment template and configure
cp .env.example .env
# Edit .env -- at minimum: OPENAI_KEY, PEPPER, APP_SECRET_KEY
# Initialize database
python init_db.py
# Run
python app.pyAvailable at http://localhost:7789.
# Core (required)
APP_SECRET_KEY=your-secret-key
PEPPER=your-pepper-for-hashing
# AI Providers (at least one required)
OPENAI_KEY=sk-...
ANTHROPIC_KEY=sk-ant-...
GOOGLE_AI_KEY=AI...
XAI_API_KEY=xai-...
OPENROUTER_API_KEY=sk-or-...
# Voice & Speech (optional)
ELEVENLABS_KEY=...
DEEPGRAM_KEY=...
# WhatsApp (optional)
TWILIO_ACCOUNT_SID=...
TWILIO_AUTH_TOKEN=...
# Payments (optional)
STRIPE_SECRET_KEY=sk_...
STRIPE_CONNECT_CLIENT_ID=ca_...
# Security (optional, enhances protection)
CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_ZONE_ID=...See .env.example for all options.
For production with Nginx (authenticated file serving, reverse proxy):
# See nginx/ directory for configuration examples
# Windows users: Laragon provides Nginx + Redis with minimal setupWhen available, Redis powers:
- Rate limiting (multi-strategy, per-endpoint)
- JWT token revocation
- Image access token caching
- Background task queues (Dramatiq)
- Security middleware IP tracking (multi-worker safe)
Without Redis, SPARK falls back to in-memory stores (single-process only).
All 13 themes use standardized CSS variables and are WCAG AA compliant. To create a new theme, copy data/static/css/themes/_template.css and define your color palette.
Configure per prompt via the admin panel. Presets available for common use cases (interview, coaching, education). Escalation thresholds, takeover behavior, and force-lock severity are all adjustable.
SPARK started as TestMyPrompt (2024) -- a tool for testing AI prompt security, born from building a Santa Claus AI chatbot that needed to never break character. The need for forensic logging of where prompts failed evolved into a full platform.
The codebase has areas of intentional over-engineering -- exploring patterns, testing architectural limits, and learning by building. This is a deliberate choice: some systems (like the multi-layer security stack or the watchdog escalation chain) are more complex than strictly necessary because building them was part of the learning process.
It's not a tutorial project. It's a production system that I use daily -- that's how bugs, design flaws, and usability issues get caught and fixed. Development is ongoing: prompt discovery for the marketplace, deeper mobile design passes, and other improvements are actively in progress and will be published as they land.
Contributions are welcome. Areas where help is most needed:
- Testing: Basic test suite exists (security, watchdog) -- needs broader coverage
- Type Hints: Partial coverage, needs mypy integration
- API Documentation: Beyond auto-generated docs
- New Themes: Following the
_template.csspattern
Please open an issue before submitting large changes.
Developed by: Jordi Cor
Early contributor: My nephew, who helped during the TestMyPrompt era with testing, code reviews, and backend development.
Built with AI assistance: Claude, GPT, and Codex -- the "vibe coding" approach where AI writes for speed and humans review for quality.
MIT License -- see LICENSE for details.
- Santa Claus AI -- The project that started it all