signalwire-sdk 2.0.0

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+require_relative '../../datamap/data_map'
+
+module SignalWire
+  module Skills
+    module Builtin
+      class WeatherApiSkill < SkillBase
+        def name;        'weather_api'; end
+        def description; 'Get current weather information from WeatherAPI.com'; end
+
+        def setup
+          @api_key   = get_param('api_key', env_var: 'WEATHER_API_KEY')
+          @tool_name = get_param('tool_name', default: 'get_weather')
+          @temp_unit = get_param('temperature_unit', default: 'fahrenheit')
+          return false unless @api_key && !@api_key.empty?
+          true
+        end
+
+        def register_tools
+          if @temp_unit == 'celsius'
+            temp_field      = 'temp_c'
+            feels_field     = 'feelslike_c'
+            unit_name       = 'Celsius'
+          else
+            temp_field      = 'temp_f'
+            feels_field     = 'feelslike_f'
+            unit_name       = 'Fahrenheit'
+          end
+
+          response_template =
+            "Tell the user the current weather conditions. " \
+            "Express all temperatures in #{unit_name} using natural language numbers " \
+            "without abbreviations or symbols for clear text-to-speech pronunciation. " \
+            "Current conditions: ${current.condition.text}. " \
+            "Temperature: ${current.#{temp_field}} degrees #{unit_name}. " \
+            "Wind: ${current.wind_dir} at ${current.wind_mph} miles per hour. " \
+            "Cloud coverage: ${current.cloud} percent. " \
+            "Feels like: ${current.#{feels_field}} degrees #{unit_name}."
+
+          # Default to the WeatherAPI.com host; WEATHER_API_BASE_URL
+          # overrides for tests and the audit fixture. The `/v1/current.json`
+          # path is preserved so the audit can match on `current.json`.
+          base = ENV['WEATHER_API_BASE_URL']
+          base = 'https://api.weatherapi.com' if base.nil? || base.empty?
+          base = base.sub(/\/$/, '')
+
+          tool = {
+            'function'    => @tool_name,
+            'description' => 'Get current weather information for any location',
+            'parameters'  => {
+              'type' => 'object',
+              'properties' => {
+                'location' => { 'type' => 'string', 'description' => 'The city, state, country, or location to get weather for' }
+              },
+              'required' => ['location']
+            },
+            'data_map' => {
+              'webhooks' => [
+                {
+                  'url'    => "#{base}/v1/current.json?key=#{@api_key}&q=${lc:enc:args.location}&aqi=no",
+                  'method' => 'GET',
+                  'output' => Swaig::FunctionResult.new(response_template).to_h
+                }
+              ],
+              'error_keys' => ['error'],
+              'output' => Swaig::FunctionResult.new(
+                'Sorry, I cannot get weather information right now. Please try again later or check if the location name is correct.'
+              ).to_h
+            }
+          }
+
+          [{ datamap: tool }]
+        end
+
+        def get_parameter_schema
+          {
+            'api_key'          => { 'type' => 'string', 'required' => true, 'hidden' => true, 'env_var' => 'WEATHER_API_KEY' },
+            'tool_name'        => { 'type' => 'string', 'default' => 'get_weather' },
+            'temperature_unit' => { 'type' => 'string', 'default' => 'fahrenheit', 'enum' => %w[fahrenheit celsius] }
+          }
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('weather_api') do |params|
+  SignalWire::Skills::Builtin::WeatherApiSkill.new(params)
+end

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

