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

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

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

{voodoo_framework-2.3.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.3.0"
+__version__ = "2.4.0"
 
 __all__ = [
     # Core runtime

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

@@ -10,6 +10,7 @@ from voodoo.cli import (
     generate,
     new,
     objects,
+    protocol,
     recover,
     routes,
     schedules,
@@ -43,6 +44,7 @@ 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)

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/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