Metadata-Version: 2.4
Name: tui-agent-dashboard
Version: 0.1.0
Summary: Beautiful terminal UI for monitoring AI agent operations, costs, and attribution
Project-URL: Homepage, https://github.com/yourusername/tui-agent-dashboard
Project-URL: Documentation, https://github.com/yourusername/tui-agent-dashboard#readme
Project-URL: Repository, https://github.com/yourusername/tui-agent-dashboard
Project-URL: Issues, https://github.com/yourusername/tui-agent-dashboard/issues
Author-email: Agent Builder <builder@example.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,dashboard,monitoring,observability,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: stripe>=7.0.0
Requires-Dist: textual>=0.47.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# tui-agent-dashboard

A beautiful terminal UI dashboard for monitoring AI agent operations, costs, and attribution in real-time—think `htop` meets agent observability.

## What is this?

`tui-agent-dashboard` brings observability to your AI agent infrastructure with a gorgeous, keyboard-driven terminal interface. It integrates seamlessly with your existing `agent-cost-attribution-layer` and `ai-agent-spend-guardian` systems to surface real-time metrics, cost breakdowns, and request attribution without leaving your terminal. Built for developers who prefer TUIs over web dashboards.

## Features

- **Live Agent Activity Panel** – Monitor active agents, request throughput, and execution status in real-time
- **Cost Attribution Dashboard** – View API costs broken down by agent, model, and time period
- **Request Inspector** – Search and inspect individual requests with full attribution metadata
- **Health & Performance Metrics** – Track agent health, latency, and error rates at a glance
- **Interactive Navigation** – Vim-style keybindings (j/k scroll, tab to switch panels, `/` search)
- **Export Capabilities** – Dump data to JSON/CSV or take ASCII screenshots for sharing
- **Multiple Themes** – Dark and light modes with configurable refresh rates
- **Plugin Support** – Out-of-the-box integration with LiteLLM, LangChain, and raw OpenAI/Anthropic proxies
- **Docker Ready** – Run locally with `docker-compose` or deploy anywhere

## Quick Start

### Installation

```bash
pip install tui-agent-dashboard
```

### Configuration

Copy `.env.example` to `.env` and configure your data sources:

```bash
cp .env.example .env
```

Update with your agent infrastructure endpoints:

```env
AGENT_ATTRIBUTION_API_URL=http://localhost:8000
SPEND_GUARDIAN_API_URL=http://localhost:8001
REFRESH_RATE_MS=1000
```

### Run

```bash
tui-agent-dashboard
```

Or with Docker:

```bash
docker-compose up
```

## Usage

Once running, interact with the dashboard using keyboard commands:

| Command | Action |
|---------|--------|
| `Tab` | Switch between panels (Activity, Costs, Health, Inspector) |
| `j` / `k` | Scroll down / up |
| `/` | Open search / filter |
| `e` | Export current view to JSON/CSV |
| `s` | Take ASCII screenshot |
| `q` | Quit |
| `1-4` | Jump directly to panel |

### Example: Monitor costs by agent

1. Launch the dashboard
2. Press `Tab` until you reach the **Costs** panel
3. Use `j`/`k` to browse agents sorted by spend
4. Press `e` to export to CSV

### Example: Export metrics

Press `e` from any panel to export real-time data:

```bash
# Exported to:
# tui-agent-dashboard-2025-05-04T09-03-42.json
# tui-agent-dashboard-2025-05-04T09-03-42.csv
```

## Tech Stack

- **Framework**: [Textual](https://textual.textualize.io/) – Modern Python TUI library with GPU-accelerated rendering
- **Backend Integration**: FastAPI-compatible REST client
- **Data Models**: Pydantic for type-safe data validation
- **Testing**: pytest with comprehensive integration tests
- **Containerization**: Docker & Docker Compose
- **Python**: 3.9+

## Development

Clone and install in editable mode:

```bash
git clone <repo>
cd tui-agent-dashboard
pip install -e ".[dev]"
```

Run tests:

```bash
pytest tests/
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## License

MIT