pyagent-studio 0.1.0__tar.gz

pyagent_studio-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+site/
+.env
+*.log

pyagent_studio-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+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.

pyagent_studio-0.1.0/README.md

@@ -0,0 +1,110 @@
+# 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.

pyagent_studio-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyagent-studio"
+version = "0.1.0"
+description = "Terminal-based interactive workbench for designing, simulating, and debugging agent systems"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{name = "PyAgent Team", email = "team@pyagent.org"}]
+keywords = ["agents", "TUI", "studio", "LLM", "textual", "workbench"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pyagent-blueprint>=0.1.0",
+    "pyagent-trace>=0.1.0",
+    "click>=8.1",
+]
+
+[project.urls]
+Homepage = "https://pyagent.org"
+Repository = "https://github.com/pyagent-core/pyagent"
+Documentation = "https://pyagent.org"
+
+[project.optional-dependencies]
+tui = ["textual>=3.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "textual-dev>=1.0"]
+
+[project.scripts]
+pyagent-studio = "pyagent_studio.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyagent_studio"]

pyagent_studio-0.1.0/src/pyagent_studio/__init__.py

@@ -0,0 +1,14 @@
+"""PyAgent Studio — terminal-based interactive workbench for agent systems."""
+
+from pyagent_studio.services.blueprint_service import BlueprintService
+from pyagent_studio.services.governance_service import GovernanceService
+from pyagent_studio.services.simulation_service import SimulationService
+from pyagent_studio.services.trace_service import TraceService
+
+__all__ = [
+    "BlueprintService",
+    "GovernanceService",
+    "SimulationService",
+    "TraceService",
+]
+__version__ = "0.1.0"

pyagent_studio-0.1.0/src/pyagent_studio/app.py

