devsper 2.1.6__py3-none-any.whl

devsper/reasoning/store.py

@@ -0,0 +1,67 @@
+"""
+Reasoning store: in-memory store backed by a ReasoningGraph. Used by swarm/agents.
+
+Thread-safe for concurrent add_node from executor's worker pool (asyncio run_in_executor).
+"""
+
+import secrets
+import threading
+from devsper.reasoning.graph import ReasoningGraph
+from devsper.reasoning.nodes import ReasoningNode
+
+
+def _short_id() -> str:
+    return secrets.token_hex(4)
+
+
+class ReasoningStore:
+    """Store for reasoning nodes. Wraps ReasoningGraph; agents write/query via this."""
+
+    def __init__(self) -> None:
+        self._graph = ReasoningGraph()
+        self._lock = threading.Lock()
+
+    @property
+    def graph(self) -> ReasoningGraph:
+        return self._graph
+
+    def add_node(
+        self,
+        agent_id: str,
+        task_id: str,
+        content: str,
+        dependencies: list[str] | None = None,
+        node_id: str | None = None,
+    ) -> ReasoningNode:
+        """Create and add a reasoning node. Returns the new node. Thread-safe for concurrent workers."""
+        nid = node_id or _short_id()
+        node = ReasoningNode(
+            id=nid,
+            agent_id=agent_id,
+            task_id=task_id,
+            content=content,
+            dependencies=dependencies or [],
+        )
+        with self._lock:
+            self._graph.add_node(node)
+        return node
+
+    def query_nodes(
+        self,
+        *,
+        agent_id: str | None = None,
+        task_id: str | None = None,
+        limit: int = 100,
+    ) -> list[ReasoningNode]:
+        """Query stored nodes by optional agent_id and/or task_id. Thread-safe."""
+        with self._lock:
+            return self._graph.query_nodes(
+                agent_id=agent_id,
+                task_id=task_id,
+                limit=limit,
+            )
+
+    def get_dependencies(self, node_id: str) -> list[ReasoningNode]:
+        """Return dependencies of the given node. Thread-safe."""
+        with self._lock:
+            return self._graph.get_dependencies(node_id)

devsper/runtime/__init__.py

@@ -0,0 +1,12 @@
+"""Runtime utilities: replay, telemetry, visualization."""
+
+from devsper.runtime.replay import replay_execution
+from devsper.runtime.telemetry import collect_telemetry, print_telemetry_summary
+from devsper.runtime.visualize import visualize_scheduler_dag
+
+__all__ = [
+    "replay_execution",
+    "collect_telemetry",
+    "print_telemetry_summary",
+    "visualize_scheduler_dag",
+]

devsper/runtime/health.py

