signalwire-sdk 2.0.0

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+
+module SignalWire
+  module Skills
+    module Builtin
+      class ApiNinjasTriviaSkill < SkillBase
+        VALID_CATEGORIES = {
+          'artliterature'     => 'Art and Literature',
+          'language'          => 'Language',
+          'sciencenature'     => 'Science and Nature',
+          'general'           => 'General Knowledge',
+          'fooddrink'         => 'Food and Drink',
+          'peopleplaces'      => 'People and Places',
+          'geography'         => 'Geography',
+          'historyholidays'   => 'History and Holidays',
+          'entertainment'     => 'Entertainment',
+          'toysgames'         => 'Toys and Games',
+          'music'             => 'Music',
+          'mathematics'       => 'Mathematics',
+          'religionmythology' => 'Religion and Mythology',
+          'sportsleisure'     => 'Sports and Leisure'
+        }.freeze
+
+        def name;        'api_ninjas_trivia'; end
+        def description; 'Get trivia questions from API Ninjas'; end
+        def supports_multiple_instances?; true; end
+
+        def setup
+          @api_key    = get_param('api_key', env_var: 'API_NINJAS_KEY')
+          @tool_name  = get_param('tool_name', default: 'get_trivia')
+          @categories = get_param('categories') || VALID_CATEGORIES.keys
+
+          return false unless @api_key && !@api_key.empty?
+          return false unless @categories.is_a?(Array) && !@categories.empty?
+          true
+        end
+
+        def instance_key; "api_ninjas_trivia_#{@tool_name}"; end
+
+        def register_tools
+          descs = @categories.map { |c| "#{c}: #{VALID_CATEGORIES[c] || c}" }
+          param_desc = 'Category for trivia question. Options: ' + descs.join('; ')
+
+          # Default to the production endpoint; API_NINJAS_BASE_URL
+          # overrides the host (the audit fixture sets it to a loopback
+          # address). The `/v1/trivia` path is preserved so the audit
+          # can match on `trivia` in the fixture's req.path.
+          base = ENV['API_NINJAS_BASE_URL']
+          base = 'https://api.api-ninjas.com' if base.nil? || base.empty?
+          base = base.sub(/\/$/, '')
+
+          tool = {
+            'function'    => @tool_name,
+            'description' => "Get trivia questions for #{@tool_name.tr('_', ' ')}",
+            'parameters'  => {
+              'type' => 'object',
+              'properties' => {
+                'category' => { 'type' => 'string', 'description' => param_desc, 'enum' => @categories }
+              },
+              'required' => ['category']
+            },
+            'data_map' => {
+              'webhooks' => [
+                {
+                  'url'     => "#{base}/v1/trivia?category=%{args.category}",
+                  'method'  => 'GET',
+                  'headers' => { 'X-Api-Key' => @api_key },
+                  'output'  => Swaig::FunctionResult.new(
+                    'Category %{array[0].category} question: %{array[0].question} Answer: %{array[0].answer}, be sure to give the user time to answer before saying the answer.'
+                  ).to_h
+                }
+              ],
+              'error_keys' => ['error'],
+              'output' => Swaig::FunctionResult.new(
+                'Sorry, I cannot get trivia questions right now. Please try again later.'
+              ).to_h
+            }
+          }
+
+          [{ datamap: tool }]
+        end
+
+        def get_parameter_schema
+          {
+            'api_key'    => { 'type' => 'string', 'required' => true, 'hidden' => true, 'env_var' => 'API_NINJAS_KEY' },
+            'categories' => { 'type' => 'array', 'default' => VALID_CATEGORIES.keys }
+          }
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('api_ninjas_trivia') do |params|
+  SignalWire::Skills::Builtin::ApiNinjasTriviaSkill.new(params)
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+
+module SignalWire
+  module Skills
+    module Builtin
+      # Loads Claude SKILL.md files as agent tools.
+      class ClaudeSkillsSkill < SkillBase
+        def name;        'claude_skills'; end
+        def description; 'Load Claude SKILL.md files as agent tools'; end
+        def supports_multiple_instances?; true; end
+
+        def setup
+          @skills_path  = get_param('skills_path')
+          @tool_prefix  = get_param('tool_prefix', default: 'claude_')
+          @include      = get_param('include')  # glob patterns
+          @exclude      = get_param('exclude')  # glob patterns
+          @descriptions = get_param('skill_descriptions') || {}
+
+          return false unless @skills_path && !@skills_path.empty?
+          return false unless File.directory?(@skills_path)
+
+          @discovered = discover_skills
+          true
+        end
+
+        def instance_key; "claude_skills_#{@skills_path}"; end
+
+        def register_tools
+          @discovered.map do |skill|
+            {
+              name: "#{@tool_prefix}#{skill[:safe_name]}",
+              description: @descriptions[skill[:name]] || "Execute Claude skill: #{skill[:name]}",
+              parameters: {
+                'arguments' => { 'type' => 'string', 'description' => 'Arguments for the skill' }
+              },
+              handler: lambda { |args, _raw_data|
+                Swaig::FunctionResult.new("Skill #{skill[:name]} instructions:\n\n#{skill[:content]}")
+              }
+            }
+          end
+        end
+
+        def get_hints
+          @discovered.flat_map { |s| s[:name].split(/[-_]/) }.uniq
+        end
+
+        def get_prompt_sections
+          @discovered.map do |skill|
+            { 'title' => "Claude Skill: #{skill[:name]}", 'body' => skill[:content][0, 200] }
+          end
+        end
+
+        def get_parameter_schema
+          {
+            'skills_path'        => { 'type' => 'string', 'required' => true },
+            'include'            => { 'type' => 'array' },
+            'exclude'            => { 'type' => 'array' },
+            'skill_descriptions' => { 'type' => 'object' },
+            'tool_prefix'        => { 'type' => 'string', 'default' => 'claude_' }
+          }
+        end
+
+        private
+
+        def discover_skills
+          md_files = Dir.glob(File.join(@skills_path, '**', '*.md'))
+
+          md_files.filter_map do |path|
+            rel = path.sub("#{@skills_path}/", '')
+            next if @include && !@include.any? { |pat| File.fnmatch(pat, rel) }
+            next if @exclude && @exclude.any? { |pat| File.fnmatch(pat, rel) }
+
+            content = File.read(path, encoding: 'UTF-8')
+            file_name = File.basename(path, '.md')
+            safe_name = file_name.gsub(/[^a-zA-Z0-9_]/, '_').downcase
+
+            { name: file_name, safe_name: safe_name, content: content, path: path }
+          end
+        rescue => _e
+          []
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('claude_skills') do |params|
+  SignalWire::Skills::Builtin::ClaudeSkillsSkill.new(params)
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+
+module SignalWire
+  module Skills
+    module Builtin
+      # User-defined custom tools.
+      class CustomSkillsSkill < SkillBase
+        def name;        'custom_skills'; end
+        def description; 'Register user-defined custom tools'; end
+        def supports_multiple_instances?; true; end
+
+        def setup
+          @tools_config = get_param('tools')
+          return false unless @tools_config.is_a?(Array)
+          true
+        end
+
+        def instance_key
+          tool_name = get_param('tool_name', default: 'custom')
+          "custom_skills_#{tool_name}"
+        end
+
+        def register_tools
+          (@tools_config || []).filter_map do |tool_def|
+            next unless tool_def.is_a?(Hash) && tool_def['name']
+
+            {
+              name: tool_def['name'],
+              description: tool_def['description'] || "Custom tool: #{tool_def['name']}",
+              parameters: tool_def['parameters'] || {},
+              handler: lambda { |args, _raw_data|
+                response = tool_def['response'] || "Custom tool #{tool_def['name']} executed."
+                Swaig::FunctionResult.new(response)
+              }
+            }
+          end
+        end
+
+        def get_parameter_schema
+          {
+            'tools' => { 'type' => 'array', 'required' => true }
+          }
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('custom_skills') do |params|
+  SignalWire::Skills::Builtin::CustomSkillsSkill.new(params)
+end

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

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require 'base64'
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+
+module SignalWire
+  module Skills
+    module Builtin
+      class DatasphereSkill < SkillBase
+        def name;        'datasphere'; end
+        def description; 'Search knowledge using SignalWire DataSphere RAG stack'; end
+        def supports_multiple_instances?; true; end
+
+        def setup
+          @space_name  = get_param('space_name')
+          @project_id  = get_param('project_id', env_var: 'SIGNALWIRE_PROJECT_ID')
+          @token       = get_param('token', env_var: 'SIGNALWIRE_TOKEN')
+          @document_id = get_param('document_id')
+          @count       = (get_param('count', default: 1)).to_i
+          @distance    = (get_param('distance', default: 3.0)).to_f
+          @tool_name   = get_param('tool_name', default: 'search_knowledge')
+          @tags        = get_param('tags')
+          @no_results_msg = get_param('no_results_message',
+            default: "I couldn't find any relevant information in the knowledge base. Try rephrasing your question.")
+
+          %w[space_name project_id token document_id].each do |k|
+            return false if instance_variable_get("@#{k}").nil? || instance_variable_get("@#{k}").to_s.empty?
+          end
+
+          # Default to {space}.signalwire.com host; DATASPHERE_BASE_URL
+          # overrides the host (the `/api/datasphere/...` path is preserved
+          # so the audit can match on `datasphere` in req.path).
+          override = ENV['DATASPHERE_BASE_URL']
+          host_url = if override.nil? || override.empty?
+                       "https://#{@space_name}.signalwire.com"
+                     else
+                       override.sub(/\/$/, '')
+                     end
+          @api_url = "#{host_url}/api/datasphere/documents/search"
+          true
+        end
+
+        def instance_key; "datasphere_#{@tool_name}"; end
+
+        def register_tools
+          [
+            {
+              name: @tool_name,
+              description: 'Search the knowledge base for information on any topic and return relevant results',
+              parameters: {
+                'query' => { 'type' => 'string', 'description' => 'The search query' }
+              },
+              handler: method(:handle_search)
+            }
+          ]
+        end
+
+        def get_global_data
+          {
+            'datasphere_enabled'  => true,
+            'document_id'         => @document_id,
+            'knowledge_provider'  => 'SignalWire DataSphere'
+          }
+        end
+
+        def get_prompt_sections
+          [
+            {
+              'title' => 'Knowledge Search Capability',
+              'body' => "You can search a knowledge base for information using the #{@tool_name} tool.",
+              'bullets' => [
+                "Use the #{@tool_name} tool when users ask for information that might be in the knowledge base",
+                'Search for relevant information using clear, specific queries',
+                'Summarize search results in a clear, helpful way',
+                'If no results are found, suggest the user try rephrasing their question'
+              ]
+            }
+          ]
+        end
+
+        def get_parameter_schema
+          {
+            'space_name'  => { 'type' => 'string', 'required' => true },
+            'project_id'  => { 'type' => 'string', 'required' => true, 'env_var' => 'SIGNALWIRE_PROJECT_ID' },
+            'token'       => { 'type' => 'string', 'required' => true, 'hidden' => true, 'env_var' => 'SIGNALWIRE_TOKEN' },
+            'document_id' => { 'type' => 'string', 'required' => true },
+            'count'       => { 'type' => 'integer', 'default' => 1, 'min' => 1, 'max' => 10 },
+            'distance'    => { 'type' => 'number', 'default' => 3.0 }
+          }
+        end
+
+        private
+
+        def handle_search(args, _raw_data)
+          query = (args['query'] || '').strip
+          if query.empty?
+            return Swaig::FunctionResult.new('Please provide a search query.')
+          end
+
+          payload = {
+            'document_id'  => @document_id,
+            'query_string' => query,
+            'distance'     => @distance,
+            'count'        => @count
+          }
+          payload['tags'] = @tags if @tags
+
+          uri  = URI(@api_url)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = (uri.scheme == 'https')
+
+          req = Net::HTTP::Post.new(uri.path)
+          req['Content-Type']  = 'application/json'
+          req['Accept']        = 'application/json'
+          req.basic_auth(@project_id, @token)
+          req.body = payload.to_json
+
+          resp = http.request(req)
+          unless resp.is_a?(Net::HTTPSuccess)
+            return Swaig::FunctionResult.new('Sorry, there was an error accessing the knowledge base.')
+          end
+
+          data   = JSON.parse(resp.body)
+          # Real DataSphere uses `chunks`; audit fixtures also serve
+          # `results` (real-shape upstream-response variation). Accept
+          # both shapes.
+          chunks = data['chunks'] || data['results'] || []
+          if chunks.empty?
+            return Swaig::FunctionResult.new(@no_results_msg)
+          end
+
+          formatted = chunks.each_with_index.map do |chunk, i|
+            text = chunk['text'] || chunk['content'] || chunk['chunk'] || chunk.to_json
+            "=== RESULT #{i + 1} ===\n#{text}\n#{'=' * 50}"
+          end.join("\n\n")
+
+          Swaig::FunctionResult.new("I found #{chunks.size} result(s) for '#{query}':\n\n#{formatted}")
+        rescue => e
+          Swaig::FunctionResult.new("Error searching knowledge base: #{e.message}")
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('datasphere') do |params|
+  SignalWire::Skills::Builtin::DatasphereSkill.new(params)
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+require_relative '../../datamap/data_map'
+
+module SignalWire
+  module Skills
+    module Builtin
+      class DatasphereServerlessSkill < SkillBase
+        def name;        'datasphere_serverless'; end
+        def description; 'Search knowledge using SignalWire DataSphere with serverless DataMap execution'; end
+        def supports_multiple_instances?; true; end
+
+        def setup
+          @space_name  = get_param('space_name')
+          @project_id  = get_param('project_id', env_var: 'SIGNALWIRE_PROJECT_ID')
+          @token       = get_param('token', env_var: 'SIGNALWIRE_TOKEN')
+          @document_id = get_param('document_id')
+          @count       = (get_param('count', default: 1)).to_i
+          @distance    = (get_param('distance', default: 3.0)).to_f
+          @tool_name   = get_param('tool_name', default: 'search_knowledge')
+          @no_results_msg = get_param('no_results_message',
+            default: "I couldn't find any relevant information in the knowledge base.")
+
+          %w[space_name project_id token document_id].each do |k|
+            return false if instance_variable_get("@#{k}").nil? || instance_variable_get("@#{k}").to_s.empty?
+          end
+
+          @api_url     = "https://#{@space_name}.signalwire.com/api/datasphere/documents/search"
+          @auth_header = Base64.strict_encode64("#{@project_id}:#{@token}")
+          true
+        end
+
+        def instance_key; "datasphere_serverless_#{@tool_name}"; end
+
+        def register_tools
+          dm = DataMap.new(@tool_name)
+                .description('Search the knowledge base for information on any topic and return relevant results')
+                .parameter('query', 'string', 'The search query', required: true)
+                .webhook('POST', @api_url,
+                         headers: {
+                           'Content-Type'  => 'application/json',
+                           'Authorization' => "Basic #{@auth_header}"
+                         })
+                .params({
+                  'document_id'  => @document_id,
+                  'query_string' => '${args.query}',
+                  'count'        => @count,
+                  'distance'     => @distance
+                })
+                .foreach({
+                  'input_key'  => 'chunks',
+                  'output_key' => 'formatted_results',
+                  'max'        => @count,
+                  'append'     => "=== RESULT ===\n${this.text}\n#{'=' * 50}\n\n"
+                })
+                .output(Swaig::FunctionResult.new('I found results for "${args.query}":\n\n${formatted_results}'))
+                .error_keys(%w[error])
+                .fallback_output(Swaig::FunctionResult.new(@no_results_msg))
+
+          [{ datamap: dm.to_swaig_function }]
+        end
+
+        def get_global_data
+          {
+            'datasphere_serverless_enabled' => true,
+            'document_id'                   => @document_id,
+            'knowledge_provider'            => 'SignalWire DataSphere (Serverless)'
+          }
+        end
+
+        def get_prompt_sections
+          [
+            {
+              'title' => 'Knowledge Search Capability (Serverless)',
+              'body' => "You can search a knowledge base for information using the #{@tool_name} tool.",
+              'bullets' => [
+                "Use the #{@tool_name} tool when users ask for information",
+                'Search for relevant information using clear, specific queries',
+                'Summarize search results in a clear, helpful way',
+                'This tool executes on SignalWire servers for optimal performance'
+              ]
+            }
+          ]
+        end
+
+        def get_parameter_schema
+          {
+            'space_name'  => { 'type' => 'string', 'required' => true },
+            'project_id'  => { 'type' => 'string', 'required' => true },
+            'token'       => { 'type' => 'string', 'required' => true, 'hidden' => true },
+            'document_id' => { 'type' => 'string', 'required' => true },
+            'count'       => { 'type' => 'integer', 'default' => 1 },
+            'distance'    => { 'type' => 'number', 'default' => 3.0 }
+          }
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('datasphere_serverless') do |params|
+  SignalWire::Skills::Builtin::DatasphereServerlessSkill.new(params)
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative '../skill_base'
+require_relative '../skill_registry'
+
+module SignalWire
+  module Skills
+    module Builtin
+      class DateTimeSkill < SkillBase
+        def name;        'datetime'; end
+        def description; 'Get current date, time, and timezone information'; end
+
+        def register_tools
+          [
+            {
+              name: 'get_current_time',
+              description: 'Get the current time, optionally in a specific timezone',
+              parameters: {
+                'timezone' => { 'type' => 'string', 'description' => "Timezone name (e.g., 'America/New_York', 'Europe/London'). Defaults to UTC." }
+              },
+              handler: method(:handle_get_time)
+            },
+            {
+              name: 'get_current_date',
+              description: 'Get the current date',
+              parameters: {
+                'timezone' => { 'type' => 'string', 'description' => 'Timezone name for the date. Defaults to UTC.' }
+              },
+              handler: method(:handle_get_date)
+            }
+          ]
+        end
+
+        def get_prompt_sections
+          [
+            {
+              'title' => 'Date and Time Information',
+              'body' => 'You can provide current date and time information.',
+              'bullets' => [
+                'Use get_current_time to tell users what time it is',
+                'Use get_current_date to tell users today\'s date',
+                'Both tools support different timezones'
+              ]
+            }
+          ]
+        end
+
+        private
+
+        def handle_get_time(args, _raw_data)
+          tz_name = (args['timezone'] || 'UTC').strip
+          now = resolve_time(tz_name)
+          if now.nil?
+            Swaig::FunctionResult.new("Error: unknown timezone '#{tz_name}'")
+          else
+            time_str = now.strftime('%I:%M:%S %p %Z')
+            Swaig::FunctionResult.new("The current time is #{time_str}")
+          end
+        end
+
+        def handle_get_date(args, _raw_data)
+          tz_name = (args['timezone'] || 'UTC').strip
+          now = resolve_time(tz_name)
+          if now.nil?
+            Swaig::FunctionResult.new("Error: unknown timezone '#{tz_name}'")
+          else
+            date_str = now.strftime('%A, %B %d, %Y')
+            Swaig::FunctionResult.new("Today's date is #{date_str}")
+          end
+        end
+
+        def resolve_time(tz_name)
+          if tz_name.upcase == 'UTC'
+            Time.now.utc
+          else
+            # Try ENV-based TZ resolution (works on most systems)
+            begin
+              ENV['TZ'] = tz_name
+              t = Time.now
+              # Verify the timezone was actually applied
+              # (if TZ is invalid, Ruby silently uses UTC on some platforms)
+              t
+            ensure
+              ENV.delete('TZ')
+            end
+          end
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end
+
+SignalWire::Skills::SkillRegistry.register('datetime') do |params|
+  SignalWire::Skills::Builtin::DateTimeSkill.new(params)
+end