voodoo-framework 2.4.0__tar.gz → 2.5.1__tar.gz

{voodoo_framework-2.4.0/src/voodoo_framework.egg-info → voodoo_framework-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 2.4.0
+Version: 2.5.1
 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>
@@ -119,14 +119,16 @@ Voodoo is **not** a wrapper around other frameworks. It's a unified runtime wher
 
 ```bash
 pip install voodoo-framework
-voodoo new my_app
+voodoo create 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.
+`voodoo create` scaffolds a full local runtime app with durable tasks, scheduler, events, and agent runtime — all on zero infrastructure. The generated app includes a crash/restart demo proving durability.
+
+> **Want a minimal scaffold?** Use `voodoo new` instead for a bare-bones app with just UI routing.
 
 > **Want AI features?** Install with `pip install "voodoo-framework[ai]"` to add OpenAI, Anthropic, Gemini, and Ollama SDKs.
 
@@ -232,7 +234,7 @@ if __name__ == "__main__":
 | **Human-in-the-Loop** | `ask_human()` + `approve()`/`deny()` — humans as compute participants, not afterthoughts |
 | **Adaptive execution** | Planner resolves capabilities to compute participants; supervisor steers with retry, fallback, budget control |
 | **Durable by default** | Tasks, executions, schedules, and events survive process restarts — backed by SQLite out of the box |
-| **Zero-config runtime** | `voodoo new` → `voodoo dev` → working app. No build step. Add `voodoo.toml` when you need configuration |
+| **Zero-config runtime** | `voodoo create` → `voodoo dev` → working app. No build step. Add `voodoo.toml` when you need configuration |
 | **Local-first, cloud-capable** | SQLite by default; PostgreSQL, Redis, and S3/R2 are optional adapters behind the same contracts |
 
 ## The Computational Model

{voodoo_framework-2.4.0 → voodoo_framework-2.5.1}/README.md

@@ -52,14 +52,16 @@ Voodoo is **not** a wrapper around other frameworks. It's a unified runtime wher
 
 ```bash
 pip install voodoo-framework
-voodoo new my_app
+voodoo create 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.
+`voodoo create` scaffolds a full local runtime app with durable tasks, scheduler, events, and agent runtime — all on zero infrastructure. The generated app includes a crash/restart demo proving durability.
+
+> **Want a minimal scaffold?** Use `voodoo new` instead for a bare-bones app with just UI routing.
 
 > **Want AI features?** Install with `pip install "voodoo-framework[ai]"` to add OpenAI, Anthropic, Gemini, and Ollama SDKs.
 
@@ -165,7 +167,7 @@ if __name__ == "__main__":
 | **Human-in-the-Loop** | `ask_human()` + `approve()`/`deny()` — humans as compute participants, not afterthoughts |
 | **Adaptive execution** | Planner resolves capabilities to compute participants; supervisor steers with retry, fallback, budget control |
 | **Durable by default** | Tasks, executions, schedules, and events survive process restarts — backed by SQLite out of the box |
-| **Zero-config runtime** | `voodoo new` → `voodoo dev` → working app. No build step. Add `voodoo.toml` when you need configuration |
+| **Zero-config runtime** | `voodoo create` → `voodoo dev` → working app. No build step. Add `voodoo.toml` when you need configuration |
 | **Local-first, cloud-capable** | SQLite by default; PostgreSQL, Redis, and S3/R2 are optional adapters behind the same contracts |
 
 ## The Computational Model

{voodoo_framework-2.4.0 → voodoo_framework-2.5.1}/src/voodoo/__init__.py

@@ -102,7 +102,7 @@ from .ui.styles import (
 from .ui.styles.theme import Theme, ThemeColors, create_theme
 from .workers import task
 
-__version__ = "2.4.0"
+__version__ = "2.5.1"
 
 __all__ = [
     # Core runtime

{voodoo_framework-2.4.0 → voodoo_framework-2.5.1}/src/voodoo/cli/__init__.py

@@ -4,6 +4,7 @@ from voodoo.cli import (
     agents,
     ai,
     approvals,
+    create,
     dev,
     doctor,
     executions,
@@ -32,6 +33,7 @@ app = typer.Typer(
 )
 
 app.command()(new.new)
+app.command()(create.create)
 app.command()(dev.dev)
 app.command()(generate.generate)
 app.add_typer(auth_app, name="auth")

voodoo_framework-2.5.1/src/voodoo/cli/create.py

@@ -0,0 +1,361 @@
+"""CLI: ``voodoo create <app>`` — scaffold a full local runtime app.
+
+Sprint 22: Local runtime DX.  Evolves ``voodoo new`` to wire up the full
+local runtime (durable tasks, scheduler, events, object store, agent runtime)
+with a crash/restart demo proving durability.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+
+from voodoo.cli import terminal
+
+__all__ = ["create"]
+
+# ---------------------------------------------------------------------------
+# Template: main.py — full local runtime
+# ---------------------------------------------------------------------------
+
+_MAIN_PY = '''"""{name} — a Voodoo autonomous app.
+
+This app demonstrates the full local runtime:
+  - Durable tasks (queue + workers) that survive restarts
+  - Scheduler for recurring jobs
+  - Mesh events for real-time communication
+  - Agent runtime with mock provider (no network needed)
+
+Run:  python main.py   or   voodoo dev
+"""
+
+from voodoo import (
+    Agent,
+    App,
+    Button,
+    Card,
+    Container,
+    Heading,
+    Stack,
+    Text,
+    event,
+    page,
+    state,
+    tool,
+)
+from voodoo.workers.queue import enqueue, queue
+
+app = App()
+
+# ---------------------------------------------------------------------------
+# State
+# ---------------------------------------------------------------------------
+
+counter = state("counter", 0)
+log_lines = state("log_lines", [])
+agent_result = state("agent_result", "Click to run the agent")
+
+
+def _log(msg: str) -> None:
+    """Append a timestamped line to the on-screen log."""
+    from datetime import datetime
+
+    ts = datetime.now().strftime("%H:%M:%S")
+    lines = log_lines.get()
+    lines.append(f"[{{ts}}] {{msg}}")
+    # Keep last 20 lines
+    log_lines.set(lines[-20:])
+
+
+# ---------------------------------------------------------------------------
+# Durable task — survives restarts
+# ---------------------------------------------------------------------------
+
+@queue("increment")
+async def increment_worker(payload: dict) -> None:
+    """Durable worker: increments the counter and logs the result."""
+    n = counter.get() + 1
+    counter.set(n)
+    _log(f"increment task done → counter = {{n}}")
+
+
+# ---------------------------------------------------------------------------
+# Agent (mock provider — no network needed)
+# ---------------------------------------------------------------------------
+
+@tool
+async def get_counter() -> str:
+    """Return the current counter value."""
+    return str(counter.get())
+
+
+agent = Agent(
+    model="mock:test",
+    tools=["get_counter"],
+)
+
+
+# ---------------------------------------------------------------------------
+# Routes
+# ---------------------------------------------------------------------------
+
+@page("/")
+def home():
+    return Container(
+        Stack(
+            Heading("{name}", level=1),
+            Text(
+                "A Voodoo autonomous app — durable tasks, scheduler, "
+                "events, and agents, all running on zero infrastructure.",
+                tone="muted",
+            ),
+            _status_card(),
+            _task_card(),
+            _agent_card(),
+            _log_card(),
+            gap="lg",
+        )
+    )
+
+
+def _status_card():
+    return Card(
+        Stack(
+            Heading("Runtime", level=2),
+            Text(f"Counter: {{counter.get()}}"),
+            Text(f"Log entries: {{len(log_lines.get())}}"),
+            gap="sm",
+        )
+    )
+
+
+def _task_card():
+    return Card(
+        Stack(
+            Heading("Durable Tasks", level=2),
+            Text(
+                "Enqueue a durable task. It survives restarts — "
+                "stop the server, start it again, and watch the counter increment.",
+                tone="muted",
+            ),
+            Button(
+                "Enqueue increment",
+                onclick="vd.event('enqueue_task')",
+                variant="primary",
+            ),
+            gap="sm",
+        )
+    )
+
+
+def _agent_card():
+    return Card(
+        Stack(
+            Heading("Agent", level=2),
+            Text(f"Result: {{agent_result.get()}}"),
+            Button(
+                "Run agent",
+                onclick="vd.event('run_agent')",
+                variant="secondary",
+            ),
+            gap="sm",
+        )
+    )
+
+
+def _log_card():
+    return Card(
+        Stack(
+            Heading("Event Log", level=2),
+            *[Text(line, tone="muted") for line in log_lines.get()],
+            gap="xs",
+        )
+    )
+
+
+# ---------------------------------------------------------------------------
+# Events
+# ---------------------------------------------------------------------------
+
+@event
+async def enqueue_task(element_id, value):
+    """Enqueue a durable increment task."""
+    await enqueue("increment", {{"source": "ui"}})
+    _log("enqueued increment task")
+
+
+@event
+async def run_agent(element_id, value):
+    """Run the agent and display the result."""
+    _log("running agent...")
+    run = await agent.run("What is the current counter value?")
+    agent_result.set(run.output)
+    _log(f"agent done: {{run.output}}")
+
+
+# ---------------------------------------------------------------------------
+# Startup — enqueue a demo task on first boot
+# ---------------------------------------------------------------------------
+
+@app.on_startup
+async def on_startup():
+    """On first boot, enqueue a demo task to prove durability."""
+    import os
+
+    marker = ".voodoo/state/.booted"
+    if not os.path.exists(marker):
+        os.makedirs(os.path.dirname(marker), exist_ok=True)
+        with open(marker, "w") as f:
+            f.write("booted")
+        await enqueue("increment", {{"source": "startup"}})
+        _log("first boot — enqueued demo task")
+    else:
+        _log("restart detected — pending tasks will be recovered")
+
+
+if __name__ == "__main__":
+    app.run()
+'''
+
+# ---------------------------------------------------------------------------
+# Template: voodoo.toml
+# ---------------------------------------------------------------------------
+
+_VOODOO_TOML = """[app]
+name = "{name}"
+
+# Local-first defaults — zero infrastructure required.
+# The runtime uses SQLite, local filesystem, and in-memory queues by default.
+# Override with env vars or this config for production:
+#   VOODOO_DATABASE_URL=postgresql://...
+#   VOODOO_QUEUE_PROVIDER=redis
+#   VOODOO_OBJECT_STORE_PROVIDER=s3
+"""
+
+# ---------------------------------------------------------------------------
+# Template: pyproject.toml
+# ---------------------------------------------------------------------------
+
+_PYPROJECT_TOML = """[project]
+name = "{name}"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "voodoo-framework",
+]
+"""
+
+
+# ---------------------------------------------------------------------------
+# Command
+# ---------------------------------------------------------------------------
+
+
+def create(
+    project_name: str = typer.Argument(..., help="Name of the project to create"),
+) -> None:
+    """Scaffold a full local runtime app with durable tasks, scheduler, events, and agents.
+
+    The generated app runs on zero infrastructure (SQLite + local filesystem)
+    and includes a crash/restart demo proving durability.
+    """
+    project_dir = Path(project_name)
+    if project_dir.exists():
+        terminal.error(f"Directory '{project_name}' already exists")
+        raise typer.Exit(1)
+
+    terminal.wordmark()
+    terminal.blank()
+    terminal.status("creating", project_name)
+    terminal.blank()
+
+    # Create directory structure
+    project_dir.mkdir(parents=True)
+    (project_dir / "app").mkdir()
+    (project_dir / ".voodoo" / "state").mkdir(parents=True)
+
+    # Write files
+    (project_dir / "main.py").write_text(_MAIN_PY.format(name=project_name))
+    (project_dir / "voodoo.toml").write_text(_VOODOO_TOML.format(name=project_name))
+    (project_dir / "pyproject.toml").write_text(
+        _PYPROJECT_TOML.format(name=project_name)
+    )
+
+    terminal.label_value("created", f"{project_name}/")
+    terminal.tree(
+        [
+            "main.py          # App entry point — full runtime demo",
+            "voodoo.toml      # Runtime configuration",
+            "pyproject.toml   # Python project metadata",
+            "app/             # Folder-based routes (add page.py files here)",
+            ".voodoo/state/   # Local state (SQLite, queue, schedules)",
+        ]
+    )
+    terminal.blank()
+
+    # Install dependencies
+    terminal.status("installing", "dependencies")
+    terminal.blank()
+
+    local_venv = project_dir / ".venv"
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "uv", "venv", str(local_venv)],
+            check=True,
+            capture_output=True,
+        )
+        subprocess.run(
+            [
+                str(local_venv / "bin" / "python"),
+                "-m",
+                "uv",
+                "pip",
+                "install",
+                "-e",
+                ".",
+            ],
+            cwd=str(project_dir),
+            check=True,
+            capture_output=True,
+        )
+        terminal.muted("installed via uv")
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        # Fallback to plain venv + pip
+        try:
+            subprocess.run(
+                [sys.executable, "-m", "venv", str(local_venv)],
+                check=True,
+                capture_output=True,
+            )
+            subprocess.run(
+                [
+                    str(local_venv / "bin" / "pip"),
+                    "install",
+                    "-e",
+                    ".",
+                ],
+                cwd=str(project_dir),
+                check=True,
+                capture_output=True,
+            )
+            terminal.muted("installed via pip")
+        except subprocess.CalledProcessError as exc:
+            terminal.warning(f"dependency install failed: {exc}")
+            terminal.muted("run 'cd {project_name} && pip install -e .' manually")
+
+    terminal.blank()
+    terminal.success("ready")
+    terminal.blank()
+    terminal.next_steps(
+        [
+            f"cd {project_name}",
+            "voodoo dev",
+            "",
+            "Then open http://localhost:8000 and click 'Enqueue increment'.",
+            "Stop the server (Ctrl+C), run 'voodoo dev' again — the counter",
+            "increments because the task is durable.",
+        ]
+    )

{voodoo_framework-2.4.0 → voodoo_framework-2.5.1}/src/voodoo/cli/dev.py

@@ -70,6 +70,9 @@ def dev(
     terminal.label_value("docs", f"{local_url}/docs")
     terminal.blank()
 
+    # Sprint 22: runtime banner — show providers and runtime state
+    _print_runtime_banner()
+
     local_venv_python = (
         Path(".venv/bin/python")
         if os.name != "nt"
@@ -117,3 +120,54 @@ def dev(
     except KeyboardInterrupt:
         terminal.blank()
         terminal.status("runtime", "stopped")
+
+
+def _print_runtime_banner() -> None:
+    """Print runtime providers and state (Sprint 22)."""
+    from voodoo.config import get_config
+
+    cfg = get_config()
+
+    # Providers
+    terminal.heading("providers")
+    db_provider = cfg.database.provider.lower()
+    terminal.status("database", db_provider)
+
+    queue_provider = cfg.queue.provider.lower()
+    terminal.status("queue", queue_provider)
+
+    # Object store
+    terminal.status("objects", cfg.objects.provider.lower())
+
+    # Agent runtime
+    try:
+        from voodoo.ai.providers import _PROVIDER_CLASSES
+
+        providers = list(_PROVIDER_CLASSES.keys())
+        terminal.status("agents", ", ".join(providers) if providers else "none")
+    except Exception:
+        terminal.status("agents", "mock")
+
+    # MCP endpoint
+    terminal.label_value("mcp", "/mcp")
+
+    # Registered workers
+    try:
+        from voodoo.workers.queue import _workers
+
+        worker_names = list(_workers.keys())
+        if worker_names:
+            terminal.label_value("workers", ", ".join(worker_names))
+        else:
+            terminal.label_value("workers", "none")
+    except Exception:
+        terminal.label_value("workers", "none")
+
+    # Schedules DB
+    schedule_path = Path(".voodoo/state/schedules.db")
+    if schedule_path.exists():
+        terminal.status("scheduler", "ready")
+    else:
+        terminal.status("scheduler", "will be created")
+
+    terminal.blank()

{voodoo_framework-2.4.0 → voodoo_framework-2.5.1}/src/voodoo/protocol/schemas.py

@@ -17,7 +17,7 @@ Compatibility policy (see ``docs/protocol.md``):
 
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import UTC, datetime
 from enum import StrEnum
 from typing import Any
 
@@ -150,8 +150,8 @@ class Identity(BaseModel):
     id: str = Field(description="Globally unique entity ID (UUID4).")
     kind: str = Field(description="Entity kind (e.g. 'agent', 'execution', 'task').")
     owner: str | None = None
-    created_at: datetime = Field(default_factory=datetime.utcnow)
-    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
     metadata: dict[str, Any] = Field(default_factory=dict)
 
 
@@ -165,7 +165,7 @@ class Capability(BaseModel):
     delegate_to: str | None = None
     expires_at: datetime | None = None
     revoked: bool = False
-    issued_at: datetime = Field(default_factory=datetime.utcnow)
+    issued_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
     issued_by: str | None = None
 
 
@@ -228,8 +228,8 @@ class Intent(BaseModel):
     requires: list[str] = Field(default_factory=list)
     constraints: list[Constraint] = Field(default_factory=list)
     effect_ids: list[str] = Field(default_factory=list)
-    created_at: datetime = Field(default_factory=datetime.utcnow)
-    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
     result: Any = None
     error: str | None = None
 
@@ -248,7 +248,7 @@ class Effect(BaseModel):
     status: EffectStatus = EffectStatus.PENDING
     result: Any = None
     error: str | None = None
-    created_at: datetime = Field(default_factory=datetime.utcnow)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
     executed_at: datetime | None = None
     actor: str | None = None
     principal: str | None = None
@@ -275,10 +275,76 @@ class Execution(BaseModel):
     error: str | None = None
     metadata: dict[str, Any] = Field(default_factory=dict)
     checkpoint: dict[str, Any] | None = None
-    created_at: datetime = Field(default_factory=datetime.utcnow)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
     started_at: datetime | None = None
     completed_at: datetime | None = None
 
+    # -- runtime conversion ------------------------------------------------
+
+    @classmethod
+    def from_runtime_execution(
+        cls,
+        exec: Any,  # noqa: ANN401 — runtime.Execution
+    ) -> Execution:
+        """Convert a runtime ``Execution`` to a protocol ``Execution``.
+
+        Runtime ``State`` objects in ``state_changes`` are converted to dicts
+        via ``model_dump()`` so the protocol representation is JSON-safe.
+        """
+        return cls(
+            id=exec.id,
+            trace_id=exec.trace_id,
+            parent_execution_id=exec.parent_execution_id,
+            status=ExecutionStatus(exec.status.value),
+            intent=exec.intent,
+            actor=exec.actor,
+            compute=exec.compute,
+            capabilities=list(exec.capabilities),
+            resources=exec.resources,
+            effects=list(exec.effects),
+            state_changes=[
+                s.model_dump() if hasattr(s, "model_dump") else s
+                for s in exec.state_changes
+            ],
+            result=exec.result,
+            error=exec.error,
+            metadata=dict(exec.metadata),
+            checkpoint=exec.checkpoint,
+            created_at=exec.created_at,
+            started_at=exec.started_at,
+            completed_at=exec.completed_at,
+        )
+
+    def to_runtime_execution(self) -> Any:  # noqa: ANN401
+        """Convert this protocol ``Execution`` back to a runtime ``Execution``.
+
+        Requires ``voodoo.runtime.execution.Execution`` to be importable.
+        Uses a lazy import to avoid circular dependencies.
+        """
+        from voodoo.runtime.execution import Execution as RuntimeExecution
+        from voodoo.runtime.execution import ExecutionStatus as RuntimeStatus
+
+        return RuntimeExecution(
+            id=self.id,
+            trace_id=self.trace_id,
+            parent_execution_id=self.parent_execution_id,
+            status=RuntimeStatus(self.status.value),
+            intent=self.intent,
+            actor=self.actor,
+            compute=self.compute,
+            capabilities=list(self.capabilities),
+            resources=self.resources,
+            effects=list(self.effects),
+            state_changes=self.state_changes,
+            result=self.result,
+            error=self.error,
+            metadata=dict(self.metadata),
+            checkpoint=self.checkpoint,
+            created_at=self.created_at,
+            started_at=self.started_at,
+            completed_at=self.completed_at,
+        )
+
 
 class Task(BaseModel):
     """A queued work item (worker task)."""
@@ -326,7 +392,7 @@ class ObjectRef(BaseModel):
     content_type: str | None = None
     checksum: str | None = None
     metadata: dict[str, Any] = Field(default_factory=dict)
-    created_at: datetime = Field(default_factory=datetime.utcnow)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
 
 
 class Error(BaseModel):
@@ -339,7 +405,7 @@ class Error(BaseModel):
     trace_id: str | None = None
     details: dict[str, Any] = Field(default_factory=dict)
     cause: str | None = None
-    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
 
 
 class TelemetrySpan(BaseModel):
@@ -370,7 +436,7 @@ class Approval(BaseModel):
     decided_by: str | None = None
     decided_at: datetime | None = None
     reason: str | None = None
-    created_at: datetime = Field(default_factory=datetime.utcnow)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
     participant: str | None = None
 
 
@@ -389,8 +455,8 @@ class AgentEntity(BaseModel):
     config: dict[str, Any] = Field(default_factory=dict)
     state: str = "active"
     metadata: dict[str, Any] = Field(default_factory=dict)
-    created_at: datetime = Field(default_factory=datetime.utcnow)
-    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
 
 
 class AgentRun(BaseModel):
@@ -424,8 +490,8 @@ class MemoryEntry(BaseModel):
     tags: list[str] = Field(default_factory=list)
     source_execution_id: str | None = None
     importance: float = 0.5
-    created_at: datetime = Field(default_factory=datetime.utcnow)
-    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
     expires_at: datetime | None = None