2 unstable releases

0.2.0	Nov 7, 2025
0.1.0	Oct 26, 2025

#887 in Asynchronous

MIT/Apache

2.5MB
55K SLoC

Periplon

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

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:

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:

All tests pass: cargo test --lib --tests --features server
Code is formatted: cargo fmt
No clippy warnings: cargo clippy
Documentation is updated

See CLAUDE.md for development guidelines.

License

MIT OR Apache-2.0

Resources

Built with ❤️ in Rust

Dependencies

~25–63MB
~1M SLoC

bin+lib periplon

2 unstable releases

Periplon

Table of Contents

Overview

Features

DSL System

Rust SDK

Installation

For DSL Users

For SDK Users

Quick Start - DSL

Creating Your First Workflow

Running the Workflow

Generate Workflow from Natural Language

Advanced Example: Variable Interpolation

Tools

Executor CLI

TUI (Terminal Interface)

SDK Usage

Simple Query

Interactive Client

Documentation

DSL System

Getting Started

SDK Reference

Example Workflows

Examples

DSL Workflow Examples

SDK Examples

Requirements

Testing

Contributing

License

Resources

Dependencies