trace-agent-server 0.0.1__py3-none-any.whl

trace_agent_server/services/dashboard.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from trace_agent_server.models import Event, Run
+from trace_agent_server.schemas import (
+    DashboardResponse,
+    DashboardStats,
+    DashboardTrendItem,
+    DashboardTopTool,
+    DashboardTopError,
+)
+
+
+def build_dashboard(session: Session, period: str) -> DashboardResponse:
+    now = datetime.now(timezone.utc)
+    if period == "24h":
+        cutoff = now - timedelta(hours=24)
+    elif period == "7d":
+        cutoff = now - timedelta(days=7)
+    else:  # 30d
+        cutoff = now - timedelta(days=30)
+
+    # Base query for runs in period
+    base_query = select(Run).where(Run.started_at >= cutoff)
+    runs = list(session.scalars(base_query))
+
+    total = len(runs)
+    completed = sum(1 for r in runs if r.status == "completed")
+    failed = sum(1 for r in runs if r.status == "failed")
+    running = sum(1 for r in runs if r.status == "running")
+    total_errors = sum(r.error_count for r in runs)
+    total_tools = sum(r.tool_count for r in runs)
+    total_artifacts = sum(r.artifact_count for r in runs)
+    total_prompt = sum(r.total_prompt_tokens for r in runs)
+    total_completion = sum(r.total_completion_tokens for r in runs)
+
+    durations = [
+        int((r.ended_at - r.started_at).total_seconds() * 1000)
+        for r in runs
+        if r.ended_at and r.started_at
+    ]
+    avg_duration = int(sum(durations) / len(durations)) if durations else None
+
+    # Trend: daily counts for last 7 days
+    trend = []
+    for i in range(6, -1, -1):
+        day_start = (now - timedelta(days=i)).replace(hour=0, minute=0, second=0, microsecond=0)
+        day_end = day_start + timedelta(days=1)
+        day_runs = list(session.scalars(
+            select(Run).where(Run.started_at >= day_start, Run.started_at < day_end)
+        ))
+        trend.append(DashboardTrendItem(
+            date=day_start.strftime("%Y-%m-%d"),
+            runs=len(day_runs),
+            completed=sum(1 for r in day_runs if r.status == "completed"),
+            failed=sum(1 for r in day_runs if r.status == "failed"),
+        ))
+
+    # Top tools from events
+    tool_stats = session.execute(
+        select(Event.tool_name, func.count(Event.id), func.avg(Event.duration_ms))
+        .where(Event.type.in_(["tool.succeeded", "tool.failed"]), Event.timestamp >= cutoff)
+        .group_by(Event.tool_name)
+        .order_by(func.count(Event.id).desc())
+        .limit(10)
+    ).all()
+    top_tools = [
+        DashboardTopTool(tool_name=name or "unknown", call_count=count, avg_duration_ms=int(avg_ms or 0))
+        for name, count, avg_ms in tool_stats
+    ]
+
+    # Top errors
+    error_stats = session.execute(
+        select(Event.error_code, func.count(Event.id))
+        .where(Event.error_code.isnot(None), Event.timestamp >= cutoff)
+        .group_by(Event.error_code)
+        .order_by(func.count(Event.id).desc())
+        .limit(10)
+    ).all()
+    top_errors = [
+        DashboardTopError(error_code=code, count=count)
+        for code, count in error_stats
+    ]
+
+    # Provider distribution
+    provider_dist = session.execute(
+        select(Run.provider, func.count(Run.id))
+        .where(Run.started_at >= cutoff)
+        .group_by(Run.provider)
+    ).all()
+    provider_distribution = [{"provider": p or "unknown", "count": c} for p, c in provider_dist]
+
+    # Model distribution
+    model_dist = session.execute(
+        select(Run.model, func.count(Run.id))
+        .where(Run.started_at >= cutoff)
+        .group_by(Run.model)
+    ).all()
+    model_distribution = [{"model": m, "count": c} for m, c in model_dist if m]
+
+    return DashboardResponse(
+        stats=DashboardStats(
+            total_runs=total,
+            completed_runs=completed,
+            failed_runs=failed,
+            running_runs=running,
+            total_errors=total_errors,
+            total_tools=total_tools,
+            total_artifacts=total_artifacts,
+            avg_duration_ms=avg_duration,
+            total_prompt_tokens=total_prompt,
+            total_completion_tokens=total_completion,
+            total_tokens=total_prompt + total_completion,
+        ),
+        trend=trend,
+        top_tools=top_tools,
+        top_errors=top_errors,
+        provider_distribution=provider_distribution,
+        model_distribution=model_distribution,
+    )

