crewui 0.1.0__py3-none-any.whl

crewui/__init__.py

@@ -0,0 +1,42 @@
+"""crewui - a Textual TUI for any sequential CrewAI crew.
+
+``CrewAIPipelineTUI`` is a Textual App that renders a sidebar task tracker, an
+agent output log, and a pipeline log for a CrewAI ``Crew``. The host builds the
+crew and hands it in; the TUI stays out of crew construction entirely.
+
+The package depends only on ``crewai`` and ``textual``. Live metrics come
+straight from CrewAI (token usage off ``kickoff()``'s result); everything
+host-specific is delegated to injected callbacks, so nothing here reaches up
+into the host application:
+
+- ``on_start()`` - fired in the worker thread right before kickoff (e.g. to
+  bind a run id and stamp the start time)
+- ``on_complete(result)`` - fired right after kickoff (e.g. to persist run
+  metrics)
+- ``get_token_cost(input_tokens, output_tokens)`` - returns the USD estimate to
+  display; cost is not a CrewAI metric, so the host supplies it
+
+Human review (``Task(human_input=True)``) is routed to the TUI's input box
+instead of a blocking terminal ``input()`` - see ``crewui.app``.
+
+Typical usage::
+
+    from crewui import CrewAIPipelineTUI
+
+    CrewAIPipelineTUI(
+        crew=build_my_crew(),
+        record_prefix="myapp",
+        pipeline_name="My Pipeline",
+    ).run()
+
+The class owns a default theme; a derived class ships its own look by setting
+its own ``CSS_PATH``.
+"""
+
+from __future__ import annotations
+
+from crewui.app import CrewAIPipelineTUI
+
+__version__ = "0.1.0"
+
+__all__ = ["CrewAIPipelineTUI", "__version__"]

crewui/__main__.py

@@ -0,0 +1,15 @@
+"""``python -m crewui`` entry point.
+
+Kept to two lines and a guard so it mirrors the console script exactly: both
+routes go through ``crewui.cli:main``, so a wheel cannot ship one working and
+the other broken.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from crewui.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

crewui/_helpers.py

@@ -0,0 +1,78 @@
+"""crewui._helpers - Pure functions extracted from CrewAIPipelineTUI.
+
+The TUI class itself (CrewAIPipelineTUI) is App + widgets + threading and needs
+a textual.pilot harness to test properly. The pure-logic helpers it relies on -
+truncation, log routing, step-message formatting, sidebar layout, metrics
+block formatting - have no Textual or threading dependency and live here so
+they can be branch-covered by ordinary unit tests.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from crewai.agents.parser import AgentAction, AgentFinish
+
+
+def truncate(text: str, limit: int) -> str:
+    """Return ``text`` truncated to ``limit`` characters.
+
+    Returns the input unchanged when it is already at or below the limit.
+    """
+    return text[:limit] if len(text) > limit else text
+
+
+def route_log_record(record_name: str, prefix: str) -> str:
+    """Decide which TUI log pane a logging record belongs in.
+
+    Returns ``"agent"`` when ``record_name`` starts with ``prefix`` (the host
+    app's record prefix), else ``"crew"``.
+    """
+    return "agent" if record_name.startswith(prefix) else "crew"
+
+
+def task_layout(tasks: list[Any]) -> list[tuple[str, str]]:
+    """Build the sidebar entries for a sequential pipeline.
+
+    For each task that has an assigned agent, return a ``(heading, role)``
+    pair in pipeline order. ``heading`` is the task's display name
+    (``Task.name``), falling back to the agent role when a task carries no
+    name; ``role`` is the agent role shown on the task's status row. Because
+    the heading is per-task rather than per-agent, an agent that runs more than
+    one task in the pipeline gets a distinct heading for each.
+
+    Tasks with no agent are skipped, so a partially-wired crew never raises.
+    """
+    layout: list[tuple[str, str]] = []
+    for task in tasks:
+        agent = getattr(task, "agent", None)
+        if agent is None:
+            continue
+        role = agent.role
+        layout.append((task.name or role, role))
+    return layout
+
+
+def format_metrics_block(total_tokens: int, estimated_cost_usd: float, status: str = "done") -> str:
+    """Render the fixed-width metrics summary shown in the sidebar."""
+    return f" Tokens:  {total_tokens:,}\n Cost:    ${estimated_cost_usd:.4f}\n Status:  {status}"
+
+
+def format_step_message(step: object) -> str:
+    """Format a CrewAI step (AgentAction / AgentFinish / other) as rich-text.
+
+    AgentAction yields a Thought + tool-call line and an optional result block.
+    AgentFinish yields an Answer line. Anything else is rendered as its
+    truncated ``str()``. Trusts the crewai parser types - the caller's
+    callback is responsible for swallowing any unexpected exceptions, since
+    the step-callback contract is fire-and-forget telemetry.
+    """
+    if isinstance(step, AgentAction):
+        tool_call = f"[cyan]> {step.tool}[/cyan]({truncate(step.tool_input, 120)})"
+        msg = f"[yellow]Thought:[/yellow] {step.thought}\n{tool_call}"
+        if step.result:
+            msg += f"\n[dim]{truncate(step.result, 300)}[/dim]"
+        return msg
+    if isinstance(step, AgentFinish):
+        return f"[bold green]Answer:[/bold green] {truncate(str(step.output), 500)}"
+    return truncate(str(step), 300)

