durable_workflow 0.1.0

data/examples/service_integration.rb

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Service Integration - Calling external services from workflow
+#
+# Demonstrates: Call step, service resolution, error handling
+#
+# Run: ruby examples/service_integration.rb
+# Requires: Redis running on localhost:6379
+
+require "bundler/setup"
+require "securerandom"
+require "durable_workflow"
+require "durable_workflow/storage/redis"
+
+DurableWorkflow.configure do |c|
+  c.store = DurableWorkflow::Storage::Redis.new(url: "redis://localhost:6379")
+end
+
+# Inventory service (must be globally accessible constant)
+module InventoryService
+  STOCK = {
+    "PROD-001" => 50,
+    "PROD-002" => 0,
+    "PROD-003" => 10
+  }
+
+  def self.check_availability(product_id:, quantity:)
+    available = STOCK.fetch(product_id, 0)
+    {
+      product_id: product_id,
+      requested: quantity,
+      available: available,
+      in_stock: available >= quantity
+    }
+  end
+
+  def self.reserve(product_id:, quantity:)
+    current = STOCK.fetch(product_id, 0)
+    raise "Insufficient stock" if current < quantity
+
+    STOCK[product_id] = current - quantity
+    {
+      reservation_id: "RES-#{SecureRandom.hex(4)}",
+      product_id: product_id,
+      quantity: quantity,
+      remaining: STOCK[product_id]
+    }
+  end
+end
+
+workflow = DurableWorkflow::Core::Parser.parse(<<~YAML)
+  id: inventory_check
+  name: Inventory Check and Reserve
+  version: "1.0"
+
+  inputs:
+    product_id:
+      type: string
+      required: true
+    quantity:
+      type: integer
+      required: true
+
+  steps:
+    - id: start
+      type: start
+      next: check
+
+    - id: check
+      type: call
+      service: InventoryService
+      method: check_availability
+      input:
+        product_id: "$input.product_id"
+        quantity: "$input.quantity"
+      output: availability
+      next: decide
+
+    - id: decide
+      type: router
+      routes:
+        - when:
+            field: availability.in_stock
+            op: eq
+            value: true
+          then: reserve
+      default: out_of_stock
+
+    - id: reserve
+      type: call
+      service: InventoryService
+      method: reserve
+      input:
+        product_id: "$input.product_id"
+        quantity: "$input.quantity"
+      output: reservation
+      next: success
+
+    - id: success
+      type: assign
+      set:
+        status: reserved
+      next: end
+
+    - id: out_of_stock
+      type: assign
+      set:
+        status: out_of_stock
+        error: "Insufficient stock available"
+      next: end
+
+    - id: end
+      type: end
+      result:
+        status: "$status"
+        availability: "$availability"
+        reservation: "$reservation"
+        error: "$error"
+YAML
+
+runner = DurableWorkflow::Runners::Sync.new(workflow)
+
+# Available product
+result = runner.run(input: { product_id: "PROD-001", quantity: 5 })
+puts "PROD-001 (qty 5): #{result.output[:status]}"
+puts "  Reservation: #{result.output[:reservation][:reservation_id]}" if result.output[:reservation]
+
+# Out of stock
+result = runner.run(input: { product_id: "PROD-002", quantity: 1 })
+puts "\nPROD-002 (qty 1): #{result.output[:status]}"
+puts "  Error: #{result.output[:error]}"
+
+# Partial availability
+result = runner.run(input: { product_id: "PROD-003", quantity: 20 })
+puts "\nPROD-003 (qty 20): #{result.output[:status]}"
+puts "  Error: #{result.output[:error]}"

data/examples/support_agent/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "durable_workflow", path: "../.."
+gem "redis"

data/examples/support_agent/README.md

