athar 0.1.0__py3-none-any.whl

athar/__init__.py

@@ -0,0 +1,25 @@
+"""
+Athar (أثر): A local-first, time-travel debugger for multi-agent LLM systems.
+"""
+
+from .core.tracer import (
+    traced,
+    TracerContext,
+    get_active_trace_id,
+    set_active_trace_id,
+    get_trace_store,
+    set_trace_store,
+)
+from .storage.sqlite_store import TraceStore
+
+__version__ = "0.1.0"
+__all__ = [
+    "traced",
+    "TracerContext",
+    "TraceStore",
+    "get_active_trace_id",
+    "set_active_trace_id",
+    "get_trace_store",
+    "set_trace_store",
+    "__version__",
+]

athar/adapters/crucible_adapter.py

@@ -0,0 +1,17 @@
+from typing import Any, Dict
+from ..core.tracer import traced
+
+class CrucibleAdapter:
+    """
+    Adapter for Crucible integration.
+    """
+    @staticmethod
+    def wrap_agent(agent_instance: Any):
+        """
+        Wraps a Crucible agent's act or run method with our tracer.
+        """
+        if hasattr(agent_instance, "run"):
+            agent_instance.run = traced(agent_instance.run)
+        elif hasattr(agent_instance, "act"):
+            agent_instance.act = traced(agent_instance.act)
+        return agent_instance

athar/core/tracer.py