crewui/app.py

@@ -0,0 +1,308 @@
+"""crewui.app - the Textual App for a sequential CrewAI pipeline.
+
+``CrewAIPipelineTUI`` renders a sidebar task tracker, an agent output log, and
+a pipeline log for a sequential crew. The host builds the crew and hands it in,
+so the TUI stays out of crew construction.
+
+Human review (``Task(human_input=True)``) is handled by routing CrewAI's
+feedback prompt to the input box instead of a blocking terminal ``input()`` -
+see ``_make_tui_human_input_provider`` and ``_await_feedback``.
+
+The sidebar title is the host-supplied ``pipeline_name``; ``record_prefix`` is
+used only to route log records to the agent vs pipeline pane. The sidebar reads
+each task's display name (``Task.name``) and agent role straight off
+``crew.tasks``, so the caller only wires the crew - no separate task map.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from crewai import Crew
+from textual import work
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.css.query import NoMatches
+from textual.widgets import Input, Label, RichLog, Static
+
+from crewui._helpers import (
+    format_metrics_block,
+    format_step_message,
+    route_log_record,
+    task_layout,
+    truncate,
+)
+
+if TYPE_CHECKING:
+    from crewai.core.providers.human_input import SyncHumanInputProvider
+
+logger = logging.getLogger(__name__)
+
+
+class CrewAIPipelineTUI(App[None]):
+    # The class owns the default theme. Absolute (not the bare "default.tcss")
+    # because Textual resolves a relative CSS_PATH against the *concrete*
+    # class's module file - so a derived class would otherwise look for the
+    # stylesheet next to its own module. A derived class overrides the theme
+    # by setting its own CSS_PATH.
+    CSS_PATH = str(Path(__file__).parent / "default.tcss")
+
+    def __init__(
+        self,
+        crew: Crew,
+        record_prefix: str = "pipeline",
+        pipeline_name: str = "",
+        dry_run: bool = False,
+        on_start: Callable[[], None] | None = None,
+        on_complete: Callable[[object], None] | None = None,
+        get_token_cost: Callable[[int, int], float] | None = None,
+    ) -> None:
+        super().__init__()
+        self._crew = crew
+        self._record_prefix = record_prefix
+        self._pipeline_name = pipeline_name
+        self._dry_run = dry_run
+        self._on_start = on_start
+        self._on_complete = on_complete
+        self._get_token_cost = get_token_cost
+        self._task_widgets: list[tuple[Label, Label]] = []
+        # Human-review bridge: the worker thread parks on this event while the
+        # operator types feedback into the input box on the UI thread.
+        self._feedback_event: threading.Event | None = None
+        self._feedback_value: str = ""
+        self._log_handler: _TUILogHandler | None = None
+        self._crew.step_callback = self._make_step_callback()
+
+    def compose(self) -> ComposeResult:
+        with Horizontal():
+            with Vertical(id="sidebar"):
+                yield Label(self._pipeline_name, id="sidebar-title")
+
+                for heading, role in task_layout(self._crew.tasks):
+                    yield Label(heading, classes="phase-heading")
+                    name_lbl = Label(role, classes="task-name")
+                    status_lbl = Label("Waiting", classes="task-status")
+                    self._task_widgets.append((name_lbl, status_lbl))
+                    yield name_lbl
+                    yield status_lbl
+
+                yield Static("", id="metrics")
+
+            with Vertical(id="main"):
+                with Vertical(id="messages-pane"):
+                    yield Label("Agent Output", classes="pane-title")
+                    yield RichLog(id="agent-log", highlight=True, markup=True, wrap=True)
+                    yield Input(
+                        placeholder="Human review (idle)",
+                        disabled=True,
+                        id="human-input",
+                    )
+                with Vertical(id="logs-pane"):
+                    yield Label("Pipeline Logs", id="logs-title", classes="pane-title")
+                    yield RichLog(id="crew-log", highlight=True, markup=True)
+
+    def on_mount(self) -> None:
+        # Held so on_unmount can detach it. A handler left on the root logger
+        # after the app stops would route later records through call_from_thread
+        # into a dead app - harmless in a one-shot CLI, a leak anywhere the host
+        # keeps running after the TUI closes.
+        self._log_handler = _TUILogHandler(self)
+        logging.getLogger().addHandler(self._log_handler)
+        if self._dry_run:
+            self._write_crew("[yellow]Dry run mode: pipeline not started.[/yellow]")
+            # Render the metrics block zeroed so the sidebar reads as a complete
+            # preview rather than a blank panel - no run happened, so the
+            # figures are zero and the status says so.
+            self.query_one("#metrics", Static).update(
+                format_metrics_block(total_tokens=0, estimated_cost_usd=0.0, status="dry run")
+            )
+        else:
+            self._start_run()
+
+    def on_unmount(self) -> None:
+        if self._log_handler is not None:
+            logging.getLogger().removeHandler(self._log_handler)
+            self._log_handler = None
+
+    @work(thread=True)
+    def _start_run(self) -> None:
+        from crewai.core.providers.human_input import reset_provider, set_provider
+
+        if self._on_start is not None:
+            self._on_start()
+
+        for i, task in enumerate(self._crew.tasks):
+            orig: Callable[..., None] | None = task.callback
+            task.callback = self._make_task_callback(i, orig)
+
+        self.call_from_thread(self._set_task_running, 0)
+
+        # Route CrewAI's human_input feedback prompt to the input box instead of
+        # a blocking terminal input(). Set in this (worker) thread so kickoff's
+        # get_provider() - same thread - picks it up; reset when the run ends.
+        token = set_provider(_make_tui_human_input_provider(self))
+        try:
+            result = self._crew.kickoff()
+            self.call_from_thread(self._on_done, result)
+        except Exception as exc:
+            self.call_from_thread(self._write_agent, f"[bold red]Pipeline error: {exc}[/bold red]")
+            self.call_from_thread(self._write_crew, f"[bold red]Pipeline error: {exc}[/bold red]")
+        finally:
+            reset_provider(token)
+
+    def _make_task_callback(
+        self, idx: int, orig: Callable[..., None] | None
+    ) -> Callable[..., None]:
+        def _cb(output: object) -> None:
+            self.call_from_thread(self._set_task_done, idx)
+            if orig is not None:
+                orig(output)
+
+        return _cb
+
+    def _make_step_callback(self) -> Callable[[object], None]:
+        def _cb(step: object) -> None:
+            try:
+                msg = format_step_message(step)
+            except Exception as exc:
+                logger.debug("step callback error: %s", exc)
+                return
+            self.call_from_thread(self._write_agent, msg)
+
+        return _cb
+
+    def _set_task_running(self, idx: int) -> None:
+        if idx < len(self._task_widgets):
+            name_lbl, status_lbl = self._task_widgets[idx]
+            name_lbl.add_class("running")
+            status_lbl.add_class("running")
+            status_lbl.update("Running...")
+
+    def _set_task_done(self, idx: int) -> None:
+        if idx < len(self._task_widgets):
+            name_lbl, status_lbl = self._task_widgets[idx]
+            name_lbl.remove_class("running")
+            name_lbl.add_class("done")
+            status_lbl.remove_class("running")
+            status_lbl.add_class("done")
+            status_lbl.update("Done")
+        next_idx = idx + 1
+        if next_idx < len(self._task_widgets):
+            self._set_task_running(next_idx)
+
+    def _on_done(self, result: object) -> None:
+        raw = getattr(result, "raw", str(result))
+        self._write_agent("[bold green]Pipeline complete.[/bold green]")
+        self._write_agent(truncate(raw, 2000))
+
+        # Hand the result to the host for persistence; a save failure must not
+        # take the UI down, so swallow and surface it in the pipeline log.
+        if self._on_complete is not None:
+            try:
+                self._on_complete(result)
+            except Exception as exc:
+                logger.debug("on_complete callback error: %s", exc)
+                self._write_crew(f"[yellow]Metrics error: {exc}[/yellow]")
+
+        usage = getattr(result, "token_usage", None)
+        if usage is None:
+            return
+
+        input_tokens = getattr(usage, "prompt_tokens", 0)
+        output_tokens = getattr(usage, "completion_tokens", 0)
+        cost = self._get_token_cost(input_tokens, output_tokens) if self._get_token_cost else 0.0
+        try:
+            self.query_one("#metrics", Static).update(
+                format_metrics_block(
+                    total_tokens=getattr(usage, "total_tokens", input_tokens + output_tokens),
+                    estimated_cost_usd=cost,
+                )
+            )
+        except NoMatches:
+            logger.debug("metrics widget not mounted")
+
+    def _write_agent(self, msg: str) -> None:
+        try:
+            self.query_one("#agent-log", RichLog).write(msg)
+        except NoMatches:
+            logger.debug("agent-log widget not mounted, dropping message")
+
+    def _write_crew(self, msg: str) -> None:
+        try:
+            self.query_one("#crew-log", RichLog).write(msg)
+        except NoMatches:
+            logger.debug("crew-log widget not mounted, dropping message")
+
+    # -- human review --
+
+    def _await_feedback(self) -> str:
+        """Worker-thread side of the human-review gate.
+
+        Opens the input box on the UI thread, parks until the operator submits,
+        then returns what they typed. Empty (just Enter) means "accept", per
+        CrewAI's feedback loop.
+        """
+        self._feedback_event = threading.Event()
+        self._feedback_value = ""
+        self.call_from_thread(self._open_feedback_gate)
+        self._feedback_event.wait()
+        return self._feedback_value
+
+    def _open_feedback_gate(self) -> None:
+        self._write_agent(
+            "[bold yellow]Human review requested - reply below (Enter to accept).[/bold yellow]"
+        )
+        inp = self.query_one("#human-input", Input)
+        inp.placeholder = "Your feedback - Enter to accept, or type changes"
+        inp.disabled = False
+        inp.focus()
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        if event.input.id != "human-input" or self._feedback_event is None:
+            return
+        self._feedback_value = event.value
+        event.input.value = ""
+        event.input.disabled = True
+        event.input.placeholder = "Human review (idle)"
+        self._feedback_event.set()
+
+
+def _make_tui_human_input_provider(app: CrewAIPipelineTUI) -> SyncHumanInputProvider:
+    """Build a CrewAI human-input provider that routes the feedback prompt to
+    the TUI input box instead of a blocking terminal ``input()``.
+
+    Isolated here, with a deferred import, because it leans on crewai's
+    semi-internal provider API (``crewai.core.providers.human_input``). That is
+    the sanctioned injection point but may move between versions - this is the
+    one place to fix if it does. ``output_to_review`` is accepted (crewai passes the
+    answer under review) but unused: the step-callback already streams that
+    answer into the agent-log pane before the gate opens.
+    """
+    from crewai.core.providers.human_input import SyncHumanInputProvider
+
+    # crewai ships no stubs, so SyncHumanInputProvider is Any and mypy --strict
+    # rejects subclassing it; the subclass is the sanctioned injection point.
+    class _TUIHumanInputProvider(SyncHumanInputProvider):  # type: ignore[misc]
+        @staticmethod
+        def _prompt_input(crew: Crew | None = None, output_to_review: str | None = None) -> str:
+            return app._await_feedback()
+
+    return _TUIHumanInputProvider()
+
+
+class _TUILogHandler(logging.Handler):
+    def __init__(self, app: CrewAIPipelineTUI) -> None:
+        super().__init__()
+        self._app = app
+
+    def emit(self, record: logging.LogRecord) -> None:
+        msg = self.format(record)
+        target = route_log_record(record.name, self._app._record_prefix)
+        if target == "agent":
+            self._app.call_from_thread(self._app._write_agent, msg)
+        else:
+            self._app.call_from_thread(self._app._write_crew, msg)

crewui/cli.py

@@ -0,0 +1,65 @@
+"""crewui.cli - the command-line surface.
+
+``crewui`` is a library first: the point of the package is ``from crewui import
+CrewAIPipelineTUI`` inside a host app. The CLI carries just enough to make an
+install self-evidently working - a ``--version`` that both entry points share,
+and a ``demo`` subcommand that runs the bundled offline pipeline so a fresh
+``pipx install crewui`` shows something on screen without an API key.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from crewui import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="crewui",
+        description="A Textual TUI for sequential CrewAI pipelines.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"crewui {__version__}",
+    )
+    sub = parser.add_subparsers(dest="command")
+    demo = sub.add_parser(
+        "demo",
+        help="Run the bundled offline demo pipeline in the TUI (no API key needed).",
+    )
+    demo.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Render the layout without walking the pipeline.",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point for the ``crewui`` console script and ``python -m crewui``.
+
+    Returns a process exit code. With no subcommand, prints help and exits 0 -
+    the install is proven working by ``--version`` and ``demo``, so a bare
+    invocation is informational, not an error.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "demo":
+        # Imported lazily so ``crewui --version`` does not pull in textual and
+        # construct crewai agents just to print a string.
+        from crewui.demo import run_demo
+
+        run_demo(dry_run=args.dry_run)
+        return 0
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

