signalwire_agents 1.1.0

data/lib/signalwire_agents/datamap/data_map.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require_relative '../swaig/function_result'
+
+module SignalWireAgents
+  # Fluent builder for server-side DataMap tools.
+  #
+  # DataMap tools execute on SignalWire servers without requiring webhook
+  # endpoints. This class provides a chainable API for building data_map
+  # configurations that become SWAIG function definitions.
+  #
+  # All mutator methods return +self+ so calls can be chained:
+  #
+  #   dm = DataMap.new('get_weather')
+  #        .purpose('Get current weather')
+  #        .parameter('location', 'string', 'City name', required: true)
+  #        .webhook('GET', 'https://api.weather.com/v1/current?q=${location}')
+  #        .output(Swaig::FunctionResult.new('Weather: ${response.current.temp_f}F'))
+  #
+  class DataMap
+    attr_reader :function_name
+
+    def initialize(function_name)
+      @function_name = function_name
+      @purpose_text = ''
+      @parameters = {}       # name => { "type" => ..., "description" => ... }
+      @required_params = []
+      @expressions = []
+      @webhooks = []
+      @fallback_output = nil
+      @global_error_keys = []
+    end
+
+    # Set the function description / purpose.
+    def purpose(desc)
+      @purpose_text = desc
+      self
+    end
+
+    # Alias for +purpose+.
+    def description(desc)
+      purpose(desc)
+    end
+
+    # Add a typed parameter to the function signature.
+    #
+    # @param name [String]
+    # @param type [String] JSON-Schema type (string, number, boolean, array, object)
+    # @param desc [String] Human-readable description
+    # @param required [Boolean] whether the parameter is required
+    # @param enum [Array<String>, nil] optional list of allowed values
+    def parameter(name, type, desc, required: false, enum: nil)
+      param_def = { "type" => type, "description" => desc }
+      param_def["enum"] = enum if enum && !enum.empty?
+      @parameters[name] = param_def
+      @required_params << name if required && !@required_params.include?(name)
+      self
+    end
+
+    # Add an expression (pattern-matching rule).
+    #
+    # @param test_value [String] template string to test, e.g. "${args.command}"
+    # @param pattern [String, Regexp] regex pattern to match against
+    # @param output [Swaig::FunctionResult, Hash] result when pattern matches
+    # @param nomatch_output [Swaig::FunctionResult, Hash, nil] result when pattern does not match
+    def expression(test_value, pattern, output, nomatch_output: nil)
+      pattern_str = pattern.is_a?(Regexp) ? pattern.source : pattern.to_s
+      output_h = output.respond_to?(:to_h) ? output.to_h : output
+
+      expr_def = {
+        "string"  => test_value,
+        "pattern" => pattern_str,
+        "output"  => output_h
+      }
+
+      if nomatch_output
+        nomatch_h = nomatch_output.respond_to?(:to_h) ? nomatch_output.to_h : nomatch_output
+        expr_def["nomatch-output"] = nomatch_h
+      end
+
+      @expressions << expr_def
+      self
+    end
+
+    # Add a webhook (HTTP call) to the data_map pipeline.
+    #
+    # @param method [String] HTTP method (GET, POST, PUT, DELETE, etc.)
+    # @param url [String] endpoint URL (may contain ${variable} substitutions)
+    # @param headers [Hash, nil] optional HTTP headers
+    # @param form_param [String, nil] send JSON body as a single form parameter
+    # @param input_args_as_params [Boolean] merge function arguments into params
+    # @param require_args [Array<String>, nil] only execute when these args are present
+    def webhook(method, url, headers: nil, form_param: nil, input_args_as_params: false, require_args: nil)
+      wh = {
+        "url"    => url,
+        "method" => method.upcase
+      }
+      wh["headers"]              = headers           if headers
+      wh["form_param"]           = form_param        if form_param
+      wh["input_args_as_params"] = true               if input_args_as_params
+      wh["require_args"]         = require_args       if require_args
+      @webhooks << wh
+      self
+    end
+
+    # Add expressions to run after the most-recently-added webhook completes.
+    def webhook_expressions(expressions)
+      raise ArgumentError, "Must add webhook before setting webhook expressions" if @webhooks.empty?
+
+      @webhooks.last["expressions"] = expressions
+      self
+    end
+
+    # Set the request body for the most-recently-added webhook (POST / PUT).
+    def body(data)
+      raise ArgumentError, "Must add webhook before setting body" if @webhooks.empty?
+
+      @webhooks.last["body"] = data
+      self
+    end
+
+    # Set request params for the most-recently-added webhook.
+    def params(data)
+      raise ArgumentError, "Must add webhook before setting params" if @webhooks.empty?
+
+      @webhooks.last["params"] = data
+      self
+    end
+
+    # Configure array processing on the most-recently-added webhook response.
+    #
+    # @param config [Hash] must include keys: input_key, output_key, append. Optional: max.
+    def foreach(config)
+      raise ArgumentError, "Must add webhook before setting foreach" if @webhooks.empty?
+      raise ArgumentError, "foreach config must be a Hash" unless config.is_a?(Hash)
+
+      required_keys = %w[input_key output_key append]
+      missing = required_keys - config.keys.map(&:to_s)
+      raise ArgumentError, "foreach config missing required keys: #{missing.inspect}" unless missing.empty?
+
+      @webhooks.last["foreach"] = config
+      self
+    end
+
+    # Set the output result for the most-recently-added webhook.
+    #
+    # @param result [Swaig::FunctionResult, Hash]
+    def output(result)
+      raise ArgumentError, "Must add webhook before setting output" if @webhooks.empty?
+
+      @webhooks.last["output"] = result.respond_to?(:to_h) ? result.to_h : result
+      self
+    end
+
+    # Set a fallback output used when all webhooks fail.
+    #
+    # @param result [Swaig::FunctionResult, Hash]
+    def fallback_output(result)
+      @fallback_output = result.respond_to?(:to_h) ? result.to_h : result
+      self
+    end
+
+    # Set error keys on the most-recently-added webhook, or at the top level
+    # if no webhook has been added yet.
+    def error_keys(keys)
+      if @webhooks.any?
+        @webhooks.last["error_keys"] = keys
+      else
+        @global_error_keys = keys
+      end
+      self
+    end
+
+    # Set top-level error keys (applies to all webhooks).
+    def global_error_keys(keys)
+      @global_error_keys = keys
+      self
+    end
+
+    # Serialize this DataMap into a complete SWAIG function definition Hash.
+    #
+    # @return [Hash] with keys: "function", "description", "parameters", "data_map"
+    def to_swaig_function
+      # Build parameter schema
+      if @parameters.any?
+        param_schema = {
+          "type"       => "object",
+          "properties" => @parameters.dup
+        }
+        param_schema["required"] = @required_params.dup if @required_params.any?
+      else
+        param_schema = { "type" => "object", "properties" => {} }
+      end
+
+      # Build data_map
+      data_map = {}
+      data_map["expressions"] = @expressions      if @expressions.any?
+      data_map["webhooks"]    = @webhooks          if @webhooks.any?
+      data_map["output"]      = @fallback_output   if @fallback_output
+      data_map["error_keys"]  = @global_error_keys if @global_error_keys.any?
+
+      {
+        "function"    => @function_name,
+        "description" => @purpose_text.empty? ? "Execute #{@function_name}" : @purpose_text,
+        "parameters"  => param_schema,
+        "data_map"    => data_map
+      }
+    end
+
+    # ----------------------------------------------------------------
+    # Class-level convenience constructors
+    # ----------------------------------------------------------------
+
+    # Build a simple API-calling tool in one shot.
+    #
+    # @param name [String]
+    # @param url [String]
+    # @param response_template [String]
+    # @param parameters [Hash, nil] name => { "type" => ..., "description" => ..., "required" => bool }
+    # @param method [String] HTTP method (default GET)
+    # @param headers [Hash, nil]
+    # @param body [Hash, nil]
+    # @param error_keys [Array<String>, nil]
+    # @return [DataMap]
+    def self.create_simple_api_tool(name:, url:, response_template:, parameters: nil,
+                                    method: 'GET', headers: nil, body: nil, error_keys: nil)
+      dm = new(name)
+
+      if parameters
+        parameters.each do |pname, pdef|
+          dm.parameter(
+            pname,
+            pdef.fetch("type", "string"),
+            pdef.fetch("description", "#{pname} parameter"),
+            required: pdef.fetch("required", false)
+          )
+        end
+      end
+
+      dm.webhook(method, url, headers: headers)
+      dm.body(body) if body
+      dm.error_keys(error_keys) if error_keys
+      dm.output(Swaig::FunctionResult.new(response_template))
+      dm
+    end
+
+    # Build an expression-only tool (no HTTP calls).
+    #
+    # @param name [String]
+    # @param patterns [Hash] test_value => [pattern, Swaig::FunctionResult]
+    # @param parameters [Hash, nil] same format as +create_simple_api_tool+
+    # @return [DataMap]
+    def self.create_expression_tool(name:, patterns:, parameters: nil)
+      dm = new(name)
+
+      if parameters
+        parameters.each do |pname, pdef|
+          dm.parameter(
+            pname,
+            pdef.fetch("type", "string"),
+            pdef.fetch("description", "#{pname} parameter"),
+            required: pdef.fetch("required", false)
+          )
+        end
+      end
+
+      patterns.each do |test_value, (pattern, result)|
+        dm.expression(test_value, pattern, result)
+      end
+
+      dm
+    end
+  end
+end

