Metadata-Version: 2.4
Name: voodoo-framework
Version: 3.1.0
Summary: The programmable runtime for adaptive applications and operational systems — from web and AI to distributed and physical systems.
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: python,runtime,application-runtime,distributed-systems,ai-agents,edge-computing,reactive-ui,durable-execution,operational-systems,local-first
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.4,>=0.3.0
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.**

[GitHub](https://github.com/helderperez-dev/voodoo) · [Documentation](#documentation) · [Architecture](ARCHITECTURE.md) · [Roadmap](ROADMAP.md) · [Changelog](CHANGELOG.md)

[![CI](https://github.com/helderperez-dev/voodoo/actions/workflows/ci.yml/badge.svg)](https://github.com/helderperez-dev/voodoo/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/voodoo-framework)](https://pypi.org/project/voodoo-framework/)
[![Python](https://img.shields.io/pypi/pyversions/voodoo-framework)](https://pypi.org/project/voodoo-framework/)
[![License](https://img.shields.io/badge/license-MIT-informational)](LICENSE)

Voodoo lets a Python application start small — a page, API, model, task or agent —
and grow into durable workflows, human approvals, adaptive goals, distributed
participants and physical-device systems **without replacing the execution model
underneath it**.

> Composition over configuration. Python over DSLs. Adapters over lock-in.
> Explicit capabilities over ambient authority.

## What Voodoo is

Most application stacks accumulate separate execution models as they grow:
HTTP handlers, frontend state, database jobs, queues, schedulers, agent loops,
workflow engines, event buses, human approvals, distributed workers and device
control.

Voodoo treats those as different manifestations of one programmable Runtime.

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

For operational systems, the model becomes a closed loop:

```text
World
  ↓
Observation
  ↓
Goal / Intent
  ↓
Plan
  ↓
Capability + Policy
  ↓
Execution
  ↓
Effect
  ↓
Participant
  ↓
ACK / observed evidence
  └────────────────────→ World
```

Two rules are central:

- **AI is Compute, not authority.** Agents participate in the same Runtime and
  remain subject to capabilities and policy.
- **Effect != Observation.** What the system attempted is not automatically
  treated as evidence that the real world changed.

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

## Quick start

Voodoo requires Python 3.12+.

```bash
pip install voodoo-framework

voodoo create my_app
cd my_app
voodoo dev
```

Open `http://localhost:8000`.

A fresh application needs no external database, Redis server, queue service or
object server. On first run, Voodoo creates its local durable substrate:

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

### Small application

```python
from voodoo import App, page
from voodoo.ui import Heading, Page, Stack, Text

app = App()


@page("/")
def home():
    return Page(
        Stack(
            Heading("Hello, Voodoo", level=1),
            Text("One application. One runtime."),
            gap="md",
        )
    )


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

## Start simple, grow only when needed

Voodoo is designed for progressive complexity. You do not need World Models,
Goals, AI or distributed execution to build a normal application.

| You need | Use |
|---|---|
| UI-local mutable value | `state()` |
| Persistent business data | `Model` |
| Indexed business queries | `field(index=True)` + `where/order_by` |
| Page / browser interaction | Voodoo UI + Python-callable events |
| HTTP/API surface | routing / API primitives |
| Retryable background work | `@task` |
| Future or recurring work | Runtime scheduling |
| Decoupled notification | Mesh / event bus |
| Meaningful governed work | `Execution` |
| LLM reasoning and tool use | `Agent` + `@tool` |
| Authorization to produce effects | `Capability` + `Policy` |
| Human decision during work | HITL approval |
| Durable desired outcome | `Goal` + `GoalRuntime` |
| Operational reality | `Entity` + `Observation` + `WorldModel` |
| Physical/external participant | Edge / `DeviceGateway` |
| Governed node-to-node work | Runtime Fabric |

See [Choosing primitives](docs/choosing-primitives.md) for the semantic
boundaries between state, models, events, tools, tasks, capabilities and
executions.

## One Runtime, one durable substrate

Voodoo Store is the default embedded infrastructure for a local application.

```text
Application
    │
    ▼
Voodoo Runtime
    │
    ├── Model / Data
    ├── Jobs / Queue
    ├── Scheduler / Cron / Triggers
    ├── Events / Outbox
    ├── Objects
    ├── Execution / Workflow / Goal / HITL
    ├── Identity
    └── Edge / device state
    │
    ▼
RuntimeStore
    │
    ▼
.voodoo/application.vstore
```

The default path is **local-first and single-writer**. PostgreSQL, SQLite,
Redis, S3-compatible object storage and OpenTelemetry remain explicit adapters
or integrations for workloads that need them; they are not silent defaults.

Store owns durable mechanics. Runtime owns semantics, authority and
intelligence.

Models may declare native secondary indexes without changing the query API:

```python
from voodoo import Model
from voodoo.data import field


class Customer(Model):
    email: str = field(index=True)
    score: int = field(index=True)


customers = await Customer.where(email="ada@example.com")
top = await Customer.where().order_by("-score").limit(10)
```

Indexed equality and single-column ordering are pushed into Voodoo Store;
queries without a matching declared index preserve the same API and fall back
to collection scans.

Models receive a Runtime-generated UUIDv7 identity by default. The UUID is
generated before persistence, stored as the 16-byte Collection primary key and
exposed as `uuid.UUID` in Python. Sequential business identifiers remain
ordinary explicit fields rather than the default technical identity.

Model typing carries schema semantics without duplicating them in storage
configuration: `T | None` expresses optionality, normal assignment or
`field(default=...)` expresses defaults, `field(default_factory=...)` handles
dynamic defaults, and `typing.Annotated` constraints express domain limits.
Relationships use `relation(...)` with explicit `Delete.RESTRICT`,
`Delete.CASCADE` or `Delete.SET_NULL` policies. Backend-specific `db_type`
metadata is deliberately not part of the default Model API.

## The Voodoo 3.0 architecture

Voodoo 3.0 deliberately converges concepts under one semantic owner instead of
preserving duplicate historical namespaces.

```text
src/voodoo/
├── core/          application facade, lifecycle, state and events
├── primitives/    foundational semantic concepts
├── runtime/       canonical Runtime semantics
│   ├── execution/
│   ├── scheduling/
│   ├── agency/
│   ├── distributed/
│   ├── reconciliation/
│   └── inspection/
├── world/         entities, relationships, observations, WorldModel
├── edge/          physical/external participant boundary
├── protocol/      language-neutral semantic contracts
├── ai/            native Agent/provider/tool semantics
├── integrations/  MCP, provider SDK and OpenTelemetry integrations
├── observability/ traces, metrics and runtime inspection
├── data/          Store-first Model API
├── storage/       infrastructure contracts
├── adapters/      explicit infrastructure providers
├── ui/            reactive UI and design system
├── routing/       pages and APIs
├── mesh/          realtime/event transport surface
├── auth/          application authentication surfaces
├── security/      HTTP security and redaction
└── cli/           developer tooling
```

The package root stays intentionally small:

```python
from voodoo import Agent, App, Model, page, state, task, tool
```

Advanced APIs come from the namespace that owns them:

```python
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 RemoteExecutionRequest, WorldSnapshot
from voodoo.integrations.mcp import mcp
```

See [Voodoo 3.0 public API law](docs/public-api-3.md) for the canonical import
model and the clean-break migration map from 2.x.

## Adaptive applications

An adaptive application can observe facts, express desired outcomes and allow
the Runtime to reconcile the two without creating a second orchestration model.

```python
from voodoo import App
from voodoo.primitives import Intent

app = App()

conversion = app.observation("business", "conversion")


@app.goal(
    "grow",
    observes=(conversion,),
    target_entity_id="business",
    propose=lambda goal, world: Intent(name="conversion.adjust"),
)
def growth(world):
    return world is not None and world.entity.properties.get("conversion", 0) >= 0.10


@app.capability("conversion.adjust")
async def improve(ctx):
    return {"accepted": True}
```

The application declares observations, goals and executable capabilities.
Execution, scheduling, reconciliation and authority remain Runtime concerns.

## AI and tools

AI is optional. The core package does not install provider SDKs.

```bash
pip install "voodoo-framework[ai]"
```

A tool remains normal Python while also becoming introspectable Runtime
capability for agent/tool workflows:

```python
from voodoo import Agent, tool


@tool
async def find_customer(email: str) -> dict:
    """Find a customer by email."""
    return {"email": email}


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

MCP is an interoperability boundary under `voodoo.integrations.mcp`; it is
not a second tool registry or execution model.

## Operational systems and Edge

Voodoo can connect software decisions to external or physical participants
without treating a sent command as reality.

```text
Device evidence
    ↓
Edge
    ↓
Observation
    ↓
World
    ↓
Goal / Intent
    ↓
Planner
    ↓
Capability + Policy
    ↓
Execution
    ↓
Effect
    ↓
Device
    ↓
ACK / measured evidence
    └──────────────→ Observation → World
```

Run the zero-infrastructure operational canary:

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

The example proves the important boundary: the World changes only after the
simulated device reports observed evidence, not merely because an Effect was
sent.

## Distributed Runtime

Voodoo scales by adding Runtime nodes, not by letting multiple processes write
the same Store file.

```text
same application semantics
          │
          ▼
     Runtime Fabric
      /    |    \
   node-a node-b node-c
      |      |      |
   a.vstore b.vstore c.vstore
```

Each node owns its local Store. Remote work re-enters canonical
`Capability + Policy + Execution` at the destination.

The Runtime Fabric includes authenticated node identity, durable membership,
health/discovery, placement, lease generations, replay/idempotency boundaries
and bounded failover. Failover remains constrained by the semantics of the work:
ambiguous external or physical effects must not be blindly reissued.

## Major capabilities

| Domain | Capabilities |
|---|---|
| Application | pages, APIs, reactive Python UI, design system, SEO |
| Data | Store-first `Model`, explicit SQL adapters |
| Runtime | Execution, recovery, tasks, scheduling, workflows, transactions/outbox |
| Agency | Goals, planning, adaptive supervision, reconciliation |
| Authority | Identity, Capability, contextual Policy |
| Human | durable HITL waiting/approval |
| AI | Agents, tools, provider abstraction, persistent Memory |
| Interoperability | MCP integration, language-neutral Protocol |
| Distributed | remote execution, membership, placement, leases, bounded failover |
| World | Entity, Relationship, Observation, WorldModel |
| Edge | device identity/session/effects/ACK/evidence flows |
| Observability | execution lineage, traces, metrics and inspection |
| Infrastructure | PostgreSQL, SQLite, Redis, S3 and OpenTelemetry adapters/integrations |

## Installation options

```bash
# Core Runtime + Voodoo Store
pip install voodoo-framework

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

# External infrastructure adapters
pip install "voodoo-framework[postgres,redis,s3,otel]"

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

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

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

You can also install the CLI with `uv tool install voodoo-framework` or
`pipx install voodoo-framework`.

## Configuration

A fresh application is zero-config. 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"
```

Override only the domain that actually needs external infrastructure:

```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 external data into Voodoo Store
at startup. Migration is an explicit operation.

## Examples

| Example | What it demonstrates |
|---|---|
| `examples/basics/hello_world/` | smallest application + native design system |
| `examples/web/dashboard/` | reactive UI/state |
| `examples/web/realtime/` | realtime communication |
| `examples/web/ui_magic/` | callable UI + current design-system acceptance app |
| `examples/ai/agent/` | Agent + Tool |
| `examples/ai/saas/` | UI + Agent + Tool + Mesh + Task + Model |
| `examples/adaptive/operational_closed_loop/` | Edge → World → Goal → Execution → Effect → evidence |

## Documentation

A useful reading order:

1. [Hello world](docs/hello_world.md)
2. [Choosing primitives](docs/choosing-primitives.md)
3. [Computational primitives](docs/primitives.md)
4. [Execution model](docs/execution-model.md)
5. [Runtime](docs/runtime.md)
6. [Agents](docs/agents.md) and [Tools](docs/tools.md)
7. [Human-in-the-loop](docs/hitl.md)
8. [MCP](docs/mcp.md)
9. [Protocol](docs/protocol.md)
10. [Voodoo 3.0 public API law](docs/public-api-3.md)
11. [Architecture](ARCHITECTURE.md)
12. [Roadmap](ROADMAP.md)

`SPRINT_PLAN.md` is the implementation tracker; it should not be treated as a
marketing promise for future capabilities.

## What Voodoo deliberately does not claim

Voodoo's architecture is broad, but its guarantees are intentionally explicit.

Current Voodoo 3.0 does **not** claim:

- automatic Store replication or synchronization between nodes;
- shared multi-writer `.vstore` files;
- distributed consensus;
- globally serializable cross-node transactions;
- global exactly-once execution;
- production PKI/OIDC/mTLS infrastructure;
- a managed Voodoo Cloud control plane.

The Voodoo Store 0.3 integration line exposes native Collections/index
queries, Queues, Topics/Streams, Consumer Groups, Objects, RPC, CDC,
Workflow/HITL state, lifecycle operations and heterogeneous transactions to the
Runtime. Those primitives remain single-node/local Store semantics; they do not
imply replication, consensus or global exactly-once behavior.

## What Voodoo is trying to preserve

As the project grows, these properties are architectural constraints:

- one Runtime and one canonical Execution lifecycle;
- local-first progressive complexity;
- Python application code instead of a mandatory workflow DSL;
- explicit authority for effects;
- AI as a participant, not an ambient superuser;
- replaceable infrastructure behind contracts;
- topology changes without rewriting business semantics;
- observable lineage from Intent → Execution → Effect → Observation;
- one semantic owner per concept.

## Project status

Voodoo is **beta software**.

**v3.1.0** is the current published architecture baseline: Runtime adapters
converged on the published Voodoo Store 0.3 native surface, with the modern
Model contract and UUIDv7 identity. The `main` branch may
contain post-release documentation or implementation work, so a merge to
`main` is not itself a package release.

The next numbered development sprint is intentionally selected from real
product/architecture pressure rather than by accumulating unrelated framework
features.

## Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) before
structural changes. Repository architecture is enforced by tests, including
rules that prevent removed 2.x compatibility namespaces from returning.

Security issues should follow [SECURITY.md](SECURITY.md). Community behavior is
covered by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

## License

MIT. See [LICENSE](LICENSE).
