uipath-graphscii 0.0.2
Render UiPath runtime graphs to ASCII/Unicode art
Requires Python: >=3.11

# uipath-graphscii

Render UiPath runtime graphs to ASCII/Unicode art for console output.

## Installation

```bash
pip install uipath-graphscii
```

## CLI

Render any graph JSON file straight from the terminal:

```bash
uv run graphscii samples/react-agent/graph.json
```

```
          ┌───────────┐
          │ __start__ │
          └─────┬─────┘
                │
                ▼
  ┌ model ───────────────────┐
  │          model           │
  │ claude-3-7-sonnet-latest ◀──────┐
  └─────────────┬────────────┘      │
                └───────┐           │
       ┌────────┘       ▼           │
       ▼        ┌ tool ─────────┐   │
  ┌─────────┐   │     tools     │   │
  │ __end__ │   │ tavily_search ┤───┘
  └─────────┘   └───────────────┘
```

```bash
uv run graphscii samples/supervisor-agent/graph.json
```

```
                                                      ┌───────────┐
                                                      │ __start__ │
                                                      └─────┬─────┘
                                                            │
                                                            ▼
                                                       ┌ node ──┐
                                                       │ input  │
                                                       └────┬───┘
                                                            │
                                                            ▼
                                              ┌ model ───────────────────┐
                                              │        supervisor        │
                                              │ claude-3-7-sonnet-latest ◀──────────────────────────────────┐
                                              └─────────────┬────────────┘                               │  │
                       ┌────────────────────────────────────└───────┐      __end__                       │  │
                       ▼                                    └───────▼────────────────────────────┐       │  │
  ┌ node ───────────────────────────────────┐    ┌ node ───────────────────────────────┐         │       │  │
  │                  coder                  │    │              researcher             │         │       │  │
  │          ┌───────────┐                  │    │         ┌───────────┐               │         │       │  │
  │          │ __start__ │                  │    │         │ __start__ │               │         │       │  │
  │          └─────┬─────┘                  │    │         └─────┬─────┘               │         │       │  │
  │                │                        │    │               │                     │         │       │  │
  │                ▼                        │    │               ▼                     │         │       │  │
  │  ┌ model ───────────────────┐           │    │ ┌ model ───────────────────┐        │         ▼       │  │
  │  │          model           │           │    │ │          model           │        │    ┌ node ──┐   │  │
  │  │ claude-3-7-sonnet-latest ◀─────────┐ ┤────│ │ claude-3-7-sonnet-latest ◀──────┐ ┤────│ output │──────┘
  │  └─────────────┬────────────┘         │ │    │ └─────────────┬────────────┘      │ │    └────┬───┘
  │                └─────────┐            │ │    │               └───────┐           │ │        │
  │      ┌─────────┘         ▼            │ │    │      ┌────────┘       ▼           │ │        │
  │      ▼         ┌ tool ────────────┐   │ │    │      ▼        ┌ tool ─────────┐   │ │        │
  │ ┌─────────┐    │      tools       │   │ │    │ ┌─────────┐   │     tools     │   │ │        │
  │ │ __end__ │    │ python_repl_tool ┤───┘ │    │ │ __end__ │   │ tavily_search ┤───┘ │        │
  │ └─────────┘    └──────────────────┘     │    │ └─────────┘   └───────────────┘     │        │
  └─────────────────────────────────────────┘    └─────────────────────────────────────┘        │
                                                                                                │
                                                                                                ▼
                                                                                           ┌─────────┐
                                                                                           │ __end__ │
                                                                                           └─────────┘
```

### Options

```
usage: graphscii [-h] [-t THEME] [--ascii] [--no-types] [--list-themes] [file]

positional arguments:
  file                  Path to a graph JSON file

options:
  -h, --help            show this help message and exit
  -t THEME, --theme THEME
                        Color theme (use --list-themes to see options)
  --ascii               Use plain ASCII instead of Unicode box-drawing characters
  --no-types            Hide node type labels
  --list-themes         List available themes and exit
```

### Themes

Five built-in color themes that style nodes by type (model, tool, entry/exit, etc.):

```bash
uv run graphscii samples/react-agent/graph.json --theme monokai
uv run graphscii samples/react-agent/graph.json --theme ocean
uv run graphscii samples/react-agent/graph.json --theme forest
uv run graphscii samples/react-agent/graph.json --theme dracula
uv run graphscii samples/react-agent/graph.json             # default (no color)
```

List all available themes:

```bash
uv run graphscii --list-themes
```

### Samples

Render the included sample graphs to try it out:

```bash
uv run graphscii samples/react-agent/graph.json          # simple ReAct loop
uv run graphscii samples/deep-agent/graph.json           # middleware chain with 10 tools
uv run graphscii samples/workflow-agent/graph.json       # linear workflow with branching
uv run graphscii samples/supervisor-agent/graph.json     # nested subgraphs
```