data/lib/signalwire_agents/logging.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module SignalWireAgents
+  module Logging
+    LEVELS = { debug: 0, info: 1, warn: 2, error: 3, off: 4 }.freeze
+
+    # Returns the current global log level, derived from:
+    #   1. SIGNALWIRE_LOG_MODE=off  -> :off  (suppresses everything)
+    #   2. SIGNALWIRE_LOG_LEVEL env  -> the named level
+    #   3. Default                   -> :info
+    def self.global_level
+      @global_level || resolve_level_from_env
+    end
+
+    def self.global_level=(level)
+      level = level.to_sym if level.is_a?(String)
+      raise ArgumentError, "Unknown log level: #{level}" unless LEVELS.key?(level)
+
+      @global_level = level
+    end
+
+    def self.reset!
+      @global_level = nil
+    end
+
+    def self.suppressed?
+      global_level == :off
+    end
+
+    # Convenience factory
+    def self.logger(name)
+      Logger.new(name)
+    end
+
+    # -------------------------------------------------------------------
+    class Logger
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+        @output = $stderr
+      end
+
+      def debug(msg)
+        log(:debug, msg)
+      end
+
+      def info(msg)
+        log(:info, msg)
+      end
+
+      def warn(msg)
+        log(:warn, msg)
+      end
+
+      def error(msg)
+        log(:error, msg)
+      end
+
+      private
+
+      def log(level, msg)
+        return if Logging.suppressed?
+        return if LEVELS[level] < LEVELS[Logging.global_level]
+
+        timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S')
+        @output.puts "[#{timestamp}] #{level.upcase} [#{@name}] #{msg}"
+      end
+    end
+
+    # -------------------------------------------------------------------
+    # Private helpers
+    # -------------------------------------------------------------------
+    private_class_method def self.resolve_level_from_env
+      if ENV['SIGNALWIRE_LOG_MODE']&.downcase == 'off'
+        @global_level = :off
+        return :off
+      end
+
+      raw = ENV['SIGNALWIRE_LOG_LEVEL']
+      if raw
+        sym = raw.downcase.to_sym
+        if LEVELS.key?(sym)
+          @global_level = sym
+          return sym
+        end
+      end
+
+      :info # default — not cached so env changes take effect
+    end
+  end
+end

