signalwire_agents 1.1.0

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+
+module SignalWireAgents
+  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.")
+
+          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' }
+          }
+        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")
+
+            Swaig::FunctionResult.new("Web search results for '#{query}':\n\n#{formatted}")
+          rescue => e
+            Swaig::FunctionResult.new("Sorry, I encountered an error while searching: #{e.message}")
+          end
+        end
+
+        def google_search(query, num)
+          uri = URI('https://www.googleapis.com/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
+
+SignalWireAgents::Skills::SkillRegistry.register('web_search') do |params|
+  SignalWireAgents::Skills::Builtin::WebSearchSkill.new(params)
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+
+module SignalWireAgents
+  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)
+          # Step 1: Search
+          search_uri = URI("https://en.wikipedia.org/w/api.php?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
+          articles = results.first(@num_results).filter_map do |r|
+            title = r['title']
+            extract_uri = URI("https://en.wikipedia.org/w/api.php?action=query&prop=extracts&exintro&explaintext&format=json&titles=#{URI.encode_www_form_component(title)}")
+            extract_resp = Net::HTTP.get_response(extract_uri)
+            next unless extract_resp.is_a?(Net::HTTPSuccess)
+
+            pages = JSON.parse(extract_resp.body).dig('query', 'pages') || {}
+            page = pages.values.first
+            extract = page&.dig('extract')&.strip
+            next if extract.nil? || extract.empty?
+
+            "**#{title}**\n\n#{extract}"
+          end
+
+          return @no_results_msg if articles.empty?
+          articles.join("\n\n#{'=' * 50}\n\n")
+        end
+      end
+    end
+  end
+end
+
+SignalWireAgents::Skills::SkillRegistry.register('wikipedia_search') do |params|
+  SignalWireAgents::Skills::Builtin::WikipediaSearchSkill.new(params)
+end

data/lib/signalwire_agents/skills/skill_base.rb

@@ -0,0 +1,58 @@
+# 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 Skills
+    # Base class for all skills. Subclasses override the metadata methods
+    # and +register_tools+ to supply tool hashes.
+    class SkillBase
+      attr_reader :params
+
+      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
+
+      def initialize(params = {})
+        @params = (params || {}).transform_keys(&:to_s)
+      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_agents/skills/skill_manager.rb

@@ -0,0 +1,85 @@
+# 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'
+
+module SignalWireAgents
+  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
+      def initialize
+        @skills = {}   # instance_key => SkillBase instance
+        @mutex  = Mutex.new
+      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

data/lib/signalwire_agents/skills/skill_registry.rb

@@ -0,0 +1,76 @@
+# 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'
+
+module SignalWireAgents
+  module Skills
+    # Global registry mapping skill names to factory lambdas.
+    #
+    #   SkillRegistry.register('datetime') { |params| DateTimeSkill.new(params) }
+    #   factory = SkillRegistry.get_factory('datetime')
+    #   skill   = factory.call({ 'timezone' => 'UTC' })
+    #
+    class SkillRegistry
+      @factories = {}  # skill_name => lambda { |params| SkillBase }
+      @mutex     = Mutex.new
+
+      class << self
+        # Register a skill factory.
+        # @param skill_name [String]
+        # @yield [params] block that receives params hash and returns a SkillBase
+        def register(skill_name, &block)
+          @mutex.synchronize do
+            @factories[skill_name.to_s] = block
+          end
+        end
+
+        # Register with an explicit lambda / proc instead of a block.
+        # @param skill_name [String]
+        # @param factory [Proc]
+        def register_skill(skill_name, factory)
+          @mutex.synchronize do
+            @factories[skill_name.to_s] = factory
+          end
+        end
+
+        # Get the factory for a skill.
+        # @param skill_name [String]
+        # @return [Proc, nil]
+        def get_factory(skill_name)
+          @mutex.synchronize { @factories[skill_name.to_s] }
+        end
+
+        # List all registered skill names.
+        # @return [Array<String>]
+        def list_skills
+          @mutex.synchronize { @factories.keys.dup }
+        end
+
+        # Check if a skill is registered.
+        # @param skill_name [String]
+        # @return [Boolean]
+        def registered?(skill_name)
+          @mutex.synchronize { @factories.key?(skill_name.to_s) }
+        end
+
+        # Clear all registrations (primarily for testing).
+        def reset!
+          @mutex.synchronize { @factories.clear }
+        end
+
+        # Register all built-in skills. Called at load time.
+        def register_builtins!
+          # Each builtin file calls SkillRegistry.register on require.
+          # We just need to require them all.
+          builtin_dir = File.join(__dir__, 'builtin')
+          Dir[File.join(builtin_dir, '*.rb')].sort.each { |f| require f }
+        end
+      end
+    end
+  end
+end