Voodoo

The programmable runtime for adaptive applications and operational systems.

Voodoo lets Python applications grow from a page or API into durable workers, agents, human approvals, realtime communication and production infrastructure without replacing the execution model underneath them.

Composition over configuration. Python over DSLs. Adapters over lock-in. Explicit capabilities over unrestricted autonomy.

Why Voodoo?

Modern applications often assemble separate frameworks for HTTP, UI, persistence, queues, scheduling, AI, realtime communication and observability. Voodoo provides these as composable capabilities of one runtime.

The central model is:

Entity → State → Intent → Capability → Execution → Effect → State

An Execution is not every function call. It is meaningful work worth observing, authorizing, recovering, accounting for, waiting on, or reasoning about.

Quick start

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

Open http://localhost:8000. The default path requires no external database, queue or object store.

voodoo create is the primary onboarding path and scaffolds the local runtime. If you deliberately want only the smallest UI/routing scaffold, use voodoo new.

AI provider SDKs are optional:

pip install "voodoo-framework[ai]"

The core package does not install OpenAI, Anthropic, Gemini or Ollama SDKs. Providers are resolved lazily when used.

Start simple, add runtime capabilities when they matter

You need	Voodoo primitive
UI-local mutable value	`state()`
Persistent business data	`Model`
Browser interaction	`@event`
Decoupled application notification	Mesh / event bus
Retryable background work	`@task`
Meaningful durable/observable work	`Execution`
LLM reasoning and tool use	`Agent` + `@tool`
Authorization to produce an effect	`Capability`
Human decision inside work	HITL approval
Future/recurring work	Scheduler

See docs/choosing-primitives.md for the semantic boundaries between State, Model, Memory, events, tools, tasks, capabilities and executions.

A small AI + data + event example

Install the ai extra for real providers, or use mock:* locally. This example intentionally claims only the chain it executes: Agent → Tool → Model → Mesh.

from voodoo import Agent, Model, tool
from voodoo.mesh import mesh


class Lead(Model):
    name: str
    email: str


@tool
async def create_lead(name: str, email: str) -> str:
    lead = await Lead.create(name=name, email=email)
    await mesh.emit("lead.created", {"id": lead.id, "name": name})
    return f"Created lead #{lead.id}"


@mesh.on("lead.created")
async def notify(payload):
    print("new lead", payload["name"])


agent = Agent(model="mock:test", tools=["create_lead"])

For the broader UI → agent → tool → event → worker → database demonstration, run examples/ai_saas/main.py. Tools registered with @tool are also available to Voodoo's MCP integration; that exposure is a separate integration boundary rather than a fake step inserted into the local call chain.

What makes Voodoo different

One execution model. APIs, agents, tools, workers and human workflows can participate in a traceable runtime rather than forming independent orchestration stacks.
AI is one form of Compute. Agents are powerful participants, not the foundation every application must depend on.
Durable when it matters. Executions, tasks, schedules and approvals can survive process restarts using local persistence by default.
Human-in-the-loop is native. Waiting for approval is an execution lifecycle state, not an ad-hoc polling pattern.
Local-first, production-capable. SQLite/local filesystem provide the default path; PostgreSQL, Redis and S3-compatible storage are adapters.
Adaptive execution is optional. Planner/supervisor capabilities are available when capability resolution, fallback or budget steering is useful; simple paths remain simple.
Observability is part of the runtime. Correlation and execution context connect meaningful work across boundaries.

Computational model

Intent       desired outcome
Capability   ability + authorization to produce an effect
Execution    meaningful unit of runtime work
Effect       change produced by an execution
State        operational truth

Compute, Time, Resource, and Constraint govern how an Execution happens. See docs/primitives.md, docs/execution-model.md, ARCHITECTURE.md, and docs/runtime-consolidation.md.

Major capabilities

Application: server-rendered/reactive Python UI, routing/APIs, design system/themes, SEO, async ORM, auth and security middleware.

Runtime: ExecutionEngine, durable execution/checkpoints/recovery, workers/tasks, scheduler, event infrastructure, human approvals, capability security, telemetry and optional adaptive planning/supervision.

