signalwire-sdk 2.0.0

data/lib/signalwire/skills/builtin/google_maps.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+
+module SignalWire
+  module Skills
+    module Builtin
+      class GoogleMapsSkill < SkillBase
+        def name;        'google_maps'; end
+        def description; 'Validate addresses and compute driving routes using Google Maps'; end
+
+        def setup
+          @api_key         = get_param('api_key', env_var: 'GOOGLE_MAPS_API_KEY')
+          @lookup_tool     = get_param('lookup_tool_name', default: 'lookup_address')
+          @route_tool      = get_param('route_tool_name', default: 'compute_route')
+          return false unless @api_key && !@api_key.empty?
+          true
+        end
+
+        def register_tools
+          [
+            {
+              name: @lookup_tool,
+              description: 'Validate and geocode a street address or business name using Google Maps',
+              parameters: {
+                'address'  => { 'type' => 'string', 'description' => 'The address or business name to look up' },
+                'bias_lat' => { 'type' => 'number', 'description' => 'Latitude to bias results toward (optional)' },
+                'bias_lng' => { 'type' => 'number', 'description' => 'Longitude to bias results toward (optional)' }
+              },
+              handler: method(:handle_lookup)
+            },
+            {
+              name: @route_tool,
+              description: 'Compute a driving route between two points using Google Maps Routes API',
+              parameters: {
+                'origin_lat' => { 'type' => 'number', 'description' => 'Origin latitude' },
+                'origin_lng' => { 'type' => 'number', 'description' => 'Origin longitude' },
+                'dest_lat'   => { 'type' => 'number', 'description' => 'Destination latitude' },
+                'dest_lng'   => { 'type' => 'number', 'description' => 'Destination longitude' }
+              },
+              handler: method(:handle_route)
+            }
+          ]
+        end
+
+        def get_hints
+          %w[address location route directions miles distance]
+        end
+
+        def get_prompt_sections
+          [
+            {
+              'title' => 'Google Maps',
+              'body' => 'You can validate addresses and compute driving routes.',
+              'bullets' => [
+                "Use #{@lookup_tool} to validate and geocode addresses or business names",
+                "Use #{@route_tool} to get driving distance and time between two points",
+                "Address lookup supports spoken numbers (e.g. 'seven one four' becomes '714')",
+                'You can bias address results toward a known location to find the nearest match'
+              ]
+            }
+          ]
+        end
+
+        def get_parameter_schema
+          {
+            'api_key'          => { 'type' => 'string', 'required' => true, 'hidden' => true, 'env_var' => 'GOOGLE_MAPS_API_KEY' },
+            'lookup_tool_name' => { 'type' => 'string', 'default' => 'lookup_address' },
+            'route_tool_name'  => { 'type' => 'string', 'default' => 'compute_route' }
+          }
+        end
+
+        private
+
+        def handle_lookup(args, _raw_data)
+          address = (args['address'] || '').strip
+          if address.empty?
+            return Swaig::FunctionResult.new('Please provide an address or business name to look up.')
+          end
+
+          bias_lat = args['bias_lat']
+          bias_lng = args['bias_lng']
+
+          # Use Geocoding API
+          params = { address: address, key: @api_key }
+          uri = URI('https://maps.googleapis.com/maps/api/geocode/json')
+          uri.query = URI.encode_www_form(params)
+
+          resp = Net::HTTP.get_response(uri)
+          unless resp.is_a?(Net::HTTPSuccess)
+            return Swaig::FunctionResult.new("I couldn't find that address. Could you provide a more specific address?")
+          end
+
+          data = JSON.parse(resp.body)
+          results = data['results'] || []
+          if results.empty?
+            return Swaig::FunctionResult.new("I couldn't find that address. Could you provide a more specific address?")
+          end
+
+          r = results.first
+          location = r.dig('geometry', 'location') || {}
+          formatted = r['formatted_address'] || address
+
+          Swaig::FunctionResult.new(
+            "Address: #{formatted}\nCoordinates: #{location['lat']}, #{location['lng']}"
+          )
+        rescue => e
+          Swaig::FunctionResult.new("Error looking up address: #{e.message}")
+        end
+
+        def handle_route(args, _raw_data)
+          origin_lat = args['origin_lat']
+          origin_lng = args['origin_lng']
+          dest_lat   = args['dest_lat']
+          dest_lng   = args['dest_lng']
+
+          if [origin_lat, origin_lng, dest_lat, dest_lng].any?(&:nil?)
+            return Swaig::FunctionResult.new('All four coordinates are required: origin_lat, origin_lng, dest_lat, dest_lng.')
+          end
+
+          uri = URI('https://routes.googleapis.com/directions/v2:computeRoutes')
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+
+          request = Net::HTTP::Post.new(uri.path)
+          request['Content-Type']      = 'application/json'
+          request['X-Goog-Api-Key']    = @api_key
+          request['X-Goog-FieldMask']  = 'routes.distanceMeters,routes.duration'
+          request.body = {
+            origin:      { location: { latLng: { latitude: origin_lat, longitude: origin_lng } } },
+            destination: { location: { latLng: { latitude: dest_lat,   longitude: dest_lng } } },
+            travelMode: 'DRIVE',
+            routingPreference: 'TRAFFIC_AWARE'
+          }.to_json
+
+          resp = http.request(request)
+          data = JSON.parse(resp.body)
+
+          routes = data['routes'] || []
+          if routes.empty?
+            return Swaig::FunctionResult.new("I couldn't compute a route between those locations.")
+          end
+
+          route = routes.first
+          distance_m  = route['distanceMeters'] || 0
+          duration_s  = (route['duration'] || '0s').to_s.delete('s').to_i
+          distance_mi = distance_m / 1609.344
+          duration_min = duration_s / 60.0
+
+          Swaig::FunctionResult.new(
+            "Distance: #{'%.1f' % distance_mi} miles\nEstimated travel time: #{duration_min.to_i} minutes"
+          )
+        rescue => e
+          Swaig::FunctionResult.new("Error computing route: #{e.message}")
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('google_maps') do |params|
+  SignalWire::Skills::Builtin::GoogleMapsSkill.new(params)
+end

