voodoo-framework 1.19.0__tar.gz → 2.0.0__tar.gz

{voodoo_framework-1.19.0 → voodoo_framework-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 1.19.0
+Version: 2.0.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-1.19.0 → voodoo_framework-2.0.0}/src/voodoo/__init__.py

@@ -20,12 +20,14 @@ import warnings
 from typing import Any
 
 from .adapters import TailwindAdapter, VoodooCSSAdapter
+from .agents import AgentEntity, AgentRegistry, AgentRunRecord, SQLiteAgentRegistry
 from .ai import LLMProvider, ModelDescriptor, VoodooModelProvider
 from .ai.agent import Agent, AgentRun
 from .ai.tools import ToolRegistry, ToolSpec, tool
 from .config import config
 from .core import App, create_app, event, page, register_event, state, ws_manager
 from .data import FK, BaseModel, Model
+from .memory import MemoryEntry, MemoryLayer, MemoryStore, SQLiteMemoryStore
 from .mesh import mesh
 from .routing.api import api
 from .telemetry import trace
@@ -59,6 +61,7 @@ from .ui import (
     Header,
     Heading,
     Hero,
+    Html,
     Icon,
     Input,
     Label,
@@ -99,7 +102,7 @@ from .ui.styles import (
 from .ui.styles.theme import Theme, ThemeColors, create_theme
 from .workers import task
 
-__version__ = "1.19.0"
+__version__ = "2.0.0"
 
 __all__ = [
     # Core runtime
@@ -127,6 +130,16 @@ __all__ = [
     "LLMProvider",
     "VoodooModelProvider",
     "ModelDescriptor",
+    # Memory (Sprint 16)
+    "MemoryEntry",
+    "MemoryLayer",
+    "MemoryStore",
+    "SQLiteMemoryStore",
+    # Agent registry (Sprint 17)
+    "AgentEntity",
+    "AgentRegistry",
+    "AgentRunRecord",
+    "SQLiteAgentRegistry",
     # Data
     "BaseModel",
     "Model",
@@ -167,6 +180,7 @@ __all__ = [
     # UI — icons & markdown
     "Icon",
     "Markdown",
+    "Html",
     # UI — chat primitives
     "MessageList",
     "ChatMessage",

{voodoo_framework-1.19.0 → voodoo_framework-2.0.0}/src/voodoo/adapters/voodoo_css.py

@@ -486,6 +486,54 @@ button, input, select, textarea {{ font: inherit; color: inherit; }}
     color: var(--vd-color-text-muted); padding: 0 {s}xs);
 }}
 
+/* App shell — full-viewport sidebar + main layout (chat apps) */
+.vd-app-shell {{
+    display: flex; align-items: stretch;
+    width: 100%; height: 100dvh; overflow: hidden;
+}}
+.vd-app-shell > .vd-sidebar {{
+    height: 100dvh; border-right: 1px solid var(--vd-color-border);
+}}
+.vd-chat-main {{
+    flex: 1; min-width: 0; display: flex; flex-direction: column;
+    height: 100dvh; overflow: hidden;
+    padding: {s}lg); gap: {s}md);
+}}
+.vd-chat-scroll {{
+    flex: 1; min-height: 0; overflow-y: auto;
+    display: flex; flex-direction: column;
+    border: 1px solid var(--vd-color-border);
+    border-radius: {r}lg); background: var(--vd-color-surface);
+    padding: {s}md);
+}}
+.vd-chat-row {{
+    width: 100%; align-items: center;
+}}
+.vd-chat-row > .vd-button:first-child {{
+    flex: 1; justify-content: flex-start; text-align: left;
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    background: transparent; color: var(--vd-color-text);
+    border: none; font-weight: var(--vd-weight-normal);
+}}
+.vd-chat-row > .vd-button:first-child:hover {{
+    background: var(--vd-color-surface); color: var(--vd-color-primary);
+}}
+.vd-chat-row > .vd-button:last-child {{
+    flex-shrink: 0; background: transparent; border: none;
+    color: var(--vd-color-text-muted); padding: {s}xs);
+}}
+.vd-chat-row > .vd-button:last-child:hover {{ color: var(--vd-color-danger); }}
+.vd-suggestions {{
+    display: flex; flex-wrap: wrap; gap: {s}sm);
+}}
+.vd-suggestions > .vd-button {{
+    background: var(--vd-color-surface); border: 1px solid var(--vd-color-border);
+    color: var(--vd-color-text); font-weight: var(--vd-weight-normal);
+}}
+.vd-suggestions > .vd-button:hover {{
+    border-color: var(--vd-color-primary); color: var(--vd-color-primary);
+}}
+
 /* Markdown rendered inside components */
 .vd-markdown p {{ margin: 0 0 {s}sm); }}
 .vd-markdown p:last-child {{ margin-bottom: 0; }}

