swale

The audit-first pipeline orchestration platform for organizations that need to prove what happened, when, and why.

Vision

swale combines provability with composability—enabling you to definitively prove what happened during pipeline execution while building arbitrarily complex workflows from simple, reusable primitives.

Unlike agent orchestration frameworks where the LLM drives control flow, swale pipelines are explicit structures known ahead of time. Agents execute tasks within them as first-class workers. The result: predictable, debuggable systems where complex behavior emerges from composing simple primitives, not hoping an agent "figures it out."

---

What Makes swale Different

The Core Insight

Most pipeline platforms focus on execution speed, durability, or developer experience alone. swale is audit-first: the ability to definitively prove what happened is not an afterthought—it's the primary design constraint that shapes all other decisions.

Traditional CI/CD	Agent Frameworks	swale
Can't handle AI workflows	LLM drives control flow	AI-native, but explicit
Basic job logs	Fuzzy memory/scratchpad	Hermetic snapshots
Rigid or unpredictable	Black box decisions	Composable, provable

---

Core Principles

Pipelines Are Explicit and Defined

All execution paths are declared ahead of time. Even agent-driven routing happens through explicit, predefined routes. This makes pipelines testable, versionable, and reasonnable—agents influence control flow but operate within known boundaries.

Agents Are Workers, Not Orchestrators

An agent step is interchangeable with a script step. Both follow the same contract, both produce audit snapshots, both compose with any primitive. The "brain" is the static structure you define—not the LLM.

This distinction matters: pipelines remain predictable even when agents produce unpredictable outputs.

Explicit State Management

Unlike frameworks with fuzzy memory systems, swale uses strictly typed state containers. State transitions are atomic, happening only when steps complete successfully. Every transition is captured in the ledger.

This enables:

• Predictable debugging: See exact state at any point
• Safe parallelism: No race conditions from shared mutable memory
• Clear contracts: Steps declare inputs and outputs upfront

Filesystem as Communication Layer

Steps communicate via files, not direct memory sharing. This makes swale inherently inspectable and language-agnostic—any process that can read/write files can participate.

Audit-First Design

The ledger system exists first; execution features build on top of auditability. Every step captures:

• Complete inputs and outputs
• Environment state at execution time
• Agent decisions with full context (prompts, model choices, responses)
• Artifact lineage showing what produced what

Why this matters:

• Compliance: Regulated industries (finance, healthcare) need evidence trails
• Reproduction: Exact reproduction of any run for debugging
• Root cause analysis: See complete state when failures occurred
• Confidence in changes: Compare before/after snapshots to understand impact

---

Project Status

⚠️ Active Development — All APIs are unstable and subject to change.

The framework is undergoing significant architectural overhaul and usage is not yet recommended for production.

---

Quick Start

# Install from source
pip install -e .

# Run tests
pytest

# Type check
mypy src/swale/
ruff check src/swale/

---

Core Concepts

Artifacts

Artifacts are the first-class citizens of swale. Every file, document, or data object that a step reads or writes is an artifact with:

• Stable identity: An Artifact has a consistent logical ID (e.g., "plan")
• Versioned snapshots: Each capture creates an immutable ArtifactRecord in the ledger
• Provenance tracking: produced_by and consumed_by fields show the complete lineage
• Declarative contracts: Steps declare required inputs and promised outputs upfront

Why artifacts matter:

• Type safety: Artifacts are explicit objects with metadata, not implicit file paths
• Fail-fast validation: Missing dependencies caught before expensive operations run
• Self-documenting pipelines: Reading a step's constructor shows its full I/O contract
• Impact analysis: When a step fails, you can trace which downstream artifacts are affected

Artifact types:

• PROJECT_FILE: Files that evolve with your project (e.g., src/Foo.php)
• PIPELINE_ONLY: Internal pipeline files stored in the ledger (e.g., plans/myplan.md)
• EPHEMERAL: Temporary files cleaned up after execution

Snapshot strategies:

• FULL: Capture entire content (critical outputs)
• DIFF: Unified diff from project state (source code changes)
• HASH_ONLY: SHA256 hash only (large binaries)
• NONE: No capture (cache, temp files)

Steps

The fundamental building block. Two categories:

Category	Purpose	Examples
Lexical	Control flow	Branch, StepSequence, LoopSequence, Parallel
Executive	Do work	BaseStep, AgentStep, FnStep

Every step:

• Declares artifact requirements (inputs) and outputs
• Produces a hermetic snapshot on completion
• Composes with any other step or primitive

PipelineContext

Typed state container that flows through a pipeline. Carries configuration, intermediate results, and the artifact registry.

Execution

The executor runs steps with:

• Gating: Pre-step validation (including artifact contract checks)
• Checkpointing: Resumable execution from failure points
• Retry strategies: Automatic recovery with backoff

---

Package Structure

swale/
├── core/              ← Core framework (BaseStep, PipelineContext, executor, artifacts)
├── agent_harness/     ← Agent invocation infrastructure
├── cli/               ← Command-line interface
├── discovery/         ← Pipeline and step discovery
├── infrastructure/    ← Infrastructure abstractions
├── ledger/            ← Audit trail and run history
├── orchestration/     ← Pipeline orchestration logic
├── providers/         ← External service providers
├── steps/             ← Advanced step primitives
└── teams/             ← Multi-agent team orchestration

---

Development

# Auto-fix linting
ruff check --fix src/swale/
ruff format src/swale/

# Verify
ruff check src/swale/
mypy src/swale/
pytest

Before committing:

• ruff check passes with zero errors
• mypy passes with zero errors
• Tests pass
• No unjustified # type: ignore