durable_workflow 0.1.0

data/lib/durable_workflow/extensions/ai/types.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Extensions
+    module AI
+      # Module to hold dynamically generated RubyLLM::Tool classes
+      module GeneratedTools
+      end
+
+      # Message role enum (AI-specific, not in core)
+      module Types
+        MessageRole = DurableWorkflow::Types::Strict::String.enum('system', 'user', 'assistant', 'tool')
+      end
+
+      # Handoff definition
+      class HandoffDef < BaseStruct
+        attribute :agent_id, DurableWorkflow::Types::Strict::String
+        attribute? :description, DurableWorkflow::Types::Strict::String.optional
+      end
+
+      # Agent definition
+      class AgentDef < BaseStruct
+        attribute :id, DurableWorkflow::Types::Strict::String
+        attribute? :name, DurableWorkflow::Types::Strict::String.optional
+        attribute :model, DurableWorkflow::Types::Strict::String
+        attribute? :instructions, DurableWorkflow::Types::Strict::String.optional
+        attribute :tools, DurableWorkflow::Types::Strict::Array.of(DurableWorkflow::Types::Strict::String).default([].freeze)
+        attribute :handoffs, DurableWorkflow::Types::Strict::Array.of(HandoffDef).default([].freeze)
+      end
+
+      # Tool parameter
+      class ToolParam < BaseStruct
+        attribute :name, DurableWorkflow::Types::Strict::String
+        attribute? :type, DurableWorkflow::Types::Strict::String.optional.default('string')
+        attribute? :required, DurableWorkflow::Types::Strict::Bool.default(true)
+        attribute? :description, DurableWorkflow::Types::Strict::String.optional
+      end
+
+      # Tool definition
+      class ToolDef < BaseStruct
+        attribute :id, DurableWorkflow::Types::Strict::String
+        attribute :description, DurableWorkflow::Types::Strict::String
+        attribute :parameters, DurableWorkflow::Types::Strict::Array.of(ToolParam).default([].freeze)
+        attribute :service, DurableWorkflow::Types::Strict::String
+        attribute :method_name, DurableWorkflow::Types::Strict::String
+
+        def to_function_schema
+          {
+            name: id,
+            description:,
+            parameters: {
+              type: 'object',
+              properties: parameters.each_with_object({}) do |p, h|
+                h[p.name] = { type: p.type, description: p.description }.compact
+              end,
+              required: parameters.select(&:required).map(&:name)
+            }
+          }
+        end
+
+        # Convert to RubyLLM::Tool class
+        def to_ruby_llm_tool
+          tool_def = self
+          class_name = id.split('_').map(&:capitalize).join
+          short_name = id # Use the tool id as the name (e.g., "classify_request")
+
+          # Create named class under GeneratedTools module
+          AI::GeneratedTools.const_set(class_name, Class.new(RubyLLM::Tool) do
+            # Store reference to original definition
+            @tool_def = tool_def
+
+            # Set description
+            description tool_def.description
+
+            # Override name to avoid long namespace in tool name
+            define_method(:name) { short_name }
+
+            # Define parameters
+            tool_def.parameters.each do |p|
+              param p.name.to_sym,
+                    type: p.type.to_sym,
+                    desc: p.description,
+                    required: p.required
+            end
+
+            # Execute calls the service method
+            define_method(:execute) do |**args|
+              svc = Object.const_get(tool_def.service)
+              svc.public_send(tool_def.method_name, **args)
+            end
+
+            class << self
+              attr_reader :tool_def
+            end
+          end)
+        end
+      end
+
+      # Tool call from LLM
+      class ToolCall < BaseStruct
+        attribute :id, DurableWorkflow::Types::Strict::String
+        attribute :name, DurableWorkflow::Types::Strict::String
+        attribute :arguments, DurableWorkflow::Types::Hash.default({}.freeze)
+      end
+
+      # Message in conversation
+      class Message < BaseStruct
+        attribute :role, Types::MessageRole
+        attribute? :content, DurableWorkflow::Types::Strict::String.optional
+        attribute? :tool_calls, DurableWorkflow::Types::Strict::Array.of(ToolCall).optional
+        attribute? :tool_call_id, DurableWorkflow::Types::Strict::String.optional
+        attribute? :name, DurableWorkflow::Types::Strict::String.optional
+
+        def self.system(content)
+          new(role: 'system', content:)
+        end
+
+        def self.user(content)
+          new(role: 'user', content:)
+        end
+
+        def self.assistant(content, tool_calls: nil)
+          new(role: 'assistant', content:, tool_calls:)
+        end
+
+        def self.tool(content, tool_call_id:, name: nil)
+          new(role: 'tool', content:, tool_call_id:, name:)
+        end
+
+        def system? = role == 'system'
+        def user? = role == 'user'
+        def assistant? = role == 'assistant'
+        def tool? = role == 'tool'
+        def tool_calls? = tool_calls&.any?
+      end
+
+      # LLM response
+      class Response < BaseStruct
+        attribute? :content, DurableWorkflow::Types::Strict::String.optional
+        attribute :tool_calls, DurableWorkflow::Types::Strict::Array.of(ToolCall).default([].freeze)
+        attribute? :finish_reason, DurableWorkflow::Types::Strict::String.optional
+        attribute? :usage, DurableWorkflow::Types::Hash.optional
+
+        def tool_calls? = tool_calls.any?
+      end
+
+      # Moderation result
+      class ModerationResult < BaseStruct
+        attribute :flagged, DurableWorkflow::Types::Strict::Bool
+        attribute? :categories, DurableWorkflow::Types::Hash.optional
+        attribute? :scores, DurableWorkflow::Types::Hash.optional
+      end
+
+      # Guardrail check
+      class GuardrailCheck < BaseStruct
+        attribute :type, DurableWorkflow::Types::Strict::String
+        attribute? :pattern, DurableWorkflow::Types::Strict::String.optional
+        attribute? :block_on_match, DurableWorkflow::Types::Strict::Bool.default(true)
+        attribute? :max, DurableWorkflow::Types::Strict::Integer.optional
+        attribute? :min, DurableWorkflow::Types::Strict::Integer.optional
+      end
+
+      # Guardrail result
+      class GuardrailResult < BaseStruct
+        attribute :passed, DurableWorkflow::Types::Strict::Bool
+        attribute :check_type, DurableWorkflow::Types::Strict::String
+        attribute? :reason, DurableWorkflow::Types::Strict::String.optional
+      end
+
+      # AI Step Configs
+      class AgentConfig < Core::StepConfig
+        attribute :agent_id, DurableWorkflow::Types::Strict::String
+        attribute :prompt, DurableWorkflow::Types::Strict::String
+        attribute :output, DurableWorkflow::Types::Coercible::Symbol
+      end
+
+      class GuardrailConfig < Core::StepConfig
+        attribute? :content, DurableWorkflow::Types::Strict::String.optional
+        attribute? :input, DurableWorkflow::Types::Strict::String.optional
+        attribute :checks, DurableWorkflow::Types::Strict::Array.default([].freeze)
+        attribute? :on_fail, DurableWorkflow::Types::Strict::String.optional
+      end
+
+      class HandoffConfig < Core::StepConfig
+        attribute? :to, DurableWorkflow::Types::Strict::String.optional
+        attribute? :from, DurableWorkflow::Types::Strict::String.optional
+        attribute? :reason, DurableWorkflow::Types::Strict::String.optional
+      end
+
+      class FileSearchConfig < Core::StepConfig
+        attribute :query, DurableWorkflow::Types::Strict::String
+        attribute :files, DurableWorkflow::Types::Strict::Array.of(DurableWorkflow::Types::Strict::String).default([].freeze)
+        attribute? :max_results, DurableWorkflow::Types::Strict::Integer.optional.default(10)
+        attribute? :output, DurableWorkflow::Types::Coercible::Symbol.optional
+      end
+
+      class MCPConfig < Core::StepConfig
+        attribute :server, DurableWorkflow::Types::Strict::String
+        attribute :tool, DurableWorkflow::Types::Strict::String
+        attribute? :arguments, DurableWorkflow::Types::Hash.default({}.freeze)
+        attribute? :output, DurableWorkflow::Types::Coercible::Symbol.optional
+      end
+
+      # MCP Server configuration for consuming external MCP servers
+      class MCPServerConfig < BaseStruct
+        attribute? :url, DurableWorkflow::Types::Strict::String.optional
+        attribute? :headers, DurableWorkflow::Types::Hash.default({}.freeze)
+        attribute? :transport, DurableWorkflow::Types::Coercible::Symbol.default(:http)
+        attribute? :command, DurableWorkflow::Types::Strict::Array.of(DurableWorkflow::Types::Strict::String).optional
+      end
+    end
+  end
+end