@@ -0,0 +1,204 @@
+import asyncio
+import contextvars
+import functools
+import hashlib
+import json
+import time
+import uuid
+from typing import Callable, Any, Optional, Dict
+
+from ..storage.sqlite_store import TraceStore
+
+# Context variables for tracking active trace execution context across async/threads
+_active_trace_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar("active_trace_id", default=None)
+_active_parent_node_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar("active_parent_node_id", default=None)
+_global_store: Optional[TraceStore] = None
+
+def get_trace_store() -> TraceStore:
+    """Returns the singleton or newly initialized default TraceStore."""
+    global _global_store
+    if _global_store is None:
+        _global_store = TraceStore()
+    return _global_store
+
+def set_trace_store(store: TraceStore):
+    """Overrides the global trace store (useful for testing or custom paths)."""
+    global _global_store
+    _global_store = store
+
+def get_active_trace_id() -> Optional[str]:
+    """Returns the currently active trace ID if running inside a trace context."""
+    return _active_trace_id.get()
+
+def set_active_trace_id(trace_id: Optional[str]):
+    """Manually sets the active trace ID for the current context."""
+    _active_trace_id.set(trace_id)
+
+
+class TracerContext:
+    """
+    Context manager to scope a sequence of agent calls under a single trace session.
+    Supports both synchronous ('with') and asynchronous ('async with') execution.
+    """
+    def __init__(self, trace_id: Optional[str] = None, name: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None):
+        self.trace_id = trace_id or f"trace_{uuid.uuid4().hex[:12]}"
+        self.name = name
+        self.metadata = metadata or {}
+        self._token_trace: Optional[contextvars.Token] = None
+        self._token_parent: Optional[contextvars.Token] = None
+
+    def __enter__(self):
+        store = get_trace_store()
+        store.ensure_trace(self.trace_id, name=self.name, metadata=self.metadata)
+        self._token_trace = _active_trace_id.set(self.trace_id)
+        self._token_parent = _active_parent_node_id.set(None)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._token_trace:
+            _active_trace_id.reset(self._token_trace)
+        if self._token_parent:
+            _active_parent_node_id.reset(self._token_parent)
+
+    async def __aenter__(self):
+        return self.__enter__()
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        return self.__exit__(exc_type, exc_val, exc_tb)
+
+
+def _compute_hash(inputs_json: str, outputs_json: str) -> str:
+    """Computes a deterministic SHA-256 content hash of inputs and outputs."""
+    hasher = hashlib.sha256()
+    hasher.update(inputs_json.encode("utf-8"))
+    hasher.update(outputs_json.encode("utf-8"))
+    return hasher.hexdigest()
+
+
+def traced(func: Optional[Callable] = None, *, name: Optional[str] = None, cost: float = 0.0) -> Callable:
+    """
+    Decorator to wrap an agent or tool function to record inputs, outputs, state snapshots,
+    latency, and content hashes into Athar's local trace store.
+
+    Usage:
+        @traced
+        def my_agent(prompt: str):
+            ...
+
+        @traced(name="SummarizerTool", cost=0.002)
+        async def call_llm(messages):
+            ...
+    """
+    def decorator(fn: Callable) -> Callable:
+        func_display_name = name or fn.__name__
+
+        if asyncio.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def async_wrapper(*args, **kwargs):
+                store = get_trace_store()
+                
+                # Active or new trace session
+                trace_id = _active_trace_id.get()
+                if not trace_id:
+                    trace_id = f"trace_{uuid.uuid4().hex[:12]}"
+                    store.ensure_trace(trace_id, name=f"Run: {func_display_name}")
+
+                parent_id = _active_parent_node_id.get()
+                node_id = f"node_{uuid.uuid4().hex[:12]}"
+
+                # Serialize inputs
+                input_payload = {"args": args, "kwargs": kwargs}
+                input_json = json.dumps(input_payload, default=str)
+
+                start_time = time.time()
+                result = None
+                error = None
+
+                # Push this node as parent for subsequent nested calls
+                parent_token = _active_parent_node_id.set(node_id)
+                trace_token = _active_trace_id.set(trace_id)
+
+                try:
+                    result = await fn(*args, **kwargs)
+                    return result
+                except Exception as e:
+                    error = str(e)
+                    raise
+                finally:
+                    latency = round(time.time() - start_time, 4)
+                    _active_parent_node_id.reset(parent_token)
+                    _active_trace_id.reset(trace_token)
+
+                    output_payload = {"result": result, "error": error}
+                    output_json = json.dumps(output_payload, default=str)
+                    step_hash = _compute_hash(input_json, output_json)
+
+                    # Store execution step
+                    store.insert_node(
+                        node_id=node_id,
+                        trace_id=trace_id,
+                        parent_node_id=parent_id,
+                        func_name=func_display_name,
+                        input_data=input_payload,
+                        output_data=output_payload,
+                        state_snapshot={"args": repr(args), "kwargs": repr(kwargs)},
+                        latency=latency,
+                        cost=cost,
+                        step_hash=step_hash
+                    )
+            return async_wrapper
+        else:
+            @functools.wraps(fn)
+            def sync_wrapper(*args, **kwargs):
+                store = get_trace_store()
+                
+                trace_id = _active_trace_id.get()
+                if not trace_id:
+                    trace_id = f"trace_{uuid.uuid4().hex[:12]}"
+                    store.ensure_trace(trace_id, name=f"Run: {func_display_name}")
+
+                parent_id = _active_parent_node_id.get()
+                node_id = f"node_{uuid.uuid4().hex[:12]}"
+
+                input_payload = {"args": args, "kwargs": kwargs}
+                input_json = json.dumps(input_payload, default=str)
+
+                start_time = time.time()
+                result = None
+                error = None
+
+                parent_token = _active_parent_node_id.set(node_id)
+                trace_token = _active_trace_id.set(trace_id)
+
+                try:
+                    result = fn(*args, **kwargs)
+                    return result
+                except Exception as e:
+                    error = str(e)
+                    raise
+                finally:
+                    latency = round(time.time() - start_time, 4)
+                    _active_parent_node_id.reset(parent_token)
+                    _active_trace_id.reset(trace_token)
+
+                    output_payload = {"result": result, "error": error}
+                    output_json = json.dumps(output_payload, default=str)
+                    step_hash = _compute_hash(input_json, output_json)
+
+                    store.insert_node(
+                        node_id=node_id,
+                        trace_id=trace_id,
+                        parent_node_id=parent_id,
+                        func_name=func_display_name,
+                        input_data=input_payload,
+                        output_data=output_payload,
+                        state_snapshot={"args": repr(args), "kwargs": repr(kwargs)},
+                        latency=latency,
+                        cost=cost,
+                        step_hash=step_hash
+                    )
+            return sync_wrapper
+
+    if func is not None:
+        return decorator(func)
+    return decorator

