Metadata-Version: 2.4
Name: pyagent-studio
Version: 0.1.0
Summary: Terminal-based interactive workbench for designing, simulating, and debugging agent systems
Project-URL: Homepage, https://pyagent.org
Project-URL: Repository, https://github.com/pyagent-core/pyagent
Project-URL: Documentation, https://pyagent.org
Author-email: PyAgent Team <team@pyagent.org>
License: MIT
Keywords: LLM,TUI,agents,studio,textual,workbench
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: pyagent-blueprint>=0.1.0
Requires-Dist: pyagent-trace>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: textual-dev>=1.0; extra == 'dev'
Provides-Extra: tui
Requires-Dist: textual>=3.0; extra == 'tui'
Description-Content-Type: text/markdown

# pyagent-studio

**Terminal-based interactive workbench** for designing, simulating, debugging, and governing multi-agent LLM systems. Built with [Textual](https://textual.textualize.io/) for a rich TUI experience.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

## Install

```bash
pip install pyagent-studio[tui]    # Full TUI (requires textual)
pip install pyagent-studio          # Services only (no TUI)
```

Depends on: `pyagent-blueprint`, `pyagent-trace`, `click`.

## Quick Start

```bash
# Launch with a blueprint
pyagent-studio blueprint.yaml

# Or launch and browse discovered blueprints
pyagent-studio
```

## Screens

### Dashboard
List discovered YAML blueprints, view validation status, agent/workflow counts.

```
┌─────────────────────────────────────────────────────────────┐
│  PyAgent Studio — Dashboard                                 │
├─────────────────────────────────────────────────────────────┤
│ File                  │ Name             │ Agents │ Status   │
│ customer_support.yaml │ customer-support │ 3      │ ✓ Valid  │
│ research_agent.yaml   │ research-agent   │ 2      │ ✓ Valid  │
└─────────────────────────────────────────────────────────────┘
```

### Editor
YAML editing with live validation panel showing Pydantic errors as you type.

### Graph
ASCII-rendered workflow DAG showing agents as boxes and edges as pattern connections.

### Simulation
Run blueprints with MockLLM (no API keys needed), stream results with timing and token counts.

### Traces
Browse recorded trace spans from `pyagent-trace` Recorder JSONL files.

### Cost
Cost breakdown tables by pattern, agent, and model with bar chart visualization.

### Governance
Validation issues, compliance scoring (% of checks passing), and semantic diff between blueprint versions.

## Key Bindings

| Key | Action |
|-----|--------|
| `Tab` / `Shift+Tab` | Switch screens |
| `q` | Quit |
| `Ctrl+S` | Save blueprint |
| `Ctrl+V` | Validate |
| `Ctrl+R` | Render graph |
| `Ctrl+T` | Run simulation |
| `Ctrl+D` | Show diff |

## Services (Headless API)

Use the services layer without the TUI for scripting and CI:

```python
from pyagent_studio import BlueprintService, SimulationService, GovernanceService

# Load and validate
svc = BlueprintService()
spec = svc.load("blueprint.yaml")
issues = svc.validate()
print(svc.summary())

# Run simulation
import asyncio
sim = SimulationService()
result = asyncio.run(sim.run(spec, "support", "I can't see my invoice"))
print(result.output)

# Governance
gov = GovernanceService()
report = gov.check_compliance(spec)
print(gov.format_report(report))
```

### TraceService

```python
from pyagent_studio import TraceService

traces = TraceService()
spans = traces.load("traces.jsonl")
llm_calls = traces.query(event_type="llm_call")
print(traces.summary())
```

## Full Documentation

See [pyagent.dev](https://pyagent.dev) for full API reference and integration guides.