data/lib/durable_workflow/extensions/ai.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# AI Extension loader
+# Usage: require "durable_workflow/extensions/ai"
+
+require_relative 'ai/ai'

data/lib/durable_workflow/extensions/base.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Extensions
+    # Base class for extensions
+    # Extensions inherit from this and call register! to set up
+    class Base
+      class << self
+        # Extension name (used as key in workflow.extensions)
+        def extension_name
+          @extension_name ||= (name ? name.split('::').last.downcase : 'anonymous')
+        end
+
+        attr_writer :extension_name
+
+        # Register all components of the extension
+        def register!
+          register_configs
+          register_executors
+          register_parser_hooks
+        end
+
+        # Override in subclass to register config classes
+        def register_configs
+          # Example:
+          # DurableWorkflow::Core.register_config("agent", AgentConfig)
+        end
+
+        # Override in subclass to register executors
+        def register_executors
+          # Example:
+          # DurableWorkflow::Core::Executors::Registry.register("agent", AgentExecutor)
+        end
+
+        # Override in subclass to register parser hooks
+        def register_parser_hooks
+          # Example:
+          # DurableWorkflow::Core::Parser.after_parse { |wf| ... }
+        end
+
+        # Helper to get extension data from workflow
+        def data_from(workflow)
+          workflow.extensions[extension_name.to_sym] || {}
+        end
+
+        # Helper to store extension data in workflow
+        def store_in(workflow, data)
+          workflow.with(extensions: workflow.extensions.merge(extension_name.to_sym => data))
+        end
+      end
+    end
+
+    # Registry of loaded extensions
+    @extensions = {}
+
+    class << self
+      attr_reader :extensions
+
+      def register(name, extension_class)
+        @extensions[name.to_sym] = extension_class
+        extension_class.register!
+      end
+
+      def [](name)
+        @extensions[name.to_sym]
+      end
+
+      def loaded?(name)
+        @extensions.key?(name.to_sym)
+      end
+
+      def reset!
+        @extensions = {}
+      end
+    end
+  end
+end