athar/storage/sqlite_store.py

@@ -0,0 +1,241 @@
+import sqlite3
+import json
+import os
+import threading
+import uuid
+from typing import Dict, Any, Optional, List
+
+DEFAULT_DB_PATH = os.environ.get("ATHAR_DB_PATH", "agent_traces.db")
+
+class TraceStore:
+    """
+    SQLite-backed local storage for trace steps and execution branches.
+    Uses WAL mode for high-concurrency non-blocking writes from agents
+    and reads from the UI.
+    """
+    def __init__(self, db_path: str = DEFAULT_DB_PATH):
+        self.db_path = db_path
+        self._local = threading.local()
+        self._init_db()
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        if not hasattr(self._local, "conn"):
+            self._local.conn = sqlite3.connect(self.db_path, timeout=10.0)
+            self._local.conn.row_factory = sqlite3.Row
+            # Enforce WAL mode for concurrent multi-process / multi-thread access
+            self._local.conn.execute("PRAGMA journal_mode=WAL;")
+            self._local.conn.execute("PRAGMA synchronous=NORMAL;")
+        return self._local.conn
+
+    def _init_db(self):
+        c = self.conn.cursor()
+        c.execute('''
+            CREATE TABLE IF NOT EXISTS traces (
+                trace_id TEXT PRIMARY KEY,
+                name TEXT,
+                status TEXT DEFAULT 'completed',
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                metadata TEXT
+            )
+        ''')
+        c.execute('''
+            CREATE TABLE IF NOT EXISTS nodes (
+                node_id TEXT PRIMARY KEY,
+                trace_id TEXT NOT NULL,
+                parent_node_id TEXT,
+                branch_id TEXT DEFAULT 'main',
+                func_name TEXT NOT NULL,
+                input_data TEXT,
+                output_data TEXT,
+                state_snapshot TEXT,
+                cost REAL DEFAULT 0.0,
+                latency REAL DEFAULT 0.0,
+                step_hash TEXT,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY(trace_id) REFERENCES traces(trace_id) ON DELETE CASCADE
+            )
+        ''')
+        # Indexes for fast querying
+        c.execute('CREATE INDEX IF NOT EXISTS idx_nodes_trace_id ON nodes(trace_id);')
+        c.execute('CREATE INDEX IF NOT EXISTS idx_nodes_parent_id ON nodes(parent_node_id);')
+        self.conn.commit()
+
+    def ensure_trace(self, trace_id: str, name: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None):
+        """Ensures a trace record exists in the traces table."""
+        c = self.conn.cursor()
+        c.execute("SELECT trace_id FROM traces WHERE trace_id = ?", (trace_id,))
+        if not c.fetchone():
+            meta_json = json.dumps(metadata or {})
+            trace_name = name or f"Trace {trace_id[:8]}"
+            c.execute(
+                "INSERT INTO traces (trace_id, name, metadata) VALUES (?, ?, ?)",
+                (trace_id, trace_name, meta_json)
+            )
+            self.conn.commit()
+
+    def insert_node(
+        self,
+        node_id: str,
+        trace_id: str,
+        parent_node_id: Optional[str],
+        func_name: str,
+        input_data: Any,
+        output_data: Any,
+        state_snapshot: Optional[Any] = None,
+        latency: float = 0.0,
+        cost: float = 0.0,
+        step_hash: Optional[str] = None,
+        branch_id: str = "main"
+    ) -> str:
+        """Inserts a trace node, auto-registering the trace if missing."""
+        self.ensure_trace(trace_id)
+        c = self.conn.cursor()
+        
+        input_json = json.dumps(input_data, default=str) if not isinstance(input_data, str) else input_data
+        output_json = json.dumps(output_data, default=str) if not isinstance(output_data, str) else output_data
+        state_json = json.dumps(state_snapshot or {}, default=str) if not isinstance(state_snapshot, str) else state_snapshot
+
+        c.execute('''
+            INSERT INTO nodes (
+                node_id, trace_id, parent_node_id, branch_id, func_name,
+                input_data, output_data, state_snapshot, cost, latency, step_hash
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ''', (
+            node_id, trace_id, parent_node_id, branch_id, func_name,
+            input_json, output_json, state_json, cost, latency, step_hash
+        ))
+        
+        # Update trace timestamp
+        c.execute("UPDATE traces SET updated_at = CURRENT_TIMESTAMP WHERE trace_id = ?", (trace_id,))
+        self.conn.commit()
+        return node_id
+
+    def list_traces(self) -> List[Dict[str, Any]]:
+        """Returns all traces with aggregated stats (node count, duration)."""
+        c = self.conn.cursor()
+        c.execute('''
+            SELECT 
+                t.trace_id,
+                t.name,
+                t.status,
+                t.created_at,
+                t.updated_at,
+                t.metadata,
+                COUNT(n.node_id) as node_count,
+                COALESCE(SUM(n.latency), 0.0) as total_latency,
+                COALESCE(SUM(n.cost), 0.0) as total_cost
+            FROM traces t
+            LEFT JOIN nodes n ON t.trace_id = n.trace_id
+            GROUP BY t.trace_id
+            ORDER BY t.created_at DESC
+        ''')
+        rows = c.fetchall()
+        result = []
+        for row in rows:
+            item = dict(row)
+            try:
+                item["metadata"] = json.loads(item["metadata"]) if item["metadata"] else {}
+            except Exception:
+                item["metadata"] = {}
+            result.append(item)
+        return result
+
+    def get_trace(self, trace_id: str) -> Optional[Dict[str, Any]]:
+        c = self.conn.cursor()
+        c.execute("SELECT * FROM traces WHERE trace_id = ?", (trace_id,))
+        row = c.fetchone()
+        if not row:
+            return None
+        item = dict(row)
+        try:
+            item["metadata"] = json.loads(item["metadata"]) if item["metadata"] else {}
+        except Exception:
+            item["metadata"] = {}
+        return item
+
+    def get_nodes(self, trace_id: str) -> List[Dict[str, Any]]:
+        """Returns all nodes for a given trace sorted chronologically."""
+        c = self.conn.cursor()
+        c.execute("SELECT * FROM nodes WHERE trace_id = ? ORDER BY created_at ASC", (trace_id,))
+        rows = c.fetchall()
+        nodes = []
+        for row in rows:
+            node = dict(row)
+            try:
+                node["input_data"] = json.loads(node["input_data"]) if node["input_data"] else None
+            except Exception:
+                pass
+            try:
+                node["output_data"] = json.loads(node["output_data"]) if node["output_data"] else None
+            except Exception:
+                pass
+            try:
+                node["state_snapshot"] = json.loads(node["state_snapshot"]) if node["state_snapshot"] else {}
+            except Exception:
+                pass
+            nodes.append(node)
+        return nodes
+
+    def get_node(self, node_id: str) -> Optional[Dict[str, Any]]:
+        c = self.conn.cursor()
+        c.execute("SELECT * FROM nodes WHERE node_id = ?", (node_id,))
+        row = c.fetchone()
+        if not row:
+            return None
+        node = dict(row)
+        try:
+            node["input_data"] = json.loads(node["input_data"]) if node["input_data"] else None
+        except Exception:
+            pass
+        try:
+            node["output_data"] = json.loads(node["output_data"]) if node["output_data"] else None
+        except Exception:
+            pass
+        try:
+            node["state_snapshot"] = json.loads(node["state_snapshot"]) if node["state_snapshot"] else {}
+        except Exception:
+            pass
+        return node
+
+    def delete_trace(self, trace_id: str) -> bool:
+        c = self.conn.cursor()
+        c.execute("DELETE FROM nodes WHERE trace_id = ?", (trace_id,))
+        c.execute("DELETE FROM traces WHERE trace_id = ?", (trace_id,))
+        self.conn.commit()
+        return c.rowcount > 0
+
+    def fork_node(self, node_id: str, new_state: Dict[str, Any], branch_name: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Creates a branched execution node from an existing step with mutated state.
+        """
+        original = self.get_node(node_id)
+        if not original:
+            raise ValueError(f"Node {node_id} not found.")
+
+        new_node_id = f"node_{uuid.uuid4().hex[:12]}"
+        branch_id = branch_name or f"branch_{uuid.uuid4().hex[:6]}"
+
+        # Record the forked replay node
+        self.insert_node(
+            node_id=new_node_id,
+            trace_id=original["trace_id"],
+            parent_node_id=original["parent_node_id"],
+            func_name=f"{original['func_name']} (forked)",
+            input_data={"mutated_state": new_state, "forked_from": node_id},
+            output_data={"status": "replayed", "message": "Replay execution initialized from mutated state"},
+            state_snapshot=new_state,
+            latency=0.001,
+            cost=0.0,
+            step_hash=f"fork_{uuid.uuid4().hex[:8]}",
+            branch_id=branch_id
+        )
+
+        return {
+            "original_node_id": node_id,
+            "new_node_id": new_node_id,
+            "branch_id": branch_id,
+            "trace_id": original["trace_id"]
+        }

athar/ui/app.py

@@ -0,0 +1,184 @@
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import RedirectResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+import os
+import time
+from typing import List, Dict, Any, Optional
+
+from ..storage.sqlite_store import TraceStore
+
+app = FastAPI(
+    title="Athar UI & API",
+    description="Local-first time-travel debugger for multi-agent LLM systems",
+    version="0.1.0"
+)
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+STATIC_DIR = os.path.join(BASE_DIR, "static")
+
+if os.path.exists(STATIC_DIR):
+    app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+def get_store() -> TraceStore:
+    db_path = os.environ.get("ATHAR_DB_PATH", "agent_traces.db")
+    return TraceStore(db_path=db_path)
+
+class ReplayRequest(BaseModel):
+    new_state: Dict[str, Any]
+    branch_name: Optional[str] = None
+
+class CreateTraceRequest(BaseModel):
+    name: Optional[str] = None
+    trace_id: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+@app.get("/", include_in_schema=False)
+def root_redirect():
+    return RedirectResponse(url="/static/index.html")
+
+@app.get("/api/health")
+def health():
+    return {
+        "status": "healthy",
+        "service": "athar",
+        "version": "0.1.0",
+        "storage": "sqlite-wal"
+    }
+
+@app.get("/api/traces")
+def list_traces():
+    store = get_store()
+    traces = store.list_traces()
+    return {"traces": traces, "count": len(traces)}
+
+@app.get("/api/traces/{trace_id}")
+def get_trace(trace_id: str):
+    store = get_store()
+    trace = store.get_trace(trace_id)
+    if not trace:
+        raise HTTPException(status_code=404, detail="Trace not found")
+    return {"trace": trace}
+
+@app.get("/api/traces/{trace_id}/nodes")
+def get_trace_nodes(trace_id: str):
+    store = get_store()
+    nodes = store.get_nodes(trace_id)
+    return {"trace_id": trace_id, "nodes": nodes, "count": len(nodes)}
+
+@app.post("/api/traces")
+def create_trace(payload: CreateTraceRequest):
+    store = get_store()
+    trace_id = payload.trace_id or f"trace_{int(time.time()*1000)}"
+    store.ensure_trace(trace_id, name=payload.name, metadata=payload.metadata)
+    return {"status": "created", "trace_id": trace_id}
+
+@app.post("/api/replay/{node_id}")
+def replay_from_node(node_id: str, payload: ReplayRequest):
+    """
+    Fork-and-replay from the given step.
+    Creates a new branch in the trace graph with mutated state.
+    """
+    store = get_store()
+    node = store.get_node(node_id)
+    if not node:
+        raise HTTPException(status_code=404, detail=f"Node {node_id} not found")
+
+    try:
+        fork_result = store.fork_node(
+            node_id=node_id,
+            new_state=payload.new_state,
+            branch_name=payload.branch_name
+        )
+        return {
+            "status": "success",
+            "message": f"Successfully forked from node {node_id}",
+            "data": fork_result
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.delete("/api/traces/{trace_id}")
+def delete_trace(trace_id: str):
+    store = get_store()
+    deleted = store.delete_trace(trace_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="Trace not found")
+    return {"status": "deleted", "trace_id": trace_id}
+
+@app.post("/api/seed-sample")
+def seed_sample_trace():
+    """Seeds a realistic sample multi-agent research trace for instant demonstration."""
+    store = get_store()
+    sample_trace_id = f"sample_trace_{int(time.time())}"
+    store.ensure_trace(
+        sample_trace_id,
+        name="Multi-Agent Market Analysis",
+        metadata={"author": "Athar Demo", "environment": "local"}
+    )
+
+    # Step 1: User prompt
+    n1 = store.insert_node(
+        node_id=f"node_root_{int(time.time())}",
+        trace_id=sample_trace_id,
+        parent_node_id=None,
+        func_name="orchestrator_agent",
+        input_data={"user_prompt": "Analyze impact of AI code assistants on engineering velocity."},
+        output_data={"delegations": ["web_search_tool", "data_synthesis_agent"]},
+        state_snapshot={"step": 1, "status": "planning"},
+        latency=0.32,
+        cost=0.0015,
+        step_hash="sha256_root_step_sample"
+    )
+
+    # Step 2: Tool call
+    n2 = store.insert_node(
+        node_id=f"node_tool_{int(time.time())}",
+        trace_id=sample_trace_id,
+        parent_node_id=n1,
+        func_name="web_search_tool",
+        input_data={"query": "AI coding tools benchmark velocity 2026"},
+        output_data={"results": ["Benchmark A: 35% speedup in boilerplate", "Benchmark B: 42% PR cycle time drop"]},
+        state_snapshot={"step": 2, "cache_hit": False},
+        latency=0.74,
+        cost=0.0008,
+        step_hash="sha256_search_tool_sample"
+    )
+
+    # Step 3: Synthesis
+    store.insert_node(
+        node_id=f"node_synth_{int(time.time())}",
+        trace_id=sample_trace_id,
+        parent_node_id=n2,
+        func_name="data_synthesis_agent",
+        input_data={"raw_metrics": ["35% speedup", "42% PR drop"]},
+        output_data={"final_report": "AI assistants show measured 35-42% reduction in cycle times for routine tasks."},
+        state_snapshot={"step": 3, "confidence": 0.94},
+        latency=1.15,
+        cost=0.0042,
+        step_hash="sha256_synthesis_sample"
+    )
+
+    return {"status": "seeded", "trace_id": sample_trace_id}
+
+def main():
+    import argparse
+    import uvicorn
+
+    parser = argparse.ArgumentParser(description="Athar: Local-first time-travel debugger for LLM agents")
+    parser.add_argument("--port", type=int, default=4173, help="Port to run the UI server on (default: 4173)")
+    parser.add_argument("--host", type=str, default="127.0.0.1", help="Host interface (default: 127.0.0.1)")
+    parser.add_argument("--db", type=str, default=None, help="Custom SQLite trace DB path")
+    args = parser.parse_args()
+
+    if args.db:
+        os.environ["ATHAR_DB_PATH"] = args.db
+
+    print(f"\n=======================================================")
+    print(f"  ATHAR (أثر) · Local-First Multi-Agent Debugger")
+    print(f"  Web UI: http://{args.host}:{args.port}")
+    print(f"=======================================================\n")
+    uvicorn.run(app, host=args.host, port=args.port)
+
+if __name__ == "__main__":
+    main()