agentviz 0.3.0__tar.gz

agentviz-0.3.0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: agentviz
+Version: 0.3.0
+Summary: Real-time 3D visualization for multi-agent AI systems
+License: MIT
+Project-URL: Homepage, https://github.com/tonystark3110/AGENTVIZ
+Project-URL: Repository, https://github.com/tonystark3110/AGENTVIZ
+Project-URL: Issues, https://github.com/tonystark3110/AGENTVIZ/issues
+Project-URL: Change Log, https://github.com/tonystark3110/AGENTVIZ/releases
+Keywords: ai-agents,multi-agent,visualization,mcp,llm,observability,tracing,opentelemetry
+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 :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.1.0; extra == "langgraph"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.28.0; extra == "crewai"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.0.3; extra == "openai-agents"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otel"
+Provides-Extra: mcp
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.1.0; extra == "all"
+Requires-Dist: langgraph>=0.1.0; extra == "all"
+Requires-Dist: crewai>=0.28.0; extra == "all"
+Requires-Dist: openai-agents>=0.0.3; extra == "all"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "all"
+
+# agentviz
+
+Real-time 3D visualization for multi-agent AI systems. Drop one decorator on your agent functions and watch them appear as robots in a live 3D scene — calls, responses, token streams, errors, and latency all rendered as they happen.
+
+```
+pip install agentviz
+agentviz serve
+```
+
+---
+
+## How it works
+
+1. You run `agentviz serve` — starts a local FastAPI server + opens the 3D UI in your browser
+2. You decorate your agent functions with `@agentviz.trace`
+3. Every call, response, error, and token stream is sent to the server and rendered live
+
+The server can be self-hosted anywhere (Linode, Railway, Docker). Multiple agents on different machines can all connect to the same room.
+
+---
+
+## Quick start
+
+### Simplest — one decorator
+
+```python
+import agentviz
+
+agentviz.init(server="http://localhost:8000")
+
+@agentviz.trace
+async def fetch_data(query: str) -> str:
+    return await db.query(query)
+
+@agentviz.trace(name="Planner", to="orchestrator", color="#9B59B6")
+async def plan(goal: str) -> str:
+    return await llm.plan(goal)
+```
+
+That's it. Run your agents — they show up in the UI automatically.
+
+### Environment variables (zero code changes)
+
+```bash
+export AGENTVIZ_SERVER=http://localhost:8000
+export AGENTVIZ_PROJECT=my-team
+```
+
+Then just use `@agentviz.trace` with no `init()` call.
+
+### WebSocket SDK (full control)
+
+```python
+from agentviz import AgentVizClient
+
+async with AgentVizClient(
+    server="ws://localhost:8000/agent-ws",
+    name="DataFetcher",
+    color="#E74C3C",
+) as client:
+    call_id = await client.emit_call(to="orchestrator", message="Fetching records…")
+    result  = await do_work()
+    await client.emit_response(to="orchestrator", call_id=call_id, result=result)
+```
+
+### HTTP client (serverless / AWS Lambda / Cloud Run)
+
+```python
+from agentviz import HttpAgentVizClient
+
+client = HttpAgentVizClient(server="https://my-agentviz.railway.app", name="Lambda")
+
+call_id = client.emit_call(to="orchestrator", message="Processing event…")
+result  = process(event)
+client.emit_response(to="orchestrator", call_id=call_id, result=result)
+```
+
+### Token streaming
+
+```python
+async for chunk in llm.stream(prompt):
+    await client.emit_token(chunk.delta)
+await client.emit_stream_end()
+```
+
+Tokens accumulate in a speech bubble above the robot in real-time.
+
+---
+
+## Features
+
+- **`@agentviz.trace`** — works on any `async` or `sync` function, no boilerplate
+- **Trace trees** — nested calls automatically build a parent→child hierarchy (via `contextvars`)
+- **Token streaming** — live speech bubble above each robot as the LLM generates
+- **Error visualization** — red glow + shake animation on agent errors
+- **Latency labels** — floating ms labels between agents, color-coded by speed
+- **Dynamic agents** — robots spawn and despawn as agents connect and disconnect
+- **5 layouts** — `semicircle`, `pipeline`, `star`, `mesh`, `grid` — switch live from the UI
+- **Room isolation** — `?room=project-name` separates teams on the same server
+- **Session recording** — SQLite-backed, replay any past session from the UI
+- **No orchestrator required** — works for peer-to-peer autonomous agent systems
+
+---
+
+## Integrations
+
+### LangChain
+
+```python
+from agentviz.integrations.langchain import AgentVizCallbackHandler
+from agentviz import HttpAgentVizClient
+
+client  = HttpAgentVizClient(server="http://localhost:8000", name="LangChainAgent")
+handler = AgentVizCallbackHandler(client)
+
+chain.invoke({"input": "..."}, config={"callbacks": [handler]})
+```
+
+### LangGraph
+
+```python
+from agentviz.integrations.langgraph import get_langgraph_callbacks
+
+callbacks = get_langgraph_callbacks(client)
+graph.invoke(state, config={"callbacks": callbacks})
+```
+
+### OpenAI Agents SDK
+
+```python
+from agentviz.integrations.openai_agents import patch_openai_agents
+import agentviz
+
+agentviz.init(server="http://localhost:8000")
+patch_openai_agents()   # patches globally — all agents auto-traced from here
+```
+
+### OpenTelemetry
+
+```python
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from agentviz.integrations.otel import AgentVizSpanExporter
+
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(AgentVizSpanExporter()))
+```
+
+Every OTEL span becomes a call/response/error event in the 3D scene automatically.
+
+### MCP server (Claude Desktop / Cursor)
+
+Add to your MCP host config:
+
+```json
+{
+  "mcpServers": {
+    "agentviz": {
+      "command": "python",
+      "args": ["-m", "agentviz.mcp_server"],
+      "env": {
+        "AGENTVIZ_SERVER": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+Then use `agentviz_emit_call`, `agentviz_emit_response`, `agentviz_emit_token` etc. as tools from within Claude.
+
+---
+
+## Self-hosting
+
+### Docker
+
+```bash
+docker build -t agentviz .
+docker run -p 8000:8000 agentviz
+```
+
+### docker-compose
+
+```bash
+docker-compose up
+```
+
+### Railway / Render / Fly.io
+
+Push the repo and set the start command to:
+
+```
+agentviz serve --host 0.0.0.0 --port $PORT --no-browser
+```
+
+---
+
+## CLI
+
+```
+agentviz serve                         # start server, open browser
+agentviz serve --port 9000             # custom port
+agentviz serve --no-browser            # headless (for servers)
+agentviz serve --demo                  # also start demo agents
+agentviz --version
+```
+
+Or:
+
+```
+python -m agentviz serve
+```
+
+---
+
+## Multi-room / multi-team
+
+Each URL `?room=<name>` gets its own isolated scene, agent registry, and session history. Share a single deployed server across multiple teams:
+
+```
+https://agentviz.mycompany.com/?room=search-team
+https://agentviz.mycompany.com/?room=billing-team
+```
+
+---
+
+## License
+
+MIT

agentviz-0.3.0/README.md

@@ -0,0 +1,229 @@
+# agentviz
+
+Real-time 3D visualization for multi-agent AI systems. Drop one decorator on your agent functions and watch them appear as robots in a live 3D scene — calls, responses, token streams, errors, and latency all rendered as they happen.
+
+```
+pip install agentviz
+agentviz serve
+```
+
+---
+
+## How it works
+
+1. You run `agentviz serve` — starts a local FastAPI server + opens the 3D UI in your browser
+2. You decorate your agent functions with `@agentviz.trace`
+3. Every call, response, error, and token stream is sent to the server and rendered live
+
+The server can be self-hosted anywhere (Linode, Railway, Docker). Multiple agents on different machines can all connect to the same room.
+
+---
+
+## Quick start
+
+### Simplest — one decorator
+
+```python
+import agentviz
+
+agentviz.init(server="http://localhost:8000")
+
+@agentviz.trace
+async def fetch_data(query: str) -> str:
+    return await db.query(query)
+
+@agentviz.trace(name="Planner", to="orchestrator", color="#9B59B6")
+async def plan(goal: str) -> str:
+    return await llm.plan(goal)
+```
+
+That's it. Run your agents — they show up in the UI automatically.
+
+### Environment variables (zero code changes)
+
+```bash
+export AGENTVIZ_SERVER=http://localhost:8000
+export AGENTVIZ_PROJECT=my-team
+```
+
+Then just use `@agentviz.trace` with no `init()` call.
+
+### WebSocket SDK (full control)
+
+```python
+from agentviz import AgentVizClient
+
+async with AgentVizClient(
+    server="ws://localhost:8000/agent-ws",
+    name="DataFetcher",
+    color="#E74C3C",
+) as client:
+    call_id = await client.emit_call(to="orchestrator", message="Fetching records…")
+    result  = await do_work()
+    await client.emit_response(to="orchestrator", call_id=call_id, result=result)
+```
+
+### HTTP client (serverless / AWS Lambda / Cloud Run)
+
+```python
+from agentviz import HttpAgentVizClient
+
+client = HttpAgentVizClient(server="https://my-agentviz.railway.app", name="Lambda")
+
+call_id = client.emit_call(to="orchestrator", message="Processing event…")
+result  = process(event)
+client.emit_response(to="orchestrator", call_id=call_id, result=result)
+```
+
+### Token streaming
+
+```python
+async for chunk in llm.stream(prompt):
+    await client.emit_token(chunk.delta)
+await client.emit_stream_end()
+```
+
+Tokens accumulate in a speech bubble above the robot in real-time.
+
+---
+
+## Features
+
+- **`@agentviz.trace`** — works on any `async` or `sync` function, no boilerplate
+- **Trace trees** — nested calls automatically build a parent→child hierarchy (via `contextvars`)
+- **Token streaming** — live speech bubble above each robot as the LLM generates
+- **Error visualization** — red glow + shake animation on agent errors
+- **Latency labels** — floating ms labels between agents, color-coded by speed
+- **Dynamic agents** — robots spawn and despawn as agents connect and disconnect
+- **5 layouts** — `semicircle`, `pipeline`, `star`, `mesh`, `grid` — switch live from the UI
+- **Room isolation** — `?room=project-name` separates teams on the same server
+- **Session recording** — SQLite-backed, replay any past session from the UI
+- **No orchestrator required** — works for peer-to-peer autonomous agent systems
+
+---
+
+## Integrations
+
+### LangChain
+
+```python
+from agentviz.integrations.langchain import AgentVizCallbackHandler
+from agentviz import HttpAgentVizClient
+
+client  = HttpAgentVizClient(server="http://localhost:8000", name="LangChainAgent")
+handler = AgentVizCallbackHandler(client)
+
+chain.invoke({"input": "..."}, config={"callbacks": [handler]})
+```
+
+### LangGraph
+
+```python
+from agentviz.integrations.langgraph import get_langgraph_callbacks
+
+callbacks = get_langgraph_callbacks(client)
+graph.invoke(state, config={"callbacks": callbacks})
+```
+
+### OpenAI Agents SDK
+
+```python
+from agentviz.integrations.openai_agents import patch_openai_agents
+import agentviz
+
+agentviz.init(server="http://localhost:8000")
+patch_openai_agents()   # patches globally — all agents auto-traced from here
+```
+
+### OpenTelemetry
+
+```python
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from agentviz.integrations.otel import AgentVizSpanExporter
+
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(AgentVizSpanExporter()))
+```
+
+Every OTEL span becomes a call/response/error event in the 3D scene automatically.
+
+### MCP server (Claude Desktop / Cursor)
+
+Add to your MCP host config:
+
+```json
+{
+  "mcpServers": {
+    "agentviz": {
+      "command": "python",
+      "args": ["-m", "agentviz.mcp_server"],
+      "env": {
+        "AGENTVIZ_SERVER": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+Then use `agentviz_emit_call`, `agentviz_emit_response`, `agentviz_emit_token` etc. as tools from within Claude.
+
+---
+
+## Self-hosting
+
+### Docker
+
+```bash
+docker build -t agentviz .
+docker run -p 8000:8000 agentviz
+```
+
+### docker-compose
+
+```bash
+docker-compose up
+```
+
+### Railway / Render / Fly.io
+
+Push the repo and set the start command to:
+
+```
+agentviz serve --host 0.0.0.0 --port $PORT --no-browser
+```
+
+---
+
+## CLI
+
+```
+agentviz serve                         # start server, open browser
+agentviz serve --port 9000             # custom port
+agentviz serve --no-browser            # headless (for servers)
+agentviz serve --demo                  # also start demo agents
+agentviz --version
+```
+
+Or:
+
+```
+python -m agentviz serve
+```
+
+---
+
+## Multi-room / multi-team
+
+Each URL `?room=<name>` gets its own isolated scene, agent registry, and session history. Share a single deployed server across multiple teams:
+
+```
+https://agentviz.mycompany.com/?room=search-team
+https://agentviz.mycompany.com/?room=billing-team
+```
+
+---
+
+## License
+
+MIT

agentviz-0.3.0/agentviz/__init__.py

@@ -0,0 +1,53 @@
+"""
+AgentViz — Real-time 3D visualization for multi-agent AI systems.
+
+LangChain-style quick start
+----------------------------
+    import agentviz
+
+    # Option A: env vars (no code changes needed)
+    #   export AGENTVIZ_SERVER=https://agentviz.yourdomain.com
+    #   export AGENTVIZ_PROJECT=my-team
+
+    # Option B: one-line programmatic config
+    agentviz.init(server="https://agentviz.yourdomain.com", project="my-team")
+
+    # Decorate any function — async or sync
+    @agentviz.trace
+    async def fetch_data(query: str) -> str:
+        return await db.query(query)
+
+    @agentviz.trace(name="Planner", to="orchestrator", color="#9B59B6")
+    async def plan(goal: str) -> str:
+        return await llm.plan(goal)
+
+    # Auto-patch every installed framework at once
+    agentviz.instrument_all()
+
+Manual SDK (full control)
+--------------------------
+    from agentviz import AgentVizClient       # WebSocket — local / same-network
+    from agentviz import HttpAgentVizClient   # HTTP     — cloud / serverless
+"""
+
+# ── LangChain-style top-level API ─────────────────────────────────────────────
+from .config  import init, configure
+from .tracing import trace, Agent, instrument_all
+
+# ── Low-level SDK clients ─────────────────────────────────────────────────────
+from .sdk         import AgentVizClient
+from .http_client import HttpAgentVizClient
+
+__all__ = [
+    # LangChain-style
+    "init",
+    "configure",
+    "trace",
+    "Agent",
+    "instrument_all",
+    # SDK clients
+    "AgentVizClient",
+    "HttpAgentVizClient",
+]
+
+__version__ = "0.3.0"

agentviz-0.3.0/agentviz/__main__.py

@@ -0,0 +1,4 @@
+# Allows: python -m agentviz serve
+from agentviz.cli import cli
+
+cli()