data/lib/durable_workflow/runners/adapters/inline.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Runners
+    module Adapters
+      class Inline
+        def initialize(store: nil)
+          @store = store
+        end
+
+        def enqueue(workflow_id:, workflow_data:, execution_id:, action:, **kwargs)
+          # Execute immediately in current thread (for testing/dev)
+          perform(
+            workflow_id:,
+            workflow_data:,
+            execution_id:,
+            action:,
+            **kwargs
+          )
+        end
+
+        def perform(workflow_id:, workflow_data:, execution_id:, action:, input: {}, response: nil, approved: nil, **_)
+          workflow = DurableWorkflow.registry[workflow_id]
+          raise ExecutionError, "Workflow not found: #{workflow_id}" unless workflow
+
+          store = @store || DurableWorkflow.config&.store
+          raise ConfigError, 'No store configured' unless store
+
+          engine = Core::Engine.new(workflow, store:)
+
+          # Engine saves Execution with proper typed status - no manual status update needed
+          case action.to_sym
+          when :start
+            engine.run(input:, execution_id:)
+          when :resume
+            engine.resume(execution_id, response:, approved:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/runners/adapters/sidekiq.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Runners
+    module Adapters
+      class Sidekiq
+        def initialize(job_class: nil)
+          @job_class = job_class || default_job_class
+        end
+
+        def enqueue(workflow_id:, workflow_data:, execution_id:, action:, queue: nil, priority: nil, **kwargs)
+          job_args = {
+            workflow_id:,
+            workflow_data:,
+            execution_id:,
+            action: action.to_s,
+            **kwargs.compact
+          }
+
+          if queue
+            @job_class.set(queue:).perform_async(job_args)
+          else
+            @job_class.perform_async(job_args)
+          end
+
+          execution_id
+        end
+
+        private
+
+        def default_job_class
+          # Define a default job class if sidekiq is available
+          return @default_job_class if defined?(@default_job_class)
+
+          @default_job_class = Class.new do
+            if defined?(::Sidekiq::Job)
+              include ::Sidekiq::Job
+
+              def perform(args)
+                args = DurableWorkflow::Utils.deep_symbolize(args)
+
+                workflow = DurableWorkflow.registry[args[:workflow_id]]
+                raise DurableWorkflow::ExecutionError, "Workflow not found: #{args[:workflow_id]}" unless workflow
+
+                store = DurableWorkflow.config&.store
+                raise DurableWorkflow::ConfigError, 'No store configured' unless store
+
+                engine = DurableWorkflow::Core::Engine.new(workflow, store:)
+
+                # Engine saves Execution with proper typed status - no manual status update needed
+                case args[:action].to_sym
+                when :start
+                  engine.run(input: args[:input], execution_id: args[:execution_id])
+                when :resume
+                  engine.resume(args[:execution_id], response: args[:response], approved: args[:approved])
+                end
+              end
+            end
+          end
+
+          # Register in Object so it can be found by Sidekiq
+          Object.const_set(:DurableWorkflowJob, @default_job_class) unless defined?(::DurableWorkflowJob)
+
+          @default_job_class
+        end
+      end
+    end
+  end
+end

data/lib/durable_workflow/runners/async.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Runners
+    class Async
+      attr_reader :workflow, :store, :adapter
+
+      def initialize(workflow, store: nil, adapter: nil)
+        @workflow = workflow
+        @store = store || DurableWorkflow.config&.store
+        raise ConfigError, 'No store configured' unless @store
+
+        @adapter = adapter || Adapters::Inline.new(store: @store)
+      end
+
+      # Queue workflow for execution, return immediately
+      def run(input: {}, execution_id: nil, queue: nil, priority: nil)
+        exec_id = execution_id || SecureRandom.uuid
+
+        # Pre-create Execution with :pending status
+        execution = Core::Execution.new(
+          id: exec_id,
+          workflow_id: workflow.id,
+          status: :pending,
+          input: input.freeze,
+          ctx: {}
+        )
+        store.save(execution)
+
+        # Enqueue
+        adapter.enqueue(
+          workflow_id: workflow.id,
+          workflow_data: serialize_workflow,
+          execution_id: exec_id,
+          input:,
+          action: :start,
+          queue:,
+          priority:
+        )
+
+        exec_id
+      end
+
+      # Queue resume
+      def resume(execution_id, response: nil, approved: nil, queue: nil)
+        adapter.enqueue(
+          workflow_id: workflow.id,
+          workflow_data: serialize_workflow,
+          execution_id:,
+          response:,
+          approved:,
+          action: :resume,
+          queue:
+        )
+
+        execution_id
+      end
+
+      # Poll for completion
+      def wait(execution_id, timeout: 30, interval: 0.1)
+        deadline = Time.now + timeout
+
+        while Time.now < deadline
+          execution = store.load(execution_id)
+
+          case execution&.status
+          when :completed, :failed, :halted
+            return build_result(execution)
+          end
+
+          sleep(interval)
+        end
+
+        nil # Timeout
+      end
+
+      # Get current status
+      def status(execution_id)
+        execution = store.load(execution_id)
+        execution&.status || :unknown
+      end
+
+      private
+
+      def serialize_workflow
+        { id: workflow.id, name: workflow.name, version: workflow.version }
+      end
+
+      def build_result(execution)
+        Core::ExecutionResult.new(
+          status: execution.status,
+          execution_id: execution.id,
+          output: execution.result,
+          halt: execution.status == :halted ? Core::HaltResult.new(data: execution.halt_data || {}) : nil,
+          error: execution.error
+        )
+      end
+    end
+  end
+end

data/lib/durable_workflow/runners/stream.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module DurableWorkflow
+  module Runners
+    # Stream event type
+    class Event < BaseStruct
+      attribute :type, Types::Strict::String
+      attribute :data, Types::Hash.default({}.freeze)
+      attribute :timestamp, Types::Any
+
+      def to_h
+        { type:, data:, timestamp: timestamp.is_a?(Time) ? timestamp.iso8601 : timestamp }
+      end
+
+      def to_json(*)
+        JSON.generate(to_h)
+      end
+
+      def to_sse
+        "event: #{type}\ndata: #{to_json}\n\n"
+      end
+    end
+
+    class Stream
+      EVENTS = %w[
+        workflow.started workflow.completed workflow.halted workflow.failed
+        step.started step.completed step.failed step.halted
+      ].freeze
+
+      attr_reader :workflow, :store, :subscribers
+
+      def initialize(workflow, store: nil)
+        @workflow = workflow
+        @store = store || DurableWorkflow.config&.store
+        raise ConfigError, 'No store configured' unless @store
+
+        @subscribers = []
+      end
+
+      # Subscribe to events
+      def subscribe(events: nil, &block)
+        @subscribers << { events:, handler: block }
+        self
+      end
+
+      # Run with event streaming
+      def run(input: {}, execution_id: nil)
+        emit('workflow.started', workflow_id: workflow.id, input:)
+
+        engine = StreamingEngine.new(workflow, store:, emitter: method(:emit))
+        result = engine.run(input:, execution_id:)
+
+        case result.status
+        when :completed
+          emit('workflow.completed', execution_id: result.execution_id, output: result.output)
+        when :halted
+          emit('workflow.halted', execution_id: result.execution_id, halt: result.halt&.data, prompt: result.halt&.prompt)
+        when :failed
+          emit('workflow.failed', execution_id: result.execution_id, error: result.error)
+        end
+
+        result
+      end
+
+      # Resume with event streaming
+      def resume(execution_id, response: nil, approved: nil)
+        emit('workflow.resumed', execution_id:)
+
+        engine = StreamingEngine.new(workflow, store:, emitter: method(:emit))
+        result = engine.resume(execution_id, response:, approved:)
+
+        case result.status
+        when :completed
+          emit('workflow.completed', execution_id: result.execution_id, output: result.output)
+        when :halted
+          emit('workflow.halted', execution_id: result.execution_id, halt: result.halt&.data, prompt: result.halt&.prompt)
+        when :failed
+          emit('workflow.failed', execution_id: result.execution_id, error: result.error)
+        end
+
+        result
+      end
+
+      # Emit event
+      def emit(type, **data)
+        event = Event.new(type:, data:, timestamp: Time.now)
+
+        subscribers.each do |sub|
+          next if sub[:events] && !sub[:events].include?(type)
+
+          sub[:handler].call(event)
+        end
+      end
+    end
+
+    # Engine subclass with event hooks
+    class StreamingEngine < Core::Engine
+      def initialize(workflow, store:, emitter:)
+        super(workflow, store:)
+        @emitter = emitter
+      end
+
+      private
+
+      def execute_step(state, step)
+        @emitter.call('step.started', step_id: step.id, step_type: step.type)
+
+        outcome = super
+
+        event = case outcome.result
+                when Core::HaltResult then 'step.halted'
+                else 'step.completed'
+                end
+
+        @emitter.call(event, step_id: step.id, output: outcome.result.output)
+
+        outcome
+      rescue StandardError => e
+        @emitter.call('step.failed', step_id: step.id, error: e.message)
+        raise
+      end
+    end
+  end
+end

data/lib/durable_workflow/runners/sync.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module DurableWorkflow
+  module Runners
+    class Sync
+      attr_reader :workflow, :store
+
+      def initialize(workflow, store: nil)
+        @workflow = workflow
+        @store = store || DurableWorkflow.config&.store
+        raise ConfigError, 'No store configured' unless @store
+      end
+
+      # Run workflow, block until complete/halted
+      def run(input: {}, execution_id: nil)
+        engine = Core::Engine.new(workflow, store:)
+        engine.run(input:, execution_id:)
+      end
+
+      # Resume halted workflow
+      def resume(execution_id, response: nil, approved: nil)
+        engine = Core::Engine.new(workflow, store:)
+        engine.resume(execution_id, response:, approved:)
+      end
+
+      # Run until fully complete (auto-handle halts with block)
+      # Without block, returns halted result when halt encountered
+      def run_until_complete(input: {}, execution_id: nil)
+        result = run(input:, execution_id:)
+
+        while result.halted? && block_given?
+          response = yield result.halt
+          result = resume(result.execution_id, response:)
+        end
+
+        result
+      end
+    end
+  end
+end