voodoo-framework 1.2.0__tar.gz → 1.4.0__tar.gz

{voodoo_framework-1.2.0 → voodoo_framework-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 1.2.0
+Version: 1.4.0
 Summary: Voodoo Framework
 Requires-Python: >=3.12
 Requires-Dist: starlette

{voodoo_framework-1.2.0 → voodoo_framework-1.4.0}/src/voodoo/__init__.py

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

{voodoo_framework-1.2.0 → voodoo_framework-1.4.0}/src/voodoo/cli/__init__.py

@@ -1,6 +1,6 @@
 import typer
 
-from voodoo.cli import ai, dev, doctor, generate, new, recover, routes, version
+from voodoo.cli import ai, dev, doctor, generate, new, recover, routes, tasks, version
 from voodoo.cli.auth import auth_app
 from voodoo.cli.inspect import inspect_app
 
@@ -18,6 +18,7 @@ app.command()(generate.generate)
 app.add_typer(auth_app, name="auth")
 app.add_typer(ai.ai_app, name="ai")
 app.add_typer(inspect_app, name="inspect")
+app.add_typer(tasks.tasks_app, name="tasks")
 app.command()(version.version)
 app.command()(doctor.doctor)
 app.command()(routes.routes)

{voodoo_framework-1.2.0 → voodoo_framework-1.4.0}/src/voodoo/cli/inspect.py

@@ -52,13 +52,15 @@ def _load_app(app_str: str | None) -> Any:
     return getattr(mod, attr, None)
 
 
-
 def _is_json(json_mode: bool) -> bool:
     """JSON mode: explicit flag or global --json in argv."""
     return bool(json_mode) or terminal.is_json_mode()
 
+
 def _table(columns: list[str]) -> Table:
-    table = Table(show_header=True, header_style="dim", border_style="#262626", pad_edge=False)
+    table = Table(
+        show_header=True, header_style="dim", border_style="#262626", pad_edge=False
+    )
     for c in columns:
         table.add_column(c)
     return table
@@ -75,9 +77,13 @@ def _emit(data: Any, json_mode: bool = False) -> None:
 
 @inspect_app.command("run")
 def inspect_run(
-    execution_id: str = typer.Argument(None, help="Execution id (lists recent if omitted)"),
+    execution_id: str = typer.Argument(
+        None, help="Execution id (lists recent if omitted)"
+    ),
     app_str: str = typer.Option(None, "--app", help="App instance (e.g. main:app)"),
-    json_mode: bool = typer.Option(False, "--json", help="Output machine-readable JSON"),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON"
+    ),
 ):
     """Show an execution — status, intent, capabilities, effects, cost."""
     from voodoo.runtime import engine
@@ -121,7 +127,10 @@ def inspect_run(
             ("intent", d["intent"] or "-"),
             ("actor", d["actor"]),
             ("cost", f"{d['cost']:.6f}"),
-            ("duration", f"{d['duration_seconds']:.3f}s" if d["duration_seconds"] else "-"),
+            (
+                "duration",
+                f"{d['duration_seconds']:.3f}s" if d["duration_seconds"] else "-",
+            ),
         ]
     )
     if d["capabilities"]:
@@ -136,8 +145,12 @@ def inspect_run(
 @inspect_app.command("agent")
 def inspect_agent(
     app_str: str = typer.Option(None, "--app"),
-    json_mode: bool = typer.Option(False, "--json", help="Output machine-readable JSON"),
-    url: str = typer.Option(None, "--url", help="Live server URL (e.g. http://localhost:8000)"),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON"
+    ),
+    url: str = typer.Option(
+        None, "--url", help="Live server URL (e.g. http://localhost:8000)"
+    ),
     limit: int = typer.Option(10, "--limit"),
 ):
     """Recent agent runs: model, tokens, cost, tool calls, status."""
