crewui 0.1.0__tar.gz

crewui-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to crewui
+
+crewui is a small, focused package: a Textual TUI for a sequential CrewAI
+pipeline. The bar is that it stays small and stays honest about its one
+dependency seam. These are the rules that keep it there.
+
+## The line the package holds
+
+**crewui reads a `Crew` and renders it. It does not reach up into the host.**
+
+Everything application-specific — a run id, metrics, pricing, persistence — is
+injected through the `on_start` / `on_complete` / `get_token_cost` callbacks.
+If you find yourself importing anything from a host application, or adding a
+third runtime dependency, stop: that logic belongs in the host, passed in as a
+callback, not in crewui.
+
+There are exactly **two** runtime dependencies — `crewai` and `textual` — and
+that is a promise, not an accident. A presentation layer that drags in a
+transitive dependency tree is a liability in someone else's app.
+
+## The one seam that reaches past the public surface
+
+Human review leans on `crewai.core.providers.human_input`, which is
+semi-internal. It is isolated to a single factory (`_make_tui_human_input_provider`)
+and a deferred import in `crewui/app.py`, on purpose: when crewai moves it, that
+is the one place to fix. This is also why the crewai pin has a ceiling
+(`<1.16`) — a minor bump is a review event for that seam, not an automatic
+upgrade. See the README's version-pin section.
+
+## Before you commit
+
+Run the same stack CI runs, inside a `.venv` with `pip install -e ".[dev]"`:
+
+```bash
+ruff check .
+mypy
+pylint crewui
+pytest --cov=crewui --cov-branch --cov-report=term-missing --cov-fail-under=95
+```
+
+Then `git diff origin/main --stat` to confirm only what you meant to change is
+staged. Running the linters is part of the work, not a formality left for
+review.
+
+- **Branch** from current `main`, named `<type>/<short-description>` where
+  `<type>` matches the commit type (`feat/`, `fix/`, `docs/`, `chore/`,
+  `refactor/`). Do not work on `main`.
+- **Commit** with Conventional Commits — `<type>(<scope>)?: <subject>`,
+  lowercase imperative subject. CI checks this, and `cz bump` derives the
+  version from it.
+- **Never** force-push, `push --delete`, or `branch -D` a shared or PR branch
+  without explicit authorisation. `--force-with-lease` is no exception.
+- Never put session URLs in commit messages or PR bodies.
+
+## Testing discipline
+
+The pure helpers (`crewui/_helpers.py`) are unit-tested to full branch
+coverage. The App layer is driven through Textual's `pilot` harness against the
+fake offline crew in `tests/conftest.py` — never against a real `crewai.Crew`,
+so the suite needs no API key and makes no network call. A new code path in the
+App gets a pilot test; a new helper gets a unit test.
+
+An assertion that still passes on empty output is not an assertion — check the
+value, not just that nothing raised.
+
+## Releasing
+
+Versions are derived from commit messages, not chosen by hand:
+
+```bash
+cz bump                  # reads commits since the last tag, decides the increment
+git push --follow-tags   # the bump commit carries the tag with it
+```
+
+Pushing a `v*` tag is the only thing that triggers `release.yml`: build,
+`twine check`, smoke-test the built wheel on 3.10 and 3.13 (both entry points
+must agree), then publish to PyPI via Trusted Publishing and cut a GitHub
+release. Nothing publishes on an ordinary push or pull request.
+
+Do not cut the release through the GitHub UI — `release.yml` runs
+`gh release create` itself, and a hand-made release makes that step fail after
+PyPI has already published.

crewui-0.1.0/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/MANIFEST.in

@@ -0,0 +1,7 @@
+# Ship the suite and docs so a downstream packager can verify the build they
+# are shipping, rather than taking our word for it or fetching from git.
+include README.md CONTRIBUTING.md LICENSE
+recursive-include tests *.py
+# The default stylesheet is package data (see pyproject), but spell it out here
+# too so the sdist carries it even if package-data handling changes.
+recursive-include crewui *.tcss py.typed

crewui-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,126 @@
+# 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/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-0.1.0/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-0.1.0/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)