pyagent-studio 0.1.0__py3-none-any.whl

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/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/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/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/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/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/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()

pyagent_studio/screens/governance.py

@@ -0,0 +1,77 @@
+"""GovernanceScreen: validation issues, policy compliance, diff view."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.screen import Screen
+from textual.widgets import Footer, Header, Static
+
+from pyagent_blueprint.schema import BlueprintSpec
+from pyagent_studio.services.governance_service import GovernanceService
+from pyagent_studio.widgets.diff_view import DiffView
+from pyagent_studio.widgets.validation_log import ValidationLog
+
+
+class GovernanceScreen(Screen):
+    """Display validation issues, compliance score, and spec diff."""
+
+    BINDINGS = [("q", "quit", "Quit")]
+
+    DEFAULT_CSS = """
+    GovernanceScreen Vertical {
+        height: 1fr;
+    }
+    GovernanceScreen ValidationLog {
+        height: 1fr;
+        border: solid green;
+    }
+    GovernanceScreen DiffView {
+        height: 1fr;
+        border: solid blue;
+    }
+    """
+
+    def __init__(
+        self,
+        spec: BlueprintSpec | None = None,
+        old_spec: BlueprintSpec | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._spec = spec
+        self._old_spec = old_spec
+        self._service = GovernanceService()
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("[bold]Governance & Compliance[/bold]", id="title")
+        with Vertical():
+            yield Static("", id="score")
+            yield ValidationLog(id="gov-validation")
+            yield DiffView(id="gov-diff")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        if self._spec:
+            self._run_compliance()
+        if self._spec and self._old_spec:
+            self._run_diff()
+
+    def _run_compliance(self) -> None:
+        report = self._service.check_compliance(self._spec)
+        score_widget = self.query_one("#score", Static)
+        score_widget.update(
+            f"[bold]Compliance Score: {report.score:.0%}[/bold] "
+            f"({report.passed}/{report.total_checks} checks passing)"
+        )
+        log = self.query_one("#gov-validation", ValidationLog)
+        log.load_issues(report.issues)
+
+    def _run_diff(self) -> None:
+        changes = self._service.diff(self._old_spec, self._spec)
+        diff_view = self.query_one("#gov-diff", DiffView)
+        diff_view.load_changes(changes)
+
+    def action_quit(self) -> None:
+        self.app.exit()

pyagent_studio/screens/graph.py

@@ -0,0 +1,42 @@
+"""GraphScreen: ASCII/Rich renderable DAG of workflow topology."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.screen import Screen
+from textual.widgets import Footer, Header, Static
+
+from pyagent_blueprint.renderer import BlueprintRenderer
+from pyagent_blueprint.schema import BlueprintSpec
+
+
+class GraphScreen(Screen):
+    """Display the workflow DAG as a Mermaid-like ASCII diagram."""
+
+    BINDINGS = [("q", "quit", "Quit")]
+
+    def __init__(self, spec: BlueprintSpec | None = None, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._spec = spec
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("[bold]Workflow Graph[/bold]", id="title")
+        yield Static("No blueprint loaded", id="graph-content")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        if self._spec is not None:
+            self.load_spec(self._spec)
+
+    def load_spec(self, spec: BlueprintSpec) -> None:
+        """Render the blueprint graph."""
+        self._spec = spec
+        renderer = BlueprintRenderer()
+        mermaid = renderer.to_mermaid(spec)
+
+        content = self.query_one("#graph-content", Static)
+        content.update(f"```\n{mermaid}\n```")
+
+    def action_quit(self) -> None:
+        self.app.exit()

pyagent_studio/screens/simulation.py

@@ -0,0 +1,64 @@
+"""SimulationScreen: run blueprint with MockLLM, stream results."""
+
+from __future__ import annotations
+
+import asyncio
+
+from textual.app import ComposeResult
+from textual.screen import Screen
+from textual.widgets import Footer, Header, Input, RichLog, Static
+
+from pyagent_blueprint.schema import BlueprintSpec
+from pyagent_studio.services.simulation_service import SimulationService
+
+
+class SimulationScreen(Screen):
+    """Run simulations against a compiled blueprint and display results."""
+
+    BINDINGS = [
+        ("ctrl+t", "run_simulation", "Run"),
+        ("q", "quit", "Quit"),
+    ]
+
+    DEFAULT_CSS = """
+    SimulationScreen RichLog {
+        height: 1fr;
+        border: solid green;
+    }
+    """
+
+    def __init__(self, spec: BlueprintSpec | None = None, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._spec = spec
+        self._service = SimulationService()
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("[bold]Simulation[/bold]", id="title")
+        yield Input(placeholder="Enter task to simulate...", id="task-input")
+        yield RichLog(id="sim-output")
+        yield Footer()
+
+    async def on_input_submitted(self, event: Input.Submitted) -> None:
+        """Run simulation when input is submitted."""
+        if self._spec is None:
+            log = self.query_one("#sim-output", RichLog)
+            log.write("[red]No blueprint loaded[/red]")
+            return
+
+        await self._run(event.value)
+
+    async def _run(self, task: str) -> None:
+        log = self.query_one("#sim-output", RichLog)
+        log.write(f"\n[bold]Running:[/bold] {task}")
+
+        for wf_name in self._spec.workflows:
+            result = await self._service.run(self._spec, wf_name, task)
+            if result.success:
+                log.write(f"[green]✓ {wf_name}[/green] ({result.elapsed_ms:.0f}ms)")
+                log.write(f"  Output: {result.output[:200]}")
+            else:
+                log.write(f"[red]✗ {wf_name}[/red]: {result.error}")
+
+    def action_quit(self) -> None:
+        self.app.exit()

pyagent_studio/screens/traces.py

@@ -0,0 +1,43 @@
+"""TracesScreen: browse recorded traces, inspect spans."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.screen import Screen
+from textual.widgets import Footer, Header, Static
+
+from pyagent_studio.services.trace_service import TraceService
+from pyagent_studio.widgets.trace_table import TraceTable
+
+
+class TracesScreen(Screen):
+    """Browse recorded trace spans from pyagent-trace Recorder."""
+
+    BINDINGS = [("q", "quit", "Quit")]
+
+    def __init__(self, trace_path: str | None = None, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._trace_path = trace_path
+        self._service = TraceService()
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("[bold]Traces[/bold]", id="title")
+        yield TraceTable(id="trace-table")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        if self._trace_path:
+            self.load_traces(self._trace_path)
+
+    def load_traces(self, path: str) -> None:
+        """Load and display traces from a JSONL file."""
+        try:
+            spans = self._service.load(path)
+            table = self.query_one("#trace-table", TraceTable)
+            table.load_spans(spans)
+        except FileNotFoundError:
+            pass
+
+    def action_quit(self) -> None:
+        self.app.exit()

pyagent_studio/services/__init__.py

@@ -0,0 +1,13 @@
+"""Studio services — headless logic for blueprint, simulation, traces, governance."""
+
+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",
+]

pyagent_studio/services/blueprint_service.py

@@ -0,0 +1,115 @@
+"""BlueprintService: load, validate, compile blueprints for the studio."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pyagent_blueprint import (
+    BlueprintCompiler,
+    BlueprintValidator,
+    RuntimeGraph,
+    load_blueprint,
+)
+from pyagent_blueprint.loader import BlueprintLoadError
+from pyagent_blueprint.schema import BlueprintSpec
+from pyagent_blueprint.validator import ValidationIssue
+
+
+class BlueprintService:
+    """Headless service for loading, validating, and compiling blueprints.
+
+    Wraps ``pyagent-blueprint`` for use by TUI screens and tests.
+    """
+
+    def __init__(self) -> None:
+        self._compiler = BlueprintCompiler()
+        self._validator = BlueprintValidator()
+        self._spec: BlueprintSpec | None = None
+        self._graph: RuntimeGraph | None = None
+        self._path: Path | None = None
+
+    def load(self, path: str | Path) -> BlueprintSpec:
+        """Load a blueprint from file.
+
+        Args:
+            path: Path to YAML/JSON blueprint.
+
+        Returns:
+            Validated ``BlueprintSpec``.
+
+        Raises:
+            BlueprintLoadError: On load/validation failure.
+        """
+        self._path = Path(path)
+        self._spec = load_blueprint(self._path)
+        self._graph = None
+        return self._spec
+
+    def validate(self) -> list[ValidationIssue]:
+        """Run static validation on the loaded spec.
+
+        Returns:
+            List of validation issues.
+
+        Raises:
+            RuntimeError: If no spec loaded.
+        """
+        if self._spec is None:
+            raise RuntimeError("No blueprint loaded. Call load() first.")
+        return self._validator.validate(self._spec)
+
+    def compile(self) -> RuntimeGraph:
+        """Compile the loaded spec into a RuntimeGraph.
+
+        Returns:
+            Executable ``RuntimeGraph``.
+
+        Raises:
+            RuntimeError: If no spec loaded.
+        """
+        if self._spec is None:
+            raise RuntimeError("No blueprint loaded. Call load() first.")
+        self._graph = self._compiler.compile(self._spec)
+        return self._graph
+
+    def discover_blueprints(self, directory: str | Path = ".") -> list[Path]:
+        """Find all YAML/JSON blueprint files in a directory.
+
+        Args:
+            directory: Root directory to search.
+
+        Returns:
+            List of file paths.
+        """
+        root = Path(directory)
+        files: list[Path] = []
+        for ext in ("*.yaml", "*.yml", "*.json"):
+            files.extend(root.glob(f"**/{ext}"))
+        return sorted(files)
+
+    @property
+    def spec(self) -> BlueprintSpec | None:
+        return self._spec
+
+    @property
+    def graph(self) -> RuntimeGraph | None:
+        return self._graph
+
+    @property
+    def path(self) -> Path | None:
+        return self._path
+
+    def summary(self) -> dict[str, Any]:
+        """Quick summary of loaded blueprint."""
+        if self._spec is None:
+            return {"loaded": False}
+        return {
+            "loaded": True,
+            "name": self._spec.metadata.name,
+            "version": self._spec.metadata.version,
+            "agents": len(self._spec.agents),
+            "workflows": len(self._spec.workflows),
+            "providers": len(self._spec.providers),
+            "contracts": len(self._spec.contracts),
+        }