@@ -0,0 +1,141 @@
+# 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 WebSearchSkill < SkillBase
+        def name;        'web_search'; end
+        def description; 'Search the web for information using Google Custom Search API'; end
+        def version;     '2.0.0'; end
+        def supports_multiple_instances?; true; end
+
+        def setup
+          @api_key           = get_param('api_key', env_var: 'GOOGLE_SEARCH_API_KEY')
+          @search_engine_id  = get_param('search_engine_id', env_var: 'GOOGLE_SEARCH_ENGINE_ID')
+          @num_results       = (get_param('num_results', default: 3)).to_i
+          @tool_name         = get_param('tool_name', default: 'web_search')
+          @no_results_msg    = get_param('no_results_message',
+            default: "I couldn't find quality results for that query. Try rephrasing your search.")
+
+          # Optional prefix/postfix wrapped around every non-empty search
+          # result. Use these to give the calling agent a mechanical cue
+          # (e.g. "tell the user this came from a public web search")
+          # without needing prompt-side rules. Mirrors Python parity.
+          @response_prefix   = get_param('response_prefix',  default: '')
+          @response_postfix  = get_param('response_postfix', default: '')
+
+          return false unless @api_key && !@api_key.empty?
+          return false unless @search_engine_id && !@search_engine_id.empty?
+          true
+        end
+
+        def instance_key; "web_search_#{@tool_name}"; end
+
+        def register_tools
+          [
+            {
+              name: @tool_name,
+              description: 'Search the web for high-quality information, automatically filtering low-quality results',
+              parameters: {
+                'query' => { 'type' => 'string', 'description' => 'The search query - what you want to find information about' }
+              },
+              handler: method(:handle_search)
+            }
+          ]
+        end
+
+        def get_global_data
+          { 'web_search_enabled' => true, 'search_provider' => 'Google Custom Search', 'quality_filtering' => true }
+        end
+
+        def get_prompt_sections
+          [
+            {
+              'title' => 'Web Search Capability (Quality Enhanced)',
+              'body' => "You can search the internet for high-quality information using the #{@tool_name} tool.",
+              'bullets' => [
+                "Use the #{@tool_name} tool when users ask for information you need to look up",
+                'The search automatically filters out low-quality results like empty pages',
+                'Results are ranked by content quality, relevance, and domain reputation',
+                'Summarize the high-quality results in a clear, helpful way'
+              ]
+            }
+          ]
+        end
+
+        def get_parameter_schema
+          {
+            'api_key'          => { 'type' => 'string', 'required' => true, 'hidden' => true, 'env_var' => 'GOOGLE_SEARCH_API_KEY' },
+            'search_engine_id' => { 'type' => 'string', 'required' => true, 'hidden' => true, 'env_var' => 'GOOGLE_SEARCH_ENGINE_ID' },
+            'num_results'      => { 'type' => 'integer', 'default' => 3, 'min' => 1, 'max' => 10 },
+            'no_results_message' => { 'type' => 'string' },
+            'response_prefix'  => { 'type' => 'string', 'default' => '' },
+            'response_postfix' => { 'type' => 'string', 'default' => '' }
+          }
+        end
+
+        private
+
+        def handle_search(args, _raw_data)
+          query = (args['query'] || '').strip
+          if query.empty?
+            return Swaig::FunctionResult.new('Please provide a search query. What would you like me to search for?')
+          end
+
+          begin
+            results = google_search(query, @num_results)
+            if results.empty?
+              return Swaig::FunctionResult.new(@no_results_msg)
+            end
+
+            formatted = results.map.with_index(1) do |r, i|
+              "=== RESULT #{i} ===\nTitle: #{r['title']}\nURL: #{r['url']}\nSnippet: #{r['snippet']}\n#{'=' * 50}"
+            end.join("\n\n")
+
+            response = "Web search results for '#{query}':\n\n#{formatted}"
+            response = "#{@response_prefix}\n\n#{response}"  unless @response_prefix.nil?  || @response_prefix.empty?
+            response = "#{response}\n\n#{@response_postfix}" unless @response_postfix.nil? || @response_postfix.empty?
+            Swaig::FunctionResult.new(response)
+          rescue => e
+            Swaig::FunctionResult.new("Sorry, I encountered an error while searching: #{e.message}")
+          end
+        end
+
+        def google_search(query, num)
+          # Default to Google CSE; WEB_SEARCH_BASE_URL overrides for tests
+          # and the audit fixture (matches Rust SDK's behavior — env var is
+          # the *host*, the `/customsearch/v1` path is appended below so
+          # the audit can match on `customsearch` in req.path).
+          base = ENV['WEB_SEARCH_BASE_URL']
+          base = 'https://www.googleapis.com' if base.nil? || base.empty?
+          uri = URI("#{base.sub(/\/$/, '')}/customsearch/v1")
+          uri.query = URI.encode_www_form(
+            key: @api_key,
+            cx: @search_engine_id,
+            q: query,
+            num: [num, 10].min
+          )
+
+          response = Net::HTTP.get_response(uri)
+          return [] unless response.is_a?(Net::HTTPSuccess)
+
+          data = JSON.parse(response.body)
+          (data['items'] || []).first(num).map do |item|
+            { 'title' => item['title'] || '', 'url' => item['link'] || '', 'snippet' => item['snippet'] || '' }
+          end
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('web_search') do |params|
+  SignalWire::Skills::Builtin::WebSearchSkill.new(params)
+end

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

