pixelgraph 0.1.0__tar.gz

pixelgraph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Дiegushko Хименес
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pixelgraph-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include requirements.txt
+recursive-include pixelgraph/static *

pixelgraph-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: pixelgraph
+Version: 0.1.0
+Summary: 8-bit visualization for LangGraph agents
+Author-email: Diego <diego@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/diegonov1/PixelGraph
+Project-URL: Repository, https://github.com/diegonov1/PixelGraph
+Project-URL: Issues, https://github.com/diegonov1/PixelGraph/issues
+Keywords: langgraph,langchain,visualization,8-bit,agents,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: langchain-core>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: httpx>=0.25.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.0.40; extra == "langgraph"
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=0.0.5; extra == "openai"
+Provides-Extra: all
+Requires-Dist: pixelgraph[dev,langgraph,openai]; extra == "all"
+Dynamic: license-file
+
+# PixelGraph
+
+> 8-bit visualization for LangGraph agents
+
+PixelGraph transforms your LangGraph agent interactions into a retro 8-bit game experience. Watch your AI agents think, speak, and use tools in a nostalgic pixel-art environment.
+
+## Features
+
+- **Drop-in Integration**: Works with any existing LangGraph application
+- **Real-time Visualization**: See agent thoughts, speech, and tool usage
+- **8-bit Aesthetics**: Pixel art sprites and retro styling
+- **WebSocket Communication**: Bidirectional real-time updates
+- **Action Queue**: Smooth animation sequencing regardless of event speed
+
+## Quick Start
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/diegonov1/PixelGraph.git
+cd PixelGraph
+
+# Install Python dependencies
+pip install -r requirements.txt
+
+# Install frontend dependencies
+cd frontend && npm install && cd ..
+```
+
+### Run Demo Mode
+
+Without any LLM API key, you can run the demo:
+
+```bash
+# Terminal 1: Start backend
+python examples/simple_demo.py
+
+# Terminal 2: Start frontend
+cd frontend && npm run dev
+```
+
+Open http://localhost:3000 in your browser.
+
+### Run with LangGraph
+
+```bash
+# Set your OpenAI API key
+export OPENAI_API_KEY=your-api-key
+
+# Run the LangGraph example
+python examples/langgraph_example.py
+```
+
+## Usage
+
+Integrate PixelGraph with your existing LangGraph application:
+
+```python
+from langgraph.graph import StateGraph
+from pixelgraph import GameServer
+
+# Your existing LangGraph code
+graph = StateGraph(State)
+# ... add nodes and edges ...
+app = graph.compile()
+
+# Add visualization with one line
+server = GameServer(app)
+server.serve()
+```
+
+### Visual Configuration
+
+Customize how agents appear in the game:
+
+```python
+from pixelgraph import GameServer
+from pixelgraph.schemas.events import VisualConfig, AgentConfig
+
+config = VisualConfig(
+    title="My Agent Team",
+    theme="dungeon",
+    nodes={
+        "researcher": AgentConfig(sprite="wizard", color="blue"),
+        "writer": AgentConfig(sprite="bard", color="red"),
+    }
+)
+
+server = GameServer(app, config=config)
+server.serve()
+```
+
+## Architecture
+
+```
+Frontend (React + Phaser)     Backend (FastAPI + LangGraph)
+     ┌─────────────┐              ┌─────────────┐
+     │   Phaser    │◄─WebSocket──►│  GameServer │
+     │   Canvas    │              │             │
+     └─────────────┘              │  Callback   │
+     ┌─────────────┐              │   Handler   │
+     │   React     │              │      ▲      │
+     │   HUD/Log   │              │      │      │
+     └─────────────┘              │  LangGraph  │
+                                  └─────────────┘
+```
+
+### Event Flow
+
+1. LangGraph emits events during execution
+2. `GameVisualizerCallbackHandler` captures and transforms events
+3. Events are sent via WebSocket to the frontend
+4. Frontend queues events in the `ActionQueue`
+5. Phaser consumes events one at a time, playing animations
+
+## Development
+
+### Project Structure
+
+```
+pixelgraph/
+├── pixelgraph/          # Python package
+│   ├── __init__.py      # Package exports
+│   ├── callback.py      # LangChain callback handler
+│   ├── server.py        # FastAPI WebSocket server
+│   ├── schemas/         # Pydantic event schemas
+│   └── static/          # Built frontend (after npm build)
+├── frontend/            # React + Phaser frontend
+│   ├── src/
+│   │   ├── game/        # Phaser logic
+│   │   │   ├── scenes/  # Game scenes
+│   │   │   ├── entities/# Sprite classes
+│   │   │   └── systems/ # Event bus, action queue
+│   │   └── components/  # React UI components
+│   └── public/assets/   # Sprites and assets
+├── examples/            # Usage examples
+└── tests/               # Test suite
+```
+
+### Commands
+
+```bash
+make install      # Install all dependencies
+make dev          # Run both backend and frontend
+make build        # Build frontend for production
+make test         # Run tests
+make docker-dev   # Run with Docker (development)
+make docker-prod  # Run with Docker (production)
+```
+
+## Roadmap
+
+- [ ] Multi-agent support with dynamic positioning
+- [ ] Tool-specific animations (search, calculator, etc.)
+- [ ] Speed control for event playback
+- [ ] Custom sprite support
+- [ ] Themes (dungeon, sci-fi, city)
+- [ ] Export conversation as GIF
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please read our contributing guidelines first.

pixelgraph-0.1.0/README.md

@@ -0,0 +1,167 @@
+# PixelGraph
+
+> 8-bit visualization for LangGraph agents
+
+PixelGraph transforms your LangGraph agent interactions into a retro 8-bit game experience. Watch your AI agents think, speak, and use tools in a nostalgic pixel-art environment.
+
+## Features
+
+- **Drop-in Integration**: Works with any existing LangGraph application
+- **Real-time Visualization**: See agent thoughts, speech, and tool usage
+- **8-bit Aesthetics**: Pixel art sprites and retro styling
+- **WebSocket Communication**: Bidirectional real-time updates
+- **Action Queue**: Smooth animation sequencing regardless of event speed
+
+## Quick Start
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/diegonov1/PixelGraph.git
+cd PixelGraph
+
+# Install Python dependencies
+pip install -r requirements.txt
+
+# Install frontend dependencies
+cd frontend && npm install && cd ..
+```
+
+### Run Demo Mode
+
+Without any LLM API key, you can run the demo:
+
+```bash
+# Terminal 1: Start backend
+python examples/simple_demo.py
+
+# Terminal 2: Start frontend
+cd frontend && npm run dev
+```
+
+Open http://localhost:3000 in your browser.
+
+### Run with LangGraph
+
+```bash
+# Set your OpenAI API key
+export OPENAI_API_KEY=your-api-key
+
+# Run the LangGraph example
+python examples/langgraph_example.py
+```
+
+## Usage
+
+Integrate PixelGraph with your existing LangGraph application:
+
+```python
+from langgraph.graph import StateGraph
+from pixelgraph import GameServer
+
+# Your existing LangGraph code
+graph = StateGraph(State)
+# ... add nodes and edges ...
+app = graph.compile()
+
+# Add visualization with one line
+server = GameServer(app)
+server.serve()
+```
+
+### Visual Configuration
+
+Customize how agents appear in the game:
+
+```python
+from pixelgraph import GameServer
+from pixelgraph.schemas.events import VisualConfig, AgentConfig
+
+config = VisualConfig(
+    title="My Agent Team",
+    theme="dungeon",
+    nodes={
+        "researcher": AgentConfig(sprite="wizard", color="blue"),
+        "writer": AgentConfig(sprite="bard", color="red"),
+    }
+)
+
+server = GameServer(app, config=config)
+server.serve()
+```
+
+## Architecture
+
+```
+Frontend (React + Phaser)     Backend (FastAPI + LangGraph)
+     ┌─────────────┐              ┌─────────────┐
+     │   Phaser    │◄─WebSocket──►│  GameServer │
+     │   Canvas    │              │             │
+     └─────────────┘              │  Callback   │
+     ┌─────────────┐              │   Handler   │
+     │   React     │              │      ▲      │
+     │   HUD/Log   │              │      │      │
+     └─────────────┘              │  LangGraph  │
+                                  └─────────────┘
+```
+
+### Event Flow
+
+1. LangGraph emits events during execution
+2. `GameVisualizerCallbackHandler` captures and transforms events
+3. Events are sent via WebSocket to the frontend
+4. Frontend queues events in the `ActionQueue`
+5. Phaser consumes events one at a time, playing animations
+
+## Development
+
+### Project Structure
+
+```
+pixelgraph/
+├── pixelgraph/          # Python package
+│   ├── __init__.py      # Package exports
+│   ├── callback.py      # LangChain callback handler
+│   ├── server.py        # FastAPI WebSocket server
+│   ├── schemas/         # Pydantic event schemas
+│   └── static/          # Built frontend (after npm build)
+├── frontend/            # React + Phaser frontend
+│   ├── src/
+│   │   ├── game/        # Phaser logic
+│   │   │   ├── scenes/  # Game scenes
+│   │   │   ├── entities/# Sprite classes
+│   │   │   └── systems/ # Event bus, action queue
+│   │   └── components/  # React UI components
+│   └── public/assets/   # Sprites and assets
+├── examples/            # Usage examples
+└── tests/               # Test suite
+```
+
+### Commands
+
+```bash
+make install      # Install all dependencies
+make dev          # Run both backend and frontend
+make build        # Build frontend for production
+make test         # Run tests
+make docker-dev   # Run with Docker (development)
+make docker-prod  # Run with Docker (production)
+```
+
+## Roadmap
+
+- [ ] Multi-agent support with dynamic positioning
+- [ ] Tool-specific animations (search, calculator, etc.)
+- [ ] Speed control for event playback
+- [ ] Custom sprite support
+- [ ] Themes (dungeon, sci-fi, city)
+- [ ] Export conversation as GIF
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please read our contributing guidelines first.

