Voodoo

The AI-native application framework for Python.

Build reactive UIs, APIs, agents, background workers, realtime systems, MCP tools, and data-driven applications in one Python runtime. Built for the future of adaptive applications.

Voodoo favors composition over configuration, Python over DSLs, adapters over lock-in, events over tightly coupled systems, and explicit capabilities over unrestricted AI autonomy.

Table of Contents

• Why Voodoo?
• Quick Start
• The AI SaaS App
• What Makes Voodoo Different
• Architectural Primitives
• Features
• Installation
• Configuration
• Documentation
• Examples
• Project Status & Roadmap
• Contributing
• Security
• License

Why Voodoo?

Modern application development is fragmented. You assemble a frontend framework, a backend framework, a database, a queue, an event bus, an AI SDK, an auth system, a deployment pipeline — and spend more time gluing them together than building your product.

Voodoo asks: what if all of that was one thing?

Voodoo is not a wrapper around other frameworks. It's a unified runtime where UI, API, agents, workers, events, and data are first-class primitives that share a single execution model.

Quick start

pip install voodoo-framework
voodoo new my_app
cd my_app
voodoo dev

Open http://localhost:8000 — that's it. No npm, no bundler, no config files.

The scaffold produces only app/page.py, voodoo.toml, and pyproject.toml — nothing else. No main.py, no .env, no placeholder directories.

Want AI features? Install with pip install "voodoo-framework[ai]" to add OpenAI, Anthropic, Gemini, and Ollama SDKs.

The AI SaaS app

Here's a complete example exercising the full chain — UI → agent → tool → MCP → mesh → worker → database:

from voodoo import (
    App,
    page,
    state,
    event,
    Agent,
    tool,
    Container,
    Heading,
    Text,
    Button,
    Card,
    Div,
    Table,
)

app = App()

# --- Data model ---
from voodoo import Model


class Lead(Model):
    name: str
    email: str
    status: str = "new"


# --- Tool (one definition, four consumers) ---
@tool
async def create_lead(name: str, email: str) -> str:
    """Create a new lead in the database."""
    lead = await Lead.create(name=name, email=email)
    return f"Created lead #{lead.id}: {name}"


# --- Agent with tool calling ---
agent = Agent(
    model="openai:gpt-4o",
    tools=["create_lead"],
    system_prompt="You are a sales assistant. Use tools to create leads.",
)

# --- Realtime mesh event ---
from voodoo.mesh import mesh


@mesh.on("lead.created")
async def notify_slack(payload):
    # Triggered when a lead is created
    print(f"New lead notification: {payload}")


# --- Reactive UI ---
leads = state([])


@page("/")
def dashboard():
    return Container(
        Heading("AI SaaS Dashboard", level=1),
        Card(
            Text("Ask the AI to create leads"),
            Button("Create Lead", onclick="vd.event('create_lead', 'btn')"),
        ),
        Div(
            Table(*leads.get()),
            id="leads-table",
        ),
    )


@event
async def create_lead(element_id, value):
    run = await agent.run("Create a lead for Ada Lovelace, ada@x.io")
    # Agent calls create_lead tool → DB insert → mesh event fires
    all_leads = await Lead.all()
    leads.set(all_leads)


if __name__ == "__main__":
    app.run()

What makes Voodoo different

Architectural Primitives

Voodoo is built on eight fundamental computational primitives from which all higher-level capabilities emerge:

flowchart LR
    subgraph Primitives
        State
        Capability
        Intent
        Effect
        Time
        Compute
        Resource
        Constraint
    end

    Intent -->|requires| Capability
    Capability -->|resolved by| Compute
    Compute -->|produces| Effect
    Effect -->|updates| State
    State -->|observed| Intent
    Time --> Constraint
    Constraint --> Compute
    Resource --> Compute

from voodoo.primitives import State, Capability, Intent, Effect

See docs/primitives.md for the full model.

Features

UI & Frontend

• Reactive UI — Component system in pure Python with WebSocket-driven DOM patches
• Design System — Built-in theme engine with Tailwind adapter support
• SEO & GEO — Server-side rendering, sitemaps, OpenGraph, and Generative Engine Optimization

AI & Agents

• Agents — Provider-driven execution loop with tool calling (OpenAI, Anthropic, Gemini, Ollama)
• Tools — @tool decorator with auto-generated JSON schemas from type hints
• MCP — Built-in Model Context Protocol server; every tool is automatically exposed
• Human-in-the-Loop — ask_human(), approve()/deny(), Task(human=True) — humans as compute participants

Backend & Data

• Data — Async SQLite ORM with RLS policies and lifecycle hooks
• Auth — JWT tokens, API keys, session cookies, RBAC route guards
• Workers — @task decorator with retries, timeout, and telemetry spans
• Voodoo Mesh — Realtime event bus with local + remote boundaries

Runtime & Infrastructure

• Runtime Engine — Unified ExecutionEngine producing Execution records for every operation
• Durable Execution — SQLite-backed execution store with checkpointing and voodoo recover CLI
• Planner — Deterministic capability → compute participant resolution with fallbacks
• Adaptive Runtime — Supervisor loop with retry, fallback, delegation, budget steering
• Telemetry — Correlation IDs, request tracking, agent token/cost accounting
• Security — CORS, CSRF, rate limiting, security headers — all on by default

