Periplon

A powerful DSL and Rust SDK for building multi-agent AI workflows and automation.

Table of Contents

• Overview
• Features
• Installation
• Quick Start - DSL
• Tools
  • Executor CLI
  • TUI (Terminal Interface)
• SDK Usage
• Documentation
• Examples
• Contributing
• License

Overview

Periplon provides a comprehensive DSL (Domain-Specific Language) for orchestrating multi-agent AI workflows with zero configuration. Define complex automation tasks in YAML, and let Periplon handle the execution, state management, and agent coordination.

Key Capabilities:

• 📝 Powerful DSL - YAML-based workflow definition language
• 🔄 Multi-Agent Workflows - Orchestrate complex AI agent interactions
• 🚀 Zero Configuration - Start instantly with embedded web UI and API server
• 🤖 Natural Language Generation - Create workflows from plain English
• 💾 State Management - Checkpoint and resume execution
• 🔌 Extensible - Plugin architecture with ports and adapters
• 🦀 Type-Safe Rust SDK - Strong typing with compile-time guarantees for advanced use cases

Features

DSL System

The Periplon DSL is the primary interface for building workflows:

• Multi-Agent Workflows: Define and orchestrate multiple specialized AI agents
• Natural Language Generation: Create workflows from plain English descriptions
• State Management: Automatic checkpoint and resume execution
• Dependency Resolution: DAG-based task execution with automatic ordering
• Variable System: Scoped variables with ${variable} interpolation
• Loop Support: ForEach, While, RepeatUntil, Repeat patterns for iterative tasks
• Validation: Comprehensive workflow validation before execution
• Tool Filtering: Control which tools each agent can access
• Permission Modes: Fine-grained control over agent capabilities
• Lifecycle Hooks: on_start, on_complete, on_error event handlers
• HTTP Collections: Fetch data from REST APIs with authentication

Rust SDK

For advanced programmatic usage:

• Hexagonal Architecture: Clean separation with ports and adapters pattern
• Type Safety: Strong Rust types with compile-time guarantees
• Async I/O: Non-blocking async/await using tokio
• Stream-Based: Efficient streaming without buffering
• Error Handling: Rich error types with context
• Testability: Mock adapters for isolated testing

Installation

For DSL Users

Build the executor CLI and TUI:

# Build the executor CLI with full features
cargo build --release --features full

# Build the TUI
cargo build --release --bin periplon-tui --features tui

Binaries will be available at:

• ./target/release/periplon-executor
• ./target/release/periplon-tui

For SDK Users

Add to your Cargo.toml:

[dependencies]
periplon = "0.1.0"
tokio = { version = "1", features = ["full"] }
futures = "0.3"

For detailed installation instructions, see Installation Guide.

Quick Start - DSL

Creating Your First Workflow

Create a simple workflow file hello-world.yaml:

name: "Hello World Workflow"
version: "1.0.0"
description: "A simple workflow demonstrating multi-agent coordination"

agents:
  greeter:
    description: "Generate friendly greetings"
    model: "claude-sonnet-4-5"
    permissions:
      mode: "default"

  writer:
    description: "Save greetings to a file"
    model: "claude-sonnet-4-5"
    tools: [Write]
    permissions:
      mode: "acceptEdits"

tasks:
  generate_greeting:
    description: "Generate a friendly greeting message"
    agent: "greeter"

  save_greeting:
    description: "Save the greeting to greeting.txt"
    agent: "writer"
    depends_on: [generate_greeting]

Running the Workflow

# Validate the workflow
./target/release/periplon-executor validate hello-world.yaml

# Run the workflow
./target/release/periplon-executor run hello-world.yaml

Generate Workflow from Natural Language

# Generate a workflow from description
./target/release/periplon-executor generate \
  "Create a workflow that analyzes a codebase, finds todos, and generates a report" \
  -o analyze-todos.yaml

# Run the generated workflow
./target/release/periplon-executor run analyze-todos.yaml

Advanced Example: Variable Interpolation

name: "Project Analysis"
version: "1.0.0"

inputs:
  project_name:
    type: string
    required: true
    default: "MyProject"

  output_dir:
    type: string
    required: true
    default: "./reports"

agents:
  analyzer:
    description: "Analyze code for ${workflow.project_name}"
    model: "claude-sonnet-4-5"
    tools: [Read, Grep, Glob]
    inputs:
      target_dir:
        type: string
        required: true

tasks:
  scan_codebase:
    description: "Scan ${workflow.project_name} codebase for issues"
    agent: "analyzer"
    inputs:
      target_dir: "./src"
    outputs:
      report:
        source:
          type: file
          path: "${workflow.output_dir}/analysis.json"

See the DSL Overview for comprehensive documentation.

Tools

Executor CLI

A complete workflow orchestration platform with zero configuration:

