examples/

README

Trellis Examples

This directory contains examples demonstrating different ways to use the Trellis engine.

🚀 Start Here

New to Trellis? Begin with:

1. Tour — Run trellis run ./examples/tour for a guided walkthrough
2. Hello World — Minimal example using in-memory graphs

Then explore by category below based on your needs.

---

📑 Table of Contents

• 🚀 Start Here
• 1. Getting Started
• 2. Core Features
• 3. Infrastructure & Patterns
• 4. Advanced Control
• 5. Production & Observability
• 6. Internals & API

---

1. Getting Started

Tour (The Product)

Concepts: Loam Adapter, Markdown Files, CLI A content-heavy example that demonstrates the features of the Trellis file format (.md files). This is what you run with trellis run ./examples/tour.

Hello World (Standard)

Concepts: MemoryLoader, TUI, trellis.Runner The standard entry point for developers building internal tools. It shows how to define a graph in Go code (in-memory) and run it using the standard Runner.

---

2. Core Features

Default Context (Mocking)

Concepts: default_context, Mocking, Local Dev Demonstrates how to define fallback values in start.md. These defaults act as mocks for local development, allowing you to run flows without needing lengthy CLI context flags.

Data Validation (Fail Fast)

Concepts: required_context, Fail Fast Shows how to enforce data contracts using required_context. If a required key is missing, the engine stops immediately, preventing "silent failures" later in the flow.

Typed Flow (Context Schema)

Concepts: context_schema, Typed Context, Fail Fast Demonstrates type validation for context values before nodes render. Useful for catching data mismatches early.

Tools Demo (Safety & Metadata)

Concepts: on_error, metadata.confirm_msg, Implicit IDs Demonstrates robust tool usage, including Safety Middleware (confirmation prompts) and Error Handling (on_error transitions).

3. Infrastructure & Patterns

Manual Security (Encryption & PII)

Concepts: Middleware, Encryption, PII Masking Showcases how to securely wrap the state store with encryption and PII sanitization middleware. This is a manual infrastructure setup (wrapping the runner) rather than a built-in feature.

Compensation Manual (Transaction Rollback)

Concepts: Saga Pattern, on_error, Rollback Demonstrates how to implement distributed transactions with compensating actions (Rollback) using standard Trellis primitives (Manual Wiring).

Compensation Native (Automatic Rollback)

Concepts: Native SAGA, do/undo, on_error: rollback Demonstrates the new Native SAGA orchestration in Trellis v0.7. The engine automatically handles the stack unwinding and compensation execution when a failure occurs.

Compensation Durable (Long Running)

Concepts: Durable Execution, Persistence, Signals Demonstrates a Long Running SAGA. The flow pauses for an external signal (Manager Approval), is interrupted (process exit), resumed from disk, and then rolled back upon Rejection.

Confirm Demo (Unix Style)

Concepts: input_type: confirm, input_default, Unix Conventions Demonstrates the native confirmation UX. It shows how the engine follows standard CLI conventions (Enter = Yes) and how to formally override those defaults for secure flows.

Process Demo (Dynamic Scripts)

Concepts: x-exec, Tools, YAML Metadata Demonstrates the power of Universal Action Semantics. This example shows how to define and execute dynamic OS processes (scripts) directly from node metadata without pre-compiling Go tools.

Polyglot Tools (Script Adapter)

Concepts: tools.yaml, Python/Node/PowerShell, JSON IO A reference implementation for the Unix-Style Contract. Shows how to write scriptable tools in multiple languages that receive arguments via Environment Variables and return structured JSON output, all registered via a safe tools.yaml manifest.

Inline Tool Demo (Zero-Config)

Concepts: Standalone Nodes, Dynamic x-exec Demonstrates how to execute tools without any tools.yaml file. Everything is self-contained in the Markdown metadata, allowing for portable and easy-to-distribute flows.

---

4. Advanced Control

Global Signals (Interrupts)

Concepts: on_signal, Graceful Shutdown, Ctrl+C Demonstrates how to handle global interruptions (like SIGINT) gracefully. Instead of crashing, the flow transitions to a confirmation node ("Are you sure?"), preventing data loss.

Sub-graph Demo (Modularity)

Concepts: Modular Graphs, Portability, Logical Segregation Demonstrates how to split a complex state machine into multiple smaller, manageable files. This is the cornerstone of building complex, enterprise-ready automation.

Reload Demo (Live Dev)

Concepts: --watch, Hot Reload, DX Shows how Trellis supports a high-velocity developer experience. Modify your Markdown files and see the engine reload the logic in real-time without restarting the process.

Context Injection (Testing & Automation)

Concepts: --context, Seed State, Templates Demonstrates how to inject initial data into the flow via the CLI flag --context. Critical for automated testing or integration with legacy systems.

---

5. Production & Observability

Signals Demo (Interrupts & Timeouts)

Concepts: on_signal, step_timeout Demonstrates global signals (interrupts) and step timeouts.

Structured Logging (Production)

Concepts: slog (JSON Logs), Prometheus (Metrics) Demonstrates industry-standard observability by integrating Trellis with Go's log/slog and prometheus/client_golang. Shows how to output machine-readable logs and metrics.

Observability (Hooks & Debug)

Concepts: LifecycleHooks, --debug, Events Demonstrates how to use the --debug flag to visualize state transitions and events in the console.

---

6. Internals & API

Low Level API (Advanced)

Concepts: Manual Loop, engine.Render, engine.Navigate Demonstrates how to manually drive the engine without using the trellis.Runner. Useful if you need to integrate Trellis into a custom UI framework, a game engine, or a non-standard event loop.

DSL Graph (Go Builders)

Concepts: pkg/dsl, Fluent API, Type Safety Demonstrates how to build graphs using the Go DSL (Fluent Builders) instead of YAML/Markdown files. Ideal for scenarios requiring compile-time type safety and programmatic graph construction.

Observability Introspection (Deep Dive)

Concepts: introspection.TypedWatcher, lifecycle Integration Advanced example showing integration with the lifecycle package for unified observability across the Engine, Workers, and Signals.

Reactivity Demo (SSE & WebUI)

Concepts: SSE, State Delta, Chat Interface, Frontend Integration Demonstrates the integrated web chat UI (/ui) with Server-Sent Events for real-time state updates. Shows how frontends can consume deltas efficiently and inject tool results via HTTP.