Metadata-Version: 2.4
Name: voodoo-framework
Version: 2.9.0
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: voodoo-store<0.3,>=0.2.2
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"
Requires-Dist: aiosqlite; extra == "dev"
Provides-Extra: sqlite
Requires-Dist: aiosqlite; extra == "sqlite"
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 a Python application start as a page or API and grow into durable
workers, agents, human approvals, distributed participants and physical-device
workflows without replacing the execution model underneath it.

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

## Why Voodoo?

Modern systems often assemble separate frameworks for HTTP, UI, persistence,
queues, scheduling, AI, realtime communication, workflow execution,
observability and devices. Voodoo provides a common runtime model so those
pieces can converge when the application actually needs them.

```text
Entity → State → Intent → Capability → Execution → Effect → State
```

`Compute`, `Time`, `Resource` and `Constraint` govern Execution. AI is one form
of Compute, not a second runtime.

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

For operational systems Voodoo also keeps attempted action and observed reality
separate:

```text
Effect != Observation
```

An Effect records what the runtime tried to do. An Observation records evidence
about what actually happened in the World.

## Quick start

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

Open `http://localhost:8000`. On first run Voodoo creates:

```text
.voodoo/application.vstore
```

That Store is the default durable application substrate for local data, durable
work, scheduling, event state, objects, execution state, workflows, approvals,
identity state, and Edge/device state. A local application does not require an
external database, Redis, queue server, or object server.

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.

## Voodoo Store by default

Voodoo Store is embedded application infrastructure. The framework owns one
Runtime Store handle per process/application lifecycle and shares it across
Store-backed Runtime domains.

```text
Application
    |
    v
Voodoo Runtime
    |
    +-- Model / Data
    +-- Jobs / Queue
    +-- Scheduler
    +-- Events
    +-- Objects
    +-- Execution / Workflow / HITL
    +-- Identity
    +-- Edge
    |
    v
.voodoo/application.vstore
```

The Store is local-first and single-writer. PostgreSQL, SQLite, Redis, S3 and
other infrastructure remain explicit adapters for workloads that need them;
they are not silent defaults.

## Start simple

| You need | Voodoo primitive |
|---|---|
| UI-local mutable value | `state()` |
| Persistent business data | `Model` |
| Browser interaction | Python-callable UI event/action |
| Decoupled application notification | Mesh / event bus |
| Retryable background work | `@task` / durable queue |
| Meaningful durable/observable work | `Execution` |
| LLM reasoning and tool use | `Agent` + `@tool` |
| Authorization to produce an effect | `Capability` |
| Human decision inside work | HITL approval |
| Operational identity/evidence | `Entity` + `Observation` + `WorldModel` |
| Durable desired outcome | `Goal` + `GoalRuntime` |
| External physical participant | Edge / `DeviceGateway` |
| Future/recurring work | Scheduler |

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

## Small AI + data + event example

```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"])
```

With the default configuration, `Lead` is persisted through Voodoo Store. Tools
may also be exposed through MCP, but MCP is a separate interoperability
boundary, not a fake step inserted into every tool call.

## Operational closed loop

The operational runtime keeps attempted effects separate from observed reality:

```text
simulated device
  → Edge
  → Observation
  → World
  → Goal / Intent
  → context-aware Planner
  → Capability + Policy
  → Execution
  → Effect
  → device
  → ACK / observed evidence
  → Observation
  → World
```

Run the canary with:

```bash
python examples/operational_closed_loop/main.py
```

The World does not change merely because an Effect was sent. It changes only
when the simulated device reports observed evidence back through the Edge
boundary.

## What makes Voodoo different

- **One execution model.** APIs, agents, tools, workers, humans, remote nodes and
  devices can converge on one traceable runtime instead of independent
  orchestration stacks.
- **World-aware operational state.** `Entity`, `Relationship`, `Observation` and
  `WorldModel` represent changing operational reality with provenance.
- **Governed agency.** Goal/Intent planning can use current World context, but
  authority still flows through Capability and Policy.
- **AI is Compute.** Agents are powerful participants, not ambient authority.
- **Durable when it matters.** Executions, tasks, schedules, Goals and approvals
  have persistence/recovery seams.
- **Human-in-the-loop is native.** Waiting is an execution lifecycle state.
- **Distributed without a second runtime.** Remote work re-enters the same
  ExecutionEngine, capability and policy boundary.