## Python API

### Simple linear chain

```python
from uipath.runtime.schema import UiPathRuntimeGraph, UiPathRuntimeNode, UiPathRuntimeEdge
from uipath_graphscii import render

graph = UiPathRuntimeGraph(
    nodes=[
        UiPathRuntimeNode(id="a", name="Start", type="entry"),
        UiPathRuntimeNode(id="b", name="Process", type="tool"),
        UiPathRuntimeNode(id="c", name="End", type="exit"),
    ],
    edges=[
        UiPathRuntimeEdge(source="a", target="b"),
        UiPathRuntimeEdge(source="b", target="c"),
    ],
)

print(render(graph))
```

```
  ┌ entry ───┐
  │  Start   │
  └────┬─────┘
       │
       ▼
  ┌ tool ────┐
  │ Process  │
  └─────┬────┘
        │
        ▼
  ┌ exit ──┐
  │  End   │
  └────────┘
```

### Branching with edge labels

```python
graph = UiPathRuntimeGraph(
    nodes=[
        UiPathRuntimeNode(id="start", name="User Input", type="entry"),
        UiPathRuntimeNode(id="router", name="Router", type="condition"),
        UiPathRuntimeNode(id="search", name="Web Search", type="tool"),
        UiPathRuntimeNode(id="calc", name="Calculator", type="tool"),
        UiPathRuntimeNode(id="respond", name="Respond", type="model"),
    ],
    edges=[
        UiPathRuntimeEdge(source="start", target="router"),
        UiPathRuntimeEdge(source="router", target="search", label="search"),
        UiPathRuntimeEdge(source="router", target="calc", label="calc"),
        UiPathRuntimeEdge(source="search", target="respond"),
        UiPathRuntimeEdge(source="calc", target="respond"),
    ],
)

print(render(graph))
```

```
          ┌ entry ─────┐
          │ User Input │
          └──────┬─────┘
                 │
                 ▼
          ┌ condition ─┐
          │   Router   │
          └──────┬─────┘
         ┌search─└──calc──┐
         ▼                ▼
  ┌ tool ──────┐   ┌ tool ──────┐
  │ Web Search │   │ Calculator │
  └──────┬─────┘   └─────┬─────┘
         └──────┌─────────┘
                ▼
          ┌ model ───┐
          │ Respond  │
          └──────────┘
```

### Nested subgraphs

```python
sub = UiPathRuntimeGraph(
    nodes=[
        UiPathRuntimeNode(id="s1", name="Fetch Data", type="tool"),
        UiPathRuntimeNode(id="s2", name="Transform", type="action"),
    ],
    edges=[UiPathRuntimeEdge(source="s1", target="s2")],
)

graph = UiPathRuntimeGraph(
    nodes=[
        UiPathRuntimeNode(id="a", name="Start", type="entry"),
        UiPathRuntimeNode(id="b", name="ETL Pipeline", type="subgraph", subgraph=sub),
        UiPathRuntimeNode(id="c", name="Done", type="exit"),
    ],
    edges=[
        UiPathRuntimeEdge(source="a", target="b"),
        UiPathRuntimeEdge(source="b", target="c"),
    ],
)

print(render(graph))
```

```
      ┌ entry ──┐
      │  Start  │
      └────┬────┘
           │
           ▼
  ┌ subgraph ──────┐
  │  ETL Pipeline  │
  │ ┌ tool ──────┐ │
  │ │ Fetch Data │ │
  │ └──────┬─────┘ │
  │        │       │
  │        ▼       │
  │ ┌ action ────┐ │
  │ │ Transform  │ │
  │ └────────────┘ │
  └───────┬────────┘
          │
          ▼
     ┌ exit ──┐
     │  Done  │
     └────────┘
```

### Themes (Python API)

```python
from uipath_graphscii import render, RenderOptions, get_theme

options = RenderOptions(theme=get_theme("monokai"))
print(render(graph, options))
```

## Options

```python
from uipath_graphscii import RenderOptions

options = RenderOptions(
    use_unicode=True,   # Use Unicode box-drawing characters (default: True)
    show_types=True,    # Show node types in box borders (default: True)
    padding=2,          # Padding around the diagram (default: 2)
)

print(render(graph, options))
```

### ASCII mode

```python
print(render(graph, RenderOptions(use_unicode=False)))
```

```
  + entry ---+
  |  Start   |
  +----+-----+
       |
       v
  + tool ----+
  | Process  |
  +-----+----+
        |
        v
  + exit --+
  |  End   |
  +--------+
```

## Testing

```bash
uv run pytest tests/ -v
```