AI Integration Guide

About This Vignette

This vignette documents putior’s capabilities for AI assistants (like Claude, ChatGPT, or GitHub Copilot). It’s designed to be read by language models to understand how to use putior effectively.

For Humans

If you’re a human reader, you probably want one of these instead:

Guide	Description
Quick Start	Create your first diagram in 2 minutes
Annotation Guide	Complete syntax reference
Quick Reference	Printable cheat sheet
API Reference	Full function documentation
Troubleshooting	Common issues and solutions

For AI Assistants

This content is automatically available via:

putior_guide() - Returns this documentation as a string
MCP server - Exposed as a tool via putior_mcp_server()
ACP server - Available via /runs endpoint from putior_acp_server()

Programmatic Access

# Get guide documentation as a string
guide_text <- putior_guide()

# Use in prompt engineering
prompt <- paste("You have access to putior:", guide_text)

# Or access via MCP tools
tools <- putior_mcp_tools()

MCP/ACP Integration

When running as an MCP or ACP server, AI assistants can:

Discover capabilities via putior_guide tool
Extract annotations via put tool
Generate diagrams via put_diagram tool
Auto-detect workflows via put_auto tool

When putior warns during a call (invalid annotations, a < in a title or label, a diagram over Mermaid’s size limits, …), the tool returns the warnings as a second text part after its result, since R warnings never reach an MCP client otherwise. The put_diagram tool writes them as Mermaid comment lines (%% ...), so the diagram still renders if the client joins both parts; its first part is always exactly the Mermaid code.

Over HTTP, the MCP server (putior_mcp_server(type = "http")) and the ACP server scan only their root folder (by default the working directory). By default they listen on 127.0.0.1, so only programs on this machine reach them; to serve other machines, set host and a token. See the Security sections of ?putior_mcp_server and ?putior_acp_server.

See the MCP Server section in CLAUDE.md for setup instructions.

Agent-Almanac Integration

putior’s procedural documentation lives in the agent-almanac repository, which provides 6 skills for the complete putior workflow:

Skill	Purpose
`install-putior`	Installation and dependency setup
`analyze-codebase-workflow`	Auto-detect workflows in arbitrary codebases
`annotate-source-files`	Add PUT annotations to source files
`generate-workflow-diagram`	Generate themed Mermaid diagrams
`configure-putior-mcp`	Set up MCP/ACP server for AI assistants
`setup-putior-ci`	GitHub Actions CI/CD for diagram auto-refresh

Guide Documentation

The content below is the same as returned by putior_guide():

putior Quick Reference

For step-by-step procedures, see the agent-almanac putior skills: install-putior, analyze-codebase-workflow, annotate-source-files, generate-workflow-diagram, configure-putior-mcp, setup-putior-ci

Direct Access (Non-R Environments)

Access this guide without running R:

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

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

Quick Start

# 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:

# 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"`

Values go in double or single quotes. A value may contain the other kind of quote (label:"Don't panic", label:'Say "hi"') but not its own; there are no escapes, so backslashes in Windows paths stay as they are. A comment may follow the last value (# put id:"a", label:"Load" # first step). With validate = TRUE (the default), put() warns about each property it cannot read.

Multiline Annotations

Use backslash for continuation:

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

Block Comment Annotations

Languages using // comments also support PUT annotations inside /* */ and /** */ blocks:

/**
 * put id:"handler", label:"Request Handler", input:"request.json", output:"response.json"
 */
function handleRequest(req, res) { ... }

Use * put as the line prefix inside block comment bodies. Backslash continuation does not work inside block comments, so keep each annotation on one line.

Multi-Language Comment Syntax

putior automatically detects comment style by file extension (18 languages with auto-detection, 30+ total):

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

Examples by Language

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

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

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

Core Functions

`put()` - Extract Annotations

# 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

# Basic diagram
put_diagram(workflow)

# Customize appearance
put_diagram(workflow,
  direction = "LR",           # Left-to-right (default: "TD", top-down)
  theme = "github",           # Theme: github, light, dark, auto, minimal
  show_artifacts = TRUE       # Show data files as nodes (script --> file --> script)
)
put_diagram(workflow, show_artifacts = TRUE, artifact_edges = "both")  # Also the direct edges

# 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,       # Clickable nodes; need a renderer with securityLevel "loose" (not GitHub/GitLab/Quarto defaults)
  click_protocol = "vscode",  # vscode 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 = "file", file = "workflow.md")  # Save to file
mermaid_code <- put_diagram(workflow, output = "raw")  # Return as string

# Mermaid configuration in the diagram's frontmatter
put_diagram(workflow, mermaid_config = "classic")  # Default: Mermaid 11's look, also on GitHub's Mermaid 12
put_diagram(workflow, mermaid_config = "none")     # No configuration
put_diagram(workflow, mermaid_config = list(look = "neo"))  # Your own; a theme key is left out

# Screen reader text: accTitle (from title) and accDescr (a summary) are on by default
put_diagram(workflow, title = "Sales Pipeline")
put_diagram(workflow, accessibility = FALSE)       # Leave them out

Mermaid versions

putior writes classic Mermaid syntax only. The frontmatter (title and mermaid_config) needs Mermaid 9.3.0 or later, accTitle/accDescr 9.1.0 or later; for older renderers use mermaid_config = "none" and accessibility = FALSE.

Renderer	Mermaid (2026-10-12)	Source
GitHub	12.1.0	measured on github.com
pkgdown site, sandbox	12.2.0	putior’s pin
Quarto 1.10, 1.11	11.12.0	bundle (RStudio’s Quarto 1.9.38 ships it too, measured)
VS Code	11.17.0	package lock
GitLab	11.16.1	package.json
Positron	11.15.0	package lock

CI draws every diagram option on Mermaid 11.12.0, 11.17.2, 12.1.0 and 12.2.0 (tests/mermaid/). Newer syntax such as @{ shape: ... } (Mermaid 11.3+) is not used while Quarto ships 11.12.0.

`put_auto()` - Auto-Detect Workflow

Analyze code to detect inputs/outputs without annotations:

# 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

# 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

# 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

# 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

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

Hybrid Approach

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

Export for Documentation

# Save Mermaid diagram to markdown file
put_diagram(workflow, output = "file", file = "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:

run_sandbox()  # Requires shiny package

Quarto/RMarkdown Integration

# 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:

# 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

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

Guide	Description
Quick Start	First diagram in 2 minutes
Annotation Guide	Complete syntax reference
Features Tour	Auto-detection, themes, logging
API Reference	Function documentation
Showcase	Real-world examples
Quick Reference	At-a-glance reference card
Troubleshooting	Common issues and solutions