@@ -0,0 +1,91 @@
+# Support Agent
+
+AI-powered customer support workflow with tool calling and MCP integration.
+
+## Features
+
+- Multi-agent system (triage, billing, technical)
+- Tool integration (lookup orders, create tickets, check status)
+- Handoffs between specialized agents
+- Content moderation guardrails
+- MCP server for Claude Desktop integration
+
+## Setup
+
+```bash
+cd examples/support_agent
+bundle install
+
+# Set API key
+export OPENAI_API_KEY=your-key
+# or
+export ANTHROPIC_API_KEY=your-key
+
+# Start Redis
+redis-server
+```
+
+## Usage
+
+### Interactive CLI
+
+```bash
+ruby run.rb
+```
+
+### As MCP Server (Claude Desktop)
+
+1. Copy config to Claude Desktop:
+```bash
+cp config/claude_desktop.json ~/.config/claude/claude_desktop_config.json
+```
+
+2. Restart Claude Desktop
+
+3. The support tools will be available in Claude
+
+## Architecture
+
+```
+User Input
+    ↓
+┌─────────────┐
+│   Triage    │ ← Classifies request
+│   Agent     │
+└─────────────┘
+    ↓
+┌─────────────────────────────────┐
+│         Router                  │
+├─────────────┬─────────┬─────────┤
+│   Billing   │  Tech   │  Other  │
+│   Agent     │  Agent  │         │
+└─────────────┴─────────┴─────────┘
+    ↓
+Tools: lookup_order, create_ticket, check_status, escalate
+```
+
+## Tools Available
+
+| Tool | Description |
+|------|-------------|
+| `lookup_order` | Find order by ID or customer email |
+| `create_ticket` | Create support ticket |
+| `check_status` | Check ticket status |
+| `escalate` | Escalate to human agent |
+| `refund_order` | Process refund (billing only) |
+| `reset_password` | Reset user password (tech only) |
+
+## MCP Integration
+
+When running as MCP server, external AI agents can:
+
+1. Discover available tools via `tools/list`
+2. Call tools via `tools/call`
+3. Run the full workflow as a tool
+
+Example Claude Desktop interaction:
+```
+User: "I need help with order ORD-12345"
+Claude: [calls lookup_order with order_id: "ORD-12345"]
+Claude: "I found your order. It was placed on..."
+```

data/examples/support_agent/config/claude_desktop.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "support_agent": {
+      "command": "ruby",
+      "args": ["examples/support_agent/mcp_server.rb"],
+      "cwd": "/path/to/durable_workflow",
+      "env": {
+        "OPENAI_API_KEY": "your-key-here"
+      }
+    }
+  }
+}

data/examples/support_agent/mcp_server.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# MCP Server for Claude Desktop integration
+#
+# Add to ~/.config/claude/claude_desktop_config.json:
+# {
+#   "mcpServers": {
+#     "support_agent": {
+#       "command": "ruby",
+#       "args": ["examples/support_agent/mcp_server.rb"],
+#       "cwd": "/path/to/durable_workflow"
+#     }
+#   }
+# }
+
+require "bundler/setup"
+require "dotenv/load" if File.exist?(File.expand_path("../../.env", __dir__))
+require "durable_workflow"
+require "durable_workflow/extensions/ai"
+require "durable_workflow/storage/redis"
+require_relative "services"
+
+# Suppress stdout logging (corrupts MCP protocol)
+$stderr = File.open("/tmp/support_agent_mcp.log", "a")
+
+# Configure
+DurableWorkflow.configure do |c|
+  c.store = DurableWorkflow::Storage::Redis.new(url: "redis://localhost:6379")
+  c.logger = Logger.new("/dev/null")
+end
+
+DurableWorkflow::Extensions::AI.configure do |c|
+  c.api_keys[:openai] = ENV["OPENAI_API_KEY"]
+  c.api_keys[:anthropic] = ENV["ANTHROPIC_API_KEY"]
+end
+
+# Services auto-resolved via Object.const_get
+
+# Load and register workflow
+workflow = DurableWorkflow.load(File.join(__dir__, "workflow.yml"))
+DurableWorkflow.register(workflow)
+
+# Run MCP server with workflow tools + workflow itself exposed
+DurableWorkflow::Extensions::AI::MCP::Server.stdio(
+  workflow,
+  name: "support_agent",
+  expose_workflow: true  # Makes "run_support_agent" available as a tool
+)

