signalwire_agents 1.1.0

data/lib/signalwire_agents/swml/schema.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module SignalWireAgents
+  module SWML
+    class Schema
+      attr_reader :verbs
+
+      def initialize
+        @verbs = {}
+        load_schema
+      end
+
+      # Is +name+ a recognised SWML verb?
+      def valid_verb?(name)
+        @verbs.key?(name.to_s)
+      end
+
+      # Sorted list of all known verb names.
+      def verb_names
+        @verbs.keys.sort
+      end
+
+      # How many verbs are defined in the schema.
+      def verb_count
+        @verbs.size
+      end
+
+      # Return the full definition hash for a verb, or nil.
+      def get_verb(name)
+        @verbs[name.to_s]
+      end
+
+      private
+
+      def load_schema
+        schema_path = File.join(__dir__, 'schema.json')
+        unless File.exist?(schema_path)
+          raise "SWML schema.json not found at #{schema_path}"
+        end
+
+        raw = JSON.parse(File.read(schema_path))
+        defs = raw['$defs'] || {}
+        swml_method = defs['SWMLMethod'] || {}
+        any_of = swml_method['anyOf'] || []
+
+        any_of.each do |entry|
+          ref = entry['$ref']
+          next unless ref
+
+          # e.g. "#/$defs/Answer" -> "Answer"
+          def_name = ref.split('/').last
+          defn = defs[def_name]
+          next unless defn
+
+          props = defn['properties']
+          next unless props && !props.empty?
+
+          # The first property key is the actual verb name (e.g. "answer", "ai")
+          actual_verb = props.keys.first
+          @verbs[actual_verb] = {
+            'name'        => actual_verb,
+            'schema_name' => def_name,
+            'definition'  => defn
+          }
+        end
+      end
+    end
+
+    # Module-level singleton so the schema is loaded at most once.
+    def self.schema
+      @schema ||= Schema.new
+    end
+
+    # Allow resetting for tests
+    def self.reset_schema!
+      @schema = nil
+    end
+  end
+end

