universal-agent-context 0.2.0__py3-none-any.whl

uacs/visualization/visualization.py

@@ -0,0 +1,328 @@
+"""Visualization for shared context and agent interactions.
+
+Provides real-time terminal visualizations of:
+1. Context flow between agents
+2. Token usage and compression
+3. Agent dependency graphs
+4. Memory efficiency
+"""
+
+import time
+from typing import Any
+
+from rich import box
+from rich.align import Align
+from rich.console import Console
+from rich.layout import Layout
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.tree import Tree
+
+
+class ContextVisualizer:
+    """Real-time visualization of shared context."""
+
+    def __init__(self, console: Console | None = None):
+        """Initialize visualizer.
+
+        Args:
+            console: Rich console instance
+        """
+        self.console = console or Console()
+
+    def render_context_graph(self, graph: dict[str, Any]) -> Panel:
+        """Render context graph as tree structure.
+
+        Args:
+            graph: Graph structure from SharedContextManager
+
+        Returns:
+            Rich Panel with graph visualization
+        """
+        tree = Tree("🧠 Shared Context Graph")
+
+        # Group nodes by type
+        entries = [n for n in graph["nodes"] if n["type"] == "entry"]
+        summaries = [n for n in graph["nodes"] if n["type"] == "summary"]
+
+        # Add entry branch
+        if entries:
+            entries_branch = tree.add("📝 Context Entries")
+            for entry in entries:
+                agent_icon = self._get_agent_icon(entry.get("agent", "unknown"))
+                entries_branch.add(
+                    f"{agent_icon} {entry['id']} "
+                    f"({entry['tokens']} tokens) "
+                    f"[dim]{entry['timestamp'][:19]}[/dim]"
+                )
+
+        # Add summary branch
+        if summaries:
+            summaries_branch = tree.add("🗜️  Summaries")
+            for summary in summaries:
+                summaries_branch.add(
+                    f"📦 {summary['id']} "
+                    f"({summary['entry_count']} entries, "
+                    f"{summary['tokens_saved']} tokens saved)"
+                )
+
+        # Add edges info
+        if graph["edges"]:
+            edges_branch = tree.add(f"🔗 References ({len(graph['edges'])})")
+            for edge in graph["edges"][:5]:  # Show first 5
+                edges_branch.add(
+                    f"{edge['source']} → {edge['target']} [dim]({edge['type']})[/dim]"
+                )
+
+        return Panel(
+            tree, title="Context Relationships", border_style="cyan", box=box.ROUNDED
+        )
+
+    def render_stats_table(self, stats: dict[str, Any]) -> Table:
+        """Render context statistics as table.
+
+        Args:
+            stats: Statistics from SharedContextManager
+
+        Returns:
+            Rich Table with statistics
+        """
+        table = Table(
+            title="💾 Context Statistics",
+            show_header=False,
+            box=box.SIMPLE,
+            padding=(0, 2),
+        )
+
+        table.add_column("Metric", style="cyan")
+        table.add_column("Value", style="green")
+
+        table.add_row("Entries", str(stats["entry_count"]))
+        table.add_row("Summaries", str(stats["summary_count"]))
+        table.add_row("Total Tokens", f"{stats['total_tokens']:,}")
+        table.add_row("Tokens Saved", f"{stats['tokens_saved']:,}")
+        table.add_row("Compression", stats["compression_ratio"])
+        table.add_row("Storage", f"{stats['storage_size_mb']:.2f} MB")
+
+        return table
+
+    def render_agent_flow(self, entries: list) -> Panel:
+        """Render agent interaction flow.
+
+        Args:
+            entries: List of context entries
+
+        Returns:
+            Rich Panel with flow visualization
+        """
+        flow_lines = []
+
+        for i, entry in enumerate(entries[-10:]):  # Last 10 entries
+            agent = entry.get("agent", "unknown")
+            agent_icon = self._get_agent_icon(agent)
+            tokens = entry.get("token_estimate", 0)
+
+            # Create flow arrow
+            arrow = "  └─>" if i > 0 else "  ┌─>"
+            flow_lines.append(
+                f"{arrow} {agent_icon} [bold]{agent}[/bold] "
+                f"[dim]({tokens} tokens)[/dim]"
+            )
+
+        flow_text = "\n".join(flow_lines) if flow_lines else "[dim]No entries yet[/dim]"
+
+        return Panel(
+            flow_text,
+            title="🔄 Agent Interaction Flow",
+            border_style="blue",
+            box=box.ROUNDED,
+        )
+
+    def render_token_meter(self, used_tokens: int, max_tokens: int = 8000) -> Panel:
+        """Render token usage meter.
+
+        Args:
+            used_tokens: Current token count
+            max_tokens: Maximum tokens
+
+        Returns:
+            Rich Panel with token meter
+        """
+        percentage = (used_tokens / max_tokens) * 100
+        bar_width = 40
+        filled = int((percentage / 100) * bar_width)
+
+        # Choose color based on usage
+        if percentage < 50:
+            color = "green"
+        elif percentage < 80:
+            color = "yellow"
+        else:
+            color = "red"
+
+        bar = f"[{color}]{'█' * filled}[/]{color}{'░' * (bar_width - filled)}"
+
+        meter_text = f"""
+{bar}
+
+Used: {used_tokens:,} / {max_tokens:,} tokens ({percentage:.1f}%)
+Remaining: {max_tokens - used_tokens:,} tokens
+"""
+
+        return Panel(
+            meter_text.strip(),
+            title="🎯 Token Budget",
+            border_style=color,
+            box=box.ROUNDED,
+        )
+
+    def render_dashboard(
+        self,
+        graph: dict[str, Any],
+        stats: dict[str, Any],
+        token_usage: dict[str, int] | None = None,
+    ) -> Layout:
+        """Render complete dashboard layout.
+
+        Args:
+            graph: Context graph
+            stats: Context statistics
+            token_usage: Token usage info
+
+        Returns:
+            Rich Layout with full dashboard
+        """
+        layout = Layout()
+
+        # Split into sections
+        layout.split_column(
+            Layout(name="header", size=3),
+            Layout(name="body"),
+            Layout(name="footer", size=3),
+        )
+
+        # Header
+        layout["header"].update(
+            Panel(Align.center("🤖 Multi-Agent Context Dashboard"), style="bold cyan")
+        )
+
+        # Body - split into left and right
+        layout["body"].split_row(Layout(name="left"), Layout(name="right"))
+
+        # Left side - graph and flow
+        layout["left"].split_column(Layout(name="graph"), Layout(name="flow"))
+
+        layout["graph"].update(self.render_context_graph(graph))
+
+        if graph["nodes"]:
+            layout["flow"].update(self.render_agent_flow(graph["nodes"]))
+
+        # Right side - stats and tokens
+        layout["right"].split_column(Layout(name="stats"), Layout(name="tokens"))
+
+        layout["stats"].update(Panel(self.render_stats_table(stats)))
+
+        if token_usage:
+            layout["tokens"].update(
+                self.render_token_meter(
+                    token_usage.get("used", 0), token_usage.get("max", 8000)
+                )
+            )
+
+        # Footer
+        layout["footer"].update(
+            Panel(
+                "[dim]Press Ctrl+C to exit | Data updates every 2 seconds[/dim]",
+                style="dim",
+            )
+        )
+
+        return layout
+
+    def live_dashboard(self, context_manager, update_interval: float = 2.0):
+        """Run live updating dashboard.
+
+        Args:
+            context_manager: SharedContextManager instance
+            update_interval: Seconds between updates
+        """
+        with Live(
+            self.render_dashboard(
+                context_manager.get_context_graph(),
+                context_manager.get_stats(),
+                {
+                    "used": sum(
+                        e.token_estimate for e in context_manager.entries.values()
+                    )
+                },
+            ),
+            refresh_per_second=1,
+            screen=True,
+        ) as live:
+            try:
+                while True:
+                    time.sleep(update_interval)
+
+                    # Update dashboard
+                    graph = context_manager.get_context_graph()
+                    stats = context_manager.get_stats()
+                    token_usage = {
+                        "used": sum(
+                            e.token_estimate for e in context_manager.entries.values()
+                        ),
+                        "max": 8000,
+                    }
+
+                    live.update(self.render_dashboard(graph, stats, token_usage))
+            except KeyboardInterrupt:
+                pass
+
+    def _get_agent_icon(self, agent: str) -> str:
+        """Get icon for agent type.
+
+        Args:
+            agent: Agent name
+
+        Returns:
+            Icon emoji
+        """
+        icons = {
+            "claude": "🔵",
+            "gemini": "🟣",
+            "copilot": "🟢",
+            "openai": "🟡",
+            "orchestrator": "🎭",
+        }
+        return icons.get(agent.lower(), "⚪")
+
+    def render_compression_viz(
+        self, before_tokens: int, after_tokens: int, method: str = "summary"
+    ) -> Panel:
+        """Visualize compression effect.
+
+        Args:
+            before_tokens: Tokens before compression
+            after_tokens: Tokens after compression
+            method: Compression method used
+
+        Returns:
+            Rich Panel showing compression
+        """
+        savings = before_tokens - after_tokens
+        percentage = (savings / before_tokens * 100) if before_tokens > 0 else 0
+
+        viz = f"""
+Before:  {"█" * int(before_tokens / 100)} ({before_tokens:,} tokens)
+After:   {"█" * int(after_tokens / 100)} ({after_tokens:,} tokens)
+
+[green]Saved: {savings:,} tokens ({percentage:.1f}%)[/green]
+Method: {method}
+"""
+
+        return Panel(
+            viz.strip(),
+            title="🗜️  Compression Effect",
+            border_style="green",
+            box=box.ROUNDED,
+        )