data/examples/support_agent/run.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "dotenv/load" if File.exist?(File.expand_path("../../.env", __dir__))
+require "durable_workflow"
+require "durable_workflow/extensions/ai"
+require "durable_workflow/storage/redis"
+require_relative "services"
+
+# Configure
+DurableWorkflow.configure do |c|
+  c.store = DurableWorkflow::Storage::Redis.new(url: "redis://localhost:6379")
+end
+
+DurableWorkflow::Extensions::AI.configure do |c|
+  c.api_keys[:openai] = ENV["OPENAI_API_KEY"]
+  c.api_keys[:anthropic] = ENV["ANTHROPIC_API_KEY"]
+  c.default_model = "gpt-4o-mini"
+end
+
+# Services are auto-resolved via Object.const_get (SupportServices is a global module)
+
+# Load and register workflow
+workflow = DurableWorkflow.load(File.join(__dir__, "workflow.yml"))
+DurableWorkflow.register(workflow)
+runner = DurableWorkflow::Runners::Stream.new(workflow)
+
+# Subscribe to events for visibility
+runner.subscribe do |event|
+  case event.type
+  when "step.started"
+    puts "  [#{event.data[:step_id]}]" if ENV["DEBUG"]
+  when "agent.tool_use"
+    puts "  -> Tool: #{event.data[:tool]} #{event.data[:arguments]}"
+  end
+end
+
+puts "=" * 60
+puts "Customer Support Agent"
+puts "=" * 60
+puts "Type 'quit' to exit"
+puts
+
+loop do
+  print "\nYou: "
+  input = gets&.chomp
+  break if input.nil? || input.downcase == "quit"
+  next if input.empty?
+
+  begin
+    result = runner.run(input: {
+      message: input,
+      customer_id: "CUST-001"
+    })
+
+    puts "\nAgent: #{result.output[:response]}"
+    if result.output[:triage].is_a?(Hash)
+      puts "  [Category: #{result.output[:triage][:category]}, Urgency: #{result.output[:triage][:urgency]}]"
+    end
+  rescue => e
+    puts "\nError: #{e.message}"
+    puts e.backtrace.first(3).join("\n") if ENV["DEBUG"]
+  end
+end
+
+puts "\nGoodbye!"

data/examples/support_agent/services.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+# Mock services for support agent demo
+module SupportServices
+  ORDERS = {
+    "ORD-12345" => {
+      id: "ORD-12345",
+      customer_email: "alice@example.com",
+      status: "shipped",
+      total: 149.99,
+      items: [
+        { name: "Wireless Headphones", quantity: 1, price: 149.99 }
+      ],
+      created_at: "2024-01-10",
+      tracking: "1Z999AA10123456784"
+    },
+    "ORD-67890" => {
+      id: "ORD-67890",
+      customer_email: "bob@example.com",
+      status: "delivered",
+      total: 299.99,
+      items: [
+        { name: "Smart Watch", quantity: 1, price: 299.99 }
+      ],
+      created_at: "2024-01-05",
+      delivered_at: "2024-01-08"
+    }
+  }
+
+  TICKETS = {}
+
+  class << self
+    def classify_request(category:, urgency:, summary:)
+      {
+        category: category,
+        urgency: urgency,
+        summary: summary,
+        classified_at: Time.now.iso8601
+      }
+    end
+
+    def lookup_order(order_id: nil, email: nil)
+      if order_id
+        order = ORDERS[order_id]
+        return { error: "Order not found: #{order_id}" } unless order
+        order
+      elsif email
+        orders = ORDERS.values.select { |o| o[:customer_email] == email }
+        return { error: "No orders found for #{email}" } if orders.empty?
+        { orders: orders, count: orders.size }
+      else
+        { error: "Please provide order_id or email" }
+      end
+    end
+
+    def refund_order(order_id:, reason:, amount: nil)
+      order = ORDERS[order_id]
+      return { error: "Order not found: #{order_id}" } unless order
+
+      refund_amount = amount || order[:total]
+      {
+        refund_id: "REF-#{SecureRandom.hex(4).upcase}",
+        order_id: order_id,
+        amount: refund_amount,
+        reason: reason,
+        status: "processed",
+        processed_at: Time.now.iso8601
+      }
+    end
+
+    def create_ticket(subject:, description:, priority: "medium")
+      ticket_id = "TKT-#{SecureRandom.hex(4).upcase}"
+      ticket = {
+        id: ticket_id,
+        subject: subject,
+        description: description,
+        priority: priority,
+        status: "open",
+        created_at: Time.now.iso8601
+      }
+      TICKETS[ticket_id] = ticket
+      ticket
+    end
+
+    def check_status(ticket_id:)
+      ticket = TICKETS[ticket_id]
+      return { error: "Ticket not found: #{ticket_id}" } unless ticket
+      ticket
+    end
+
+    def reset_password(email:)
+      {
+        email: email,
+        reset_sent: true,
+        message: "Password reset email sent to #{email}",
+        expires_in: "24 hours"
+      }
+    end
+
+    def escalate(reason:, urgency:)
+      {
+        escalation_id: "ESC-#{SecureRandom.hex(4).upcase}",
+        reason: reason,
+        urgency: urgency,
+        status: "pending_human_review",
+        estimated_response: urgency == "high" ? "1 hour" : "4 hours",
+        created_at: Time.now.iso8601
+      }
+    end
+  end
+end