data/lib/signalwire_agents/swml/service.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+require 'openssl'
+require 'rack'
+require_relative '../logging'
+require_relative 'document'
+require_relative 'schema'
+
+module SignalWireAgents
+  module SWML
+    class Service
+      attr_reader :name, :route, :host, :port
+
+      # @param name   [String]  Human-readable service name
+      # @param route  [String]  HTTP path this service responds on (default "/")
+      # @param host   [String]  Bind address (default "0.0.0.0")
+      # @param port   [Integer, nil] Port — falls back to $PORT then 3000
+      # @param basic_auth [Array(String,String), nil] Explicit (user, pass) pair
+      def initialize(name:, route: '/', host: '0.0.0.0', port: nil, basic_auth: nil)
+        @name   = name
+        @route  = route.chomp('/')
+        @route  = '/' if @route.empty?
+        @host   = host
+        @port   = port || Integer(ENV.fetch('PORT', 3000))
+        @log    = Logging.logger("SWML::Service[#{name}]")
+        @document = Document.new
+        @routing_callbacks = {}
+        @server = nil
+
+        # --- auth --------------------------------------------------------
+        @basic_auth = if basic_auth
+                        basic_auth
+                      elsif ENV['SWML_BASIC_AUTH_USER'] && ENV['SWML_BASIC_AUTH_PASSWORD']
+                        [ENV['SWML_BASIC_AUTH_USER'], ENV['SWML_BASIC_AUTH_PASSWORD']]
+                      else
+                        [SecureRandom.uuid, SecureRandom.uuid]
+                      end
+
+        @log.info "Service '#{@name}' initialised (route=#{@route}, port=#{@port})"
+      end
+
+      # ------------------------------------------------------------------
+      # Verb auto-vivification via method_missing
+      # ------------------------------------------------------------------
+
+      def method_missing(method_name, *args, **kwargs)
+        verb = method_name.to_s
+
+        if SWML.schema.valid_verb?(verb)
+          execute_verb(verb, args, kwargs)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        SWML.schema.valid_verb?(method_name.to_s) || super
+      end
+
+      # Execute a SWML verb, adding it to the current document.
+      #
+      # For most verbs the config is a keyword-args Hash.
+      # The +sleep+ verb is special: it also accepts a bare Integer.
+      def execute_verb(verb_name, args = [], kwargs = {})
+        verb_name = verb_name.to_s
+
+        if verb_name == 'sleep'
+          # Accept sleep(2000) or sleep(duration: 2000)
+          value = if args.length == 1 && args.first.is_a?(Integer)
+                    args.first
+                  elsif kwargs.key?(:duration)
+                    kwargs[:duration]
+                  elsif !kwargs.empty?
+                    kwargs.values.first
+                  else
+                    raise ArgumentError, "sleep requires an integer duration"
+                  end
+          @document.add_verb(verb_name, value)
+        else
+          config = kwargs.transform_keys(&:to_s).reject { |_, v| v.nil? }
+          @document.add_verb(verb_name, config)
+        end
+      end
+
+      # ------------------------------------------------------------------
+      # Auth helpers
+      # ------------------------------------------------------------------
+
+      # Returns [username, password]
+      def get_basic_auth_credentials
+        @basic_auth.dup
+      end
+
+      # Build the full URL for this service.
+      #
+      #   get_full_url                       # => "http://0.0.0.0:3000/"
+      #   get_full_url(include_auth: true)   # => "http://user:pass@0.0.0.0:3000/"
+      def get_full_url(include_auth: false)
+        scheme = 'http'
+        auth   = include_auth ? "#{@basic_auth[0]}:#{@basic_auth[1]}@" : ''
+        path   = @route == '/' ? '/' : @route
+        "#{scheme}://#{auth}#{@host}:#{@port}#{path}"
+      end
+
+      # ------------------------------------------------------------------
+      # Routing callbacks & request handling
+      # ------------------------------------------------------------------
+
+      def register_routing_callback(path, &block)
+        @routing_callbacks[path] = block
+      end
+
+      # Called when a request arrives at the service's route.
+      # +request_data+ is the parsed JSON body (or nil).
+      # Returns the SWML hash to serialise as the response.
+      def on_request(request_data, callback_path)
+        if @routing_callbacks.key?(callback_path)
+          @routing_callbacks[callback_path].call(request_data)
+        else
+          @document.to_h
+        end
+      end
+
+      # ------------------------------------------------------------------
+      # Render the current SWML document
+      # ------------------------------------------------------------------
+
+      def render
+        @document.render
+      end
+
+      def render_pretty
+        @document.render_pretty
+      end
+
+      # Expose the underlying document (useful for tests and subclasses).
+      def document
+        @document
+      end
+
+      # ------------------------------------------------------------------
+      # Rack interface
+      # ------------------------------------------------------------------
+
+      # Returns a Rack-compatible application.
+      def rack_app
+        @rack_app ||= build_rack_app
+      end
+
+      # Start serving (blocking).
+      def serve
+        require 'webrick'
+        @log.info "Starting server on #{@host}:#{@port} ..."
+
+        user, _pass = @basic_auth
+        @log.info "Basic-auth credentials — user: #{user}  password: [REDACTED]"
+
+        @server = ::WEBrick::HTTPServer.new(
+          Host: @host,
+          Port: @port,
+          Logger: WEBrick::Log.new($stderr, WEBrick::Log::WARN),
+          AccessLog: []
+        )
+
+        @server.mount '/', Rack::Handler::WEBrick, rack_app
+
+        trap('INT')  { stop }
+        trap('TERM') { stop }
+
+        @server.start
+      end
+
+      # Gracefully stop the server.
+      def stop
+        @server&.shutdown
+      end
+
+      # ------------------------------------------------------------------
+      private
+      # ------------------------------------------------------------------
+
+      def build_rack_app
+        service = self
+        main_route = @route
+
+        app = Rack::Builder.new do
+          # --- public endpoints (no auth) --------------------------------
+          map '/health' do
+            run ->(_env) {
+              body = JSON.generate({ status: 'healthy' })
+              [200, { 'content-type' => 'application/json' }, [body]]
+            }
+          end
+
+          map '/ready' do
+            run ->(_env) {
+              body = JSON.generate({ status: 'ready' })
+              [200, { 'content-type' => 'application/json' }, [body]]
+            }
+          end
+
+          # --- authenticated endpoints -----------------------------------
+          map main_route do
+            use SecurityHeadersMiddleware
+            use TimingSafeBasicAuth, service
+
+            run ->(env) {
+              request = Rack::Request.new(env)
+
+              # Determine sub-path for routing callbacks
+              callback_path = env['PATH_INFO'] || '/'
+              callback_path = '/' if callback_path.empty?
+
+              request_data = nil
+              if request.post? || request.put?
+                body = request.body.read
+                request_data = JSON.parse(body) rescue nil
+              end
+
+              result = service.on_request(request_data, callback_path)
+              body   = JSON.generate(result)
+              [200, { 'content-type' => 'application/json' }, [body]]
+            }
+          end
+        end
+
+        app
+      end
+
+      # ------------------------------------------------------------------
+      # Middleware: security headers
+      # ------------------------------------------------------------------
+      class SecurityHeadersMiddleware
+        HEADERS = {
+          'x-content-type-options' => 'nosniff',
+          'x-frame-options'        => 'DENY',
+          'cache-control'          => 'no-store, no-cache, must-revalidate'
+        }.freeze
+
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          status, headers, body = @app.call(env)
+          HEADERS.each { |k, v| headers[k] = v }
+          [status, headers, body]
+        end
+      end
+
+      # ------------------------------------------------------------------
+      # Middleware: timing-safe Basic-Auth
+      # ------------------------------------------------------------------
+      class TimingSafeBasicAuth
+        def initialize(app, service)
+          @app     = app
+          @service = service
+        end
+
+        def call(env)
+          auth = Rack::Auth::Basic::Request.new(env)
+
+          unless auth.provided? && auth.basic?
+            return unauthorized
+          end
+
+          user, pass = @service.get_basic_auth_credentials
+          input_user, input_pass = auth.credentials
+
+          # Timing-safe comparison to prevent timing attacks.
+          user_ok = secure_compare(user, input_user)
+          pass_ok = secure_compare(pass, input_pass)
+
+          if user_ok && pass_ok
+            @app.call(env)
+          else
+            unauthorized
+          end
+        end
+
+        private
+
+        def unauthorized
+          body = 'Unauthorized'
+          [
+            401,
+            {
+              'content-type'     => 'text/plain',
+              'www-authenticate' => 'Basic realm="SignalWire SWML Service"'
+            },
+            [body]
+          ]
+        end
+
+        # Rack::Utils.secure_compare performs a constant-time byte comparison.
+        def secure_compare(a, b)
+          Rack::Utils.secure_compare(a.to_s, b.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/signalwire_agents/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SignalWireAgents
+  VERSION = '1.1.0'
+end

data/lib/signalwire_agents.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'signalwire_agents/version'
+require_relative 'signalwire_agents/logging'
+require_relative 'signalwire_agents/swml/document'
+require_relative 'signalwire_agents/swml/schema'
+require_relative 'signalwire_agents/swml/service'
+require_relative 'signalwire_agents/swaig/function_result'
+require_relative 'signalwire_agents/security/session_manager'
+require_relative 'signalwire_agents/contexts/context_builder'
+require_relative 'signalwire_agents/datamap/data_map'
+require_relative 'signalwire_agents/skills/skill_base'
+require_relative 'signalwire_agents/skills/skill_manager'
+require_relative 'signalwire_agents/skills/skill_registry'
+require_relative 'signalwire_agents/agent/agent_base'
+
+module SignalWireAgents
+  # Top-level convenience: re-export VERSION from version.rb
+end

metadata

@@ -0,0 +1,212 @@
+--- !ruby/object:Gem::Specification
+name: signalwire_agents
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- SignalWire
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rackup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: websocket-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A Ruby framework for building, deploying, and managing AI agents as microservices
+  that interact with the SignalWire platform.
+email: support@signalwire.com
+executables:
+- swaig-test
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/swaig-test
+- lib/signalwire_agents.rb
+- lib/signalwire_agents/agent/agent_base.rb
+- lib/signalwire_agents/contexts/context_builder.rb
+- lib/signalwire_agents/datamap/data_map.rb
+- lib/signalwire_agents/logging.rb
+- lib/signalwire_agents/prefabs/concierge.rb
+- lib/signalwire_agents/prefabs/faq_bot.rb
+- lib/signalwire_agents/prefabs/info_gatherer.rb
+- lib/signalwire_agents/prefabs/receptionist.rb
+- lib/signalwire_agents/prefabs/survey.rb
+- lib/signalwire_agents/relay/action.rb
+- lib/signalwire_agents/relay/call.rb
+- lib/signalwire_agents/relay/client.rb
+- lib/signalwire_agents/relay/constants.rb
+- lib/signalwire_agents/relay/message.rb
+- lib/signalwire_agents/relay/relay_event.rb
+- lib/signalwire_agents/rest/http_client.rb
+- lib/signalwire_agents/rest/namespaces/addresses.rb
+- lib/signalwire_agents/rest/namespaces/calling.rb
+- lib/signalwire_agents/rest/namespaces/chat.rb
+- lib/signalwire_agents/rest/namespaces/compat.rb
+- lib/signalwire_agents/rest/namespaces/datasphere.rb
+- lib/signalwire_agents/rest/namespaces/fabric.rb
+- lib/signalwire_agents/rest/namespaces/imported_numbers.rb
+- lib/signalwire_agents/rest/namespaces/logs.rb
+- lib/signalwire_agents/rest/namespaces/lookup.rb
+- lib/signalwire_agents/rest/namespaces/mfa.rb
+- lib/signalwire_agents/rest/namespaces/number_groups.rb
+- lib/signalwire_agents/rest/namespaces/phone_numbers.rb
+- lib/signalwire_agents/rest/namespaces/project.rb
+- lib/signalwire_agents/rest/namespaces/pubsub.rb
+- lib/signalwire_agents/rest/namespaces/queues.rb
+- lib/signalwire_agents/rest/namespaces/recordings.rb
+- lib/signalwire_agents/rest/namespaces/registry.rb
+- lib/signalwire_agents/rest/namespaces/short_codes.rb
+- lib/signalwire_agents/rest/namespaces/sip_profile.rb
+- lib/signalwire_agents/rest/namespaces/verified_callers.rb
+- lib/signalwire_agents/rest/namespaces/video.rb
+- lib/signalwire_agents/rest/signalwire_client.rb
+- lib/signalwire_agents/security/session_manager.rb
+- lib/signalwire_agents/server/agent_server.rb
+- lib/signalwire_agents/skills/builtin/api_ninjas_trivia.rb
+- lib/signalwire_agents/skills/builtin/claude_skills.rb
+- lib/signalwire_agents/skills/builtin/custom_skills.rb
+- lib/signalwire_agents/skills/builtin/datasphere.rb
+- lib/signalwire_agents/skills/builtin/datasphere_serverless.rb
+- lib/signalwire_agents/skills/builtin/datetime.rb
+- lib/signalwire_agents/skills/builtin/google_maps.rb
+- lib/signalwire_agents/skills/builtin/info_gatherer.rb
+- lib/signalwire_agents/skills/builtin/joke.rb
+- lib/signalwire_agents/skills/builtin/math.rb
+- lib/signalwire_agents/skills/builtin/mcp_gateway.rb
+- lib/signalwire_agents/skills/builtin/native_vector_search.rb
+- lib/signalwire_agents/skills/builtin/play_background_file.rb
+- lib/signalwire_agents/skills/builtin/spider.rb
+- lib/signalwire_agents/skills/builtin/swml_transfer.rb
+- lib/signalwire_agents/skills/builtin/weather_api.rb
+- lib/signalwire_agents/skills/builtin/web_search.rb
+- lib/signalwire_agents/skills/builtin/wikipedia_search.rb
+- lib/signalwire_agents/skills/skill_base.rb
+- lib/signalwire_agents/skills/skill_manager.rb
+- lib/signalwire_agents/skills/skill_registry.rb
+- lib/signalwire_agents/swaig/function_result.rb
+- lib/signalwire_agents/swml/document.rb
+- lib/signalwire_agents/swml/schema.json
+- lib/signalwire_agents/swml/schema.rb
+- lib/signalwire_agents/swml/service.rb
+- lib/signalwire_agents/version.rb
+homepage: https://github.com/signalwire/signalwire-agents-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: SignalWire AI Agents SDK
+test_files: []