data/lib/signalwire_agents/prefabs/concierge.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require_relative '../swaig/function_result'
+
+module SignalWireAgents
+  module Prefabs
+    # Prefab agent for providing virtual concierge services.
+    #
+    #   agent = Concierge.new(
+    #     venue_name: 'Grand Hotel',
+    #     services: ['room service', 'spa bookings'],
+    #     amenities: { 'pool' => { 'hours' => '7 AM - 10 PM', 'location' => '2nd Floor' } }
+    #   )
+    #
+    class Concierge
+      attr_reader :venue_name, :services, :amenities, :name, :route
+
+      def initialize(venue_name:, services:, amenities:, hours_of_operation: nil,
+                     special_instructions: nil, welcome_message: nil,
+                     name: 'concierge', route: '/concierge', **_opts)
+        @venue_name     = venue_name
+        @services       = services || []
+        @amenities      = (amenities || {}).transform_keys(&:to_s)
+        @hours          = hours_of_operation
+        @instructions   = special_instructions || []
+        @welcome        = welcome_message || "Welcome to #{venue_name}! How can I assist you today?"
+        @name  = name
+        @route = route
+      end
+
+      def tools
+        %w[get_amenity_info get_service_info]
+      end
+
+      def prompt_sections
+        amenity_bullets = @amenities.map { |k, v| "#{k}: #{v.is_a?(Hash) ? v.map { |a, b| "#{a}: #{b}" }.join(', ') : v}" }
+        service_bullets = @services.map { |s| s.to_s }
+
+        sections = [
+          {
+            'title' => "#{@venue_name} Concierge",
+            'body' => @welcome,
+            'bullets' => service_bullets + amenity_bullets
+          }
+        ]
+
+        if @hours
+          sections << {
+            'title' => 'Hours of Operation',
+            'body' => @hours.is_a?(Hash) ? @hours.map { |k, v| "#{k}: #{v}" }.join('; ') : @hours.to_s
+          }
+        end
+
+        sections
+      end
+
+      def global_data
+        {
+          'venue_name' => @venue_name,
+          'services'   => @services,
+          'amenities'  => @amenities
+        }
+      end
+
+      def handle_amenity_info(args, _raw_data)
+        amenity = (args['amenity'] || '').downcase
+        info = @amenities.find { |k, _v| k.downcase == amenity }&.last
+        if info
+          detail = info.is_a?(Hash) ? info.map { |k, v| "#{k}: #{v}" }.join(', ') : info.to_s
+          Swaig::FunctionResult.new("#{amenity.capitalize}: #{detail}")
+        else
+          Swaig::FunctionResult.new("I don't have information about '#{amenity}'. Available amenities: #{@amenities.keys.join(', ')}")
+        end
+      end
+
+      def handle_service_info(args, _raw_data)
+        service = (args['service'] || '').downcase
+        match = @services.find { |s| s.downcase.include?(service) }
+        if match
+          Swaig::FunctionResult.new("#{match} is available at #{@venue_name}.")
+        else
+          Swaig::FunctionResult.new("Available services: #{@services.join(', ')}")
+        end
+      end
+    end
+  end
+end

data/lib/signalwire_agents/prefabs/faq_bot.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require_relative '../swaig/function_result'
+
+module SignalWireAgents
+  module Prefabs
+    # Prefab agent for answering frequently asked questions.
+    #
+    #   agent = FaqBot.new(
+    #     faqs: [
+    #       { 'question' => 'What is SignalWire?', 'answer' => 'A cloud communications platform.' }
+    #     ]
+    #   )
+    #
+    class FaqBot
+      attr_reader :faqs, :name, :route
+
+      def initialize(faqs:, suggest_related: true, persona: nil,
+                     name: 'faq_bot', route: '/faq', **_opts)
+        raise ArgumentError, 'faqs must be a non-empty Array' unless faqs.is_a?(Array) && !faqs.empty?
+
+        @faqs            = faqs.map { |f| f.transform_keys(&:to_s) }
+        @suggest_related = suggest_related
+        @persona         = persona || 'You are a helpful FAQ bot that provides accurate answers to common questions.'
+        @name  = name
+        @route = route
+      end
+
+      def tools
+        %w[search_faq]
+      end
+
+      def prompt_sections
+        bullets = @faqs.map { |f| "Q: #{f['question']}" }
+        [
+          {
+            'title' => 'FAQ Bot',
+            'body' => @persona,
+            'bullets' => bullets
+          }
+        ]
+      end
+
+      def global_data
+        {
+          'faqs' => @faqs,
+          'suggest_related' => @suggest_related
+        }
+      end
+
+      def handle_search(args, _raw_data)
+        query = (args['query'] || '').downcase
+        match = @faqs.find { |f| f['question'].downcase.include?(query) || query.include?(f['question'].downcase) }
+        if match
+          Swaig::FunctionResult.new(match['answer'])
+        else
+          Swaig::FunctionResult.new("I don't have a specific answer for that. Here are the topics I can help with: #{@faqs.map { |f| f['question'] }.join('; ')}")
+        end
+      end
+    end
+  end
+end

data/lib/signalwire_agents/prefabs/info_gatherer.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require_relative '../swaig/function_result'
+
+module SignalWireAgents
+  module Prefabs
+    # Prefab agent for collecting answers to a series of questions.
+    #
+    #   agent = InfoGatherer.new(
+    #     questions: [
+    #       { 'key_name' => 'full_name', 'question_text' => 'What is your full name?' },
+    #       { 'key_name' => 'email',     'question_text' => 'Email?', 'confirm' => true }
+    #     ]
+    #   )
+    #
+    class InfoGatherer
+      attr_reader :questions, :name, :route
+
+      def initialize(questions:, name: 'info_gatherer', route: '/info_gatherer', **_opts)
+        raise ArgumentError, 'questions must be a non-empty Array' unless questions.is_a?(Array) && !questions.empty?
+        questions.each_with_index do |q, i|
+          raise ArgumentError, "Question #{i} missing key_name" unless q['key_name'] || q[:key_name]
+          raise ArgumentError, "Question #{i} missing question_text" unless q['question_text'] || q[:question_text]
+        end
+
+        @questions = questions.map { |q| q.transform_keys(&:to_s) }
+        @name  = name
+        @route = route
+      end
+
+      # Tool definitions this prefab provides.
+      def tools
+        %w[start_questions submit_answer]
+      end
+
+      # Build the prompt sections.
+      def prompt_sections
+        [
+          {
+            'title' => 'Info Gatherer',
+            'body' => 'You need to gather answers to a series of questions. ' \
+                      'Call start_questions to get the first question, then submit_answer after each response.'
+          }
+        ]
+      end
+
+      # Global data for initial state.
+      def global_data
+        {
+          'info_gatherer' => {
+            'questions' => @questions,
+            'question_index' => 0,
+            'answers' => []
+          }
+        }
+      end
+
+      # Tool handler: start_questions
+      def handle_start(_args, _raw_data)
+        q = @questions.first
+        Swaig::FunctionResult.new(
+          "[Question 1 of #{@questions.size}]: \"#{q['question_text']}\""
+        )
+      end
+
+      # Tool handler: submit_answer
+      def handle_submit(args, _raw_data)
+        answer = args['answer'] || ''
+        # In a real implementation, state would be tracked via global_data.
+        Swaig::FunctionResult.new("Answer recorded: #{answer}")
+      end
+    end
+  end
+end

data/lib/signalwire_agents/prefabs/receptionist.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require_relative '../swaig/function_result'
+
+module SignalWireAgents
+  module Prefabs
+    # Prefab agent for greeting callers and transferring them to departments.
+    #
+    #   agent = Receptionist.new(
+    #     departments: [
+    #       { 'name' => 'sales',   'description' => 'Product inquiries', 'number' => '+15551235555' },
+    #       { 'name' => 'support', 'description' => 'Technical help',    'number' => '+15551236666' }
+    #     ]
+    #   )
+    #
+    class Receptionist
+      attr_reader :departments, :name, :route, :greeting
+
+      def initialize(departments:, name: 'receptionist', route: '/receptionist',
+                     greeting: 'Thank you for calling. How can I help you today?', **_opts)
+        raise ArgumentError, 'departments must be a non-empty Array' unless departments.is_a?(Array) && !departments.empty?
+        departments.each_with_index do |d, i|
+          d = d.transform_keys(&:to_s)
+          raise ArgumentError, "Department #{i} missing 'name'" unless d['name']
+          raise ArgumentError, "Department #{i} missing 'number'" unless d['number']
+        end
+
+        @departments = departments.map { |d| d.transform_keys(&:to_s) }
+        @greeting    = greeting
+        @name  = name
+        @route = route
+      end
+
+      def tools
+        %w[transfer_to_department collect_caller_info]
+      end
+
+      def prompt_sections
+        bullets = @departments.map { |d| "#{d['name']}: #{d['description'] || d['name']} (#{d['number']})" }
+        [
+          {
+            'title' => 'Receptionist',
+            'body' => @greeting,
+            'bullets' => bullets
+          }
+        ]
+      end
+
+      def global_data
+        {
+          'departments' => @departments,
+          'caller_info' => {}
+        }
+      end
+
+      def handle_transfer(args, _raw_data)
+        dept_name = args['department']
+        dept = @departments.find { |d| d['name'] == dept_name }
+        if dept
+          result = Swaig::FunctionResult.new("Transferring you to #{dept_name} now.")
+          result.connect(dept['number'])
+          result
+        else
+          Swaig::FunctionResult.new("I couldn't find that department. Available departments: #{@departments.map { |d| d['name'] }.join(', ')}")
+        end
+      end
+    end
+  end
+end