- **Physical participants use the same semantics.** Edge devices report
  evidence and receive Effects without owning a DeviceExecutionEngine.
- **Store-first and local-first.** Voodoo Store provides the default embedded
  durable infrastructure; PostgreSQL, SQLite, Redis and S3-compatible storage
  are explicit adapters.
- **Observability is structural.** Trace/execution lineage connects meaningful
  work, Effects and resulting Observations.

## Canonical import model

The 2.x package root remains a compatibility facade. New code should use the
namespace that owns the concept:

```python
from voodoo import App, Agent, Model, page, state, task, tool
from voodoo.ui import Button, Card, DataTable
from voodoo.runtime import ExecutionEngine, Goal, GoalRuntime, Planner
from voodoo.world import Entity, Observation, WorldModel
from voodoo.edge import DeviceGateway, WorldAwareDeviceGateway
from voodoo.protocol import WorldSnapshot, RemoteExecutionRequest
```

See `docs/public-api-3.md` for the 3.0 import law and 2.x compatibility policy.

## Major capabilities

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

**Runtime:** ExecutionEngine, durable checkpoints/recovery, workers/tasks,
scheduler, event infrastructure, human approvals, capability security,
contextual Policy, Goal Runtime and bounded adaptive planning/supervision.

**World:** stable entities, relationships, append-only observations, durable
World storage and reasoning/policy snapshots.

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

**Distributed/Edge:** governed remote execution, replay/idempotency, distributed
WAITING/HITL, node membership/routing, device identity/auth, HTTP/MQTT Edge
semantics, effect delivery, ACKs and Edge → World evidence convergence.

**Infrastructure adapters:** PostgreSQL, SQLite, Redis, S3-compatible object
storage and OpenTelemetry are optional or explicit integrations behind Runtime
contracts.

## Installation

```bash
# Core runtime (includes the Voodoo Store dependency)
pip install voodoo-framework

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

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

# Explicit SQLite adapter when needed
pip install "voodoo-framework[sqlite]"

# Edge MQTT transport when needed
pip install "voodoo-framework[edge]"

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

Other supported installation paths include `uv tool install voodoo-framework`
and `pipx install voodoo-framework`.

## Configuration

Voodoo is zero-config locally. The effective defaults are equivalent to:

```toml
[store]
provider = "voodoo"
path = ".voodoo/application.vstore"

[database]
provider = "voodoo"

[queue]
provider = "voodoo"

[events]
provider = "voodoo"

[objects]
provider = "voodoo"
```

You normally do not need to write those blocks. Override only the domain that
needs external infrastructure. For example:

```toml
[database]
provider = "postgres"
url = "postgresql://..."

[queue]
provider = "redis"
url = "redis://..."

[objects]
provider = "s3"
bucket = "my-bucket"
```

Voodoo does not silently migrate or copy legacy SQLite/PostgreSQL/Redis/S3 data
into the Store at startup. Migration is an explicit operation.

## Current Store boundaries

The Store-first path is usable, but current 0.2.x boundaries are explicit:

- schedule enable/disable is supported, but arbitrary schedule-cursor
  repositioning is not exposed by Store 0.2.2;
- Events and Objects preserve their Framework contracts through Store-backed
  compatibility layers while richer native Python bindings evolve;
- node-local Stores are not replicated automatically;
- Voodoo does not claim distributed consensus, global serializable
  transactions, or global exactly-once execution.

## Documentation

Start here:

- `docs/hello_world.md` — first application
- `docs/choosing-primitives.md` — which abstraction to use
- `docs/primitives.md` — computational model
- `docs/execution-model.md` and `docs/runtime.md` — execution semantics
- `docs/agents.md`, `docs/tools.md`, `docs/mcp.md` — AI/tool integration
- `docs/hitl.md` — human approvals
- `docs/protocol.md` — language-neutral semantic boundary
- `docs/public-api-3.md` — canonical 3.0 import model
- `ARCHITECTURE.md` — root architecture reference
- `ROADMAP.md` — long-range architectural direction
- `SPRINT_PLAN.md` — implementation source of truth

## 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 |
| `examples/ui_magic/` | current callable UI / Design System acceptance app |
| `examples/operational_closed_loop/` | Edge → World → Goal → Execution → Effect → evidence canary |

## Project status

Voodoo is beta software. Sprint completion and a published package release are
intentionally separate operations. The repository branch may contain completed
work that has not yet been released to PyPI.

## Contributing and security

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

## License

MIT. See `LICENSE`.
