Metadata-Version: 2.4
Name: functualize-flow-viz
Version: 0.1.0
Summary: Inline flow visualization plugin for functualize job execution
Author-email: Mohammad Hakim Adiprasetya <viltohmyst@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: functualize<1.0.0,>=0.1.0
Requires-Dist: textual>=0.40.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# functualize-flow-viz

> **Status: Published** — Independently installable from PyPI.

Inline execution tree visualization plugin for functualize. Renders a live job execution tree in the terminal showing step status, durations, and nested invocations updating in real time. Automatically detects TTY capabilities and falls back to structured plain-text output for non-interactive terminals.

## Installation

```bash
pip install functualize-flow-viz
```

## Quick Start

```python
from functualize_flow_viz import FlowVizPlugin

# Register the plugin with your functualize app
plugin = FlowVizPlugin()
plugin.on_job_start("deploy", {"env": "production"})
plugin.on_log("info", "Starting deployment...")
plugin.on_invoke_start("migrate", {"target": "latest"})
plugin.on_invoke_end("migrate", None)
plugin.on_job_end("deploy", None)
```

## Features

- **Live execution tree** — Renders a real-time tree of job execution with status icons (⏳ running, ✓ success, ✗ failure, ○ pending, ⊘ timeout)
- **Nested invocation tracking** — Shows `rc.invoke()` calls as indented children in the tree, preserving parent-child relationships
- **Real-time duration refresh** — Background thread updates elapsed durations at ≤1s intervals for running nodes
- **TTY auto-detection** — Uses ANSI inline rendering on interactive terminals; falls back to plain-text output for piped/CI environments
- **Custom event handling** — Renders domain-specific visualizations including progress bars for events with progress payloads
- **Log streaming** — Buffers log messages and prints them above the inline tree widget to avoid visual corruption

## API Reference

Public classes and functions exported by this plugin:

- `FlowVizPlugin` — Main plugin class implementing the OutputRenderer protocol. Auto-selects between TTY and plain-text rendering. Methods:
  - `on_job_start(job_name, metadata)` — Initialize the execution tree for a job
  - `on_log(level, message)` — Render a log message
  - `on_status_change(old_status, new_status, message)` — Handle status transitions
  - `on_phase_change(step, action)` — Add or update a job phase node
  - `on_invoke_start(child_job_name, kwargs)` — Begin tracking a nested invocation
  - `on_invoke_end(child_job_name, result)` — Complete a nested invocation
  - `on_job_end(job_name, result)` — Finalize the tree and render final state
  - `on_event(event)` — Handle custom structured events
  - `render_log(message, level)` — OutputRenderer protocol: render log
  - `render_phase(phase, status)` — OutputRenderer protocol: render phase update
  - `render_progress(current, total, label)` — OutputRenderer protocol: render progress

Internal (non-public) classes used by `FlowVizPlugin`:

- `TreeNode` — Dataclass representing a node in the execution tree with label, status, timing, and children
- `InlineTTYRenderer` — ANSI-based renderer for interactive terminals with background refresh
- `PlainTextRenderer` — Fallback renderer producing structured plain-text without escape sequences

## Development

Run plugin tests:

```bash
uv run pytest plugins/functualize-flow-viz/tests/ -v
```