crewui/default.tcss

@@ -0,0 +1,105 @@
+Screen {
+    layout: horizontal;
+    background: $background;
+}
+
+#sidebar {
+    width: 34;
+    border-right: solid $surface;
+    padding: 1 1;
+    layout: vertical;
+    overflow-y: auto;
+}
+
+#sidebar-title {
+    color: $accent;
+    text-style: bold;
+    margin-bottom: 1;
+}
+
+.phase-heading {
+    color: $accent;
+    text-style: bold;
+    margin-top: 1;
+}
+
+.task-name {
+    color: $text-muted;
+    padding-left: 2;
+}
+
+.task-name.running {
+    color: $warning;
+    text-style: bold;
+}
+
+.task-name.done {
+    color: $success;
+}
+
+.task-status {
+    color: $text-muted;
+    padding-left: 4;
+    height: 1;
+}
+
+.task-status.running {
+    color: $warning;
+}
+
+.task-status.done {
+    color: $success;
+}
+
+#metrics {
+    dock: bottom;
+    border-top: solid $surface;
+    padding: 1;
+    color: $text-muted;
+    height: 6;
+}
+
+#main {
+    layout: vertical;
+    width: 1fr;
+}
+
+#messages-pane {
+    height: 60%;
+    border-bottom: solid $surface;
+    layout: vertical;
+}
+
+.pane-title {
+    padding: 0 1;
+    color: $accent;
+    text-style: bold;
+    height: 1;
+}
+
+#agent-log {
+    height: 1fr;
+    padding: 0 1;
+}
+
+#human-input {
+    margin: 0 1 1 1;
+    opacity: 0.4;
+}
+
+#logs-pane {
+    height: 40%;
+    layout: vertical;
+}
+
+#logs-title {
+    padding: 0 1;
+    color: $text-muted;
+    text-style: bold;
+    height: 1;
+}
+
+#crew-log {
+    height: 1fr;
+    padding: 0 1;
+}