pixelgraph-0.1.0/pixelgraph/__init__.py

@@ -0,0 +1,12 @@
+"""
+PixelGraph - 8-bit visualization for LangGraph agents
+
+A drop-in visualization library that transforms your LangGraph
+agent interactions into an 8-bit game experience.
+"""
+
+from pixelgraph.server import GameServer
+from pixelgraph.callback import GameVisualizerCallbackHandler, GameEventType
+
+__version__ = "0.1.0"
+__all__ = ["GameServer", "GameVisualizerCallbackHandler", "GameEventType"]

pixelgraph-0.1.0/pixelgraph/callback.py

@@ -0,0 +1,199 @@
+"""
+GameVisualizerCallbackHandler - The bridge between LangGraph and the visualization.
+
+This callback handler captures events from LangChain/LangGraph execution
+and transforms them into game events for the 8-bit frontend.
+"""
+
+import asyncio
+from datetime import datetime
+from typing import Any, Optional
+from uuid import UUID, uuid4
+
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.outputs import LLMResult, ChatGeneration
+
+
+class GameEventType:
+    """Event types that the frontend (Phaser) understands."""
+
+    AGENT_THINK_START = "AGENT_THINK_START"
+    AGENT_SPEAK = "AGENT_SPEAK"
+    TOOL_START = "TOOL_START"
+    TOOL_END = "TOOL_END"
+    AGENT_IDLE = "AGENT_IDLE"
+    ERROR = "ERROR"
+
+
+class GameVisualizerCallbackHandler(BaseCallbackHandler):
+    """
+    Captures LangGraph/LangChain events and sends them to an async queue
+    for consumption by a WebSocket connection.
+
+    This handler acts as a "spy" that observes the execution flow without
+    interfering with it, transforming internal events into visual instructions.
+    """
+
+    def __init__(self, event_queue: asyncio.Queue, default_agent: str = "agent"):
+        """
+        Initialize the callback handler.
+
+        Args:
+            event_queue: Async queue where events will be pushed
+            default_agent: Default agent name when none is specified in metadata
+        """
+        super().__init__()
+        self.queue = event_queue
+        self.current_active_agent = default_agent
+        self._loop = None
+
+    def _get_loop(self) -> asyncio.AbstractEventLoop:
+        """Get or create the event loop."""
+        if self._loop is None or self._loop.is_closed():
+            try:
+                self._loop = asyncio.get_running_loop()
+            except RuntimeError:
+                self._loop = asyncio.new_event_loop()
+        return self._loop
+
+    def _emit_event_sync(
+        self, event_type: str, agent_name: str, payload: dict[str, Any] | None = None
+    ):
+        """Synchronously emit an event to the queue."""
+        event = {
+            "event_id": str(uuid4()),
+            "timestamp": datetime.utcnow().isoformat(),
+            "type": event_type,
+            "agent_id": agent_name,
+            "data": payload or {},
+        }
+
+        loop = self._get_loop()
+        if loop.is_running():
+            asyncio.run_coroutine_threadsafe(self.queue.put(event), loop)
+        else:
+            self.queue.put_nowait(event)
+
+    async def _emit_event(
+        self, event_type: str, agent_name: str, payload: dict[str, Any] | None = None
+    ):
+        """Asynchronously emit an event to the queue."""
+        event = {
+            "event_id": str(uuid4()),
+            "timestamp": datetime.utcnow().isoformat(),
+            "type": event_type,
+            "agent_id": agent_name,
+            "data": payload or {},
+        }
+        await self.queue.put(event)
+
+    # --- Synchronous Callback Methods (for sync execution) ---
+
+    def on_chat_model_start(
+        self,
+        serialized: dict[str, Any],
+        messages: list[list[Any]],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Triggered when the model receives a prompt and starts processing.
+        Visual: Thought bubble '...' appears over the character.
+        """
+        metadata = metadata or {}
+        agent_name = metadata.get("agent_name", self.current_active_agent)
+        self.current_active_agent = agent_name
+
+        self._emit_event_sync(
+            GameEventType.AGENT_THINK_START, agent_name, {"status": "processing"}
+        )
+
+    def on_llm_end(
+        self,
+        response: LLMResult,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Triggered when the model has finished generating a response.
+        Visual: Speech bubble with the response text.
+        """
+        text_content = ""
+        if response.generations:
+            generation = response.generations[0][0]
+            if isinstance(generation, ChatGeneration):
+                text_content = generation.message.content
+            else:
+                text_content = generation.text
+
+        self._emit_event_sync(
+            GameEventType.AGENT_SPEAK,
+            self.current_active_agent,
+            {"content": text_content},
+        )
+
+        self._emit_event_sync(GameEventType.AGENT_IDLE, self.current_active_agent)
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Triggered when an agent decides to use a tool.
+        Visual: Character shows an icon (e.g., magnifying glass for web search).
+        """
+        tool_name = serialized.get("name", "generic_tool")
+        metadata = metadata or {}
+        agent_name = metadata.get("agent_name", self.current_active_agent)
+
+        self._emit_event_sync(
+            GameEventType.TOOL_START,
+            agent_name,
+            {"tool_name": tool_name, "input_args": input_str[:100]},
+        )
+
+    def on_tool_end(
+        self,
+        output: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Triggered when a tool finishes its work.
+        Visual: Icon disappears or character nods.
+        """
+        self._emit_event_sync(
+            GameEventType.TOOL_END,
+            self.current_active_agent,
+            {"result_preview": output[:50] + "..." if len(output) > 50 else output},
+        )
+
+    def on_chain_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Triggered when an error occurs in the chain."""
+        self._emit_event_sync(
+            GameEventType.ERROR,
+            self.current_active_agent,
+            {"error": str(error)},
+        )