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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 2.2.0
+Version: 2.3.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.3.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.3.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.3.0"
 
 __all__ = [
     # Core runtime

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

@@ -13,9 +13,11 @@ from voodoo.cli import (
     recover,
     routes,
     schedules,
+    status,
     tasks,
     theme,
     version,
+    workers_cmd,
 )
 from voodoo.cli.auth import auth_app
 from voodoo.cli.inspect import inspect_app
@@ -45,6 +47,8 @@ app.add_typer(theme.theme_app, name="theme")
 # (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.3.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.3.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.3.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.2.0 → voodoo_framework-2.3.0}/src/voodoo/telemetry/__init__.py

@@ -1,20 +1,24 @@
 from voodoo.telemetry.api import get_metrics
 from voodoo.telemetry.middleware import TelemetryMiddleware
 from voodoo.telemetry.store import (
+    Span,
     TelemetryStore,
     TraceFilter,
     logger,
+    new_trace_id,
     telemetry_store,
     trace,
     trace_id_var,
 )
 
 __all__ = [
+    "Span",
     "TelemetryMiddleware",
     "TelemetryStore",
     "TraceFilter",
     "get_metrics",
     "logger",
+    "new_trace_id",
     "telemetry_store",
     "trace",
     "trace_id_var",

voodoo_framework-2.3.0/src/voodoo/telemetry/otlp.py

@@ -0,0 +1,108 @@
+"""Optional OpenTelemetry OTLP exporter.
+
+Activated only when the ``[otel]`` extra is installed **and**
+``VOODOO_OTEL_EXPORTER`` is set (any non-empty value).  When
+active, completed :class:`Span` objects are forwarded to the
+configured OTLP endpoint (default ``http://localhost:4317``).
+
+Usage::
+
+    pip install voodoo-framework[otel]
+    export VOODOO_OTEL_EXPORTER=1
+    # optional: export OTEL_EXPORTER_OTLP_ENDPOINT=http://my-collector:4317
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+logger = logging.getLogger("voodoo.telemetry.otlp")
+
+__all__ = ["OTLPExporter", "is_available", "export_span"]
+
+#: Cached exporter instance (lazy-initialised).
+_exporter: OTLPExporter | None = None
+_checked: bool = False
+
+
+def is_available() -> bool:
+    """Return ``True`` if OTel SDK is importable and the env var is set."""
+    try:
+        import opentelemetry  # noqa: F401
+    except ImportError:
+        return False
+    return bool(os.environ.get("VOODOO_OTEL_EXPORTER"))
+
+
+class OTLPExporter:
+    """Thin wrapper around the OTel SDK's OTLP gRPC exporter.
+
+    Each call to :meth:`export_span` builds an OTel ``Span`` from our
+    :class:`voodoo.telemetry.store.Span` and forwards it via the
+    configured ``TracerProvider``.
+    """
+
+    def __init__(self) -> None:
+        from opentelemetry import trace as otel_trace
+        from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+            OTLPSpanExporter,
+        )
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+        endpoint = os.environ.get(
+            "OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317"
+        )
+        provider = TracerProvider()
+        processor = BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint))
+        provider.add_span_processor(processor)
+        otel_trace.set_tracer_provider(provider)
+        self._tracer = otel_trace.get_tracer("voodoo")
+        logger.info("OTLP exporter initialised → %s", endpoint)
+
+    def export_span(self, span: Any) -> None:
+        """Convert a voodoo :class:`Span` to an OTel span and export it."""
+        from opentelemetry import trace as otel_trace
+        from opentelemetry.trace import StatusCode
+
+        with self._tracer.start_as_current_span(
+            span.name,
+            kind=otel_trace.SpanKind.INTERNAL,
+            attributes=dict(span.attributes) if span.attributes else {},
+        ) as otel_span:
+            if span.status == "error":
+                otel_span.set_status(StatusCode.ERROR)
+            else:
+                otel_span.set_status(StatusCode.OK)
+            if span.end_time and span.start_time:
+                otel_span.set_attribute(
+                    "duration_ms",
+                    (span.end_time - span.start_time).total_seconds() * 1000,
+                )
+
+
+def _get_exporter() -> OTLPExporter | None:
+    """Return the singleton exporter, or ``None`` if unavailable."""
+    global _exporter, _checked
+    if _checked:
+        return _exporter
+    _checked = True
+    if is_available():
+        try:
+            _exporter = OTLPExporter()
+        except Exception:  # noqa: BLE001 — graceful degradation
+            logger.warning("Failed to initialise OTLP exporter", exc_info=True)
+            _exporter = None
+    return _exporter
+
+
+def export_span(span: Any) -> None:
+    """Forward *span* to the OTLP endpoint if the exporter is active."""
+    exporter = _get_exporter()
+    if exporter is not None:
+        try:
+            exporter.export_span(span)
+        except Exception:  # noqa: BLE001 — never break the runtime
+            logger.debug("OTLP export failed for span %s", span.span_id, exc_info=True)