crewui/demo.py

@@ -0,0 +1,158 @@
+"""crewui.demo - a self-contained, offline demonstration of the TUI.
+
+``crewui demo`` builds a small three-phase sequential crew and drives it through
+``CrewAIPipelineTUI`` without any LLM call or network access. It exists so that
+``pipx install crewui`` yields something immediately runnable - a live look at
+the sidebar tracker, the agent-output stream, and the pipeline log - and so the
+release smoke test has an entry point that exercises the real App end to end.
+
+The crew is a genuine ``crewai.Crew`` of genuine ``Agent`` / ``Task`` objects
+(so the sidebar reads real ``Task.name`` / ``agent.role`` values), but its
+``kickoff`` is replaced with a scripted walk that emits canned step messages
+and fires each task callback in turn. That keeps the demo deterministic and
+free of API keys while still driving every code path the App uses to render a
+run: step callbacks, per-task status transitions, and the final result +
+token-usage block.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import types
+from dataclasses import dataclass
+
+from crewai import Agent, Crew, Process, Task
+from crewai.agents.parser import AgentAction, AgentFinish
+
+from crewui.app import CrewAIPipelineTUI
+
+# The demo's scripted phases: (task name, agent role, thought, tool, tool input,
+# tool result, final answer). Nothing here is sent anywhere - it is canned prose
+# rendered into the panes so the layout and status flow are visible.
+_PHASES = [
+    (
+        "Reconnaissance",
+        "Scout",
+        "Map the surface before touching anything.",
+        "enumerate",
+        "example.com",
+        "found 3 subdomains, 2 open ports",
+        "Surface mapped: api.example.com, www.example.com, mail.example.com.",
+    ),
+    (
+        "Analysis",
+        "Analyst",
+        "Weigh what the scout turned up.",
+        "assess",
+        "3 subdomains",
+        "api.example.com exposes an unauthenticated debug route",
+        "One notable exposure on api.example.com; the rest look routine.",
+    ),
+    (
+        "Report",
+        "Scribe",
+        "Write it up so a human can act on it.",
+        "compose",
+        "1 finding",
+        "drafted a 1-paragraph summary",
+        "Report ready: 1 finding worth a closer look on api.example.com.",
+    ),
+]
+
+
+@dataclass
+class _Usage:
+    """Stand-in for CrewAI's token-usage object; only these three fields are
+    read by the App's metrics block."""
+
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+@dataclass
+class _Result:
+    """Stand-in for a CrewOutput: the App reads ``.raw`` and ``.token_usage``."""
+
+    raw: str
+    token_usage: _Usage
+
+
+def _scripted_kickoff(crew: Crew) -> _Result:
+    """Walk the crew's tasks without calling an LLM.
+
+    For each task: stream a Thought + tool-call and an Answer through the crew's
+    ``step_callback`` (both set by the App before this runs), pause briefly so
+    the transition is visible, then fire the task's ``callback`` to advance the
+    sidebar. Returns a canned result carrying ``raw`` + ``token_usage`` so the
+    App renders the completion panel and metrics block.
+    """
+    for task, phase in zip(crew.tasks, _PHASES, strict=True):
+        _, _, thought, tool, tool_input, tool_result, answer = phase
+        if crew.step_callback is not None:
+            crew.step_callback(
+                AgentAction(
+                    thought=thought, tool=tool, tool_input=tool_input, text="", result=tool_result
+                )
+            )
+        time.sleep(0.6)
+        if crew.step_callback is not None:
+            crew.step_callback(AgentFinish(thought=thought, output=answer, text=answer))
+        if task.callback is not None:
+            task.callback(answer)
+        time.sleep(0.4)
+
+    return _Result(
+        raw="Demo pipeline complete - 3 phases, 1 finding.",
+        token_usage=_Usage(prompt_tokens=1200, completion_tokens=340, total_tokens=1540),
+    )
+
+
+def build_demo_crew() -> Crew:
+    """Build the offline demo crew with a scripted ``kickoff``.
+
+    A dummy ``OPENAI_API_KEY`` is set only if none is present so that
+    constructing the agents never prompts; no request is ever made because
+    ``kickoff`` is replaced before the App can call it.
+    """
+    os.environ.setdefault("OPENAI_API_KEY", "crewui-demo-no-network")
+
+    agents = []
+    tasks = []
+    for name, role, *_ in _PHASES:
+        agent = Agent(
+            role=role,
+            goal=f"{role} phase of the demo pipeline",
+            backstory=f"The {role.lower()} in a small demonstration crew.",
+            llm="gpt-4o-mini",
+            verbose=False,
+        )
+        agents.append(agent)
+        tasks.append(
+            Task(
+                description=f"{name} phase",
+                expected_output="a short summary",
+                agent=agent,
+                name=name,
+            )
+        )
+
+    crew = Crew(agents=agents, tasks=tasks, process=Process.sequential)
+    # Replace kickoff with the scripted walk. Crew is a pydantic model, so a
+    # plain attribute assignment is rejected; object.__setattr__ installs the
+    # bound method past that guard. This is the whole reason the demo can run
+    # with no API key and no network.
+    object.__setattr__(crew, "kickoff", types.MethodType(_scripted_kickoff, crew))
+    return crew
+
+
+def run_demo(dry_run: bool = False) -> None:
+    """Launch the TUI against the offline demo crew."""
+    CrewAIPipelineTUI(
+        crew=build_demo_crew(),
+        record_prefix="crewui.demo",
+        pipeline_name="crewui demo pipeline",
+        dry_run=dry_run,
+        get_token_cost=lambda inp, out: (inp * 3 + out * 15) / 1_000_000,
+    ).run()