trace_agent_server/services/events.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlalchemy.orm import Session
+
+from trace_agent_server.models import Artifact, Event, Run
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+# In-memory pub/sub for SSE (run_id -> list of queues)
+_sse_queues: dict[str, list[asyncio.Queue]] = {}
+
+
+def _get_sse_queues(run_id: str) -> list[asyncio.Queue]:
+    return _sse_queues.get(run_id, [])
+
+
+def _register_sse_queue(run_id: str, queue: asyncio.Queue) -> None:
+    if run_id not in _sse_queues:
+        _sse_queues[run_id] = []
+    _sse_queues[run_id].append(queue)
+
+
+def _unregister_sse_queue(run_id: str, queue: asyncio.Queue) -> None:
+    if run_id in _sse_queues:
+        _sse_queues[run_id] = [q for q in _sse_queues[run_id] if q is not queue]
+        if not _sse_queues[run_id]:
+            del _sse_queues[run_id]
+
+
+def _notify_sse_listeners(run_id: str, event_data: dict[str, Any]) -> None:
+    queues = _get_sse_queues(run_id)
+    for queue in queues:
+        try:
+            queue.put_nowait(event_data)
+        except asyncio.QueueFull:
+            pass
+
+
+def record_event(
+    session: Session,
+    run: Run,
+    *,
+    actor: str,
+    event_type: str,
+    summary: str,
+    status: str | None = None,
+    step_id: str | None = None,
+    parent_step_id: str | None = None,
+    duration_ms: int | None = None,
+    provider: str | None = None,
+    model: str | None = None,
+    tool_name: str | None = None,
+    artifact_refs: list[Any] | None = None,
+    error_code: str | None = None,
+    payload_hash: str | None = None,
+    payload_full: dict[str, Any] | None = None,
+    metadata: dict[str, Any] | None = None,
+    turn_id: str | None = None,
+) -> Event:
+    run.last_event_seq += 1
+    run.updated_at = utcnow()
+    event = Event(
+        run_id=run.id,
+        turn_id=turn_id,
+        seq=run.last_event_seq,
+        timestamp=utcnow(),
+        step_id=step_id,
+        parent_step_id=parent_step_id,
+        actor=actor,
+        type=event_type,
+        summary=summary,
+        status=status,
+        duration_ms=duration_ms,
+        provider=provider,
+        model=model,
+        tool_name=tool_name,
+        artifact_refs=artifact_refs or [],
+        error_code=error_code,
+        payload_hash=payload_hash,
+        payload_full=payload_full,
+        event_metadata=metadata or {},
+    )
+    session.add(event)
+    session.flush()
+    _notify_sse_listeners(
+        run.id,
+        {
+            "id": event.id,
+            "seq": event.seq,
+            "type": event.type,
+            "actor": event.actor,
+            "summary": event.summary,
+            "status": event.status,
+            "step_id": event.step_id,
+            "tool_name": event.tool_name,
+            "timestamp": event.timestamp.isoformat() if event.timestamp else None,
+        },
+    )
+    return event
+
+
+def create_artifact(
+    session: Session,
+    run: Run,
+    *,
+    source_event_id: int | None,
+    kind: str,
+    label: str,
+    summary: str,
+    content_hash: str | None,
+    metadata: dict[str, Any] | None = None,
+) -> Artifact:
+    artifact = Artifact(
+        run_id=run.id,
+        source_event_id=source_event_id,
+        kind=kind,
+        label=label,
+        summary=summary,
+        content_hash=content_hash,
+        artifact_metadata=metadata or {},
+    )
+    session.add(artifact)
+    session.flush()
+    return artifact

