Metadata-Version: 2.4
Name: voodoo-framework
Version: 2.6.2
Summary: The programmable runtime for adaptive applications and operational systems — web, APIs, agents, workers, human workflows, distributed systems, and physical systems in one runtime.
Author-email: Helder Perez <contact@helderperez.com>
Maintainer-email: Helder Perez <contact@helderperez.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/helderperez-dev/voodoo
Project-URL: Documentation, https://github.com/helderperez-dev/voodoo#documentation
Project-URL: Repository, https://github.com/helderperez-dev/voodoo
Project-URL: Changelog, https://github.com/helderperez-dev/voodoo/blob/main/CHANGELOG.md
Project-URL: Roadmap, https://github.com/helderperez-dev/voodoo/blob/main/ROADMAP.md
Project-URL: Issues, https://github.com/helderperez-dev/voodoo/issues
Project-URL: Discussions, https://github.com/helderperez-dev/voodoo/discussions
Keywords: ai,agent,application-framework,async,durable-execution,mcp,realtime,reactive,web-framework
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: starlette
Requires-Dist: uvicorn
Requires-Dist: pydantic
Requires-Dist: aiosqlite
Requires-Dist: websockets
Requires-Dist: httpx
Requires-Dist: python-dotenv
Requires-Dist: pyyaml
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: aiofiles
Provides-Extra: ai
Requires-Dist: openai; extra == "ai"
Requires-Dist: anthropic; extra == "ai"
Requires-Dist: google-generativeai; extra == "ai"
Requires-Dist: ollama; extra == "ai"
Provides-Extra: mcp
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.3.4; extra == "postgres"
Provides-Extra: s3
Requires-Dist: boto3>=1.34; extra == "s3"
Requires-Dist: botocore>=1.34; extra == "s3"
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Provides-Extra: edge
Requires-Dist: paho-mqtt>=2.0; extra == "edge"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == "otel"
Dynamic: license-file

# 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:

```text
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

```bash
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:

```bash
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**.

```python
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

```text
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

```bash
# 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:

```bash
voodoo version
```

## Configuration

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

```yaml
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:

```yaml
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`.