Adapters (optional extras)

• PostgreSQL — Database, queue, and event store ([postgres])
• Redis — Queue and cache ([redis])
• S3/R2 — Object store with presigned URLs and multipart uploads ([s3])

Installation

Homebrew (macOS/Linux)

brew tap helderperez-dev/voodoo
brew install voodoo

uv

uv tool install voodoo-framework

Magic install script

curl -fsSL https://raw.githubusercontent.com/helderperez-dev/voodoo/main/install.sh | bash

pip / pipx

# Core (lean — no AI SDKs)
pip install voodoo-framework

# With AI providers
pip install "voodoo-framework[ai]"

# With all optional extras
pip install "voodoo-framework[ai,postgres,redis,s3]"

# With dev tools
pip install "voodoo-framework[dev]"

# Isolated environment
pipx install voodoo-framework

Verify

voodoo version

Uninstall

# Homebrew
brew uninstall voodoo && brew untap helderperez-dev/voodoo

# uv
uv tool uninstall voodoo-framework

# pip / pipx
pip uninstall voodoo-framework   # or: pipx uninstall voodoo-framework

# Magic install script
rm -rf ~/.voodoo/venv && rm -f ~/.local/bin/voodoo

Configuration

Voodoo runs zero-config out of the box. When you need to customize, create a voodoo.yaml file:

database:
  provider: sqlite          # sqlite (default) | postgres
queue:
  provider: sqlite          # sqlite (default) | postgres | redis
events:
  provider: sqlite          # sqlite (default) | postgres | memory
objects:
  provider: local           # local (default) | s3
cache:
  provider: memory          # memory (default) | redis
models:
  default: openai:gpt-4o

Environment variables follow the VOODOO_* convention and override defaults. See .env.example for the complete reference.

Key variables:

Generate a secure secret key:

voodoo auth secret-key

Documentation

Getting Started

• Installation
• Hello World
• Architecture
• Architectural Primitives

Building Apps

• Components
• Routing
• Reactive State
• Events
• Data & Models
• Design System

AI & Agents

• Agents
• Tools
• MCP
• Human-in-the-Loop

Realtime & Workers

• Mesh
• Workers

Runtime & Operations

• Runtime Engine
• Planner & Adaptive Runtime
• Telemetry
• Auth
• Deployment

Engineering

• Contributing Guide
• Security Policy
• Code of Conduct
• Changelog
• Master Roadmap
• Sprint Plan
• Architecture Reference

AI Development Workflow

• AI Agent Instructions
• Copilot Instructions
• Instruction Files — Domain-specific guidance for AI agents
• Skills — Structured workflows for common tasks
• Prompts — Structured prompts for audits, planning, and reviews

Examples

Project Status & Roadmap

Voodoo is in active development (v1.15.1, Beta). The core runtime, UI system, AI agents, MCP, durable execution, and adaptive runtime are production-ready. PostgreSQL, S3/R2, and Redis adapters are shipped behind optional extras; the AI runtime (model-provider protocol, memory, durable agents, and durable human-in-the-loop) is the current focus.

timeline
    title Voodoo Roadmap
    section Shipped (v1.0–v1.15.1)
        Core Runtime & UI : Routing : Components : Reactive state
        AI & Agents : Providers : Tools : MCP : Human-in-the-Loop
        Unified Runtime : ExecutionEngine : Planner : Adaptive supervisor
        Durable Local Runtime : SQLite queue : Executions : Scheduler : Objects : Events
        Production Providers : PostgreSQL : S3/R2 : Redis
    section In Progress (v1.16–v1.19)
        ModelProvider protocol : Model descriptors : Routing aliases
        Memory capability : Layered memory : SQLite + FTS5
        Durable Agents & HITL : Agent registry : Resumable approvals
    section Planned (v2.0+)
        Capability Security & Secrets : v2.0
        Observability & Protocol : v2.1–v2.2
        Local Runtime DX : v2.3

See the master roadmap and sprint plan for details.

Contributing

Contributions are welcome! Please read the Contributing Guide before opening a pull request.

AI coding agents: Read AGENTS.md and .github/copilot-instructions.md before making any changes. These define the architectural invariants, code style, testing standards, and sprint protocol that must be followed.

Quick start for contributors:

git clone https://github.com/helderperez-dev/voodoo.git
cd voodoo
just install          # set up dev environment
just format && just lint && just test

• Bug reports → Open an issue
• Feature requests → Open an issue
• Discussions → GitHub Discussions
• Security reports → See Security Policy (do NOT open public issues)

By participating, you agree to abide by the Code of Conduct.

Security

Voodoo includes security features on by default: CORS, CSRF protection, rate limiting, and security headers. For production deployments, review the hardening checklist in SECURITY.md.

To report a vulnerability, email contact@helderperez.com — do not open a public issue. See the full Security Policy for response timelines.

Testing

pytest

License

MIT — Copyright (c) 2026 Helder Perez and the Voodoo contributors.