data/lib/signalwire/skills/builtin/info_gatherer.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+
+module SignalWire
+  module Skills
+    module Builtin
+      class InfoGathererSkill < SkillBase
+        def name;        'info_gatherer'; end
+        def description; 'Gather answers to a configurable list of questions'; end
+        def supports_multiple_instances?; true; end
+
+        def setup
+          @questions = get_param('questions')
+          return false unless @questions.is_a?(Array) && !@questions.empty?
+
+          @questions.each_with_index do |q, i|
+            return false unless q.is_a?(Hash) && q['key_name'] && q['question_text']
+          end
+
+          prefix = get_param('prefix')
+          if prefix && !prefix.empty?
+            @start_tool = "#{prefix}_start_questions"
+            @submit_tool = "#{prefix}_submit_answer"
+            @namespace = "skill:#{prefix}"
+          else
+            @start_tool = 'start_questions'
+            @submit_tool = 'submit_answer'
+            @namespace = 'skill:info_gatherer'
+          end
+
+          @completion_message = get_param('completion_message',
+            default: 'Thank you! All questions have been answered.')
+          true
+        end
+
+        def instance_key
+          prefix = get_param('prefix')
+          prefix && !prefix.to_s.empty? ? "info_gatherer_#{prefix}" : 'info_gatherer'
+        end
+
+        def register_tools
+          [
+            {
+              name: @start_tool,
+              description: 'Start the question sequence with the first question',
+              parameters: {},
+              handler: method(:handle_start)
+            },
+            {
+              name: @submit_tool,
+              description: 'Submit an answer to the current question and move to the next one',
+              parameters: {
+                'answer'            => { 'type' => 'string', 'description' => "The user's answer to the current question" },
+                'confirmed_by_user' => { 'type' => 'boolean', 'description' => 'Only set to true when the user has explicitly confirmed the answer.' }
+              },
+              handler: method(:handle_submit)
+            }
+          ]
+        end
+
+        def get_global_data
+          {
+            @namespace => {
+              'questions'      => @questions,
+              'question_index' => 0,
+              'answers'        => []
+            }
+          }
+        end
+
+        def get_prompt_sections
+          [
+            {
+              'title' => "Info Gatherer (#{instance_key})",
+              'body' => "You need to gather answers to a series of questions from the user. " \
+                        "Start by asking if they are ready, then call #{@start_tool} to get the first question. " \
+                        "After each answer, call #{@submit_tool} to record it and get the next question."
+            }
+          ]
+        end
+
+        def get_parameter_schema
+          {
+            'questions' => { 'type' => 'array', 'required' => true },
+            'prefix'    => { 'type' => 'string' },
+            'completion_message' => { 'type' => 'string' }
+          }
+        end
+
+        private
+
+        def handle_start(args, raw_data)
+          state = extract_state(raw_data)
+          questions = state['questions'] || @questions
+          index = state['question_index'] || 0
+
+          if questions.empty? || index >= questions.size
+            return Swaig::FunctionResult.new("I don't have any questions to ask.")
+          end
+
+          current = questions[index]
+          instruction = generate_instruction(current, index, questions.size, true)
+          Swaig::FunctionResult.new(instruction)
+        end
+
+        def handle_submit(args, raw_data)
+          answer    = args['answer'] || ''
+          confirmed = args['confirmed_by_user']
+
+          state     = extract_state(raw_data)
+          questions = state['questions'] || @questions
+          index     = state['question_index'] || 0
+          answers   = state['answers'] || []
+
+          if index >= questions.size
+            return Swaig::FunctionResult.new('All questions have already been answered.')
+          end
+
+          current = questions[index]
+
+          if current['confirm'] && !confirmed
+            return Swaig::FunctionResult.new(
+              "Before submitting, read the answer \"#{answer}\" back to the user and ask them to confirm."
+            )
+          end
+
+          new_answers = answers + [{ 'key_name' => current['key_name'], 'answer' => answer }]
+          new_index   = index + 1
+
+          if new_index < questions.size
+            next_q = questions[new_index]
+            instruction = generate_instruction(next_q, new_index, questions.size, false)
+            result = Swaig::FunctionResult.new(instruction)
+          else
+            result = Swaig::FunctionResult.new(@completion_message)
+            result.toggle_functions([
+              { 'function' => @start_tool, 'active' => false },
+              { 'function' => @submit_tool, 'active' => false }
+            ])
+          end
+
+          result.update_global_data({
+            @namespace => {
+              'questions'      => questions,
+              'question_index' => new_index,
+              'answers'        => new_answers
+            }
+          })
+          result
+        end
+
+        def extract_state(raw_data)
+          return {} unless raw_data.is_a?(Hash)
+          gd = raw_data['global_data'] || {}
+          gd[@namespace] || {}
+        end
+
+        def generate_instruction(question, index, total, first)
+          text = question['question_text']
+          num  = index + 1
+
+          if first
+            instr = "Ask each question one at a time, wait for the user's answer, " \
+                    "then call #{@submit_tool} with their answer.\n\n" \
+                    "[Question #{num} of #{total}]: \"#{text}\""
+          else
+            instr = "Previous answer saved. [Question #{num} of #{total}]: \"#{text}\""
+          end
+
+          if question['prompt_add'] && !question['prompt_add'].empty?
+            instr += "\nNote: #{question['prompt_add']}"
+          end
+
+          if question['confirm']
+            instr += "\nThis question requires confirmation. Read the answer back and ask the user to confirm."
+          end
+
+          instr
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('info_gatherer') do |params|
+  SignalWire::Skills::Builtin::InfoGathererSkill.new(params)
+end

