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

{voodoo_framework-2.2.0 → voodoo_framework-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 2.2.0
+Version: 2.4.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>
@@ -59,6 +59,10 @@ 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: 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
 
 <picture>

{voodoo_framework-2.2.0 → voodoo_framework-2.4.0}/pyproject.toml

@@ -93,6 +93,11 @@ s3 = [
 redis = [
     "redis>=5.0",
 ]
+otel = [
+    "opentelemetry-api>=1.20",
+    "opentelemetry-sdk>=1.20",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.20",
+]
 
 [tool.setuptools.dynamic]
 version = { attr = "voodoo.__version__" }

{voodoo_framework-2.2.0 → voodoo_framework-2.4.0}/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.2.0"
+__version__ = "2.4.0"
 
 __all__ = [
     # Core runtime

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

@@ -10,12 +10,15 @@ from voodoo.cli import (
     generate,
     new,
     objects,
+    protocol,
     recover,
     routes,
     schedules,
+    status,
     tasks,
     theme,
     version,
+    workers_cmd,
 )
 from voodoo.cli.auth import auth_app
 from voodoo.cli.inspect import inspect_app
@@ -41,10 +44,13 @@ app.add_typer(objects.objects_app, name="objects")
 app.add_typer(agents.agents_app, name="agents")
 app.add_typer(approvals.approvals_app, name="approvals")
 app.add_typer(theme.theme_app, name="theme")
+app.add_typer(protocol.protocol_app, name="protocol")
 # Top-level aliases per the Sprint 3 CLI surface: `voodoo execution <id>`
 # (timeline from the journal) and `voodoo events` (recent journal events).
 app.command("execution")(executions.show_execution)
 app.command("events")(executions.list_events)
+app.command()(status.status)
+app.command()(workers_cmd.workers)
 app.command()(version.version)
 app.command()(doctor.doctor)
 app.command()(routes.routes)

{voodoo_framework-2.2.0 → voodoo_framework-2.4.0}/src/voodoo/cli/doctor.py

@@ -217,6 +217,54 @@ def doctor():  # noqa: C901
     except Exception:  # noqa: BLE001 - diagnostics must never crash doctor
         terminal.status("capability matrix", "unavailable")
 
+    # ── Queue depth ─────────────────────────────────
+    terminal.heading("queue")
+    try:
+        import asyncio
+
+        async def _check_queue() -> tuple[int, int]:
+            from voodoo.workers.queue import _get_queue, _workers
+
+            depth = 0
+            try:
+                q = await _get_queue()
+                if hasattr(q, "list"):
+                    tasks = await q.list()
+                    depth = len(tasks)
+                elif hasattr(q, "depth"):
+                    depth = await q.depth()
+            except Exception:
+                pass
+            return depth, len(_workers)
+
+        depth, n_workers = asyncio.run(_check_queue())
+        terminal.status("depth", str(depth))
+        terminal.status("registered workers", str(n_workers))
+    except Exception:  # noqa: BLE001
+        terminal.status("queue", "unavailable")
+
+    # ── Schedules ───────────────────────────────────
+    terminal.heading("schedules")
+    try:
+        from pathlib import Path as _Path
+
+        sched_db = _Path(cfg.db_path).parent / "schedules.db"
+        if sched_db.exists():
+            terminal.status("scheduler db", "present")
+        else:
+            terminal.status("scheduler db", "not found")
+    except Exception:  # noqa: BLE001
+        terminal.status("schedules", "unavailable")
+
+    # ── OTLP ────────────────────────────────────────
+    terminal.heading("otel")
+    try:
+        from voodoo.telemetry.otlp import is_available
+
+        terminal.status("otlp exporter", "active" if is_available() else "off")
+    except Exception:  # noqa: BLE001
+        terminal.status("otlp exporter", "off")
+
     # ── AI Kit ──────────────────────────────────────
     terminal.heading("ai kit")
 

voodoo_framework-2.4.0/src/voodoo/cli/protocol.py

@@ -0,0 +1,68 @@
+"""CLI: ``voodoo protocol export`` — export JSON Schema for protocol entities."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from voodoo.protocol import export_json_schemas, schema_for
+
+__all__ = ["protocol_app"]
+
+protocol_app = typer.Typer(
+    name="protocol",
+    help="Protocol schema operations.",
+    no_args_is_help=True,
+)
+
+
+@protocol_app.command("export")
+def export_schemas(
+    output: str = typer.Option(
+        "",
+        "--output",
+        "-o",
+        help="Output file path (default: stdout).",
+    ),
+    entity: str = typer.Option(
+        "",
+        "--entity",
+        "-e",
+        help="Export a single entity by name (e.g. 'Execution').",
+    ),
+    indent: int = typer.Option(2, "--indent", help="JSON indentation."),
+) -> None:
+    """Export JSON Schema for all Voodoo protocol entities."""
+    if entity:
+        try:
+            schema = schema_for(entity)
+        except KeyError:
+            typer.echo(f"Unknown entity: {entity}", err=True)
+            typer.echo(f"Available: {', '.join(sorted(_entity_names()))}", err=True)
+            raise typer.Exit(1) from None
+        result = json.dumps(schema, indent=indent, default=str)
+    else:
+        schemas = export_json_schemas()
+        result = json.dumps(schemas, indent=indent, default=str)
+
+    if output:
+        Path(output).write_text(result + "\n")
+        count = 1 if entity else len(_entity_names())
+        typer.echo(f"Exported {count} schema(s) to {output}")
+    else:
+        typer.echo(result)
+
+
+@protocol_app.command("list")
+def list_entities() -> None:
+    """List all protocol entity names."""
+    for name in sorted(_entity_names()):
+        typer.echo(name)
+
+
+def _entity_names() -> list[str]:
+    from voodoo.protocol.schemas import PROTOCOL_ENTITIES
+
+    return list(PROTOCOL_ENTITIES.keys())

voodoo_framework-2.4.0/src/voodoo/cli/status.py

@@ -0,0 +1,73 @@
+"""``voodoo status`` — runtime health overview.
+
+Displays a quick snapshot of the runtime: request counts, error rate,
+latency, agent activity, queue depth, and OTel export status.
+Works after a restart because rolling counters are persisted to
+``.voodoo/telemetry_summary.json``.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+__all__ = ["status"]
+
+
+def status() -> None:
+    """Show runtime health overview."""
+    from voodoo.telemetry import telemetry_store
+    from voodoo.telemetry.otlp import is_available as otlp_available
+
+    summary = telemetry_store.get_summary()
+    console = Console()
+
+    # -- header --------------------------------------------------------
+    console.print("[bold cyan]Voodoo Runtime Status[/bold cyan]")
+    console.print()
+
+    # -- requests & errors ---------------------------------------------
+    tbl = Table(show_header=True, header_style="bold")
+    tbl.add_column("Metric", style="dim")
+    tbl.add_column("Value", justify="right")
+
+    total = summary.get("requests_total", 0)
+    errors = summary.get("errors_total", 0)
+    error_rate = f"{(errors / total * 100):.1f}%" if total else "—"
+    avg_lat = summary.get("average_latency_ms", 0.0)
+
+    tbl.add_row("Requests total", str(total))
+    tbl.add_row("Errors total", str(errors))
+    tbl.add_row("Error rate", error_rate)
+    tbl.add_row("Avg latency", f"{avg_lat:.1f} ms")
+    tbl.add_row("DB queries", str(summary.get("db_queries", 0)))
+    console.print(tbl)
+    console.print()
+
+    # -- agent activity ------------------------------------------------
+    agent_tbl = Table(show_header=True, header_style="bold")
+    agent_tbl.add_column("Agent Metric", style="dim")
+    agent_tbl.add_column("Value", justify="right")
+
+    agent_tbl.add_row("Agent runs", str(summary.get("agent_runs", 0)))
+    agent_tbl.add_row("Tokens in", str(summary.get("agent_tokens_in", 0)))
+    agent_tbl.add_row("Tokens out", str(summary.get("agent_tokens_out", 0)))
+    agent_tbl.add_row("Agent cost", f"${summary.get('agent_cost', 0.0):.6f}")
+    agent_tbl.add_row("Tool calls", str(summary.get("tool_calls_total", 0)))
+    agent_tbl.add_row("Tool errors", str(summary.get("tool_errors", 0)))
+    agent_tbl.add_row("Spans recorded", str(summary.get("spans_total", 0)))
+    console.print(agent_tbl)
+    console.print()
+
+    # -- infrastructure ------------------------------------------------
+    infra_tbl = Table(show_header=True, header_style="bold")
+    infra_tbl.add_column("Infrastructure", style="dim")
+    infra_tbl.add_column("Status")
+
+    infra_tbl.add_row("OTLP export", "active" if otlp_available() else "off")
+    console.print(infra_tbl)
+
+
+app = typer.Typer(name="status", help="Runtime health overview.", no_args_is_help=True)
+app.command()(status)

voodoo_framework-2.4.0/src/voodoo/cli/workers_cmd.py

@@ -0,0 +1,71 @@
+"""``voodoo workers`` — worker state & queue depth.
+
+Shows registered background workers, their queue depth, and whether
+the worker loop is running.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+__all__ = ["workers"]
+
+
+async def _gather_worker_info() -> dict[str, Any]:
+    """Collect worker and queue state without side-effects."""
+    from voodoo.workers.queue import _get_queue, _worker_tasks, _workers
+
+    info: dict[str, Any] = {
+        "registered": list(_workers.keys()),
+        "running_tasks": len([t for t in _worker_tasks if not t.done()]),
+        "queue_depth": 0,
+    }
+
+    try:
+        q = await _get_queue()
+        if hasattr(q, "list"):
+            tasks = await q.list()
+            info["queue_depth"] = len(tasks)
+        elif hasattr(q, "depth"):
+            info["queue_depth"] = await q.depth()
+    except Exception:
+        pass
+
+    return info
+
+
+def workers() -> None:
+    """Show registered workers and queue depth."""
+    console = Console()
+    info = asyncio.run(_gather_worker_info())
+
+    console.print("[bold cyan]Voodoo Workers[/bold cyan]")
+    console.print()
+
+    tbl = Table(show_header=True, header_style="bold")
+    tbl.add_column("Worker", style="dim")
+    tbl.add_column("Status")
+
+    registered = info["registered"]
+    if not registered:
+        console.print("[dim]No workers registered.[/dim]")
+    else:
+        running = info["running_tasks"]
+        for name in registered:
+            tbl.add_row(name, "running" if running > 0 else "idle")
+        console.print(tbl)
+
+    console.print()
+    console.print(f"Queue depth: [bold]{info['queue_depth']}[/bold]")
+    console.print(f"Running worker tasks: [bold]{info['running_tasks']}[/bold]")
+
+
+app = typer.Typer(
+    name="workers", help="Worker state & queue depth.", no_args_is_help=True
+)
+app.command()(workers)

voodoo_framework-2.4.0/src/voodoo/protocol/__init__.py

@@ -0,0 +1,97 @@
+"""Voodoo protocol — canonical entity schemas for cross-language interop.
+
+This package defines the **stable semantic boundary** for the Voodoo runtime.
+Every entity is a Pydantic model with a ``schema_version`` field and full
+JSON Schema export support.
+
+Quick start::
+
+    from voodoo.protocol import Execution, Intent, SCHEMA_VERSION
+
+    intent = Intent(name="summarize", params={"text": "hello"})
+    execution = Execution(
+        id="exec-001",
+        trace_id="trace-001",
+        intent=intent,
+    )
+
+    # Serialize to JSON
+    data = execution.model_dump(mode="json")
+
+    # Round-trip
+    restored = Execution.model_validate(data)
+
+    # Export JSON Schema
+    from voodoo.protocol import export_json_schemas
+    schemas = export_json_schemas()
+
+See ``docs/protocol.md`` for the compatibility policy.
+"""
+
+from __future__ import annotations
+
+from .export import export_json_schemas, export_json_schemas_json, schema_for
+from .schemas import (
+    PROTOCOL_ENTITIES,
+    SCHEMA_VERSION,
+    AgentEntity,
+    AgentRun,
+    Approval,
+    ApprovalStatus,
+    Capability,
+    ComputeKind,
+    ComputeSpec,
+    Constraint,
+    Effect,
+    EffectStatus,
+    Error,
+    Event,
+    Execution,
+    ExecutionStatus,
+    Identity,
+    Intent,
+    IntentStatus,
+    MemoryEntry,
+    ObjectRef,
+    Resource,
+    Task,
+    TaskStatus,
+    TelemetrySpan,
+    TimeSpec,
+)
+
+__all__ = [
+    # Schema metadata
+    "SCHEMA_VERSION",
+    "PROTOCOL_ENTITIES",
+    # Enums
+    "ExecutionStatus",
+    "IntentStatus",
+    "EffectStatus",
+    "TaskStatus",
+    "ApprovalStatus",
+    "ComputeKind",
+    # Core entities
+    "Identity",
+    "Capability",
+    "Constraint",
+    "Resource",
+    "TimeSpec",
+    "ComputeSpec",
+    "Intent",
+    "Effect",
+    "Execution",
+    "Task",
+    "Event",
+    "ObjectRef",
+    "Error",
+    "TelemetrySpan",
+    "Approval",
+    "AgentEntity",
+    "AgentRun",
+    "MemoryEntry",
+    # Export
+    "export_json_schemas",
+    "export_json_schemas_json",
+    "schema_for",
+]

voodoo_framework-2.4.0/src/voodoo/protocol/export.py

@@ -0,0 +1,75 @@
+"""JSON Schema export for Voodoo protocol entities.
+
+Usage::
+
+    from voodoo.protocol import export_json_schemas
+
+    # Export all schemas as a dict
+    schemas = export_json_schemas()
+
+    # Write to a file
+    import json
+    with open("voodoo-protocol.json", "w") as f:
+        json.dump(schemas, f, indent=2)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .schemas import PROTOCOL_ENTITIES, SCHEMA_VERSION
+
+__all__ = [
+    "export_json_schemas",
+    "export_json_schemas_json",
+    "schema_for",
+]
+
+
+def export_json_schemas() -> dict[str, Any]:
+    """Export JSON Schema for all protocol entities.
+
+    Returns a dict keyed by entity name, where each value is the
+    JSON Schema for that entity (draft 2020-12).
+    """
+    schemas: dict[str, Any] = {}
+    for name, model in PROTOCOL_ENTITIES.items():
+        schema = model.model_json_schema()
+        # Add protocol-level metadata
+        schema["$schema"] = "https://json-schema.org/draft/2020-12/schema"
+        schema["$id"] = f"urn:voodoo:protocol:{name.lower()}:{SCHEMA_VERSION}"
+        schema["x-voodoo-schema-version"] = SCHEMA_VERSION
+        schemas[name] = schema
+    return schemas
+
+
+def export_json_schemas_json(indent: int = 2) -> str:
+    """Export all protocol schemas as a JSON string."""
+    return json.dumps(export_json_schemas(), indent=indent, default=str)
+
+
+def schema_for(entity_name: str) -> dict[str, Any]:
+    """Get JSON Schema for a single protocol entity by name.
+
+    Parameters
+    ----------
+    entity_name:
+        The entity name (e.g. "Execution", "Intent").
+
+    Returns
+    -------
+    dict:
+        The JSON Schema for the entity.
+
+    Raises
+    ------
+    KeyError:
+        If the entity name is not a known protocol entity.
+    """
+    model = PROTOCOL_ENTITIES[entity_name]
+    schema = model.model_json_schema()
+    schema["$schema"] = "https://json-schema.org/draft/2020-12/schema"
+    schema["$id"] = f"urn:voodoo:protocol:{entity_name.lower()}:{SCHEMA_VERSION}"
+    schema["x-voodoo-schema-version"] = SCHEMA_VERSION
+    return schema