@@ -188,10 +201,16 @@ def inspect_agent(
 
 @inspect_app.command("plan")
 def inspect_plan(
-    intent_name: str = typer.Argument(..., help="Intent name to plan (e.g. 'notify.customer')"),
-    requires: str = typer.Option(None, "--requires", help="Comma-separated required capabilities"),
+    intent_name: str = typer.Argument(
+        ..., help="Intent name to plan (e.g. 'notify.customer')"
+    ),
+    requires: str = typer.Option(
+        None, "--requires", help="Comma-separated required capabilities"
+    ),
     app_str: str = typer.Option(None, "--app", help="App instance (e.g. main:app)"),
-    json_mode: bool = typer.Option(False, "--json", help="Output machine-readable JSON"),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON"
+    ),
 ):
     """Plan an intent — show the planner's strategy + participant assignment."""
     from voodoo.primitives.intent import Intent
@@ -215,12 +234,14 @@ def inspect_plan(
         terminal.json_output(data)
         return
 
-    terminal.status_block([
-        ("intent", data["intent"]),
-        ("strategy", data["strategy"]),
-        ("steps", str(len(data["steps"]))),
-        ("unresolved", str(len(data["unresolved"]))),
-    ])
+    terminal.status_block(
+        [
+            ("intent", data["intent"]),
+            ("strategy", data["strategy"]),
+            ("steps", str(len(data["steps"]))),
+            ("unresolved", str(len(data["unresolved"]))),
+        ]
+    )
     if data["decisions"]:
         terminal.blank()
         for d in data["decisions"]:
@@ -234,7 +255,9 @@ def inspect_plan(
 @inspect_app.command("tool")
 def inspect_tool(
     app_str: str = typer.Option(None, "--app"),
-    json_mode: bool = typer.Option(False, "--json", help="Output machine-readable JSON"),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON"
+    ),
     limit: int = typer.Option(15, "--limit"),
 ):
     """Recent tool calls: name, latency, error."""
@@ -263,7 +286,9 @@ def inspect_tool(
 @inspect_app.command("task")
 def inspect_task(
     app_str: str = typer.Option(None, "--app"),
-    json_mode: bool = typer.Option(False, "--json", help="Output machine-readable JSON"),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON"
+    ),
     limit: int = typer.Option(20, "--limit"),
 ):
     """Executions whose actor is task/agent-driven (Task units)."""
@@ -294,7 +319,9 @@ def inspect_task(
 def inspect_workflow(
     trace_id: str = typer.Argument(None, help="Trace id (groups task executions)"),
     app_str: str = typer.Option(None, "--app"),
-    json_mode: bool = typer.Option(False, "--json", help="Output machine-readable JSON"),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON"
+    ),
 ):
     """Executions grouped by trace — the observable workflow structure."""
     from voodoo.runtime import ExecutionGraph, engine
@@ -313,10 +340,15 @@ def inspect_workflow(
         terminal.muted("no executions recorded in this process")
     for root in described:
         terminal.heading(f"trace {root['trace_id'][:8]} · {root.get('intent') or '-'}")
-        terminal.tree([f"{root['intent'] or root['id'][:8]} [{root['status']}]", *[
-            f"  {c.get('intent') or c['id'][:8]} [{c['status']}] (actor: {c.get('actor')})"
-            for c in root.get("children", [])
-        ]])
+        terminal.tree(
+            [
+                f"{root['intent'] or root['id'][:8]} [{root['status']}]",
+                *[
+                    f"  {c.get('intent') or c['id'][:8]} [{c['status']}] (actor: {c.get('actor')})"
+                    for c in root.get("children", [])
+                ],
+            ]
+        )
         terminal.blank()
 
 
@@ -324,7 +356,9 @@ def inspect_workflow(
 def inspect_state(
     entity: str = typer.Argument(None, help="Entity kind (e.g. lead, order)"),
     app_str: str = typer.Option(None, "--app"),
-    json_mode: bool = typer.Option(False, "--json", help="Output machine-readable JSON"),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON"
+    ),
 ):
     """Observable state changes recorded on executions."""
     from voodoo.runtime import engine
@@ -365,7 +399,9 @@ def inspect_state(
 @inspect_app.command("capabilities")
 def inspect_capabilities(
     app_str: str = typer.Option(None, "--app"),
-    json_mode: bool = typer.Option(False, "--json", help="Output machine-readable JSON"),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON"
+    ),
 ):
     """Registered capability templates and tool permission requirements."""
     from voodoo.runtime import engine
@@ -387,10 +423,12 @@ def inspect_capabilities(
     if _is_json(json_mode):
         terminal.json_output({"capabilities": cap_data, "tool_permissions": tool_perms})
         return
-    terminal.status_block([
-        ("capabilities", str(len(cap_data["capabilities"]))),
-        ("approval req.", str(len(cap_data["approval_required"]))),
-    ])
+    terminal.status_block(
+        [
+            ("capabilities", str(len(cap_data["capabilities"]))),
+            ("approval req.", str(len(cap_data["approval_required"]))),
+        ]
+    )
     if cap_data["capabilities"]:
         terminal.label_value("names", ", ".join(cap_data["capabilities"]))
     if tool_perms:
@@ -405,7 +443,9 @@ def inspect_capabilities(
 @inspect_app.command("mesh")
 def inspect_mesh(
     app_str: str = typer.Option(None, "--app"),
-    json_mode: bool = typer.Option(False, "--json", help="Output machine-readable JSON"),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON"
+    ),
 ):
     """Mesh surface: exposed functions, event handlers, active nodes."""
     from voodoo.mesh import mesh
@@ -420,11 +460,13 @@ def inspect_mesh(
     if _is_json(json_mode):
         terminal.json_output(data)
         return
-    terminal.status_block([
-        ("exposed", str(len(data["exposed"]))),
-        ("event types", str(len(data["handlers"]))),
-        ("active nodes", str(data["active_nodes"])),
-    ])
+    terminal.status_block(
+        [
+            ("exposed", str(len(data["exposed"]))),
+            ("event types", str(len(data["handlers"]))),
+            ("active nodes", str(data["active_nodes"])),
+        ]
+    )
     if data["handlers"]:
         terminal.blank()
         table = _table(["event", "handlers"])
@@ -436,9 +478,13 @@ def inspect_mesh(
 
 @inspect_app.command("approvals")
 def inspect_approvals(
-    pending_only: bool = typer.Option(False, "--pending", help="Only show pending approvals"),
+    pending_only: bool = typer.Option(
+        False, "--pending", help="Only show pending approvals"
+    ),
     app_str: str = typer.Option(None, "--app"),
-    json_mode: bool = typer.Option(False, "--json", help="Output machine-readable JSON"),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON"
+    ),
 ):
     """Human approvals — pending and decided, with capability + requester."""
     from voodoo.runtime import engine

{voodoo_framework-1.2.0 → voodoo_framework-1.4.0}/src/voodoo/cli/new.py

@@ -9,7 +9,6 @@ from rich.progress import Progress, SpinnerColumn, TextColumn
 
 from voodoo.cli import terminal
 
-
 # ---------------------------------------------------------------------------
 # Offline scaffold — used when no template repository is available.
 # Showcases Voodoo CSS (the default adapter), folder-based routing, and the

{voodoo_framework-1.2.0 → voodoo_framework-1.4.0}/src/voodoo/cli/recover.py

@@ -18,15 +18,21 @@ from voodoo.cli import terminal
 
 def recover(
     app_str: str = typer.Option(None, "--app", help="App instance (e.g. main:app)"),
-    store_path: str = typer.Option(None, "--store", help="Path to the JSONL execution store"),
-    json_mode: bool = typer.Option(False, "--json", help="Output machine-readable JSON"),
+    store_path: str = typer.Option(
+        None, "--store", help="Path to the JSONL execution store"
+    ),
+    json_mode: bool = typer.Option(
+        False, "--json", help="Output machine-readable JSON"
+    ),
 ):
     """Reload unfinished executions from the store into the engine."""
     from voodoo.runtime.engine import engine as runtime_engine
     from voodoo.runtime.persistence import JSONFileExecutionStore
 
     if store_path is None:
-        store_path = os.environ.get("VOODOO_EXECUTION_STORE", ".voodoo/executions.jsonl")
+        store_path = os.environ.get(
+            "VOODOO_EXECUTION_STORE", ".voodoo/executions.jsonl"
+        )
 
     if app_str is not None:
         # Import the app first: it may attach its own store / register
@@ -57,7 +63,9 @@ def recover(
     terminal.status_block([("store", store_path), ("recovered", str(len(recovered)))])
     from rich.table import Table
 
-    table = Table(show_header=True, header_style="dim", border_style="#262626", pad_edge=False)
+    table = Table(
+        show_header=True, header_style="dim", border_style="#262626", pad_edge=False
+    )
     for c in ("id", "intent", "status", "actor"):
         table.add_column(c)
     for ex in recovered:

voodoo_framework-1.4.0/src/voodoo/cli/tasks.py

@@ -0,0 +1,114 @@
+"""voodoo tasks — inspect and manage durable background tasks."""
+
+from __future__ import annotations
+
+import typer
+
+from voodoo.cli import terminal
+
+tasks_app = typer.Typer(
+    name="tasks",
+    help="Inspect and manage durable background tasks.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+
+def _get_queue():
+    from voodoo.workers.queue import _get_queue
+
+    return _get_queue()
+
+
+@tasks_app.command("list")
+def list_tasks(
+    status: str = typer.Option(None, "--status", help="Filter by status"),
+    task_type: str = typer.Option(None, "--type", help="Filter by task type"),
+    json_mode: bool = typer.Option(False, "--json", help="Machine-readable JSON"),
+):
+    """List recent tasks."""
+    import asyncio
+
+    from voodoo.storage.queue import TaskStatus
+
+    async def run():
+        q = await _get_queue()
+        stat = TaskStatus(status) if status else None
+        tasks = await q.list(status=stat, task_type=task_type)
+        stats = await q.stats()
+        if json_mode or terminal.is_json_mode():
+            terminal.json_output(
+                {"stats": stats.describe(), "tasks": [t.describe() for t in tasks]}
+            )
+            return
+        terminal.wordmark()
+        terminal.blank()
+        terminal.status_block(
+            [
+                ("provider", q.capabilities().provider),
+                ("total", str(stats.total)),
+                ("pending", str(stats.pending)),
+                ("running", str(stats.running)),
+                ("retrying", str(stats.retrying)),
+                ("completed", str(stats.completed)),
+                ("failed", str(stats.failed)),
+            ]
+        )
+        terminal.blank()
+        if not tasks:
+            terminal.muted("no tasks found")
+            return
+        from rich.table import Table
+
+        table = Table(
+            show_header=True, header_style="dim", border_style="#262626", pad_edge=False
+        )
+        for c in ("id", "type", "status", "priority", "attempts", "created_at"):
+            table.add_column(c)
+        for t in tasks:
+            table.add_row(
+                str(t.id),
+                t.type,
+                t.status.value,
+                str(t.priority),
+                f"{t.attempts}/{t.max_attempts}",
+                t.created_at.strftime("%H:%M:%S") if t.created_at else "-",
+            )
+        terminal.console.print(table)
+        terminal.blank()
+
+    asyncio.run(run())
+
+
+@tasks_app.command("retry")
+def retry_task(
+    task_id: int = typer.Argument(..., help="Task ID to retry"),
+    json_mode: bool = typer.Option(False, "--json", help="Machine-readable JSON"),
+):
+    """Manually retry a failed task."""
+    import asyncio
+
+    async def run():
+        q = await _get_queue()
+        result = await q.retry(task_id)
+        if result is None:
+            if json_mode or terminal.is_json_mode():
+                terminal.json_output(
+                    {"error": f"task {task_id} not found or not failed"}
+                )
+                return
+            terminal.wordmark()
+            terminal.blank()
+            terminal.muted(f"task {task_id} not found or not failed")
+            return
+        if json_mode or terminal.is_json_mode():
+            terminal.json_output(result.describe())
+            return
+        terminal.wordmark()
+        terminal.blank()
+        terminal.status_block(
+            [("task", str(result.id)), ("status", result.status.value)]
+        )
+        terminal.blank()
+
+    asyncio.run(run())

{voodoo_framework-1.2.0 → voodoo_framework-1.4.0}/src/voodoo/cli/terminal.py

@@ -151,7 +151,9 @@ def json_output(data: Any) -> None:
     """
     import json
 
-    console.print(json.dumps(data, indent=2, default=str), highlight=False, soft_wrap=True)
+    console.print(
+        json.dumps(data, indent=2, default=str), highlight=False, soft_wrap=True
+    )
 
 
 def is_json_mode() -> bool:

{voodoo_framework-1.2.0 → voodoo_framework-1.4.0}/src/voodoo/data/__init__.py

@@ -6,10 +6,13 @@ This package re-exports the names that previously lived in the flat
 
 Storage backend boundary
 -------------------------
-The default backend is SQLite (via :mod:`aiosqlite`).  The functions
-``init_db`` and ``get_db`` together with the module-level ``_db_connection``
-form the seam a future PostgreSQL adapter would replace; everything above
-them (``BaseModel``, ``Model`` and the hooks) is backend-agnostic.
+The default backend is SQLite (via :mod:`aiosqlite`) managed by the
+``VoodooDatabase`` adapter in :mod:`voodoo.storage.database` — it owns
+connection lifecycle, WAL pragmas and the ``schema_migrations`` ledger.
+``init_db`` publishes the raw aiosqlite connection as
+``_db_connection`` / ``get_db()``; everything above it (``BaseModel``,
+``Model`` and the hooks) is backend-agnostic.  A future PostgreSQL
+adapter replaces the adapter, not this package.
 """
 
 from voodoo.data.base import (

{voodoo_framework-1.2.0 → voodoo_framework-1.4.0}/src/voodoo/data/base.py

@@ -1,30 +1,54 @@
 import asyncio
-import os
 from collections.abc import Callable
 from typing import Any, get_type_hints
 
-import aiosqlite
+from voodoo.storage.database import Migration, SQLiteDatabase, VoodooDatabase
 
 _db_connection = None
+_database: SQLiteDatabase | None = None
 _triggers: dict[str, dict[str, list[Callable]]] = {}
 _rls_policies: dict[str, Callable] = {}
 
 
+async def _ensure_user_tables(db: VoodooDatabase) -> None:
+    """Create tables for every registered user model (idempotent DDL)."""
+    for model in _models:
+        await model._create_table()
+
+
+# Migration 0001: the user-model baseline. Runs once to enter the ledger,
+# then re-runs its idempotent DDL on every ``init_db`` so models imported
+# after the baseline still get their tables (preserves pre-migration
+# behavior exactly).
+USER_MODEL_BASELINE = Migration(
+    version=1,
+    name="user_model_baseline",
+    fn=_ensure_user_tables,
+    rerun=True,
+)
+
+
 async def init_db(db_path: str = None):
+    """Open (and migrate) the SQLite database backing the data layer.
+
+    The raw :class:`aiosqlite.Connection` remains the value of
+    ``_db_connection`` / ``get_db()`` so all existing callers keep working;
+    schema management now flows through the ``SQLiteDatabase`` adapter and
+    its migration ledger.
+    """
     if db_path is None:
         from voodoo.config import config
 
         db_path = config.db_path
 
-    db_dir = os.path.dirname(db_path)
-    if db_dir:
-        os.makedirs(db_dir, exist_ok=True)
-
-    global _db_connection
-    _db_connection = await aiosqlite.connect(db_path)
-    _db_connection.row_factory = aiosqlite.Row
-    for model in _models:
-        await model._create_table()
+    global _db_connection, _database
+    database = SQLiteDatabase(db_path, migrations=(USER_MODEL_BASELINE,))
+    await database.connect()
+    _db_connection = database.connection
+    _database = database
+    # Migrate after the connection is published so rerunnable migration
+    # functions can use ``get_db()``.
+    await database.migrate()
 
 
 async def get_db():
@@ -40,12 +64,13 @@ async def close_db():
     unclosed connection would keep the interpreter alive at shutdown.
     No-op when no connection is open (keeps startup lazy).
     """
-    global _db_connection
+    global _db_connection, _database
     if _db_connection is not None:
         try:
             await _db_connection.close()
         finally:
             _db_connection = None
+            _database = None
 
 
 def _get_table_name(cls_or_obj: Any) -> str:

{voodoo_framework-1.2.0 → voodoo_framework-1.4.0}/src/voodoo/data/model.py

@@ -8,13 +8,11 @@ storage layer and the ``on_insert`` / ``on_update`` hook system from
 Storage backend boundary
 -------------------------
 Everything in this module talks to the database through ``get_db()``
-and builds portable ANSI-SQL strings.  Swapping SQLite for PostgreSQL
-(or another backend) only requires replacing the connection function
-and the DDL generated by ``BaseModel._create_table``; the facade stays
-the same.  Migrations are an explicit extension point: today the only
-DDL emitted is ``CREATE TABLE IF NOT EXISTS`` (create-if-absent).  A
-future migration runner can hook into ``init_db`` without changing any
-call-site here.
+and builds portable ANSI-SQL strings.  Schema management flows through
+the ``VoodooDatabase`` adapter in :mod:`voodoo.storage.database`
+(SQLite default); the user-model DDL is migration 0001 in its ledger.
+Swapping backends means providing another adapter — no call-site here
+changes.
 """
 
 from typing import Any, get_type_hints

voodoo_framework-1.4.0/src/voodoo/queue.py

@@ -0,0 +1,12 @@
+"""Compatibility alias — the durable queue lives in ``voodoo.workers.queue``.
+
+This shim replaces itself with the real module in ``sys.modules`` so that
+``voodoo.queue is voodoo.workers.queue`` and mutable globals (``_workers``,
+``_worker_tasks``) are always current.
+"""
+
+import sys
+
+from voodoo.workers import queue  # noqa: F401
+
+sys.modules[__name__] = queue

voodoo_framework-1.4.0/src/voodoo/storage/__init__.py

@@ -0,0 +1,15 @@
+"""Voodoo storage package.
+
+Two concerns live here:
+
+- ``voodoo.storage.manager`` — the legacy ``StorageManager`` facade over
+  local-filesystem / S3-compatible uploads (import-compatible re-export of
+  the former flat ``voodoo/storage.py`` module).
+- ``voodoo.storage.database`` — the ``VoodooDatabase`` capability adapters
+  (SQLite default, PostgreSQL later) that own all durable schema through
+  the migration runner.
+"""
+
+from voodoo.storage.manager import StorageManager, storage
+
+__all__ = ["StorageManager", "storage"]

voodoo_framework-1.4.0/src/voodoo/storage/database/__init__.py

@@ -0,0 +1,29 @@
+"""Voodoo database adapters (spec §11).
+
+SQLite is the embedded default; PostgreSQL arrives behind the same
+``VoodooDatabase`` protocol as an optional extra. Migrations form one global
+version namespace: 1 = user-model baseline (registered by ``voodoo.data``),
+2+ reserved by the framework, 100+ available to applications.
+"""
+
+from voodoo.storage.database.interfaces import (
+    DatabaseCapabilities,
+    Migration,
+    VoodooDatabase,
+)
+from voodoo.storage.database.sqlite import (
+    FRAMEWORK_MIGRATIONS,
+    LEDGER_TABLE,
+    SQLiteDatabase,
+    register_framework_migration,
+)
+
+__all__ = [
+    "DatabaseCapabilities",
+    "FRAMEWORK_MIGRATIONS",
+    "LEDGER_TABLE",
+    "Migration",
+    "SQLiteDatabase",
+    "VoodooDatabase",
+    "register_framework_migration",
+]