---
name: putior
description: Extract workflow annotations from source code and generate Mermaid diagrams
version: 0.2.0.9000
tags: [r, documentation, workflow, mermaid, visualization, multi-language, code-analysis]
languages: [R, Python, SQL, JavaScript, TypeScript, Go, Rust, Java, C, C++, MATLAB, Ruby, Lua, Julia, Shell]
repository: https://github.com/pjt222/putior
documentation: https://pjt222.github.io/putior/
---

# putior Skills

Skills for AI coding assistants to help users document and visualize code workflows.

## Direct Access (Non-R Environments)

Access these skills without running R:

| Method | URL |
|--------|-----|
| Web Page | https://pjt222.github.io/putior/articles/skills.html |
| Raw Markdown | https://raw.githubusercontent.com/pjt222/putior/main/inst/SKILLS.md |
| GitHub View | https://github.com/pjt222/putior/blob/main/inst/SKILLS.md |

For R users: `putior_skills(output = "raw")` returns this content as a string.

## Quick Start

```r
# 1. Extract annotations from source files
workflow <- put("./R/")

# 2. Generate Mermaid diagram
put_diagram(workflow)

# 3. Auto-detect workflow without annotations
workflow <- put_auto("./src/")
```

## Annotation Syntax

Add `# put` comments to source files to define workflow nodes:

```r
# put id:"load", label:"Load Data", output:"raw_data.csv"
data <- read.csv("input.csv")

# put id:"transform", label:"Clean Data", input:"raw_data.csv", output:"clean.rds"
clean <- transform(data)

# put id:"analyze", label:"Run Analysis", input:"clean.rds", node_type:"decision"
results <- analyze(clean)
```

### Annotation Properties

| Property | Required | Description | Example |
|----------|----------|-------------|---------|
| `id` | Yes | Unique node identifier | `id:"load_data"` |
| `label` | No | Display text (defaults to id) | `label:"Load CSV"` |
| `input` | No | Input files/data (comma-separated) | `input:"a.csv, b.csv"` |
| `output` | No | Output files/data | `output:"result.rds"` |
| `node_type` | No | Shape: input, process (default), output, decision, start, end | `node_type:"decision"` |

### Multiline Annotations

Use backslash for continuation:

```r
# put id:"complex_step", \
#     label:"Multi-step Process", \
#     input:"file1.csv, file2.csv", \
#     output:"combined.rds"
```

## Multi-Language Comment Syntax

putior automatically detects comment style by file extension:

| Prefix | Languages | Extensions |
|--------|-----------|------------|
| `# put` | R, Python, Shell, Julia, Ruby, Perl, YAML | `.R`, `.py`, `.sh`, `.jl`, `.rb`, `.pl`, `.yaml` |
| `-- put` | SQL, Lua, Haskell | `.sql`, `.lua`, `.hs` |
| `// put` | JavaScript, TypeScript, C, C++, Java, Go, Rust, Swift, Kotlin, C#, PHP | `.js`, `.ts`, `.c`, `.cpp`, `.java`, `.go`, `.rs` |
| `% put` | MATLAB, LaTeX | `.m`, `.tex` |

### Examples by Language

```sql
-- query.sql
-- put id:"fetch", label:"Fetch Customers", output:"customers"
SELECT * FROM customers;
```

```javascript
// transform.js
// put id:"process", label:"Transform JSON", input:"data.json", output:"output.json"
const result = data.map(transform);
```

```matlab
% analysis.m
% put id:"stats", label:"Statistical Analysis", input:"data.mat", output:"results.mat"
results = compute_statistics(data);
```

## Core Functions

### `put()` - Extract Annotations

```r
# Scan directory for annotations
workflow <- put("./R/")

# Scan specific file
workflow <- put("./scripts/pipeline.R")

# Custom file pattern
workflow <- put("./src/", pattern = "\\.py$")

# Enable debug logging
workflow <- put("./R/", log_level = "DEBUG")

# Exclude test files
workflow <- put("./R/", exclude = "test")
```

### `put_diagram()` - Generate Diagrams

```r
# Basic diagram
put_diagram(workflow)

# Customize appearance
put_diagram(workflow,
  direction = "LR",           # Left-to-right (default: TB top-bottom)
  theme = "github",           # Theme: github, light, dark, auto, minimal
  show_artifacts = TRUE       # Show data files as nodes
)

# Colorblind-safe themes (viridis family)
put_diagram(workflow, theme = "viridis")  # Purple-blue-green-yellow
put_diagram(workflow, theme = "magma")    # Warm: purple-red-yellow
put_diagram(workflow, theme = "plasma")   # Vibrant: purple-pink-yellow
put_diagram(workflow, theme = "cividis")  # Blue-yellow (max accessibility)

# Interactive features
put_diagram(workflow,
  enable_clicks = TRUE,       # Make nodes clickable
  click_protocol = "vscode",  # vscode, rstudio, or file
  show_source_info = TRUE     # Show source file in nodes
)

# Output options
put_diagram(workflow, output = "clipboard")        # Copy to clipboard
put_diagram(workflow, output = "workflow.md")      # Save to file
mermaid_code <- put_diagram(workflow, output = "raw")  # Return as string
```

### `put_auto()` - Auto-Detect Workflow

Analyze code to detect inputs/outputs without annotations:

```r
# Auto-detect from R files
workflow <- put_auto("./R/")

# Control what to detect
workflow <- put_auto("./src/",
  detect_inputs = TRUE,
  detect_outputs = TRUE,
  detect_dependencies = TRUE
)

# Combine with manual annotations
workflow <- put_merge("./src/", merge_strategy = "supplement")

# Exclude vendor/test directories
workflow <- put_auto("./src/", exclude = c("vendor", "test"))
```

### `put_generate()` - Generate Annotation Templates