uacs/visualization/web_server.py

@@ -0,0 +1,364 @@
+"""Web server for UACS Context Graph Visualization.
+
+Provides a FastAPI HTTP server with WebSocket support for real-time
+visualization of context graphs, token usage, and deduplication.
+"""
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.middleware.cors import CORSMiddleware
+
+from uacs.context.shared_context import SharedContextManager
+
+logger = logging.getLogger(__name__)
+
+
+class VisualizationServer:
+    """Web server for context visualization."""
+
+    def __init__(
+        self,
+        context_manager: SharedContextManager,
+        host: str = "localhost",
+        port: int = 8081,
+    ):
+        """Initialize visualization server.
+
+        Args:
+            context_manager: SharedContextManager instance
+            host: Server host
+            port: Server port
+        """
+        self.context_manager = context_manager
+        self.host = host
+        self.port = port
+        self.app = FastAPI(title="UACS Context Visualizer")
+
+        # Store active WebSocket connections
+        self.active_connections: list[WebSocket] = []
+
+        # Setup CORS
+        self.app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+        # Setup routes
+        self._setup_routes()
+
+        # Setup static files
+        static_dir = Path(__file__).parent / "static"
+        if static_dir.exists():
+            self.app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+
+    def _setup_routes(self):
+        """Setup API routes."""
+
+        @self.app.get("/", response_class=HTMLResponse)
+        async def index():
+            """Serve main visualization page."""
+            html_file = Path(__file__).parent / "static" / "index.html"
+            if html_file.exists():
+                return html_file.read_text()
+            return HTMLResponse(content=self._get_default_html(), status_code=200)
+
+        @self.app.get("/api/graph")
+        async def get_graph():
+            """Get context graph data.
+
+            Returns:
+                JSON representation of context graph
+            """
+            try:
+                graph = self.context_manager.get_context_graph()
+                return JSONResponse(content=graph)
+            except Exception as e:
+                logger.error("Error getting graph: %s", e)
+                return JSONResponse(
+                    content={"error": str(e)},
+                    status_code=500
+                )
+
+        @self.app.get("/api/stats")
+        async def get_stats():
+            """Get token and compression statistics.
+
+            Returns:
+                JSON representation of stats
+            """
+            try:
+                stats = self.context_manager.get_stats()
+                return JSONResponse(content=stats)
+            except Exception as e:
+                logger.error("Error getting stats: %s", e)
+                return JSONResponse(
+                    content={"error": str(e)},
+                    status_code=500
+                )
+
+        @self.app.get("/api/topics")
+        async def get_topics():
+            """Get topic clusters from context entries.
+
+            Returns:
+                JSON representation of topic clusters
+            """
+            try:
+                topics = self._get_topic_clusters()
+                return JSONResponse(content=topics)
+            except Exception as e:
+                logger.error("Error getting topics: %s", e)
+                return JSONResponse(
+                    content={"error": str(e)},
+                    status_code=500
+                )
+
+        @self.app.get("/api/deduplication")
+        async def get_deduplication():
+            """Get deduplication information.
+
+            Returns:
+                JSON representation of duplicate content areas
+            """
+            try:
+                dedup_data = self._get_deduplication_data()
+                return JSONResponse(content=dedup_data)
+            except Exception as e:
+                logger.error("Error getting deduplication data: %s", e)
+                return JSONResponse(
+                    content={"error": str(e)},
+                    status_code=500
+                )
+
+        @self.app.get("/api/quality")
+        async def get_quality():
+            """Get quality distribution of context entries.
+
+            Returns:
+                JSON representation of quality scores
+            """
+            try:
+                quality_data = self._get_quality_distribution()
+                return JSONResponse(content=quality_data)
+            except Exception as e:
+                logger.error("Error getting quality data: %s", e)
+                return JSONResponse(
+                    content={"error": str(e)},
+                    status_code=500
+                )
+
+        @self.app.websocket("/ws")
+        async def websocket_endpoint(websocket: WebSocket):
+            """WebSocket endpoint for real-time updates."""
+            await self._handle_websocket(websocket)
+
+        @self.app.get("/health")
+        async def health():
+            """Health check endpoint."""
+            return JSONResponse(content={"status": "ok"})
+
+    async def _handle_websocket(self, websocket: WebSocket):
+        """Handle WebSocket connection for real-time updates.
+
+        Args:
+            websocket: WebSocket connection
+        """
+        await websocket.accept()
+        self.active_connections.append(websocket)
+
+        try:
+            while True:
+                # Send updates every 2 seconds
+                await asyncio.sleep(2)
+
+                data = {
+                    "type": "update",
+                    "graph": self.context_manager.get_context_graph(),
+                    "stats": self.context_manager.get_stats(),
+                    "topics": self._get_topic_clusters(),
+                    "quality": self._get_quality_distribution(),
+                }
+
+                await websocket.send_json(data)
+        except WebSocketDisconnect:
+            self.active_connections.remove(websocket)
+        except Exception as e:
+            logger.error("WebSocket error: %s", e)
+            if websocket in self.active_connections:
+                self.active_connections.remove(websocket)
+
+    def _get_topic_clusters(self) -> dict[str, Any]:
+        """Get topic clusters from context entries.
+
+        Returns:
+            Dictionary with topic cluster information
+        """
+        # Count topics across entries
+        topic_counts: dict[str, int] = {}
+        topic_entries: dict[str, list[str]] = {}
+
+        for entry in self.context_manager.entries.values():
+            for topic in entry.topics:
+                topic_counts[topic] = topic_counts.get(topic, 0) + 1
+                if topic not in topic_entries:
+                    topic_entries[topic] = []
+                topic_entries[topic].append(entry.id)
+
+        # Create clusters
+        clusters = []
+        for topic, count in topic_counts.items():
+            clusters.append({
+                "topic": topic,
+                "count": count,
+                "entries": topic_entries[topic],
+            })
+
+        # Sort by count
+        clusters.sort(key=lambda x: x["count"], reverse=True)
+
+        return {
+            "clusters": clusters,
+            "total_topics": len(clusters),
+        }
+
+    def _get_deduplication_data(self) -> dict[str, Any]:
+        """Get deduplication information.
+
+        Returns:
+            Dictionary with deduplication statistics
+        """
+        # Get all unique hashes
+        unique_hashes = set(entry.hash for entry in self.context_manager.entries.values())
+
+        # Count duplicates prevented by dedup index
+        total_possible = len(self.context_manager.entries) + len(self.context_manager.dedup_index) - len(unique_hashes)
+        duplicates_prevented = len(self.context_manager.dedup_index) - len(unique_hashes)
+
+        return {
+            "unique_entries": len(unique_hashes),
+            "total_entries": len(self.context_manager.entries),
+            "duplicates_prevented": duplicates_prevented,
+            "deduplication_rate": f"{(duplicates_prevented / total_possible * 100):.1f}%" if total_possible > 0 else "0%",
+        }
+
+    def _get_quality_distribution(self) -> dict[str, Any]:
+        """Get quality distribution of entries.
+
+        Returns:
+            Dictionary with quality distribution data
+        """
+        qualities = [entry.quality for entry in self.context_manager.entries.values()]
+
+        if not qualities:
+            return {
+                "distribution": [],
+                "average": 0,
+                "high_quality": 0,
+                "medium_quality": 0,
+                "low_quality": 0,
+            }
+
+        # Create distribution buckets
+        high_quality = sum(1 for q in qualities if q >= 0.8)
+        medium_quality = sum(1 for q in qualities if 0.5 <= q < 0.8)
+        low_quality = sum(1 for q in qualities if q < 0.5)
+
+        distribution = [
+            {"range": "High (0.8-1.0)", "count": high_quality},
+            {"range": "Medium (0.5-0.8)", "count": medium_quality},
+            {"range": "Low (0-0.5)", "count": low_quality},
+        ]
+
+        return {
+            "distribution": distribution,
+            "average": sum(qualities) / len(qualities),
+            "high_quality": high_quality,
+            "medium_quality": medium_quality,
+            "low_quality": low_quality,
+        }
+
+    def _get_default_html(self) -> str:
+        """Get default HTML if static file doesn't exist.
+
+        Returns:
+            HTML string
+        """
+        return """
+<!DOCTYPE html>
+<html>
+<head>
+    <title>UACS Context Visualizer</title>
+</head>
+<body>
+    <h1>UACS Context Visualizer</h1>
+    <p>Static files not found. Please check the installation.</p>
+</body>
+</html>
+"""
+
+    async def broadcast_update(self, data: dict[str, Any]):
+        """Broadcast update to all connected WebSocket clients.
+
+        Args:
+            data: Data to broadcast
+        """
+        disconnected = []
+
+        for connection in self.active_connections:
+            try:
+                await connection.send_json(data)
+            except Exception as e:
+                logger.error("Error broadcasting to connection: %s", e)
+                disconnected.append(connection)
+
+        # Remove disconnected clients
+        for connection in disconnected:
+            self.active_connections.remove(connection)
+
+
+async def start_visualization_server(
+    context_manager: SharedContextManager,
+    host: str = "localhost",
+    port: int = 8081,
+) -> VisualizationServer:
+    """Start the visualization server.
+
+    Args:
+        context_manager: SharedContextManager instance
+        host: Server host
+        port: Server port
+
+    Returns:
+        VisualizationServer instance
+    """
+    import uvicorn
+
+    server = VisualizationServer(context_manager, host, port)
+
+    # Create server config
+    config = uvicorn.Config(
+        server.app,
+        host=host,
+        port=port,
+        log_level="info",
+    )
+
+    # Start server in background
+    uvicorn_server = uvicorn.Server(config)
+
+    logger.info("Starting visualization server on %s:%s", host, port)
+
+    # Run server
+    await uvicorn_server.serve()
+
+    return server