data/lib/signalwire/skills/builtin/joke.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+require_relative '../../datamap/data_map'
+
+module SignalWire
+  module Skills
+    module Builtin
+      class JokeSkill < SkillBase
+        def name;        'joke'; end
+        def description; 'Tell jokes using the API Ninjas joke API'; end
+
+        def setup
+          @api_key   = get_param('api_key', env_var: 'API_NINJAS_KEY')
+          @tool_name = get_param('tool_name', default: 'get_joke')
+          return false unless @api_key && !@api_key.empty?
+          true
+        end
+
+        def register_tools
+          dm = DataMap.new(@tool_name)
+                .description('Get a random joke from API Ninjas')
+                .parameter('type', 'string', 'Type of joke to get', required: true, enum: %w[jokes dadjokes])
+                .webhook('GET', "https://api.api-ninjas.com/v1/${args.type}",
+                         headers: { 'X-Api-Key' => @api_key })
+                .output(Swaig::FunctionResult.new("Here's a joke: ${array[0].joke}"))
+                .error_keys(%w[error])
+                .fallback_output(Swaig::FunctionResult.new('Sorry, there is a problem with the joke service right now. Please try again later.'))
+
+          [{ datamap: dm.to_swaig_function }]
+        end
+
+        def get_global_data
+          { 'joke_skill_enabled' => true }
+        end
+
+        def get_prompt_sections
+          [
+            {
+              'title' => 'Joke Telling',
+              'body' => 'You can tell jokes to entertain users.',
+              'bullets' => [
+                "Use #{@tool_name || 'get_joke'} to tell jokes when users ask for humor",
+                'You can tell regular jokes or dad jokes',
+                'Be enthusiastic and fun when sharing jokes'
+              ]
+            }
+          ]
+        end
+
+        def get_parameter_schema
+          {
+            'api_key'   => { 'type' => 'string', 'required' => true, 'hidden' => true, 'env_var' => 'API_NINJAS_KEY' },
+            'tool_name' => { 'type' => 'string', 'default' => 'get_joke' }
+          }
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('joke') do |params|
+  SignalWire::Skills::Builtin::JokeSkill.new(params)
+end