@@ -0,0 +1,125 @@
+# 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 WikipediaSearchSkill < SkillBase
+        def name;        'wikipedia_search'; end
+        def description; 'Search Wikipedia for information about a topic and get article summaries'; end
+
+        def setup
+          @num_results    = [1, (get_param('num_results', default: 1)).to_i].max
+          @no_results_msg = get_param('no_results_message',
+            default: "I couldn't find any Wikipedia articles for that query. Try rephrasing your search or using different keywords.")
+          true
+        end
+
+        def register_tools
+          [
+            {
+              name: 'search_wiki',
+              description: 'Search Wikipedia for information about a topic and get article summaries',
+              parameters: {
+                'query' => { 'type' => 'string', 'description' => 'The search term or topic to look up on Wikipedia' }
+              },
+              handler: method(:handle_search)
+            }
+          ]
+        end
+
+        def get_prompt_sections
+          [
+            {
+              'title' => 'Wikipedia Search',
+              'body' => "You can search Wikipedia for factual information using search_wiki. This will return up to #{@num_results || 1} Wikipedia article summaries.",
+              'bullets' => [
+                'Use search_wiki for factual, encyclopedic information',
+                'Great for answering questions about people, places, concepts, and history',
+                'Returns reliable, well-sourced information from Wikipedia articles'
+              ]
+            }
+          ]
+        end
+
+        def get_parameter_schema
+          {
+            'num_results'      => { 'type' => 'integer', 'default' => 1, 'min' => 1, 'max' => 5 },
+            'no_results_message' => { 'type' => 'string' }
+          }
+        end
+
+        private
+
+        def handle_search(args, _raw_data)
+          query = (args['query'] || '').strip
+          if query.empty?
+            return Swaig::FunctionResult.new('Please provide a search query for Wikipedia.')
+          end
+
+          begin
+            result = search_wiki(query)
+            Swaig::FunctionResult.new(result)
+          rescue => e
+            Swaig::FunctionResult.new("Error searching Wikipedia: #{e.message}")
+          end
+        end
+
+        def search_wiki(query)
+          # Default to en.wikipedia.org host; WIKIPEDIA_BASE_URL overrides
+          # for tests and the audit fixture. The env var is the *host*; the
+          # `/w/api.php` path is appended below so audit_skills_dispatch
+          # can match on `api.php` in req.path.
+          base = ENV['WIKIPEDIA_BASE_URL']
+          base = 'https://en.wikipedia.org' if base.nil? || base.empty?
+          api_endpoint = "#{base.sub(/\/$/, '')}/w/api.php"
+
+          # Step 1: Search
+          search_uri = URI("#{api_endpoint}?action=query&list=search&format=json&srsearch=#{URI.encode_www_form_component(query)}&srlimit=#{@num_results}")
+          search_resp = Net::HTTP.get_response(search_uri)
+          return @no_results_msg unless search_resp.is_a?(Net::HTTPSuccess)
+
+          search_data = JSON.parse(search_resp.body)
+          results = search_data.dig('query', 'search') || []
+          return @no_results_msg if results.empty?
+
+          # Step 2: Get extracts. If the upstream returns extracts
+          # (production behavior on en.wikipedia.org), prefer those; if the
+          # response shape doesn't include `query.pages` (test fixtures,
+          # truncated responses), fall back to the snippet from step 1.
+          articles = results.first(@num_results).filter_map do |r|
+            title = r['title']
+            snippet = (r['snippet'] || '').gsub(/<[^>]+>/, '').strip
+            extract_uri = URI("#{api_endpoint}?action=query&prop=extracts&exintro&explaintext&format=json&titles=#{URI.encode_www_form_component(title)}")
+            extract_resp = Net::HTTP.get_response(extract_uri)
+
+            extract = nil
+            if extract_resp.is_a?(Net::HTTPSuccess)
+              pages = JSON.parse(extract_resp.body).dig('query', 'pages') || {}
+              page = pages.values.first
+              extract = page&.dig('extract')&.strip
+            end
+
+            content = extract && !extract.empty? ? extract : snippet
+            next if content.nil? || content.empty?
+
+            "**#{title}**\n\n#{content}"
+          end
+
+          return @no_results_msg if articles.empty?
+          articles.join("\n\n#{'=' * 50}\n\n")
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('wikipedia_search') do |params|
+  SignalWire::Skills::Builtin::WikipediaSearchSkill.new(params)
+end

data/lib/signalwire/skills/skill_base.rb