trace_agent_server/services/explanation.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+from sqlalchemy import delete, select
+from sqlalchemy.orm import Session
+
+from trace_agent_server.models import Decision, Event, Run
+
+
+def derive_explanation(session: Session, run: Run) -> dict[str, Any]:
+    events = list(session.scalars(select(Event).where(Event.run_id == run.id).order_by(Event.seq)))
+    session.execute(delete(Decision).where(Decision.run_id == run.id))
+    session.flush()
+
+    flags: list[dict[str, Any]] = []
+    seen_flags: set[tuple[str, str]] = set()
+    loop_tracker: dict[tuple[str, str], list[Event]] = defaultdict(list)
+    failure_streaks: dict[str, int] = defaultdict(int)
+    last_failure_by_tool: dict[str, Event] = {}
+    last_failure_by_command: dict[str, Event] = {}
+    retry_count = 0
+
+    def add_flag(flag_type: str, label: str, event_ids: list[int], metadata: dict[str, Any] | None = None) -> None:
+        key = (flag_type, label)
+        if key in seen_flags:
+            return
+        seen_flags.add(key)
+        flags.append({"type": flag_type, "label": label, "event_ids": event_ids, "metadata": metadata or {}})
+
+    def add_decision(
+        *,
+        seq: int,
+        kind: str,
+        label: str,
+        chosen_action: str,
+        rationale_summary: str,
+        evidence_event_ids: list[int],
+        trigger_event_ids: list[int] | None = None,
+        outcome: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        session.add(
+            Decision(
+                run_id=run.id,
+                seq=seq,
+                kind=kind,
+                label=label,
+                chosen_action=chosen_action,
+                rationale_summary=rationale_summary,
+                trigger_event_ids=trigger_event_ids or evidence_event_ids,
+                evidence_event_ids=evidence_event_ids,
+                alternatives=[],
+                outcome=outcome,
+                decision_metadata=metadata or {},
+            )
+        )
+
+    for event in events:
+        if event.type == "tool.requested":
+            tool_name = event.tool_name or "unknown tool"
+            add_decision(
+                seq=event.seq,
+                kind="tool_choice",
+                label=f"Selected {tool_name}",
+                chosen_action=tool_name,
+                rationale_summary=f"The agent changed state by requesting {tool_name}.",
+                evidence_event_ids=[event.id],
+                outcome="requested",
+            )
+            key = (tool_name, event.summary)
+            loop_tracker[key].append(event)
+            if len(loop_tracker[key]) >= 3:
+                add_flag(
+                    "loop",
+                    f"{tool_name} repeated {len(loop_tracker[key])} times without a new observable branch.",
+                    [item.id for item in loop_tracker[key][-3:]],
+                    {"tool_name": tool_name},
+                )
+            if tool_name in last_failure_by_tool:
+                failed_event = last_failure_by_tool[tool_name]
+                retry_count += 1
+                add_decision(
+                    seq=event.seq,
+                    kind="retry",
+                    label=f"Retried {tool_name}",
+                    chosen_action=tool_name,
+                    rationale_summary=f"The agent retried {tool_name} after a previous failure.",
+                    evidence_event_ids=[failed_event.id, event.id],
+                    outcome="retry",
+                )
+
+        if event.type == "tool.failed":
+            tool_name = event.tool_name or "unknown tool"
+            last_failure_by_tool[tool_name] = event
+            failure_streaks[event.step_id or tool_name] += 1
+            if failure_streaks[event.step_id or tool_name] >= 2:
+                add_flag(
+                    "blocker",
+                    f"{tool_name} failed repeatedly on the same step.",
+                    [event.id],
+                    {"tool_name": tool_name, "step_id": event.step_id},
+                )
+
+        if event.type == "tool.succeeded":
+            tool_name = event.tool_name or "unknown tool"
+            failure_streaks[event.step_id or tool_name] = 0
+            if tool_name in last_failure_by_tool:
+                failed_event = last_failure_by_tool.pop(tool_name)
+                add_decision(
+                    seq=event.seq,
+                    kind="recovery",
+                    label=f"Recovered {tool_name}",
+                    chosen_action=tool_name,
+                    rationale_summary=f"The agent recovered by completing {tool_name} after a prior failure.",
+                    evidence_event_ids=[failed_event.id, event.id],
+                    outcome="succeeded",
+                )
+
+        if event.type == "command.started":
+            command_name = str(event.event_metadata.get("command") or "unknown command")
+            add_decision(
+                seq=event.seq,
+                kind="command",
+                label=f"Ran command {command_name}",
+                chosen_action=command_name,
+                rationale_summary=f"The agent executed command {command_name}.",
+                evidence_event_ids=[event.id],
+                outcome="started",
+            )
+
+        if event.type == "command.failed":
+            command_name = str(event.event_metadata.get("command") or "unknown command")
+            last_failure_by_command[command_name] = event
+            failure_streaks[event.step_id or command_name] += 1
+            add_flag(
+                "command_failure",
+                f"{command_name} failed and may have blocked the run.",
+                [event.id],
+                {"command": command_name, "step_id": event.step_id},
+            )
+
+        if event.type == "command.succeeded":
+            command_name = str(event.event_metadata.get("command") or "unknown command")
+            failure_streaks[event.step_id or command_name] = 0
+            if command_name in last_failure_by_command:
+                failed_event = last_failure_by_command.pop(command_name)
+                add_decision(
+                    seq=event.seq,
+                    kind="recovery",
+                    label=f"Recovered command {command_name}",
+                    chosen_action=command_name,
+                    rationale_summary=f"The agent recovered by re-running {command_name} successfully.",
+                    evidence_event_ids=[failed_event.id, event.id],
+                    outcome="succeeded",
+                )
+
+        if event.type == "run.completed":
+            add_decision(
+                seq=event.seq,
+                kind="completion",
+                label="Completed run",
+                chosen_action="complete",
+                rationale_summary="The run ended with a final answer.",
+                evidence_event_ids=[event.id],
+                outcome="completed",
+            )
+        if event.type == "run.failed":
+            add_decision(
+                seq=event.seq,
+                kind="termination",
+                label="Failed run",
+                chosen_action="fail",
+                rationale_summary="The run ended after unresolved errors.",
+                evidence_event_ids=[event.id],
+                outcome="failed",
+            )
+
+    session.flush()
+    ordered_decisions = list(session.scalars(select(Decision).where(Decision.run_id == run.id).order_by(Decision.seq)))
+    narrative: list[dict[str, Any]] = []
+    if events:
+        narrative.append({"text": f"The run started with goal: {run.goal}", "evidence_event_ids": [events[0].id]})
+    if run.tool_count:
+        tool_names = sorted({event.tool_name for event in events if event.tool_name})
+        narrative.append(
+            {
+                "text": f"The agent executed {run.tool_count} tool call(s) across {len(tool_names)} tool(s): {', '.join(tool_names)}.",
+                "evidence_event_ids": [event.id for event in events if event.type in {"tool.succeeded", "tool.failed"}],
+            }
+        )
+    command_events = [event for event in events if event.type in {"command.succeeded", "command.failed"}]
+    if command_events:
+        command_names = sorted({str(event.event_metadata.get("command") or "unknown command") for event in command_events})
+        narrative.append(
+            {
+                "text": f"The agent executed {len(command_events)} command result(s): {', '.join(command_names[:4])}.",
+                "evidence_event_ids": [event.id for event in command_events],
+            }
+        )
+    if flags:
+        narrative.append(
+            {
+                "text": "Observed blockers or loops were detected and attached to evidence below.",
+                "evidence_event_ids": [event_id for flag in flags for event_id in flag["event_ids"]],
+            }
+        )
+    if ordered_decisions:
+        first_labels = ", ".join(decision.label for decision in ordered_decisions[:3])
+        narrative.append(
+            {
+                "text": f"Key turning points: {first_labels}.",
+                "evidence_event_ids": [event_id for decision in ordered_decisions[:3] for event_id in decision.evidence_event_ids],
+            }
+        )
+    if run.final_output_summary:
+        tail_event = events[-1] if events else None
+        narrative.append(
+            {
+                "text": f"Final outcome: {run.final_output_summary}",
+                "evidence_event_ids": [tail_event.id] if tail_event else [],
+            }
+        )
+
+    run.retry_count = retry_count
+    run.flag_cache = flags
+    run.explanation_cache = {"narrative": narrative}
+    session.flush()
+    return {"narrative": narrative, "flags": flags, "decisions": ordered_decisions}

trace_agent_server/services/graph.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import Any
+
+from trace_agent_server.models import Artifact, Decision, Event
+
+
+def build_execution_graph(events: list[Event], artifacts: list[Artifact]) -> dict[str, Any]:
+    nodes: list[dict[str, Any]] = []
+    edges: list[dict[str, Any]] = []
+    x = 0.0
+    y = 0.0
+
+    for index, event in enumerate(events):
+        nodes.append(
+            {
+                "id": f"event-{event.id}",
+                "type": "event",
+                "label": event.type,
+                "position": {"x": x, "y": y},
+                "data": {
+                    "summary": event.summary,
+                    "eventId": event.id,
+                    "toolName": event.tool_name,
+                    "status": event.status,
+                    "evidenceIds": [event.id],
+                },
+            }
+        )
+        if index > 0:
+            edges.append(
+                {
+                    "id": f"edge-event-{events[index - 1].id}-{event.id}",
+                    "source": f"event-{events[index - 1].id}",
+                    "target": f"event-{event.id}",
+                    "label": None,
+                    "animated": event.type in {"tool.failed", "run.failed"},
+                }
+            )
+        x += 220
+        if (index + 1) % 4 == 0:
+            x = 0.0
+            y += 170
+
+    artifact_y = y + 200
+    for index, artifact in enumerate(artifacts):
+        nodes.append(
+            {
+                "id": f"artifact-{artifact.id}",
+                "type": "artifact",
+                "label": artifact.label,
+                "position": {"x": float(index * 220), "y": artifact_y},
+                "data": {
+                    "summary": artifact.summary,
+                    "artifactId": artifact.id,
+                    "kind": artifact.kind,
+                    "evidenceIds": [artifact.source_event_id] if artifact.source_event_id else [],
+                },
+            }
+        )
+        if artifact.source_event_id:
+            edges.append(
+                {
+                    "id": f"edge-artifact-{artifact.id}",
+                    "source": f"event-{artifact.source_event_id}",
+                    "target": f"artifact-{artifact.id}",
+                    "label": "artifact",
+                    "animated": False,
+                }
+            )
+    return {"nodes": nodes, "edges": edges}
+
+
+def build_decision_graph(decisions: list[Decision]) -> dict[str, Any]:
+    nodes: list[dict[str, Any]] = []
+    edges: list[dict[str, Any]] = []
+    for index, decision in enumerate(decisions):
+        nodes.append(
+            {
+                "id": f"decision-{decision.id}",
+                "type": "decision",
+                "label": decision.label,
+                "position": {"x": float(index * 240), "y": 60.0 if index % 2 == 0 else 180.0},
+                "data": {
+                    "kind": decision.kind,
+                    "summary": decision.rationale_summary,
+                    "decisionId": decision.id,
+                    "evidenceIds": decision.evidence_event_ids,
+                    "outcome": decision.outcome,
+                },
+            }
+        )
+        if index > 0:
+            edges.append(
+                {
+                    "id": f"edge-decision-{decisions[index - 1].id}-{decision.id}",
+                    "source": f"decision-{decisions[index - 1].id}",
+                    "target": f"decision-{decision.id}",
+                    "label": decision.kind,
+                    "animated": decision.kind in {"retry", "recovery"},
+                }
+            )
+    return {"nodes": nodes, "edges": edges}