data/lib/signalwire/skills/builtin/math.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+
+module SignalWire
+  module Skills
+    module Builtin
+      class MathSkill < SkillBase
+        def name;        'math'; end
+        def description; 'Perform basic mathematical calculations'; end
+
+        def register_tools
+          [
+            {
+              name: 'calculate',
+              description: 'Perform a mathematical calculation with basic operations (+, -, *, /, %, **)',
+              parameters: {
+                'expression' => { 'type' => 'string', 'description' => "Mathematical expression to evaluate (e.g., '2 + 3 * 4', '(10 + 5) / 3')" }
+              },
+              handler: method(:handle_calculate)
+            }
+          ]
+        end
+
+        def get_prompt_sections
+          [
+            {
+              'title' => 'Mathematical Calculations',
+              'body' => 'You can perform mathematical calculations for users.',
+              'bullets' => [
+                'Use the calculate tool for any math expressions',
+                'Supports basic operations: +, -, *, /, %, ** (power)',
+                'Can handle parentheses for complex expressions'
+              ]
+            }
+          ]
+        end
+
+        private
+
+        # Safe expression evaluator. Only allows numbers and basic operators.
+        # Never calls eval on untrusted input.
+        def handle_calculate(args, _raw_data)
+          expression = (args['expression'] || '').strip
+          if expression.empty?
+            return Swaig::FunctionResult.new('Please provide a mathematical expression to calculate.')
+          end
+
+          result = safe_eval(expression)
+          Swaig::FunctionResult.new("#{expression} = #{result}")
+        rescue ZeroDivisionError
+          Swaig::FunctionResult.new('Error: Division by zero is not allowed.')
+        rescue => _e
+          Swaig::FunctionResult.new('Error: Invalid expression. Only numbers and basic math operators (+, -, *, /, %, **, parentheses) are allowed.')
+        end
+
+        # Tokenize, parse, and evaluate a mathematical expression safely.
+        # This uses a simple recursive-descent parser — no eval/exec.
+        def safe_eval(expr)
+          tokens = tokenize(expr)
+          pos = [0]
+          result = parse_expr(tokens, pos)
+          raise 'Unexpected tokens after expression' unless pos[0] >= tokens.length
+          result
+        end
+
+        def tokenize(expr)
+          tokens = []
+          i = 0
+          while i < expr.length
+            ch = expr[i]
+            if ch =~ /\s/
+              i += 1
+            elsif ch =~ /[\d.]/ || (ch == '-' && (tokens.empty? || %w[( + - * / % **].include?(tokens.last)))
+              num_str = +''
+              if ch == '-'
+                num_str << ch
+                i += 1
+              end
+              while i < expr.length && expr[i] =~ /[\d.]/
+                num_str << expr[i]
+                i += 1
+              end
+              tokens << num_str
+            elsif ch == '*' && i + 1 < expr.length && expr[i + 1] == '*'
+              tokens << '**'
+              i += 2
+            elsif '+-*/%()'.include?(ch)
+              tokens << ch
+              i += 1
+            else
+              raise "Invalid character: #{ch}"
+            end
+          end
+          tokens
+        end
+
+        def parse_expr(tokens, pos)
+          left = parse_term(tokens, pos)
+          while pos[0] < tokens.length && %w[+ -].include?(tokens[pos[0]])
+            op = tokens[pos[0]]
+            pos[0] += 1
+            right = parse_term(tokens, pos)
+            left = op == '+' ? left + right : left - right
+          end
+          left
+        end
+
+        def parse_term(tokens, pos)
+          left = parse_power(tokens, pos)
+          while pos[0] < tokens.length && %w[* / %].include?(tokens[pos[0]])
+            op = tokens[pos[0]]
+            pos[0] += 1
+            right = parse_power(tokens, pos)
+            case op
+            when '*' then left *= right
+            when '/'
+              raise ZeroDivisionError, 'division by zero' if right == 0
+              left = left.to_f / right
+            when '%'
+              raise ZeroDivisionError, 'division by zero' if right == 0
+              left %= right
+            end
+          end
+          left
+        end
+
+        def parse_power(tokens, pos)
+          base = parse_unary(tokens, pos)
+          if pos[0] < tokens.length && tokens[pos[0]] == '**'
+            pos[0] += 1
+            exp = parse_power(tokens, pos) # right-associative
+            raise 'Exponent too large (maximum is 1000)' if exp.is_a?(Numeric) && exp > 1000
+            base **= exp
+          end
+          base
+        end
+
+        def parse_unary(tokens, pos)
+          if pos[0] < tokens.length && tokens[pos[0]] == '-'
+            pos[0] += 1
+            -parse_atom(tokens, pos)
+          elsif pos[0] < tokens.length && tokens[pos[0]] == '+'
+            pos[0] += 1
+            parse_atom(tokens, pos)
+          else
+            parse_atom(tokens, pos)
+          end
+        end
+
+        def parse_atom(tokens, pos)
+          raise 'Unexpected end of expression' if pos[0] >= tokens.length
+
+          tok = tokens[pos[0]]
+          if tok == '('
+            pos[0] += 1
+            val = parse_expr(tokens, pos)
+            raise 'Missing closing parenthesis' unless pos[0] < tokens.length && tokens[pos[0]] == ')'
+            pos[0] += 1
+            val
+          elsif tok =~ /\A-?[\d.]+\z/
+            pos[0] += 1
+            tok.include?('.') ? tok.to_f : tok.to_i
+          else
+            raise "Unexpected token: #{tok}"
+          end
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('math') do |params|
+  SignalWire::Skills::Builtin::MathSkill.new(params)
+end