Argyll

Goal-Driven Orchestrator

Argyll is a goal-driven orchestrator. You declare what you want to achieve, the engine builds an execution plan, and it executes only the minimal set of steps needed. All state changes are immutable events, giving you a complete audit trail.

Getting Started

# Start with Docker Compose
docker compose up
# Engine: http://localhost:8080
# UI: http://localhost:3001

New to Argyll? Start here:

1. Quickstart - 5-minute end-to-end example
2. Core Concepts - Goals, steps, flows, events
3. Full Documentation - Complete docs map

How It Works

1. Define steps with inputs and outputs
2. Create a flow by specifying goal steps
3. Engine computes the minimal execution plan
4. Execute and audit - all state changes recorded as events

Key Features

• Event Sourcing: Complete audit trail of all state changes
• Lazy Evaluation: Execute only what's needed to reach goals
• Multi-Instance: Horizontal scaling with optimistic concurrency
• Real-Time UI: WebSocket updates, live flow monitoring
• Four Step Types: Sync/Async HTTP, Scripts (Ale/Lua), Sub-flows
• Built-In Retry: Configurable backoff strategies
• Flow Archiving: Automatic archiving of completed flows

Installation

# Docker Compose (all services)
docker compose up

# Go
go install github.com/kode4food/argyll/cmd/argyll@latest

# Manual local testing
export CATALOG_REDIS_ADDR=localhost:6379
go run ./cmd/argyll

API Overview

Full OpenAPI spec: docs/api/engine-api.yaml

# Steps
POST   /engine/step              # Register step
GET    /engine/step              # List all steps
GET    /engine/step/:stepID      # Get step
PUT    /engine/step/:stepID      # Update step
DELETE /engine/step/:stepID      # Delete step

# Flows
POST   /engine/flow              # Start flow
GET    /engine/flow              # List flows
POST   /engine/flow/query        # Query flows
GET    /engine/flow/:flowID      # Get flow state
POST   /engine/plan              # Preview execution plan

# Engine & Health
GET    /engine                   # Get complete engine state
GET    /engine/health            # Get step health status
GET    /engine/ws                # WebSocket event stream

Documentation

• Getting Started - Quickstart, dev setup, concepts
• How-To Guides - Step types, parallelism, predicates, configuration
• Go SDK - Building steps in Go
• Python SDK - Building steps in Python
• API Reference - OpenAPI specs and curl examples
• Examples - 7 runnable example steps

Status

Work in progress. Core features stable. Not yet production-ready. Use at your own risk.