signalwire-sdk 2.0.0

data/lib/signalwire/core/logging_config.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Cross-language SDK contract for serverless / deployment-mode detection.
+#
+# Mirrors signalwire.core.logging_config.get_execution_mode in the Python
+# reference. Order of precedence (FIRST match wins):
+#
+#   1. GATEWAY_INTERFACE                                           -> 'cgi'
+#   2. AWS_LAMBDA_FUNCTION_NAME or LAMBDA_TASK_ROOT                -> 'lambda'
+#   3. FUNCTION_TARGET, K_SERVICE, or GOOGLE_CLOUD_PROJECT         -> 'google_cloud_function'
+#   4. AZURE_FUNCTIONS_ENVIRONMENT, FUNCTIONS_WORKER_RUNTIME, or
+#      AzureWebJobsStorage                                         -> 'azure_function'
+#   5. otherwise                                                   -> 'server'
+#
+# The companion helper SignalWire::Utils.is_serverless_mode lives in
+# lib/signalwire/utils/serverless.rb.
+
+module SignalWire
+  module Core
+    module LoggingConfig
+      module_function
+
+      # Detect the SDK's deployment environment based on well-known
+      # environment variables.
+      #
+      # @return [String] one of 'cgi', 'lambda', 'google_cloud_function',
+      #   'azure_function', or 'server'.
+      def get_execution_mode
+        return 'cgi' if env_set?('GATEWAY_INTERFACE')
+        return 'lambda' if env_set?('AWS_LAMBDA_FUNCTION_NAME') || env_set?('LAMBDA_TASK_ROOT')
+
+        if env_set?('FUNCTION_TARGET') ||
+           env_set?('K_SERVICE') ||
+           env_set?('GOOGLE_CLOUD_PROJECT')
+          return 'google_cloud_function'
+        end
+
+        if env_set?('AZURE_FUNCTIONS_ENVIRONMENT') ||
+           env_set?('FUNCTIONS_WORKER_RUNTIME') ||
+           env_set?('AzureWebJobsStorage')
+          return 'azure_function'
+        end
+
+        'server'
+      end
+
+      def env_set?(name)
+        v = ENV[name]
+        !v.nil? && !v.empty?
+      end
+      private_class_method :env_set?
+    end
+  end
+end

data/lib/signalwire/datamap/data_map.rb

@@ -0,0 +1,315 @@
+# 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 SignalWire
+  # 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 LLM-facing tool description (a.k.a. "purpose"). *PROMPT
+    # ENGINEERING*, not developer documentation.
+    #
+    # The description string is rendered into the OpenAI tool schema
+    # +description+ field on every LLM turn. The model reads it to
+    # decide WHEN to call this tool. A vague +purpose+ is the #1 cause
+    # of "the model has the right tool but doesn't call it" failures
+    # with data-map tools.
+    #
+    # == Bad vs good
+    #
+    #   BAD : .purpose("weather api")
+    #   GOOD: .purpose("Get the current weather conditions and "      \
+    #                  "forecast for a specific city. Use this "        \
+    #                  "whenever the user asks about weather, "         \
+    #                  "temperature, rain, or similar conditions in a " \
+    #                  "named location.")
+    def purpose(desc)
+      @purpose_text = desc
+      self
+    end
+
+    # Alias for +purpose+. Sets the LLM-facing tool description. This
+    # string is read by the model to decide WHEN to call this tool.
+    # See +purpose+ for bad-vs-good examples.
+    def description(desc)
+      purpose(desc)
+    end
+
+    # Add a typed parameter to the function signature — the +desc+ is
+    # LLM-FACING.
+    #
+    # Each parameter description is rendered into the OpenAI tool
+    # schema under +parameters.properties.<name>.description+ and sent
+    # to the model. The model uses it to decide HOW to fill in the
+    # argument from user speech. It is prompt engineering, not
+    # developer FYI.
+    #
+    # == Bad vs good
+    #
+    #   BAD : .parameter("city", "string", "the city")
+    #   GOOD: .parameter("city", "string",
+    #             "The name of the city to get weather for, e.g. "   \
+    #             "'San Francisco'. Ask the user if they did not "    \
+    #             "provide one. Include the state or country if the " \
+    #             "city name is ambiguous.")
+    #
+    # @param name [String]
+    # @param type [String] JSON-Schema type (string, number, boolean, array, object)
+    # @param desc [String] LLM-facing prompt-engineering description
+    #   telling the model how to extract this value from the user's
+    #   utterance
+    # @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/logging.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module SignalWire
+  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