soveren-agent-platform 0.2.0__py3-none-any.whl

soveren_agent_platform/__init__.py

@@ -0,0 +1,5 @@
+"""Reusable runtime primitives for durable agent applications."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

soveren_agent_platform/actions/__init__.py

@@ -0,0 +1,33 @@
+"""Action lifecycle runtime."""
+
+from soveren_agent_platform.actions.contracts import ActionExecutionResult, ActionExecutor, ActionRecord, ActionStore
+from soveren_agent_platform.actions.registry import ActionRegistry
+from soveren_agent_platform.actions.sqlite import SQLiteActionStore
+from soveren_agent_platform.actions.store import (
+    approve_action,
+    deny_action,
+    get_action,
+    insert_action,
+    mark_executed,
+    mark_failed,
+    mark_retryable,
+)
+from soveren_agent_platform.actions.worker import run_actions_queue_worker, run_actions_worker
+
+__all__ = [
+    "ActionExecutionResult",
+    "ActionExecutor",
+    "ActionRecord",
+    "ActionRegistry",
+    "ActionStore",
+    "SQLiteActionStore",
+    "approve_action",
+    "deny_action",
+    "get_action",
+    "insert_action",
+    "mark_executed",
+    "mark_failed",
+    "mark_retryable",
+    "run_actions_queue_worker",
+    "run_actions_worker",
+]

soveren_agent_platform/actions/contracts.py

@@ -0,0 +1,108 @@
+"""Contracts for action execution."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol
+
+ActionResultStatus = Literal["executed", "queued", "retryable_failure", "permanent_failure"]
+
+
+@dataclass(slots=True)
+class ActionRecord:
+    id: str
+    tenant_id: str
+    kind: str
+    payload: dict[str, Any]
+    status: str
+    approval_policy: str
+    run_id: str | None = None
+    source_id: str | None = None
+    source_event_id: str | None = None
+    idempotency_key: str | None = None
+    approved_by: str | None = None
+    last_error: str | None = None
+
+
+@dataclass(slots=True)
+class ActionExecutionResult:
+    result: dict[str, Any] = field(default_factory=dict)
+    status: ActionResultStatus = "executed"
+    error: str | None = None
+    retry_after_s: int | None = None
+
+    @classmethod
+    def executed(cls, result: dict[str, Any] | None = None) -> "ActionExecutionResult":
+        return cls(result=result or {}, status="executed")
+
+    @classmethod
+    def queued(cls, result: dict[str, Any] | None = None) -> "ActionExecutionResult":
+        return cls(result=result or {}, status="queued")
+
+    @classmethod
+    def retryable_failure(
+        cls,
+        error: str,
+        *,
+        retry_after_s: int | None = None,
+        result: dict[str, Any] | None = None,
+    ) -> "ActionExecutionResult":
+        return cls(
+            result=result or {},
+            status="retryable_failure",
+            error=error,
+            retry_after_s=retry_after_s,
+        )
+
+    @classmethod
+    def permanent_failure(
+        cls,
+        error: str,
+        *,
+        result: dict[str, Any] | None = None,
+    ) -> "ActionExecutionResult":
+        return cls(result=result or {"error": error}, status="permanent_failure", error=error)
+
+
+class ActionExecutor(Protocol):
+    async def execute(self, action: ActionRecord) -> ActionExecutionResult:
+        ...
+
+
+class ActionStore(Protocol):
+    async def insert(
+        self,
+        *,
+        tenant_id: str,
+        kind: str,
+        payload: dict[str, Any],
+        run_id: str | None = None,
+        approval_policy: str = "manual",
+        source_id: str | None = None,
+        source_event_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> tuple[str, bool]:
+        ...
+
+    async def get(self, action_id: str) -> ActionRecord | None:
+        ...
+
+    async def approve(self, action_id: str, *, approver_id: str) -> bool:
+        ...
+
+    async def deny(self, action_id: str, *, approver_id: str) -> bool:
+        ...
+
+    async def mark_executing(self, action_id: str) -> bool:
+        ...
+
+    async def mark_queued(self, action_id: str, *, result: dict[str, Any] | None = None) -> None:
+        ...
+
+    async def mark_executed(self, action_id: str, *, result: dict[str, Any]) -> None:
+        ...
+
+    async def mark_failed(self, action_id: str, *, error: str) -> None:
+        ...
+
+    async def mark_retryable(self, action_id: str, *, error: str) -> bool:
+        ...

soveren_agent_platform/actions/registry.py

@@ -0,0 +1,21 @@
+"""Registry of app-provided action executors."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from soveren_agent_platform.actions.contracts import ActionExecutor
+
+
+@dataclass(slots=True)
+class ActionRegistry:
+    executors: dict[str, ActionExecutor] = field(default_factory=dict)
+
+    def register(self, kind: str, executor: ActionExecutor) -> None:
+        self.executors[kind] = executor
+
+    def get(self, kind: str) -> ActionExecutor:
+        try:
+            return self.executors[kind]
+        except KeyError as exc:
+            raise KeyError(f"no action executor registered for kind={kind!r}") from exc
+

soveren_agent_platform/actions/sqlite.py

@@ -0,0 +1,86 @@
+"""SQLite adapter for action lifecycle storage."""
+from __future__ import annotations
+
+import asyncio
+import json
+import sqlite3
+from typing import Any
+
+import soveren_agent_platform.actions.store as store
+from soveren_agent_platform.actions.contracts import ActionRecord
+
+
+class SQLiteActionStore:
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self.conn = conn
+
+    async def insert(
+        self,
+        *,
+        tenant_id: str,
+        kind: str,
+        payload: dict[str, Any],
+        run_id: str | None = None,
+        approval_policy: str = "manual",
+        source_id: str | None = None,
+        source_event_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> tuple[str, bool]:
+        return await asyncio.to_thread(
+            store.insert_action,
+            self.conn,
+            tenant_id=tenant_id,
+            kind=kind,
+            payload=payload,
+            run_id=run_id,
+            approval_policy=approval_policy,
+            source_id=source_id,
+            source_event_id=source_event_id,
+            idempotency_key=idempotency_key,
+        )
+
+    async def get(self, action_id: str) -> ActionRecord | None:
+        row = await asyncio.to_thread(store.get_action, self.conn, action_id)
+        return row_to_action(row) if row is not None else None
+
+    async def approve(self, action_id: str, *, approver_id: str) -> bool:
+        return await asyncio.to_thread(store.approve_action, self.conn, action_id, approver_id=approver_id)
+
+    async def deny(self, action_id: str, *, approver_id: str) -> bool:
+        return await asyncio.to_thread(store.deny_action, self.conn, action_id, approver_id=approver_id)
+
+    async def mark_executing(self, action_id: str) -> bool:
+        return await asyncio.to_thread(store.mark_executing, self.conn, action_id)
+
+    async def mark_queued(self, action_id: str, *, result: dict[str, Any] | None = None) -> None:
+        await asyncio.to_thread(store.mark_queued, self.conn, action_id, result=result)
+
+    async def mark_executed(self, action_id: str, *, result: dict[str, Any]) -> None:
+        await asyncio.to_thread(store.mark_executed, self.conn, action_id, result=result)
+
+    async def mark_failed(self, action_id: str, *, error: str) -> None:
+        await asyncio.to_thread(store.mark_failed, self.conn, action_id, error=error)
+
+    async def mark_retryable(self, action_id: str, *, error: str) -> bool:
+        return await asyncio.to_thread(store.mark_retryable, self.conn, action_id, error=error)
+
+
+def row_to_action(row: sqlite3.Row) -> ActionRecord:
+    try:
+        payload = json.loads(row["payload_json"]) if row["payload_json"] else {}
+    except Exception:
+        payload = {}
+    return ActionRecord(
+        id=row["id"],
+        tenant_id=row["tenant_id"],
+        run_id=row["run_id"],
+        kind=row["kind"],
+        payload=payload,
+        status=row["status"],
+        approval_policy=row["approval_policy"],
+        source_id=row["source_id"],
+        source_event_id=row["source_event_id"],
+        idempotency_key=row["idempotency_key"],
+        approved_by=row["approved_by"],
+        last_error=row["last_error"],
+    )

soveren_agent_platform/actions/store.py

@@ -0,0 +1,171 @@
+"""SQLite store for generic actions."""
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+import uuid
+from typing import Any
+
+
+def _now() -> int:
+    return int(time.time())
+
+
+def insert_action(
+    conn: sqlite3.Connection,
+    *,
+    tenant_id: str,
+    kind: str,
+    payload: dict[str, Any],
+    run_id: str | None = None,
+    approval_policy: str = "manual",
+    source_id: str | None = None,
+    source_event_id: str | None = None,
+    idempotency_key: str | None = None,
+    now: int | None = None,
+) -> tuple[str, bool]:
+    """Create an action. Return `(action_id, created)`."""
+    if idempotency_key is not None:
+        existing = conn.execute(
+            "SELECT id FROM actions WHERE idempotency_key = ?",
+            (idempotency_key,),
+        ).fetchone()
+        if existing is not None:
+            return existing["id"], False
+    now = now if now is not None else _now()
+    action_id = "act_" + uuid.uuid4().hex
+    status = "approved" if approval_policy == "auto" else "pending"
+    conn.execute(
+        "INSERT INTO actions"
+        " (id, tenant_id, run_id, kind, payload_json, status, approval_policy,"
+        "  source_id, source_event_id, idempotency_key, created_at, updated_at)"
+        " VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        (
+            action_id,
+            tenant_id,
+            run_id,
+            kind,
+            json.dumps(payload, ensure_ascii=False),
+            status,
+            approval_policy,
+            source_id,
+            source_event_id,
+            idempotency_key,
+            now,
+            now,
+        ),
+    )
+    return action_id, True
+
+
+def get_action(conn: sqlite3.Connection, action_id: str) -> sqlite3.Row | None:
+    return conn.execute("SELECT * FROM actions WHERE id = ?", (action_id,)).fetchone()
+
+
+def approve_action(
+    conn: sqlite3.Connection,
+    action_id: str,
+    *,
+    approver_id: str,
+    now: int | None = None,
+) -> bool:
+    now = now if now is not None else _now()
+    cur = conn.execute(
+        "UPDATE actions"
+        " SET status = 'approved', approved_by = ?, approved_at = ?, updated_at = ?"
+        " WHERE id = ? AND status = 'pending'",
+        (approver_id, now, now, action_id),
+    )
+    return cur.rowcount > 0
+
+
+def deny_action(
+    conn: sqlite3.Connection,
+    action_id: str,
+    *,
+    approver_id: str,
+    now: int | None = None,
+) -> bool:
+    now = now if now is not None else _now()
+    cur = conn.execute(
+        "UPDATE actions"
+        " SET status = 'denied', approved_by = ?, approved_at = ?, updated_at = ?"
+        " WHERE id = ? AND status = 'pending'",
+        (approver_id, now, now, action_id),
+    )
+    return cur.rowcount > 0
+
+
+def mark_executing(conn: sqlite3.Connection, action_id: str, *, now: int | None = None) -> bool:
+    now = now if now is not None else _now()
+    cur = conn.execute(
+        "UPDATE actions SET status = 'executing', updated_at = ?"
+        " WHERE id = ? AND status IN ('approved','queued')",
+        (now, action_id),
+    )
+    return cur.rowcount > 0
+
+
+def mark_queued(
+    conn: sqlite3.Connection,
+    action_id: str,
+    *,
+    result: dict[str, Any] | None = None,
+    now: int | None = None,
+) -> None:
+    now = now if now is not None else _now()
+    conn.execute(
+        "UPDATE actions SET status = 'queued', result_json = ?, updated_at = ?"
+        " WHERE id = ? AND status IN ('approved','queued','executing')",
+        (json.dumps(result or {}, ensure_ascii=False), now, action_id),
+    )
+
+
+def mark_executed(
+    conn: sqlite3.Connection,
+    action_id: str,
+    *,
+    result: dict[str, Any],
+    now: int | None = None,
+) -> None:
+    now = now if now is not None else _now()
+    conn.execute(
+        "UPDATE actions"
+        " SET status = 'executed', executed_at = ?, result_json = ?, updated_at = ?"
+        " WHERE id = ?",
+        (now, json.dumps(result, ensure_ascii=False), now, action_id),
+    )
+
+
+def mark_failed(
+    conn: sqlite3.Connection,
+    action_id: str,
+    *,
+    error: str,
+    now: int | None = None,
+) -> None:
+    now = now if now is not None else _now()
+    conn.execute(
+        "UPDATE actions"
+        " SET status = 'failed', last_error = ?, result_json = ?, updated_at = ?"
+        " WHERE id = ?",
+        (error[:500], json.dumps({"error": error}, ensure_ascii=False), now, action_id),
+    )
+
+
+def mark_retryable(
+    conn: sqlite3.Connection,
+    action_id: str,
+    *,
+    error: str,
+    now: int | None = None,
+) -> bool:
+    now = now if now is not None else _now()
+    cur = conn.execute(
+        "UPDATE actions"
+        " SET status = 'queued', last_error = ?, updated_at = ?"
+        " WHERE id = ? AND status = 'executing'",
+        (error[:500], now, action_id),
+    )
+    return cur.rowcount > 0

soveren_agent_platform/actions/worker.py

@@ -0,0 +1,243 @@
+"""Worker for generic platform actions."""
+from __future__ import annotations
+
+import asyncio
+import logging
+import socket
+import sqlite3
+import time
+from pathlib import Path
+
+from soveren_agent_platform.actions.contracts import ActionExecutionResult, ActionStore
+from soveren_agent_platform.actions.registry import ActionRegistry
+from soveren_agent_platform.actions.sqlite import SQLiteActionStore
+from soveren_agent_platform.queue.contracts import DurableQueue, QueueEvent
+from soveren_agent_platform.queue.sqlite import SQLiteEventQueue, row_to_queue_event
+from soveren_agent_platform.runtime.worker_loop import PollingWorkerConfig, run_polling_worker
+from soveren_agent_platform.storage.sqlite import open_sqlite
+
+log = logging.getLogger(__name__)
+
+LEASE_SECONDS = 60
+BATCH_SIZE = 5
+IDLE_INITIAL_S = 1.0
+IDLE_MAX_S = 10.0
+RETRY_BACKOFF_S = 30
+
+
+def lease_owner() -> str:
+    return f"{socket.gethostname()}/actions"
+
+
+async def run_actions_worker(
+    db_path: Path,
+    stop_event: asyncio.Event,
+    *,
+    registry: ActionRegistry,
+    recipient: str = "actions",
+    batch_size: int = BATCH_SIZE,
+    lease_seconds: int = LEASE_SECONDS,
+    retry_backoff_s: int = RETRY_BACKOFF_S,
+    idle_initial_s: float = IDLE_INITIAL_S,
+    idle_max_s: float = IDLE_MAX_S,
+) -> None:
+    conn = open_sqlite(db_path)
+    try:
+        await run_actions_queue_worker(
+            SQLiteActionStore(conn),
+            SQLiteEventQueue(conn),
+            stop_event,
+            registry=registry,
+            recipient=recipient,
+            batch_size=batch_size,
+            lease_seconds=lease_seconds,
+            retry_backoff_s=retry_backoff_s,
+            idle_initial_s=idle_initial_s,
+            idle_max_s=idle_max_s,
+        )
+    finally:
+        conn.close()
+
+
+async def run_actions_queue_worker(
+    action_store: ActionStore,
+    queue: DurableQueue,
+    stop_event: asyncio.Event,
+    *,
+    registry: ActionRegistry,
+    recipient: str = "actions",
+    batch_size: int = BATCH_SIZE,
+    lease_seconds: int = LEASE_SECONDS,
+    retry_backoff_s: int = RETRY_BACKOFF_S,
+    idle_initial_s: float = IDLE_INITIAL_S,
+    idle_max_s: float = IDLE_MAX_S,
+) -> None:
+    owner = lease_owner()
+    await run_polling_worker(
+        stop_event,
+        config=PollingWorkerConfig(
+            name=f"actions:{recipient}",
+            idle_initial_s=idle_initial_s,
+            idle_max_s=idle_max_s,
+        ),
+        claim=lambda: queue.claim_due(
+            recipient=recipient,
+            limit=batch_size,
+            lease_owner=owner,
+            lease_seconds=lease_seconds,
+        ),
+        process=lambda event: process_action_queue_event(
+            action_store,
+            event,
+            registry=registry,
+            queue=queue,
+            retry_backoff_s=retry_backoff_s,
+        ),
+    )
+
+
+async def process_action_event(
+    conn: sqlite3.Connection,
+    row: sqlite3.Row,
+    *,
+    registry: ActionRegistry,
+    retry_backoff_s: int = RETRY_BACKOFF_S,
+) -> None:
+    await process_action_queue_event(
+        SQLiteActionStore(conn),
+        row_to_queue_event(row),
+        registry=registry,
+        queue=SQLiteEventQueue(conn),
+        retry_backoff_s=retry_backoff_s,
+    )
+
+
+async def process_action_queue_event(
+    action_store: ActionStore,
+    event: QueueEvent,
+    *,
+    registry: ActionRegistry,
+    queue: DurableQueue,
+    retry_backoff_s: int = RETRY_BACKOFF_S,
+) -> None:
+    event_id = event.id
+    try:
+        action_id = str(event.payload["action_id"])
+    except KeyError as exc:
+        await queue.mark_retry(
+            event_id,
+            run_after=int(time.time()) + RETRY_BACKOFF_S,
+            last_error=f"bad action event payload: {exc}",
+        )
+        return
+
+    action = await action_store.get(action_id)
+    if action is None:
+        log.warning("action %s not found, dropping event %s", action_id, event_id)
+        await queue.mark_done(event_id)
+        return
+    if action.status in ("executed", "failed", "denied", "cancelled"):
+        await queue.mark_done(event_id)
+        return
+    if action.status not in ("approved", "queued"):
+        log.info("action %s status=%s is not executable yet", action_id, action.status)
+        await queue.mark_done(event_id)
+        return
+    if not await action_store.mark_executing(action_id):
+        await queue.mark_done(event_id)
+        return
+
+    try:
+        executor = registry.get(action.kind)
+        refreshed = await action_store.get(action_id)
+        if refreshed is None:
+            raise RuntimeError(f"action disappeared during execution: {action_id}")
+        result = await executor.execute(refreshed)
+    except Exception as exc:
+        err = f"{type(exc).__name__}: {exc}"
+        log.exception("action execution failed id=%s", action_id)
+        await _retry_action(
+            action_store,
+            queue,
+            event_id=event_id,
+            action_id=action_id,
+            error=err,
+            retry_after_s=retry_backoff_s,
+        )
+        return
+
+    await _apply_action_result(
+        action_store,
+        queue,
+        event_id=event_id,
+        action_id=action_id,
+        result=result,
+        retry_backoff_s=retry_backoff_s,
+    )
+
+
+async def _apply_action_result(
+    action_store: ActionStore,
+    queue: DurableQueue,
+    *,
+    event_id: str,
+    action_id: str,
+    result: ActionExecutionResult,
+    retry_backoff_s: int,
+) -> None:
+    if result.status == "queued":
+        await action_store.mark_queued(action_id, result=result.result)
+        await queue.mark_done(event_id)
+        return
+    if result.status == "executed":
+        await action_store.mark_executed(action_id, result=result.result)
+        await queue.mark_done(event_id)
+        return
+    if result.status == "permanent_failure":
+        await action_store.mark_failed(action_id, error=result.error or "action failed permanently")
+        await queue.mark_done(event_id)
+        return
+    if result.status == "retryable_failure":
+        await _retry_action(
+            action_store,
+            queue,
+            event_id=event_id,
+            action_id=action_id,
+            error=result.error or "action failed transiently",
+            retry_after_s=result.retry_after_s if result.retry_after_s is not None else retry_backoff_s,
+        )
+        return
+    await _retry_action(
+        action_store,
+        queue,
+        event_id=event_id,
+        action_id=action_id,
+        error=f"unsupported action result status: {result.status!r}",
+        retry_after_s=retry_backoff_s,
+    )
+
+
+async def _retry_action(
+    action_store: ActionStore,
+    queue: DurableQueue,
+    *,
+    event_id: str,
+    action_id: str,
+    error: str,
+    retry_after_s: int,
+) -> None:
+    if not await action_store.mark_retryable(action_id, error=error):
+        current = await action_store.get(action_id)
+        if current is None or current.status in ("executed", "failed", "denied", "cancelled"):
+            await queue.mark_done(event_id)
+            return
+        raise RuntimeError(
+            f"action {action_id} could not be moved to retryable state from {current.status!r}"
+        )
+    queue_status = await queue.mark_retry(
+        event_id,
+        run_after=int(time.time()) + retry_after_s,
+        last_error=error,
+    )
+    if queue_status == "dead_letter":
+        await action_store.mark_failed(action_id, error=error)

soveren_agent_platform/agent/__init__.py

@@ -0,0 +1,6 @@
+"""Agent runtime module: queue events in, agent handlers out."""
+
+from soveren_agent_platform.agent.contracts import AgentEvent, AgentHandler
+from soveren_agent_platform.agent.worker import run_agent_queue_worker, run_agent_worker
+
+__all__ = ["AgentEvent", "AgentHandler", "run_agent_queue_worker", "run_agent_worker"]

soveren_agent_platform/agent/contracts.py

@@ -0,0 +1,22 @@
+"""Contracts for the platform agent runtime."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass(slots=True)
+class AgentEvent:
+    id: str
+    tenant_id: str
+    recipient: str
+    message_type: str
+    payload: dict[str, Any]
+    correlation_id: str | None = None
+    causation_id: str | None = None
+
+
+class AgentHandler(Protocol):
+    async def handle(self, event: AgentEvent) -> None:
+        ...
+