@@ -0,0 +1,88 @@
+"""
+Health and readiness checks for orchestration (Docker healthcheck, k8s liveness).
+
+v1.9: bus_reachable, memory_store_readable, tool_scores_readable, knowledge_graph_loadable, checkpoint_dir_writable.
+"""
+
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+
+@dataclass
+class HealthReport:
+    checks: dict[str, bool]
+    errors: dict[str, str]
+    healthy: bool
+    timestamp: str
+
+
+class HealthChecker:
+    """Run health checks against config subsystems."""
+
+    async def check(self, config: object) -> HealthReport:
+        checks: dict[str, bool] = {}
+        errors: dict[str, str] = {}
+
+        # bus_reachable: start and stop bus (for Redis: connect; for memory: no-op)
+        try:
+            from devsper.bus import get_bus
+            bus = get_bus(config)
+            await bus.start()
+            await bus.stop()
+            checks["bus_reachable"] = True
+        except Exception as e:
+            checks["bus_reachable"] = False
+            errors["bus_reachable"] = str(e)
+
+        # memory_store_readable
+        try:
+            from devsper.memory.memory_store import get_default_store
+            store = get_default_store()
+            store.list_memory(limit=1)
+            checks["memory_store_readable"] = True
+        except Exception as e:
+            checks["memory_store_readable"] = False
+            errors["memory_store_readable"] = str(e)
+
+        # tool_scores_readable
+        try:
+            from devsper.tools.scoring import get_default_score_store
+            get_default_score_store().get_all_scores()
+            checks["tool_scores_readable"] = True
+        except Exception as e:
+            checks["tool_scores_readable"] = False
+            errors["tool_scores_readable"] = str(e)
+
+        # knowledge_graph_loadable
+        try:
+            from devsper.knowledge.knowledge_graph import KnowledgeGraph
+            from devsper.memory.memory_store import get_default_store
+            kg = KnowledgeGraph(store=get_default_store())
+            kg.load()
+            checks["knowledge_graph_loadable"] = True
+        except Exception as e:
+            checks["knowledge_graph_loadable"] = False
+            errors["knowledge_graph_loadable"] = str(e)
+
+        # checkpoint_dir_writable
+        try:
+            events_dir = getattr(config, "events_dir", ".devsper/events") or ".devsper/events"
+            import os
+            os.makedirs(events_dir, exist_ok=True)
+            test_file = os.path.join(events_dir, ".health_check_tmp")
+            with open(test_file, "w") as f:
+                f.write("ok")
+            os.remove(test_file)
+            checks["checkpoint_dir_writable"] = True
+        except Exception as e:
+            checks["checkpoint_dir_writable"] = False
+            errors["checkpoint_dir_writable"] = str(e)
+
+        healthy = all(checks.values()) if checks else False
+        return HealthReport(
+            checks=checks,
+            errors=errors,
+            healthy=healthy,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+        )

devsper/runtime/replay.py

@@ -0,0 +1,53 @@
+"""
+Replay swarm execution from an event log.
+
+Load events.jsonl, group by task, reconstruct execution timeline, print step-by-step replay.
+"""
+
+import os
+from devsper.types.event import Event
+
+
+def _load_events(log_path: str) -> list[Event]:
+    """Load events from a JSONL file."""
+    if not os.path.exists(log_path):
+        return []
+    events_list = []
+    with open(log_path, "r") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                events_list.append(Event.model_validate_json(line))
+            except Exception:
+                continue
+    return events_list
+
+
+def replay_execution(log_path: str) -> str:
+    """
+    Replay swarm execution from the event log at log_path.
+
+    Loads events.jsonl, sorts by timestamp, and returns a step-by-step replay transcript
+    (e.g. [planner_started] task_1 created agent_started task_1 ...).
+    """
+    events_list = _load_events(log_path)
+    if not events_list:
+        return f"No events found at {log_path}"
+
+    events_list.sort(key=lambda e: e.timestamp)
+
+    lines = []
+    for e in events_list:
+        event_type = e.type.value if hasattr(e.type, "value") else str(e.type)
+        payload = e.payload or {}
+        task_id = payload.get("task_id", "")
+        part = f"[{event_type}]"
+        if task_id:
+            part += f" {task_id}"
+        if event_type == "task_created" and payload.get("description"):
+            part += f" created"
+        lines.append(part)
+
+    return "\n".join(lines)

devsper/runtime/replay_engine.py