```r
# Print suggested annotations
put_generate("./R/")

# Copy to clipboard
put_generate("./R/", output = "clipboard")

# Multiline style
put_generate("./R/", style = "multiline")
```

## Auto-Detection Patterns

Languages with pattern-based detection (902 patterns total):

| Language | Patterns | Key Libraries |
|----------|----------|---------------|
| R | 124 | readr, data.table, DBI, arrow, ellmer |
| Python | 159 | pandas, numpy, sqlalchemy, transformers, langchain |
| JavaScript | 71 | Node.js fs, Express, mongoose, Prisma |
| TypeScript | 88 | All JS + NestJS, TypeORM |
| Java | 73 | NIO, JDBC, Jackson, Spring Boot |
| Ruby | 64 | File, CSV, Rails, ActiveRecord |
| Rust | 60 | std::fs, serde, sqlx, diesel |
| Go | 44 | os, bufio, database/sql, gorm |
| C++ | 44 | fstream, boost, std::filesystem |
| MATLAB | 44 | readtable, imread, h5read |
| Julia | 27 | CSV.jl, DataFrames, JLD2 |
| C | 24 | stdio.h, POSIX, mmap |
| Lua | 20 | io library, loadfile |
| WGSL | 17 | GPU bindings, textures, samplers, naga-oil |
| Dockerfile | 13 | FROM, COPY, ADD, EXPOSE, VOLUME, CMD, RUN |
| Shell | 12 | cat, redirects, source |
| Makefile | 10 | include, wildcard, target rules, install |
| SQL | 8 | FROM, JOIN, COPY |

### LLM Library Detection

Detects modern AI/ML libraries:

**R**: ellmer (`chat()`, `chat_openai()`, `chat_claude()`), tidyllm, httr2 API calls

**Python**: ollama, openai, anthropic, langchain, transformers, litellm, vllm, groq

## Helper Functions

```r
# Get comment prefix for extension
get_comment_prefix("sql")   # Returns "--"
get_comment_prefix("js")    # Returns "//"

# List supported extensions
get_supported_extensions()

# List supported languages
list_supported_languages()                    # All 30+ languages
list_supported_languages(detection_only = TRUE)  # 18 with auto-detection

# Get detection patterns
patterns <- get_detection_patterns("python")
patterns <- get_detection_patterns("r", type = "input")

# Available themes
get_diagram_themes()

# Interactive help
putior_help()
```

## Common Patterns

### Document Existing Codebase

```r
# 1. Auto-generate annotation suggestions
put_generate("./R/", output = "clipboard")

# 2. Paste into source files and customize
# 3. Extract and visualize
workflow <- put("./R/")
put_diagram(workflow)
```

### Quick Visualization Without Annotations

```r
# Instant workflow diagram from code analysis
workflow <- put_auto("./src/")
put_diagram(workflow, show_artifacts = TRUE)
```

### Hybrid Approach

```r
# Manual annotations for key files, auto-detect the rest
workflow <- put_merge("./src/", merge_strategy = "supplement")
put_diagram(workflow)
```

### Export for Documentation

```r
# Save Mermaid diagram to markdown file
put_diagram(workflow, output = "docs/workflow.md")

# Get raw Mermaid code for embedding
mermaid_code <- put_diagram(workflow, output = "raw")
```

## Node Types

| Type | Mermaid Shape | Use For |
|------|---------------|---------|
| `input` | Stadium `([...])` | Data sources, file loading, API inputs |
| `process` | Rectangle `[...]` (default) | Data processing, transformations |
| `output` | Subroutine `[[...]]` | Report generation, exports, final outputs |
| `decision` | Diamond `{...}` | Conditional logic, branching workflows |
| `start` | Stadium `([...])` | Workflow entry point (special boundary styling) |
| `end` | Stadium `([...])` | Workflow exit point (special boundary styling) |
| `artifact` | Cylinder `[(...)]` | Data files (auto-created with `show_artifacts = TRUE`) |

> **Note**: `artifact` nodes are automatically created by `put_diagram()` when `show_artifacts = TRUE`. They are not set manually via `node_type`.

## Diagram Themes

| Theme | Use Case |
|-------|----------|
| `light` | Bright colors (default) |
| `dark` | Dark mode environments |
| `auto` | GitHub-adaptive with solid colors |
| `minimal` | Print-friendly, grayscale |
| `github` | Optimized for README files |
| `viridis` | Colorblind-safe (purple-blue-green-yellow) |
| `magma` | Colorblind-safe (purple-red-yellow) |
| `plasma` | Colorblind-safe (purple-pink-yellow) |
| `cividis` | Maximum accessibility (blue-yellow) |

## Interactive Sandbox

Launch browser-based annotation playground:

```r
run_sandbox()  # Requires shiny package
```

## Quarto/RMarkdown Integration

```r
# In R chunk
workflow <- put("./R/")
mermaid_code <- put_diagram(workflow, output = "raw")
```

Then use `knitr::knit_child()` to embed as native Mermaid chunk.

## Logging

Enable debug output for troubleshooting:

```r
# Set globally
options(putior.log_level = "DEBUG")
set_putior_log_level("DEBUG")

# Per-call override
workflow <- put("./R/", log_level = "DEBUG")
```

Levels: `DEBUG`, `INFO`, `WARN` (default), `ERROR`

## Tips for AI Assistants

1. **Start with `put_auto()`** for unfamiliar codebases to quickly understand data flow
2. **Use `put_generate()`** to create annotation templates users can customize
3. **Prefer `put_merge()`** when combining manual and auto-detected workflows
4. **Check comment syntax** - use correct prefix for target language
5. **Enable `show_artifacts = TRUE`** to visualize data file dependencies
6. **Use `enable_clicks = TRUE`** for navigable documentation