voodoo_framework-2.0.0/src/voodoo/agents/__init__.py

@@ -0,0 +1,33 @@
+"""Agents — durable entity registry (Sprint 17).
+
+Agents are compute participants with stable identity, capabilities, state,
+and queryable execution history. The registry persists agent metadata and
+links every run to its execution record.
+
+    from voodoo import AgentEntity, AgentRegistry, SQLiteAgentRegistry
+
+    registry = SQLiteAgentRegistry("data/agents.db")
+    entity = AgentEntity(
+        agent_id="lead-scorer",
+        name="Lead Scorer",
+        model="openai:gpt-4o",
+        capabilities=["scoring.read"],
+    )
+    await registry.register(entity)
+    agent = Agent(model="openai:gpt-4o", agent_id="lead-scorer", registry=registry)
+"""
+
+from voodoo.agents.models import AgentEntity, AgentRunRecord
+from voodoo.agents.registry import (
+    AgentRegistry,
+    InMemoryAgentRegistry,
+    SQLiteAgentRegistry,
+)
+
+__all__ = [
+    "AgentEntity",
+    "AgentRegistry",
+    "AgentRunRecord",
+    "InMemoryAgentRegistry",
+    "SQLiteAgentRegistry",
+]

voodoo_framework-2.0.0/src/voodoo/agents/models.py