@@ -0,0 +1,84 @@
+"""StudioApp: main Textual application with screen routing."""
+
+from __future__ import annotations
+
+from textual.app import App, ComposeResult
+from textual.widgets import Footer, Header, TabbedContent, TabPane
+
+from pyagent_blueprint.schema import BlueprintSpec
+from pyagent_studio.services.blueprint_service import BlueprintService
+
+
+class StudioApp(App):
+    """PyAgent Studio — terminal-based interactive workbench.
+
+    Launch via: ``pyagent-studio [blueprint.yaml]``
+    """
+
+    TITLE = "PyAgent Studio"
+    CSS = """
+    TabbedContent {
+        height: 1fr;
+    }
+    """
+    BINDINGS = [
+        ("q", "quit", "Quit"),
+        ("ctrl+s", "save", "Save"),
+        ("ctrl+v", "validate", "Validate"),
+        ("ctrl+r", "render", "Render Graph"),
+        ("ctrl+t", "simulate", "Simulate"),
+        ("ctrl+d", "diff", "Diff"),
+    ]
+
+    def __init__(self, blueprint_path: str | None = None, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._blueprint_path = blueprint_path
+        self._service = BlueprintService()
+        self._spec: BlueprintSpec | None = None
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with TabbedContent():
+            with TabPane("Dashboard", id="tab-dashboard"):
+                from textual.widgets import Static
+                yield Static("[bold]Dashboard[/bold]\n\nLoad a blueprint to get started.")
+            with TabPane("Editor", id="tab-editor"):
+                from textual.widgets import Static
+                yield Static("Editor — use Ctrl+V to validate")
+            with TabPane("Graph", id="tab-graph"):
+                from textual.widgets import Static
+                yield Static("Graph — load a blueprint first")
+            with TabPane("Simulation", id="tab-sim"):
+                from textual.widgets import Static
+                yield Static("Simulation — load a blueprint first")
+            with TabPane("Traces", id="tab-traces"):
+                from textual.widgets import Static
+                yield Static("Traces — no trace file loaded")
+            with TabPane("Cost", id="tab-cost"):
+                from textual.widgets import Static
+                yield Static("Cost — no data available")
+            with TabPane("Governance", id="tab-gov"):
+                from textual.widgets import Static
+                yield Static("Governance — load a blueprint first")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        if self._blueprint_path:
+            try:
+                self._spec = self._service.load(self._blueprint_path)
+                self.notify(f"Loaded: {self._spec.metadata.name}")
+            except Exception as exc:
+                self.notify(f"Load error: {exc}", severity="error")
+
+    def action_quit(self) -> None:
+        self.exit()
+
+    def action_validate(self) -> None:
+        if self._spec is None:
+            self.notify("No blueprint loaded", severity="warning")
+            return
+        issues = self._service.validate()
+        if issues:
+            self.notify(f"{len(issues)} validation issue(s) found", severity="warning")
+        else:
+            self.notify("Blueprint is valid ✓")

pyagent_studio-0.1.0/src/pyagent_studio/cli.py

@@ -0,0 +1,30 @@
+"""CLI entry point: pyagent-studio [blueprint.yaml]."""
+
+from __future__ import annotations
+
+import click
+
+
+@click.command()
+@click.argument("blueprint", required=False, default=None, type=click.Path())
+def main(blueprint: str | None) -> None:
+    """Launch PyAgent Studio — interactive agent system workbench.
+
+    Optionally pass a blueprint YAML file to load on startup.
+    """
+    try:
+        from pyagent_studio.app import StudioApp
+    except ImportError:
+        click.echo(
+            "Error: textual is not installed. "
+            "Install with: pip install pyagent-studio[tui]",
+            err=True,
+        )
+        raise SystemExit(1)
+
+    app = StudioApp(blueprint_path=blueprint)
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

pyagent_studio-0.1.0/src/pyagent_studio/screens/__init__.py

@@ -0,0 +1,22 @@
+"""Studio screens — Textual Screen subclasses for each TUI view."""
+
+try:
+    from pyagent_studio.screens.dashboard import DashboardScreen
+    from pyagent_studio.screens.editor import EditorScreen
+    from pyagent_studio.screens.graph import GraphScreen
+    from pyagent_studio.screens.simulation import SimulationScreen
+    from pyagent_studio.screens.traces import TracesScreen
+    from pyagent_studio.screens.cost import CostScreen
+    from pyagent_studio.screens.governance import GovernanceScreen
+
+    __all__ = [
+        "CostScreen",
+        "DashboardScreen",
+        "EditorScreen",
+        "GovernanceScreen",
+        "GraphScreen",
+        "SimulationScreen",
+        "TracesScreen",
+    ]
+except ImportError:
+    __all__ = []

pyagent_studio-0.1.0/src/pyagent_studio/screens/cost.py

@@ -0,0 +1,33 @@
+"""CostScreen: cost breakdown tables by pattern/agent/model."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.screen import Screen
+from textual.widgets import Footer, Header, Static
+
+from pyagent_studio.widgets.cost_chart import CostChart
+
+
+class CostScreen(Screen):
+    """Display cost breakdown for agent system runs."""
+
+    BINDINGS = [("q", "quit", "Quit")]
+
+    def __init__(self, costs: dict[str, float] | None = None, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._costs = costs
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("[bold]Cost Analysis[/bold]", id="title")
+        yield CostChart(id="cost-chart")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        if self._costs:
+            chart = self.query_one("#cost-chart", CostChart)
+            chart.load_data(self._costs)
+
+    def action_quit(self) -> None:
+        self.app.exit()

pyagent_studio-0.1.0/src/pyagent_studio/screens/dashboard.py

@@ -0,0 +1,55 @@
+"""DashboardScreen: list blueprints, health summary, quick actions."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.screen import Screen
+from textual.widgets import DataTable, Footer, Header, Static
+
+from pyagent_studio.services.blueprint_service import BlueprintService
+
+
+class DashboardScreen(Screen):
+    """Main dashboard showing discovered blueprints and their status."""
+
+    BINDINGS = [
+        ("n", "new_blueprint", "New"),
+        ("enter", "open_blueprint", "Open"),
+        ("q", "quit", "Quit"),
+    ]
+
+    def __init__(self, service: BlueprintService | None = None, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._service = service or BlueprintService()
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("[bold]PyAgent Studio — Dashboard[/bold]", id="title")
+        yield DataTable(id="blueprint-list")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        table = self.query_one("#blueprint-list", DataTable)
+        table.add_columns("File", "Name", "Agents", "Workflows", "Status")
+        self._refresh_list(table)
+
+    def _refresh_list(self, table: DataTable) -> None:
+        """Discover and list blueprints."""
+        table.clear()
+        for path in self._service.discover_blueprints():
+            try:
+                spec = self._service.load(path)
+                issues = self._service.validate()
+                status = "✓ Valid" if not issues else f"✗ {len(issues)} issue(s)"
+                table.add_row(
+                    str(path.name),
+                    spec.metadata.name,
+                    str(len(spec.agents)),
+                    str(len(spec.workflows)),
+                    status,
+                )
+            except Exception:
+                table.add_row(str(path.name), "?", "?", "?", "✗ Load error")
+
+    def action_quit(self) -> None:
+        self.app.exit()

pyagent_studio-0.1.0/src/pyagent_studio/screens/editor.py

@@ -0,0 +1,64 @@
+"""EditorScreen: YAML editing with live validation panel."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.containers import Horizontal
+from textual.screen import Screen
+from textual.widgets import Footer, Header, TextArea
+
+from pyagent_studio.widgets.validation_log import ValidationLog
+
+
+class EditorScreen(Screen):
+    """YAML editor with live validation sidebar."""
+
+    BINDINGS = [
+        ("ctrl+s", "save", "Save"),
+        ("ctrl+v", "validate", "Validate"),
+        ("q", "quit", "Quit"),
+    ]
+
+    DEFAULT_CSS = """
+    EditorScreen Horizontal {
+        height: 1fr;
+    }
+    EditorScreen TextArea {
+        width: 2fr;
+    }
+    EditorScreen ValidationLog {
+        width: 1fr;
+        border-left: solid green;
+    }
+    """
+
+    def __init__(self, content: str = "", **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._content = content
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Horizontal():
+            yield TextArea(self._content, language="yaml", id="editor")
+            yield ValidationLog(id="validation-log")
+        yield Footer()
+
+    def action_validate(self) -> None:
+        """Validate current editor content."""
+        from pyagent_blueprint import BlueprintValidator, load_blueprint_from_str
+        from pyagent_blueprint.loader import BlueprintLoadError
+
+        editor = self.query_one("#editor", TextArea)
+        log = self.query_one("#validation-log", ValidationLog)
+
+        try:
+            spec = load_blueprint_from_str(editor.text)
+            validator = BlueprintValidator()
+            issues = validator.validate(spec)
+            log.load_issues(issues)
+        except (BlueprintLoadError, Exception) as exc:
+            log.clear()
+            log.write(f"[red]Parse error: {exc}[/red]")
+
+    def action_quit(self) -> None:
+        self.app.exit()