# Alteryx Runner

A Python-native runner for Alteryx `.yxmd` workflow files — no Alteryx installation required.

## Prerequisites

- **Python 3.11+**
- **[uv](https://docs.astral.sh/uv/)** — fast Python package manager

## Setup

```bash
# Install all dependencies
uv sync
```

## Running a Workflow

```bash
uv run python -m alteryx_runner run <path/to/workflow.yxmd> [options]
```

### Example

```bash
uv run python -m alteryx_runner run ./Alteryx_TestWorkflows/Unique\&Sample/Unique\&Sample.yxmd --verbose
```

### Options

| Flag | Description |
|---|---|
| `--verbose` | Print Browse results and detailed execution log |
| `--dry-run` | Parse and validate only — do not execute |
| `--output-dir PATH` | Write output files to a specific directory |
| `--param KEY=VALUE` | Set a workflow constant (repeatable) |
| `--format [csv\|json\|parquet]` | Default output format for Browse nodes (default: `csv`) |

### Dry-Run (Validate Only)

Check that a workflow parses correctly without executing it:

```bash
uv run python -m alteryx_runner run ./Alteryx_TestWorkflows/JoinTesting/JoinTesting.yxmd --dry-run
```

### Custom Output Directory & Format

```bash
uv run python -m alteryx_runner run ./workflow.yxmd --output-dir ./results --format parquet
```

### Workflow Parameters

Pass runtime constants with `--param`:

```bash
uv run python -m alteryx_runner run ./workflow.yxmd --param "StartDate=2024-01-01" --param "Region=West"
```

## Listing Supported Tools

See all registered Alteryx tool plugins:

```bash
uv run python -m alteryx_runner list-tools
```

## Supported Tool Categories

| Category | Tools |
|---|---|
| **In/Out** | Input Data, Output Data, Browse, Text Input |
| **Preparation** | Filter, Formula, Multi-Field Formula, Multi-Row Formula, Select, Sort, Sample, Unique, Record ID, Auto Field, Generate Rows |
| **Join** | Join, Join Multiple, Union, Append Fields, Find Replace |
| **Parse** | DateTime, RegEx, Text To Columns |
| **Transform** | Summarize, Cross Tab, Transpose |

## Project Structure

```
alteryx_runner/
├── cli.py              # CLI entry point
├── engine/
│   ├── parser.py       # .yxmd XML → workflow graph
│   ├── executor.py     # Topological execution engine
│   ├── graph.py        # DAG data structures
│   └── context.py      # Runtime context & config
├── expression/         # Alteryx expression parser
└── tools/              # Tool implementations
    ├── inout/          # Input Data, Output Data, Browse, Text Input
    ├── join/           # Join, Union, Append Fields, Find Replace
    ├── parse/          # DateTime, RegEx, Text To Columns
    ├── preparation/    # Filter, Formula, Sort, Sample, Unique, …
    └── transform/      # Summarize, Cross Tab, Transpose
```