@@ -0,0 +1,166 @@
+"""Agent entity and run-record data models (Sprint 17).
+
+``AgentEntity`` is the durable identity of an agent — name, model policy,
+tools, capabilities, permissions, configuration, and current state.
+``AgentRunRecord`` links a single agent run to its execution record.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["AgentEntity", "AgentRunRecord"]
+
+
+@dataclass
+class AgentEntity:
+    """Durable agent identity.
+
+    Parameters
+    ----------
+    agent_id:
+        Unique identifier. Auto-generated UUID if not provided.
+    name:
+        Human-readable display name.
+    description:
+        What this agent does.
+    model:
+        ``"provider:model"`` string (e.g. ``"openai:gpt-4o"``).
+    system_prompt:
+        Default system prompt for all runs.
+    capabilities:
+        Capability names granted to this agent.
+    tools:
+        Tool names available to this agent.
+    permissions:
+        Permission strings required for sensitive tools.
+    config:
+        Arbitrary configuration dict (temperature, max_tokens, etc.).
+    state:
+        Current lifecycle state (``"active"``, ``"paused"``, ``"archived"``).
+    metadata:
+        Arbitrary key-value metadata.
+    created_at:
+        ISO timestamp of creation.
+    updated_at:
+        ISO timestamp of last update.
+    """
+
+    agent_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    name: str = ""
+    description: str = ""
+    model: str = ""
+    system_prompt: str | None = None
+    capabilities: list[str] = field(default_factory=list)
+    tools: list[str] = field(default_factory=list)
+    permissions: list[str] = field(default_factory=list)
+    config: dict[str, Any] = field(default_factory=dict)
+    state: str = "active"
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: str = field(default_factory=lambda: _iso_now())
+    updated_at: str = field(default_factory=lambda: _iso_now())
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a plain dict (JSON-safe)."""
+        return {
+            "agent_id": self.agent_id,
+            "name": self.name,
+            "description": self.description,
+            "model": self.model,
+            "system_prompt": self.system_prompt,
+            "capabilities": self.capabilities,
+            "tools": self.tools,
+            "permissions": self.permissions,
+            "config": self.config,
+            "state": self.state,
+            "metadata": self.metadata,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AgentEntity:
+        """Deserialize from a plain dict."""
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class AgentRunRecord:
+    """Links an agent run to its execution.
+
+    Parameters
+    ----------
+    run_id:
+        Unique run identifier (matches ``AgentRun.run_id``).
+    agent_id:
+        The agent that performed the run.
+    execution_id:
+        The execution record ID (from the execution store).
+    prompt:
+        The input prompt.
+    output:
+        The final output.
+    status:
+        Run outcome (``"completed"``, ``"error"``, ``"failed"``).
+    tokens_in:
+        Input token count.
+    tokens_out:
+        Output token count.
+    cost:
+        Estimated cost in USD.
+    tool_calls:
+        Tool call history for this run.
+    started_at:
+        Unix timestamp when the run started.
+    completed_at:
+        Unix timestamp when the run completed.
+    trace_id:
+        Correlation ID from telemetry.
+    """
+
+    run_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    agent_id: str = ""
+    execution_id: str | None = None
+    prompt: str = ""
+    output: str = ""
+    status: str = "completed"
+    tokens_in: int = 0
+    tokens_out: int = 0
+    cost: float = 0.0
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    started_at: float = field(default_factory=time.time)
+    completed_at: float | None = None
+    trace_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a plain dict (JSON-safe)."""
+        return {
+            "run_id": self.run_id,
+            "agent_id": self.agent_id,
+            "execution_id": self.execution_id,
+            "prompt": self.prompt[:500],
+            "output": self.output[:500],
+            "status": self.status,
+            "tokens_in": self.tokens_in,
+            "tokens_out": self.tokens_out,
+            "cost": self.cost,
+            "tool_calls": self.tool_calls,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+            "trace_id": self.trace_id,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AgentRunRecord:
+        """Deserialize from a plain dict."""
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+def _iso_now() -> str:
+    """Return an ISO-8601 timestamp (UTC, second precision)."""
+    from datetime import UTC, datetime
+
+    return datetime.now(UTC).isoformat(timespec="seconds")

voodoo_framework-2.0.0/src/voodoo/agents/registry.py

@@ -0,0 +1,384 @@
+"""Agent registry — Protocol, in-memory, and SQLite implementations (Sprint 17).
+
+The registry persists agent identity and links every run to its execution
+history. The default backend is SQLite (WAL mode, busy_timeout=5000).
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any, Protocol
+
+from voodoo.agents.models import AgentEntity, AgentRunRecord
+
+__all__ = [
+    "AgentRegistry",
+    "InMemoryAgentRegistry",
+    "SQLiteAgentRegistry",
+]
+
+
+# ---------------------------------------------------------------------------
+# Protocol
+# ---------------------------------------------------------------------------
+
+
+class AgentRegistry(Protocol):
+    """Persistence contract for agent registries."""
+
+    async def register(self, entity: AgentEntity) -> None:
+        """Register or update an agent entity."""
+        ...
+
+    async def get(self, agent_id: str) -> AgentEntity | None:
+        """Fetch an agent by ID. Returns ``None`` if not found."""
+        ...
+
+    async def list_agents(
+        self,
+        state: str | None = None,
+        limit: int = 100,
+    ) -> list[AgentEntity]:
+        """List registered agents, optionally filtered by state."""
+        ...
+
+    async def update(self, entity: AgentEntity) -> None:
+        """Update an existing agent entity."""
+        ...
+
+    async def delete(self, agent_id: str) -> bool:
+        """Delete an agent. Returns ``True`` if deleted."""
+        ...
+
+    async def record_run(self, record: AgentRunRecord) -> None:
+        """Persist a run record linked to this agent."""
+        ...
+
+    async def get_runs(
+        self,
+        agent_id: str,
+        limit: int = 50,
+    ) -> list[AgentRunRecord]:
+        """List run history for an agent, newest first."""
+        ...
+
+    async def count_agents(self, state: str | None = None) -> int:
+        """Count registered agents."""
+        ...
+
+    async def count_runs(self, agent_id: str) -> int:
+        """Count runs for an agent."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# In-memory implementation
+# ---------------------------------------------------------------------------
+
+
+class InMemoryAgentRegistry:
+    """Non-durable registry for tests."""
+
+    def __init__(self) -> None:
+        self._agents: dict[str, AgentEntity] = {}
+        self._runs: dict[str, list[AgentRunRecord]] = {}
+
+    async def register(self, entity: AgentEntity) -> None:
+        self._agents[entity.agent_id] = entity
+
+    async def get(self, agent_id: str) -> AgentEntity | None:
+        return self._agents.get(agent_id)
+
+    async def list_agents(
+        self,
+        state: str | None = None,
+        limit: int = 100,
+    ) -> list[AgentEntity]:
+        agents = list(self._agents.values())
+        if state:
+            agents = [a for a in agents if a.state == state]
+        return agents[:limit]
+
+    async def update(self, entity: AgentEntity) -> None:
+        if entity.agent_id not in self._agents:
+            raise KeyError(f"Agent '{entity.agent_id}' not found")
+        self._agents[entity.agent_id] = entity
+
+    async def delete(self, agent_id: str) -> bool:
+        if agent_id in self._agents:
+            del self._agents[agent_id]
+            self._runs.pop(agent_id, None)
+            return True
+        return False
+
+    async def record_run(self, record: AgentRunRecord) -> None:
+        self._runs.setdefault(record.agent_id, []).append(record)
+
+    async def get_runs(
+        self,
+        agent_id: str,
+        limit: int = 50,
+    ) -> list[AgentRunRecord]:
+        runs = self._runs.get(agent_id, [])
+        return list(reversed(runs[-limit:]))
+
+    async def count_agents(self, state: str | None = None) -> int:
+        if state:
+            return sum(1 for a in self._agents.values() if a.state == state)
+        return len(self._agents)
+
+    async def count_runs(self, agent_id: str) -> int:
+        return len(self._runs.get(agent_id, []))
+
+
+# ---------------------------------------------------------------------------
+# SQLite implementation
+# ---------------------------------------------------------------------------
+
+_SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS agents (
+    agent_id   TEXT PRIMARY KEY,
+    name       TEXT NOT NULL DEFAULT '',
+    description TEXT NOT NULL DEFAULT '',
+    model      TEXT NOT NULL DEFAULT '',
+    system_prompt TEXT,
+    capabilities TEXT NOT NULL DEFAULT '[]',
+    tools      TEXT NOT NULL DEFAULT '[]',
+    permissions TEXT NOT NULL DEFAULT '[]',
+    config     TEXT NOT NULL DEFAULT '{}',
+    state      TEXT NOT NULL DEFAULT 'active',
+    metadata   TEXT NOT NULL DEFAULT '{}',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS agent_runs (
+    run_id       TEXT PRIMARY KEY,
+    agent_id     TEXT NOT NULL,
+    execution_id TEXT,
+    prompt       TEXT NOT NULL DEFAULT '',
+    output       TEXT NOT NULL DEFAULT '',
+    status       TEXT NOT NULL DEFAULT 'completed',
+    tokens_in    INTEGER NOT NULL DEFAULT 0,
+    tokens_out   INTEGER NOT NULL DEFAULT 0,
+    cost         REAL NOT NULL DEFAULT 0.0,
+    tool_calls   TEXT NOT NULL DEFAULT '[]',
+    started_at   REAL NOT NULL,
+    completed_at REAL,
+    trace_id     TEXT,
+    FOREIGN KEY (agent_id) REFERENCES agents(agent_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_runs_agent_id ON agent_runs(agent_id);
+"""
+
+
+class SQLiteAgentRegistry:
+    """Durable SQLite-backed agent registry.
+
+    Parameters
+    ----------
+    db_path:
+        Path to the SQLite database file. Created on first use.
+    """
+
+    def __init__(self, db_path: str = "data/agents.db") -> None:
+        self._db_path = db_path
+        Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(db_path)
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("PRAGMA busy_timeout=5000")
+        self._conn.executescript(_SCHEMA_SQL)
+        self._conn.commit()
+
+    def close(self) -> None:
+        """Close the database connection."""
+        self._conn.close()
+
+    # -- agents ------------------------------------------------------------
+
+    async def register(self, entity: AgentEntity) -> None:
+        """Insert or replace an agent entity."""
+        d = entity.to_dict()
+        self._conn.execute(
+            """
+            INSERT OR REPLACE INTO agents
+                (agent_id, name, description, model, system_prompt,
+                 capabilities, tools, permissions, config, state,
+                 metadata, created_at, updated_at)
+            VALUES
+                (:agent_id, :name, :description, :model, :system_prompt,
+                 :capabilities, :tools, :permissions, :config, :state,
+                 :metadata, :created_at, :updated_at)
+            """,
+            {
+                **d,
+                "capabilities": json.dumps(d["capabilities"]),
+                "tools": json.dumps(d["tools"]),
+                "permissions": json.dumps(d["permissions"]),
+                "config": json.dumps(d["config"]),
+                "metadata": json.dumps(d["metadata"]),
+            },
+        )
+        self._conn.commit()
+
+    async def get(self, agent_id: str) -> AgentEntity | None:
+        cur = self._conn.execute("SELECT * FROM agents WHERE agent_id = ?", (agent_id,))
+        row = cur.fetchone()
+        if row is None:
+            return None
+        return _row_to_entity(row, cur.description)
+
+    async def list_agents(
+        self,
+        state: str | None = None,
+        limit: int = 100,
+    ) -> list[AgentEntity]:
+        if state:
+            cur = self._conn.execute(
+                "SELECT * FROM agents WHERE state = ? ORDER BY created_at DESC LIMIT ?",
+                (state, limit),
+            )
+        else:
+            cur = self._conn.execute(
+                "SELECT * FROM agents ORDER BY created_at DESC LIMIT ?",
+                (limit,),
+            )
+        return [_row_to_entity(r, cur.description) for r in cur.fetchall()]
+
+    async def update(self, entity: AgentEntity) -> None:
+        entity.updated_at = _iso_now()
+        d = entity.to_dict()
+        cur = self._conn.execute(
+            "UPDATE agents SET name=:name, description=:description, "
+            "model=:model, system_prompt=:system_prompt, "
+            "capabilities=:capabilities, tools=:tools, permissions=:permissions, "
+            "config=:config, state=:state, metadata=:metadata, "
+            "updated_at=:updated_at WHERE agent_id=:agent_id",
+            {
+                **d,
+                "capabilities": json.dumps(d["capabilities"]),
+                "tools": json.dumps(d["tools"]),
+                "permissions": json.dumps(d["permissions"]),
+                "config": json.dumps(d["config"]),
+                "metadata": json.dumps(d["metadata"]),
+            },
+        )
+        if cur.rowcount == 0:
+            raise KeyError(f"Agent '{entity.agent_id}' not found")
+        self._conn.commit()
+
+    async def delete(self, agent_id: str) -> bool:
+        cur = self._conn.execute("DELETE FROM agents WHERE agent_id = ?", (agent_id,))
+        self._conn.commit()
+        return cur.rowcount > 0
+
+    # -- runs --------------------------------------------------------------
+
+    async def record_run(self, record: AgentRunRecord) -> None:
+        d = record.to_dict()
+        self._conn.execute(
+            """
+            INSERT OR REPLACE INTO agent_runs
+                (run_id, agent_id, execution_id, prompt, output, status,
+                 tokens_in, tokens_out, cost, tool_calls,
+                 started_at, completed_at, trace_id)
+            VALUES
+                (:run_id, :agent_id, :execution_id, :prompt, :output, :status,
+                 :tokens_in, :tokens_out, :cost, :tool_calls,
+                 :started_at, :completed_at, :trace_id)
+            """,
+            {**d, "tool_calls": json.dumps(d["tool_calls"])},
+        )
+        self._conn.commit()
+
+    async def get_runs(
+        self,
+        agent_id: str,
+        limit: int = 50,
+    ) -> list[AgentRunRecord]:
+        cur = self._conn.execute(
+            "SELECT * FROM agent_runs WHERE agent_id = ? "
+            "ORDER BY started_at DESC LIMIT ?",
+            (agent_id, limit),
+        )
+        return [_row_to_run(r, cur.description) for r in cur.fetchall()]
+
+    async def count_agents(self, state: str | None = None) -> int:
+        if state:
+            cur = self._conn.execute(
+                "SELECT COUNT(*) FROM agents WHERE state = ?", (state,)
+            )
+        else:
+            cur = self._conn.execute("SELECT COUNT(*) FROM agents")
+        return cur.fetchone()[0]
+
+    async def count_runs(self, agent_id: str) -> int:
+        cur = self._conn.execute(
+            "SELECT COUNT(*) FROM agent_runs WHERE agent_id = ?", (agent_id,)
+        )
+        return cur.fetchone()[0]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_AGENT_COLUMNS = [
+    "agent_id",
+    "name",
+    "description",
+    "model",
+    "system_prompt",
+    "capabilities",
+    "tools",
+    "permissions",
+    "config",
+    "state",
+    "metadata",
+    "created_at",
+    "updated_at",
+]
+
+_RUN_COLUMNS = [
+    "run_id",
+    "agent_id",
+    "execution_id",
+    "prompt",
+    "output",
+    "status",
+    "tokens_in",
+    "tokens_out",
+    "cost",
+    "tool_calls",
+    "started_at",
+    "completed_at",
+    "trace_id",
+]
+
+
+def _row_to_entity(row: Any, description: Any) -> AgentEntity:
+    """Convert a sqlite3 row to an AgentEntity."""
+    cols = [d[0] for d in description]
+    data = dict(zip(cols, row, strict=False))
+    for key in ("capabilities", "tools", "permissions", "config", "metadata"):
+        if isinstance(data.get(key), str):
+            data[key] = json.loads(data[key])
+    return AgentEntity.from_dict(data)
+
+
+def _row_to_run(row: Any, description: Any) -> AgentRunRecord:
+    """Convert a sqlite3 row to an AgentRunRecord."""
+    cols = [d[0] for d in description]
+    data = dict(zip(cols, row, strict=False))
+    if isinstance(data.get("tool_calls"), str):
+        data["tool_calls"] = json.loads(data["tool_calls"])
+    return AgentRunRecord.from_dict(data)
+
+
+def _iso_now() -> str:
+    from datetime import UTC, datetime
+
+    return datetime.now(UTC).isoformat(timespec="seconds")