@@ -0,0 +1,82 @@
+# 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'
+require_relative '../logging'
+
+module SignalWire
+  module Skills
+    # Base class for all skills. Subclasses override the metadata methods
+    # and +register_tools+ to supply tool hashes.
+    class SkillBase
+      # Python parity:
+      # - ``params`` — params hash passed at construction
+      # - ``agent`` — owning AgentBase instance (or nil for standalone)
+      # - ``logger`` — namespaced logger ``signalwire.skills.<name>``
+      # - ``swaig_fields`` — extra SWAIG fields merged into tool defs;
+      #   pulled out of ``params`` if provided
+      attr_reader :params, :agent, :logger, :swaig_fields
+
+      def name;                       raise NotImplementedError, "#{self.class}#name"; end
+      def description;                raise NotImplementedError, "#{self.class}#description"; end
+      def version;                    '1.0.0'; end
+      def required_env_vars;          []; end
+      def supports_multiple_instances?; false; end
+
+      # Python parity: ``SkillBase.__init__(self, agent, params=None)``.
+      # First positional arg is the owning AgentBase (or nil for
+      # standalone). The second is the params hash. We accept the legacy
+      # 1-arg form for backwards compatibility (``DateTimeSkill.new({...})``).
+      def initialize(agent = nil, params = nil)
+        # Backwards compat: a single Hash means params-only (no agent).
+        if agent.is_a?(Hash) && params.nil?
+          params = agent
+          agent  = nil
+        end
+        @agent  = agent
+        @params = (params || {}).transform_keys(&:to_s)
+        # Python: pop swaig_fields out of params for separate access.
+        @swaig_fields = @params.delete('swaig_fields') || {}
+        @logger = ::SignalWire::Logging.logger("signalwire.skills.#{begin
+          name
+        rescue NotImplementedError
+          self.class.name
+        end}")
+      end
+
+      # Called once after construction. Return +true+ if the skill is ready.
+      def setup; true; end
+
+      # Return an Array of tool definition hashes. Each hash should have:
+      #   :name, :description, :parameters, :handler (lambda/proc)
+      def register_tools; []; end
+
+      # Speech recognition hints.
+      def get_hints; []; end
+
+      # Global data to merge into the agent.
+      def get_global_data; {}; end
+
+      # Prompt sections to add to the agent.
+      def get_prompt_sections; []; end
+
+      # Called when the skill is unloaded.
+      def cleanup; end
+
+      # Unique key for tracking this skill instance.
+      def instance_key; name; end
+
+      # Parameter schema for GUI / validation.
+      def get_parameter_schema; {}; end
+
+      # Helper to get a param with env-var fallback.
+      def get_param(key, env_var: nil, default: nil)
+        @params[key.to_s] || @params[key.to_sym.to_s] || (env_var && ENV[env_var]) || default
+      end
+    end
+  end
+end

data/lib/signalwire/skills/skill_manager.rb

@@ -0,0 +1,97 @@
+# 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 'thread'
+require_relative 'skill_base'
+require_relative '../logging'
+
+module SignalWire
+  module Skills
+    # Thread-safe lifecycle manager for loaded skill instances.
+    #
+    #   manager = SkillManager.new
+    #   manager.load('datetime', DateTimeSkill.new)
+    #   manager.get('datetime')  #=> <DateTimeSkill>
+    #   manager.unload('datetime')
+    #
+    class SkillManager
+      # Python parity:
+      # - ``agent`` — owning AgentBase instance (or nil)
+      # - ``logger`` — namespaced logger
+      attr_reader :agent, :logger
+
+      # Python parity: ``SkillManager.__init__(self, agent)`` —
+      # SkillManager keeps a back-pointer to its agent so loaded
+      # skills can attach prompt sections / SWAIG tools directly.
+      # Ruby allows nil for standalone use (tests, registry tools).
+      def initialize(agent = nil)
+        @agent  = agent
+        @skills = {}   # instance_key => SkillBase instance
+        @mutex  = Mutex.new
+        @logger = ::SignalWire::Logging.logger('signalwire.skill_manager')
+      end
+
+      # Load a skill instance. Calls +setup+ on the skill; raises if it fails.
+      # @param key [String] the instance key
+      # @param skill [SkillBase] the skill instance
+      # @return [SkillBase] the loaded skill
+      def load(key, skill)
+        @mutex.synchronize do
+          raise ArgumentError, "Skill already loaded: #{key}" if @skills.key?(key)
+
+          unless skill.setup
+            raise "Skill setup failed for '#{key}'"
+          end
+
+          @skills[key] = skill
+        end
+        skill
+      end
+
+      # Unload a skill by instance key. Calls +cleanup+ on it.
+      # @param key [String]
+      # @return [SkillBase, nil] the removed skill, or nil
+      def unload(key)
+        @mutex.synchronize do
+          skill = @skills.delete(key)
+          skill&.cleanup
+          skill
+        end
+      end
+
+      # Retrieve a loaded skill.
+      # @param key [String]
+      # @return [SkillBase, nil]
+      def get(key)
+        @mutex.synchronize { @skills[key] }
+      end
+
+      # @return [Boolean]
+      def loaded?(key)
+        @mutex.synchronize { @skills.key?(key) }
+      end
+
+      # @return [Array<String>]
+      def loaded_keys
+        @mutex.synchronize { @skills.keys.dup }
+      end
+
+      # @return [Integer]
+      def size
+        @mutex.synchronize { @skills.size }
+      end
+
+      # Unload all skills.
+      def clear
+        @mutex.synchronize do
+          @skills.each_value(&:cleanup)
+          @skills.clear
+        end
+      end
+    end
+  end
+end