AI: agents, native provider tool calling, @tool, MCP integration, memory, model/provider abstraction and config-driven OpenAI-compatible endpoints.

Infrastructure adapters: PostgreSQL, Redis, S3-compatible object storage and OpenTelemetry are optional extras behind runtime contracts.

Installation

# Core runtime — no third-party AI provider SDKs
pip install voodoo-framework

# Model providers
pip install "voodoo-framework[ai]"

# Production adapters as needed
pip install "voodoo-framework[postgres,redis,s3,otel]"

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

Other supported installation paths include Homebrew (brew tap helderperez-dev/voodoo && brew install voodoo), uv tool install voodoo-framework, and pipx install voodoo-framework.

Verify with:

voodoo version

Configuration

Voodoo is zero-config locally. Add voodoo.yaml when you need explicit providers:

database:
  provider: sqlite
queue:
  provider: sqlite
events:
  provider: sqlite
objects:
  provider: local
cache:
  provider: memory
runtime:
  run_api_through_runtime: true

AI configuration is opt-in and requires the corresponding optional SDK:

ai:
  provider: openai
  model: gpt-4o
  api_key: "${OPENAI_API_KEY}"

Environment variables use the VOODOO_* convention. See .env.example for the full reference.

Documentation

Start here:

docs/hello_world.md — first application
docs/choosing-primitives.md — which Voodoo abstraction to use
docs/primitives.md — computational model
docs/execution-model.md and docs/runtime.md — execution semantics
docs/data.md — Models and persistence
docs/events.md and docs/mesh.md — communication boundaries
docs/workers.md — background tasks
docs/agents.md, docs/tools.md, docs/mcp.md — AI/tool integration
docs/hitl.md — human approvals
docs/telemetry.md — observability
docs/deployment.md — production deployment
ARCHITECTURE.md — root architecture reference
docs/runtime-consolidation.md — invariants that keep the runtime coherent

Examples

Example	Purpose
`examples/hello_world/`	smallest page
`examples/dashboard/`	reactive UI/state
`examples/realtime/`	realtime communication
`examples/ai_agent/`	agent/tool application
`examples/ai_saas/`	UI + Agent + Tool + Mesh + Worker + Model

The examples are intentionally progressive. Applications do not need to adopt the complete runtime surface at once.

Project status

Voodoo is beta software. The repository's SPRINT_PLAN.md is the source of truth for implementation progress; ROADMAP.md describes longer-term direction. Public API and behavior should be treated with beta-level compatibility expectations until a stable release policy is declared.

Contributing and security

See CONTRIBUTING.md for the development workflow, SECURITY.md for vulnerability reporting, and CODE_OF_CONDUCT.md for community expectations.

License

MIT. See LICENSE.

Release files for voodoo-framework 2.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for voodoo-framework 2.6.2
File	Size	Uploaded
voodoo_framework-2.6.2.tar.gz	396.8 kB	Sep 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for voodoo-framework 2.6.2
File	Interpreter	ABI	Platform	Reset
voodoo_framework-2.6.2-py3-none-any.whl 367.8 kB Sep 13, 2026	Python 3	none	any	Details

Total release size: 764.6 kB

Release files / voodoo_framework-2.6.2.tar.gz

Download URL	voodoo_framework-2.6.2.tar.gz
Size	396.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`f2223c0a148ebbd76e389c2af60326a6d8dacb10e2e885e6731cc2674a417527`
BLAKE2b-256 checksum How to use checksums	`ede9b70411377e755c126d0cfb9e4927619dbfb88d2dd96a04e9095c32bc5114`
Upload date	Sep 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / voodoo_framework-2.6.2-py3-none-any.whl

Download URL	voodoo_framework-2.6.2-py3-none-any.whl
Size	367.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1ce9b502ab4744c5a414784e8a94a6434d07214648afd193e82ece52044026e4`
BLAKE2b-256 checksum How to use checksums	`444b891b69a885dbf181230ca3b7a87b8271dd24428997d36667df9d50419515`
Upload date	Sep 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`