crewui-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: crewui
+Version: 0.1.0
+Summary: A Textual TUI for sequential CrewAI pipelines
+Author: Nathan Bottomley-Cook
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/coolhandle01/crewui
+Project-URL: Issues, https://github.com/coolhandle01/crewui/issues
+Keywords: crewai,crewai-tools,textual,tui,terminal,console,ai-agents,agentic,pipeline,observability,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: crewai<1.16,>=1.15.6
+Requires-Dist: textual>=0.60
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: pylint>=3.2; extra == "dev"
+Requires-Dist: ruff==0.16.0; extra == "dev"
+Dynamic: license-file
+
+# crewui
+
+A [Textual](https://textual.textualize.io/) terminal UI for a sequential
+[CrewAI](https://github.com/crewAIInc/crewAI) pipeline. You build a `Crew`;
+crewui renders it — a sidebar task tracker, a live agent-output stream, a
+pipeline log, and a token/cost summary — and, when a task asks for human
+review, routes the feedback prompt to an input box instead of a blocking
+terminal `input()`.
+
+crewui is a presentation layer and nothing more. It reads a `Crew` and touches
+only two things beyond it: the step/task callback contract and, for human
+review, one semi-internal crewai provider hook. Everything application-specific
+— where a run id is recorded, how run metrics are computed and priced — is
+injected through callbacks, so the package never reaches up into your app.
+
+## Install
+
+```bash
+pipx install crewui        # the CLI + the demo, isolated
+# or, as a library in your project:
+pip install crewui
+```
+
+See it run without writing any code or setting an API key:
+
+```bash
+crewui demo                # drives a scripted three-phase pipeline in the TUI
+crewui demo --dry-run      # render the layout without walking the pipeline
+```
+
+The demo is fully offline — no LLM call, no network — so it doubles as a smoke
+test that the install works.
+
+## Use it in your app
+
+```python
+from crewui import CrewAIPipelineTUI
+
+CrewAIPipelineTUI(
+    crew=build_my_crew(),          # any sequential crewai.Crew
+    record_prefix="myapp",         # log records under this name render in the agent pane
+    pipeline_name="My Pipeline",   # sidebar title
+).run()
+```
+
+The sidebar reads each task's display name (`Task.name`) and agent role straight
+off `crew.tasks`, so wiring the crew is the whole job — there is no separate task
+map to maintain.
+
+### Injecting host behaviour
+
+Three optional callbacks carry everything crewui deliberately does not know:
+
+| Callback | When it fires | Typical use |
+|---|---|---|
+| `on_start()` | worker thread, right before `kickoff()` | bind a run id, stamp the start time |
+| `on_complete(result)` | right after `kickoff()` | persist run metrics |
+| `get_token_cost(input_tokens, output_tokens)` | when rendering the summary | return the USD estimate to display |
+
+A save failure in `on_complete` is swallowed and surfaced in the pipeline log —
+persistence never takes the UI down.
+
+### Theming
+
+`CrewAIPipelineTUI` ships a usable dark theme and owns it as an absolute
+`CSS_PATH`. A subclass ships its own look by setting its own `CSS_PATH`:
+
+```python
+class MyTUI(CrewAIPipelineTUI):
+    CSS_PATH = "my_app.tcss"
+```
+
+### Human review
+
+A `Task(human_input=True)` pauses the run for feedback. crewui opens the input
+box, parks the worker thread until you submit, and feeds what you type back into
+crewai's feedback loop (empty input — just Enter — means "accept"). The routing
+leans on `crewai.core.providers.human_input`, a semi-internal API isolated to a
+single factory in `crewui/app.py` so there is one place to fix if it moves
+between crewai versions.
+
+## The crewai version pin, and the fork
+
+crewui declares `crewai>=1.15.6,<1.16`.
+
+- **The floor (1.15.6)** is the first release where the agent executor's
+  `ask_for_human_input` compatibility property is back. A 1.14.5 executor
+  regression crashed `human_input=True` with
+  `'AgentExecutor' object has no attribute 'ask_for_human_input'`; below the
+  floor, the human-review feature does not work.
+- **The ceiling (<1.16)** is deliberate, not lazy. The human-input routing is
+  the one place crewui reaches past crewai's public surface, so a minor bump is
+  a review event: re-check that seam, then move the ceiling.
+
+There is a **second, separate** human-input bug that a stock PyPI crewai still
+carries: the feedback prompt tells the operator to review "the Final Result
+above", but crewai only renders that result when `verbose=True` — so under a TUI
+with verbose off, the operator is asked to review output that was never printed.
+The downstream project this library was extracted from pins a
+[crewai fork](https://github.com/coolhandle01/crewai) that adds a
+Result-for-Review panel so the referenced output is always shown. **crewui does
+not pin that fork** — it works against stock crewai, and simply streams each
+answer into the agent-output pane before the review gate opens, which is the
+generic equivalent of what the fork's panel does. If you need the fork's exact
+behaviour, pin it in *your* application, not here.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+
+ruff check .
+mypy
+pylint crewui
+pytest --cov=crewui --cov-branch --cov-report=term-missing --cov-fail-under=95
+```
+
+The pure helpers in `crewui/_helpers.py` are unit-tested; the App itself is
+driven through Textual's `pilot` harness in `tests/test_app.py` — status
+transitions, the dry-run preview, the metrics block, the error path, and the
+human-review gate all run against a fake offline crew.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

crewui-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+crewui/__init__.py,sha256=ibQcjcIs_X2EpBTxVje2cjv0TCS5HI9L92eQPANkU_E,1479
+crewui/__main__.py,sha256=oxFD0ILWMa6IzhdyVv9Ny88R4ZfaF9g7p2Z3qvncHNI,341
+crewui/_helpers.py,sha256=YaSRuyzUhIOmqIUYfw9-SdMk1_rUgsjU3tI2gcgZ8ho,3235
+crewui/app.py,sha256=-wYmmB-8fDYFGzVmXGeb7pajvHGr29eb9MJoIrplkfs,12701
+crewui/cli.py,sha256=xp4qtMkV_3is69uXhHffyD7tgnp0w3w7gzW3fVY_mmw,1973
+crewui/default.tcss,sha256=-OOwuZEr3sLGXRPhAWvDB9_QIcSTog13p6WJ3nWzQzA,1356
+crewui/demo.py,sha256=zMciXTv3fKYOU4c2MHl2qSWPkUIuBdtBlH8DgVL-Ugc,5631
+crewui/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crewui-0.1.0.dist-info/licenses/LICENSE,sha256=8of4gImqhbFqBBXO4BxTR1Z0l6NXyQnGg1TTKm--WmY,1078
+crewui-0.1.0.dist-info/METADATA,sha256=oMp7i3LIvGPz7WmyMr8YPqunL691cNT8jFjVF0Pv0eo,6521
+crewui-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+crewui-0.1.0.dist-info/entry_points.txt,sha256=6KvX8lnhMe08KVnT2OCXTVqpTc9N5c4JNt3jo5JBLho,43
+crewui-0.1.0.dist-info/top_level.txt,sha256=GtxE0pBpJDt9WbY08D_1CgSRE3Ply5X3Tuwl3XkTwSY,7
+crewui-0.1.0.dist-info/RECORD,,

crewui-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

crewui-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+crewui = crewui.cli:main

crewui-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Bottomley-Cook
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crewui-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+crewui