• 🚀 Zero-Config Server: Start instantly with no database required
• 🎨 Embedded Web UI: Full Next.js interface built into the binary
• ⚡ Production Ready: API server and web interface in one executable
• 🔧 Developer Friendly: Hot reload, validation, natural language generation

# Build the CLI
cargo build --release --features full

# Start server with embedded web UI
./target/release/periplon-executor server --port 8080 --workers

# Access web UI at http://localhost:8080

Documentation: CLI Usage | Embedded Web UI

TUI (Terminal Interface)

Interactive terminal interface for workflow management:

• 📁 Workflow Browser: Browse and manage workflow files
• ✏️ Smart Editor: YAML editor with syntax highlighting
• 🤖 AI Generation: Create workflows from natural language
• 📊 Execution Monitor: Real-time progress tracking
• 💾 State Management: Save and resume executions
• ⌨️ Keyboard-Driven: Full keyboard navigation

# Build the TUI
cargo build --release --bin periplon-tui --features tui

# Launch TUI
./target/release/periplon-tui

# Launch with custom workflow directory
./target/release/periplon-tui --workflow-dir ./my-workflows

Documentation:

• User Guide
• Keyboard Shortcuts
• Architecture
• Troubleshooting

SDK Usage

For advanced programmatic control, use the Rust SDK directly:

Simple Query

use periplon_sdk::{query, Message, ContentBlock};
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut stream = query("What is 2 + 2?", None).await?;

    while let Some(msg) = stream.next().await {
        match msg {
            Message::Assistant(assistant_msg) => {
                for block in assistant_msg.message.content {
                    if let ContentBlock::Text { text } = block {
                        println!("Assistant: {}", text);
                    }
                }
            }
            _ => {}
        }
    }
    Ok(())
}

Interactive Client

use periplon_sdk::{PeriplonSDKClient, AgentOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let options = AgentOptions {
        allowed_tools: vec!["Read".to_string(), "Write".to_string()],
        permission_mode: Some("acceptEdits".to_string()),
        ..Default::default()
    };

    let mut client = PeriplonSDKClient::new(options);
    client.connect(None).await?;

    client.query("List files in current directory").await?;
    // Process response...

    client.disconnect().await?;
    Ok(())
}

See the Quick Start Guide for more SDK examples.

Documentation

DSL System

• DSL Overview - Introduction to the DSL
• Loop Patterns Guide - Comprehensive loop reference
• Loop Cookbook - 25 production-ready patterns
• Loop Tutorial - Step-by-step guide
• DSL Implementation - Technical details
• Natural Language Generation - NL workflow generation
• HTTP Collections - HTTP/HTTPS integration
• Security Audit - Safety analysis

Getting Started

• Installation Guide - Setup and requirements
• Quick Start Guide - Get up and running
• Configuration Guide - Agent options and settings

SDK Reference

• Rust API Documentation
• Architecture Guide - Hexagonal architecture overview
• Message Types - Message type reference
• Error Handling - Error types and patterns
• Testing Guide - Comprehensive testing (166+ tests)

Example Workflows

• Example Workflows

Examples

DSL Workflow Examples

Run the included DSL examples:

# DSL executor example
cargo run --example dsl_executor_example

Loop Pattern Examples:

• ForEach Demo - Process collections
• While Demo - Polling pattern
• Polling Demo - API polling
• Parallel Demo - Concurrent execution
• HTTP Collection Demo - Fetch from APIs
• Checkpoint Demo - Resume capability

SDK Examples

Run the included SDK examples:

# Simple query
cargo run --example simple_query

# Interactive client
cargo run --example interactive_client

See examples/ for all examples.

Requirements

• Minimum CLI version: 2.0.0
• Rust: 1.70 or later
• Tokio runtime: Required for async operations

Testing

The SDK includes comprehensive test coverage with 166+ integration tests:

# Run all tests with server features
cargo test --lib --tests --features server

# Run specific test suite
cargo test --test execution_api_tests --features server

# Run tests with output
cargo test --features server -- --nocapture

Test Suites:

• Authentication & Authorization (26 tests)
• Queue Backend Operations (22 tests)
• Storage Backend Operations (21 tests)
• Schedule Management API (22 tests)
• Execution Management API (22 tests)
• WebSocket Streaming (21 tests)
• Workflow API Integration (32 tests)

See Testing Guide for comprehensive documentation and examples.

Contributing

Contributions are welcome! Please ensure:

1. All tests pass: cargo test --lib --tests --features server
2. Code is formatted: cargo fmt
3. No clippy warnings: cargo clippy
4. Documentation is updated

See CLAUDE.md for development guidelines.

License

MIT OR Apache-2.0

Resources

• Project Documentation
• API Reference
• Examples
• Change Log

Built with ❤️ in Rust