@@ -0,0 +1,142 @@
+"""
+Deterministic replay: reconstruct entire swarm execution from an event log.
+
+Includes: planner decisions, scheduler events, agent prompts (when logged),
+tool calls, reasoning graph updates.
+"""
+
+import os
+from pathlib import Path
+from devsper.types.event import Event
+
+
+def _find_log_path(events_dir: str | Path, run_id: str) -> str | None:
+    """Find events JSONL file for run_id (stem of filename). Returns path or None."""
+    path = Path(events_dir)
+    if not path.is_dir():
+        return None
+    candidate = path / f"{run_id}.jsonl"
+    if candidate.is_file():
+        return str(candidate)
+    for f in path.glob("*.jsonl"):
+        if f.stem == run_id:
+            return str(f)
+    return None
+
+
+def _load_events(log_path: str) -> list[Event]:
+    """Load events from a JSONL file."""
+    if not os.path.isfile(log_path):
+        return []
+    out = []
+    with open(log_path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(Event.model_validate_json(line))
+            except Exception:
+                continue
+    return out
+
+
+def replay_run(
+    run_id: str,
+    events_dir: str | Path | None = None,
+) -> str:
+    """
+    Reconstruct the entire swarm execution for run_id.
+    Returns a transcript string: planner decisions, scheduler (task) events,
+    executor/agent lifecycle, tool calls, reasoning graph updates.
+    """
+    if events_dir is None:
+        try:
+            from devsper.config import get_config
+
+            events_dir = get_config().events_dir
+        except Exception:
+            events_dir = ".devsper/events"
+
+    log_path = _find_log_path(events_dir, run_id)
+    if not log_path:
+        return f"No event log found for run_id: {run_id} (looked in {events_dir})"
+
+    evs = _load_events(log_path)
+    if not evs:
+        return f"Empty event log for run_id: {run_id}"
+
+    evs.sort(key=lambda e: e.timestamp)
+    lines = [f"# Replay: {run_id}", ""]
+
+    for e in evs:
+        event_type = e.type.value if hasattr(e.type, "value") else str(e.type)
+        payload = e.payload or {}
+        ts = getattr(e.timestamp, "isoformat", lambda: str(e.timestamp))()
+
+        if event_type == "swarm_started":
+            lines.append(f"[{ts}] SWARM_STARTED")
+            lines.append(f"  user_task: {payload.get('user_task', '')[:200]}")
+        elif event_type == "planner_started":
+            lines.append(
+                f"[{ts}] PLANNER_STARTED  task_id={payload.get('task_id', '')}"
+            )
+        elif event_type == "task_created":
+            lines.append(f"[{ts}] TASK_CREATED  task_id={payload.get('task_id', '')}")
+            lines.append(f"  description: {(payload.get('description') or '')[:120]}")
+        elif event_type == "planner_finished":
+            lines.append(
+                f"[{ts}] PLANNER_FINISHED  subtask_count={payload.get('subtask_count', 0)}"
+            )
+        elif event_type == "executor_started":
+            lines.append(f"[{ts}] EXECUTOR_STARTED")
+        elif event_type == "agent_started":
+            lines.append(f"[{ts}] AGENT_STARTED  task_id={payload.get('task_id', '')}")
+        elif event_type == "task_started":
+            lines.append(f"[{ts}] TASK_STARTED  task_id={payload.get('task_id', '')}")
+        elif event_type == "tool_called":
+            lines.append(
+                f"[{ts}] TOOL_CALLED  task_id={payload.get('task_id', '')}  tool={payload.get('tool', '')}"
+            )
+            lines.append(
+                f"  result_preview: {(payload.get('result_preview') or '')[:150]}"
+            )
+        elif event_type == "reasoning_node_added":
+            lines.append(
+                f"[{ts}] REASONING_NODE_ADDED  node_id={payload.get('node_id', '')}  task_id={payload.get('task_id', '')}"
+            )
+        elif event_type == "task_completed":
+            lines.append(f"[{ts}] TASK_COMPLETED  task_id={payload.get('task_id', '')}")
+        elif event_type == "task_failed":
+            lines.append(
+                f"[{ts}] TASK_FAILED  task_id={payload.get('task_id', '')}  error={payload.get('error', '')[:100]}"
+            )
+        elif event_type == "agent_finished":
+            lines.append(f"[{ts}] AGENT_FINISHED  task_id={payload.get('task_id', '')}")
+        elif event_type == "executor_finished":
+            lines.append(f"[{ts}] EXECUTOR_FINISHED")
+        elif event_type == "swarm_finished":
+            lines.append(
+                f"[{ts}] SWARM_FINISHED  task_count={payload.get('task_count', 0)}"
+            )
+        else:
+            lines.append(f"[{ts}] {event_type.upper()}  {payload}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip()
+
+
+def list_run_ids(events_dir: str | Path | None = None) -> list[str]:
+    """List run IDs that have event logs (from *.jsonl in events_dir)."""
+    if events_dir is None:
+        try:
+            from devsper.config import get_config
+
+            events_dir = get_config().events_dir
+        except Exception:
+            events_dir = ".devsper/events"
+    path = Path(events_dir)
+    if not path.is_dir():
+        return []
+    ids_ = [f.stem for f in path.glob("*.jsonl")]
+    return sorted(ids_, reverse=True)

devsper/runtime/run_history.py

@@ -0,0 +1,204 @@
+"""
+Persistent run history: SQLite DB at ~/.config/devsper/runs.db.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+
+from devsper.intelligence.analysis.run_report import RunReport
+
+
+HISTORY_DB = Path("~/.config/devsper/runs.db").expanduser()
+
+
+@dataclass
+class RunRow:
+    run_id: str
+    root_task: str
+    strategy: str
+    started_at: str
+    finished_at: str
+    duration_seconds: float
+    total_tasks: int
+    completed_tasks: int
+    failed_tasks: int
+    estimated_cost_usd: float | None
+    models_used: str  # JSON array string
+    events_path: str
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS runs (
+    run_id TEXT PRIMARY KEY,
+    root_task TEXT,
+    strategy TEXT,
+    started_at TEXT,
+    finished_at TEXT,
+    duration_seconds REAL,
+    total_tasks INTEGER,
+    completed_tasks INTEGER,
+    failed_tasks INTEGER,
+    estimated_cost_usd REAL,
+    models_used TEXT,
+    events_path TEXT
+);
+"""
+
+
+def _ensure_db(db_path: Path) -> None:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    with sqlite3.connect(str(db_path)) as conn:
+        conn.executescript(_SCHEMA)
+
+
+class RunHistory:
+    def __init__(self, db_path: Path | None = None) -> None:
+        self._db = db_path or HISTORY_DB
+        _ensure_db(self._db)
+
+    def record_run(self, report: RunReport) -> None:
+        """Persist report to DB. Called at SWARM_FINISHED."""
+        events_path = ""
+        try:
+            from devsper.config import get_config
+            cfg = get_config()
+            events_dir = Path(cfg.events_dir)
+            candidate = events_dir / f"{report.run_id}.jsonl"
+            if candidate.is_file():
+                events_path = str(candidate)
+            else:
+                for f in events_dir.glob("*.jsonl"):
+                    if f.stem == report.run_id:
+                        events_path = str(f)
+                        break
+        except Exception:
+            pass
+        models_used_json = json.dumps(report.models_used or [])
+        with sqlite3.connect(str(self._db)) as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO runs (
+                    run_id, root_task, strategy, started_at, finished_at,
+                    duration_seconds, total_tasks, completed_tasks, failed_tasks,
+                    estimated_cost_usd, models_used, events_path
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    report.run_id,
+                    report.root_task,
+                    report.strategy,
+                    report.started_at,
+                    report.finished_at,
+                    report.total_duration_seconds,
+                    report.total_tasks,
+                    report.completed_tasks,
+                    report.failed_tasks,
+                    report.estimated_cost_usd,
+                    models_used_json,
+                    events_path,
+                ),
+            )
+
+    def list_runs(
+        self,
+        limit: int = 20,
+        filter_status: str | None = None,
+    ) -> list[RunRow]:
+        """filter_status: 'failed' to only return runs with failed_tasks > 0."""
+        with sqlite3.connect(str(self._db)) as conn:
+            conn.row_factory = sqlite3.Row
+            if filter_status == "failed":
+                cur = conn.execute(
+                    """
+                    SELECT run_id, root_task, strategy, started_at, finished_at,
+                           duration_seconds, total_tasks, completed_tasks, failed_tasks,
+                           estimated_cost_usd, models_used, events_path
+                    FROM runs WHERE failed_tasks > 0
+                    ORDER BY started_at DESC LIMIT ?
+                    """,
+                    (limit,),
+                )
+            else:
+                cur = conn.execute(
+                    """
+                    SELECT run_id, root_task, strategy, started_at, finished_at,
+                           duration_seconds, total_tasks, completed_tasks, failed_tasks,
+                           estimated_cost_usd, models_used, events_path
+                    FROM runs ORDER BY started_at DESC LIMIT ?
+                    """,
+                    (limit,),
+                )
+            rows = cur.fetchall()
+        return [_row_to_run(dict(r)) for r in rows]
+
+    def get_run(self, run_id: str) -> RunRow | None:
+        with sqlite3.connect(str(self._db)) as conn:
+            conn.row_factory = sqlite3.Row
+            cur = conn.execute(
+                "SELECT run_id, root_task, strategy, started_at, finished_at, "
+                "duration_seconds, total_tasks, completed_tasks, failed_tasks, "
+                "estimated_cost_usd, models_used, events_path FROM runs WHERE run_id = ?",
+                (run_id,),
+            )
+            row = cur.fetchone()
+        return _row_to_run(dict(row)) if row else None
+
+    def delete_run(self, run_id: str) -> None:
+        """Remove from DB and delete the events file if path is stored."""
+        row = self.get_run(run_id)
+        with sqlite3.connect(str(self._db)) as conn:
+            conn.execute("DELETE FROM runs WHERE run_id = ?", (run_id,))
+        if row and row.events_path and Path(row.events_path).is_file():
+            try:
+                Path(row.events_path).unlink()
+            except OSError:
+                pass
+
+    def get_stats(self) -> dict:
+        """Aggregate: total runs, avg duration, total cost, most-used strategy."""
+        with sqlite3.connect(str(self._db)) as conn:
+            cur = conn.execute(
+                "SELECT COUNT(*) as n, AVG(duration_seconds) as avg_dur, "
+                "SUM(estimated_cost_usd) as total_cost FROM runs"
+            )
+            row = cur.fetchone()
+            n = row[0] or 0
+            avg_dur = row[1] or 0.0
+            total_cost = row[2] or 0.0
+            cur2 = conn.execute(
+                "SELECT strategy, COUNT(*) as c FROM runs GROUP BY strategy ORDER BY c DESC LIMIT 1"
+            )
+            strat_row = cur2.fetchone()
+            most_used_strategy = strat_row[0] if strat_row else ""
+        return {
+            "total_runs": n,
+            "avg_duration_seconds": round(avg_dur, 2),
+            "total_estimated_cost_usd": round(total_cost, 4) if total_cost else 0.0,
+            "most_used_strategy": most_used_strategy,
+        }
+
+
+def _row_to_run(d: dict) -> RunRow:
+    models_raw = d.get("models_used") or "[]"
+    try:
+        _ = json.loads(models_raw)
+    except Exception:
+        models_raw = "[]"
+    return RunRow(
+        run_id=d["run_id"],
+        root_task=d.get("root_task") or "",
+        strategy=d.get("strategy") or "",
+        started_at=d.get("started_at") or "",
+        finished_at=d.get("finished_at") or "",
+        duration_seconds=float(d.get("duration_seconds") or 0),
+        total_tasks=int(d.get("total_tasks") or 0),
+        completed_tasks=int(d.get("completed_tasks") or 0),
+        failed_tasks=int(d.get("failed_tasks") or 0),
+        estimated_cost_usd=d.get("estimated_cost_usd") if d.get("estimated_cost_usd") is not None else None,
+        models_used=models_raw,
+        events_path=d.get("events_path") or "",
+    )

devsper/runtime/telemetry.py

@@ -0,0 +1,116 @@
+"""
+Execution telemetry: collect runtime metrics from event log.
+
+Metrics: task_duration, agent_latency, concurrency_levels, task_success_rate.
+Emit telemetry summary when swarm finishes.
+"""
+
+import os
+
+from devsper.types.event import Event
+
+
+def _load_events(log_path: str) -> list[Event]:
+    if not os.path.exists(log_path):
+        return []
+    events_list = []
+    with open(log_path, "r") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                events_list.append(Event.model_validate_json(line))
+            except Exception:
+                continue
+    return events_list
+
+
+def collect_telemetry(log_path: str) -> dict:
+    """
+    Collect runtime metrics from an event log.
+
+    Returns a dict with: tasks_completed, tasks_failed, avg_task_duration_seconds,
+    avg_agent_latency_seconds, max_concurrency, task_success_rate.
+    """
+    events_list = _load_events(log_path)
+    if not events_list:
+        return {
+            "tasks_completed": 0,
+            "tasks_failed": 0,
+            "avg_task_duration_seconds": 0.0,
+            "avg_agent_latency_seconds": 0.0,
+            "max_concurrency": 0,
+            "task_success_rate": 0.0,
+        }
+
+    events_list.sort(key=lambda e: e.timestamp)
+    task_started = {}
+    task_completed = {}
+    agent_started = {}
+    agent_finished = {}
+    concurrency = 0
+    max_concurrency = 0
+
+    for e in events_list:
+        t = e.timestamp
+        payload = e.payload or {}
+        task_id = payload.get("task_id")
+        typ = e.type.value if hasattr(e.type, "value") else str(e.type)
+
+        if typ == "task_started" and task_id:
+            task_started[task_id] = t
+            concurrency += 1
+            max_concurrency = max(max_concurrency, concurrency)
+        elif typ == "task_completed" and task_id:
+            task_completed[task_id] = t
+            concurrency = max(0, concurrency - 1)
+        elif typ == "task_failed" and task_id:
+            concurrency = max(0, concurrency - 1)
+        elif typ == "agent_started" and task_id:
+            agent_started[task_id] = t
+        elif typ == "agent_finished" and task_id:
+            agent_finished[task_id] = t
+
+    task_durations = []
+    for tid, start in task_started.items():
+        if tid in task_completed:
+            delta = (task_completed[tid] - start).total_seconds()
+            task_durations.append(delta)
+
+    agent_latencies = []
+    for tid, start in agent_started.items():
+        if tid in agent_finished:
+            delta = (agent_finished[tid] - start).total_seconds()
+            agent_latencies.append(delta)
+
+    completed = len(task_completed)
+    failed = sum(1 for e in events_list if (e.type.value if hasattr(e.type, "value") else str(e.type)) == "task_failed")
+    total_tasks = completed + failed
+    success_rate = (completed / total_tasks) if total_tasks else 0.0
+
+    return {
+        "tasks_completed": completed,
+        "tasks_failed": failed,
+        "avg_task_duration_seconds": round(sum(task_durations) / len(task_durations), 2) if task_durations else 0.0,
+        "avg_agent_latency_seconds": round(sum(agent_latencies) / len(agent_latencies), 2) if agent_latencies else 0.0,
+        "max_concurrency": max_concurrency,
+        "task_success_rate": round(success_rate, 2),
+    }
+
+
+def print_telemetry_summary(log_path: str) -> str:
+    """
+    Emit telemetry summary to string (e.g. for printing when swarm finishes).
+
+    Example: tasks_completed: 5, avg_task_time: 2.3s, max_concurrency: 3
+    """
+    m = collect_telemetry(log_path)
+    return (
+        f"tasks_completed: {m['tasks_completed']}\n"
+        f"tasks_failed: {m['tasks_failed']}\n"
+        f"avg_task_time: {m['avg_task_duration_seconds']}s\n"
+        f"avg_agent_latency: {m['avg_agent_latency_seconds']}s\n"
+        f"max_concurrency: {m['max_concurrency']}\n"
+        f"task_success_rate: {m['task_success_rate']}"
+    )