signalwire-sdk 2.0.0

data/lib/signalwire/pom/prompt_object_model.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+require_relative 'section'
+
+module SignalWire
+  module POM
+    # A structured data format for composing, organising, and rendering
+    # prompt instructions for large language models.
+    #
+    # The Prompt Object Model provides a tree-based representation of a
+    # prompt document composed of nested Section objects, each of which
+    # can include a title, body text, bullet points, and arbitrarily
+    # nested subsections.
+    #
+    # Mirrors Python's ``signalwire.pom.pom.PromptObjectModel``. The
+    # rendered output (Markdown / XML / JSON / YAML) is byte-for-byte
+    # identical to the Python reference so cross-language POM documents
+    # interoperate.
+    class PromptObjectModel
+      attr_accessor :sections, :debug
+
+      def initialize(debug: false)
+        @sections = []
+        @debug = debug
+      end
+
+      # Build a PromptObjectModel from JSON.
+      #
+      # +json_data+ may be either a JSON string or an already-parsed
+      # Array. Mirrors Python's
+      # ``PromptObjectModel.from_json(json_data: Union[str, dict])``.
+      def self.from_json(json_data)
+        data = json_data.is_a?(String) ? JSON.parse(json_data) : json_data
+        _from_array(data)
+      end
+
+      # Build a PromptObjectModel from YAML.
+      #
+      # +yaml_data+ may be either a YAML string or an already-parsed
+      # Array. Mirrors Python's
+      # ``PromptObjectModel.from_yaml(yaml_data: Union[str, dict])``.
+      def self.from_yaml(yaml_data)
+        data = yaml_data.is_a?(String) ? YAML.safe_load(yaml_data) : yaml_data
+        _from_array(data)
+      end
+
+      # Internal: build a PromptObjectModel from a raw Array of Hash
+      # section descriptors. Mirrors Python's ``_from_dict`` (which
+      # confusingly takes a list, not a dict).
+      def self._from_array(data)
+        pom = new
+        data = [] if data.nil?
+        unless data.is_a?(Array)
+          raise ArgumentError, "POM root must be an Array, got #{data.class.name}"
+        end
+
+        data.each_with_index do |sec, idx|
+          if idx.positive? && !sec.key?('title')
+            sec['title'] = 'Untitled Section'
+          end
+          pom.sections << _build_section(sec)
+        end
+        pom
+      end
+
+      # Internal: build a Section (recursively) from a Hash section
+      # descriptor. Mirrors Python's ``build_section`` inner helper.
+      def self._build_section(hash, is_subsection: false)
+        unless hash.is_a?(Hash)
+          raise ArgumentError, 'Each section must be a Hash.'
+        end
+
+        if hash.key?('title') && !hash['title'].is_a?(String)
+          raise ArgumentError, "'title' must be a string if present."
+        end
+        if hash.key?('subsections') && !hash['subsections'].is_a?(Array)
+          raise ArgumentError, "'subsections' must be an Array if provided."
+        end
+        if hash.key?('bullets') && !hash['bullets'].is_a?(Array)
+          raise ArgumentError, "'bullets' must be an Array if provided."
+        end
+        if hash.key?('numbered') && ![true, false].include?(hash['numbered'])
+          raise ArgumentError, "'numbered' must be a boolean if provided."
+        end
+        if hash.key?('numberedBullets') && ![true, false].include?(hash['numberedBullets'])
+          raise ArgumentError, "'numberedBullets' must be a boolean if provided."
+        end
+
+        has_body = hash.key?('body') && hash['body'] && !hash['body'].empty?
+        has_bullets = hash.key?('bullets') && hash['bullets'] && !hash['bullets'].empty?
+        has_subsections = hash.key?('subsections') && hash['subsections'] && !hash['subsections'].empty?
+        unless has_body || has_bullets || has_subsections
+          raise ArgumentError,
+                'All sections must have either a non-empty body, non-empty bullets, or subsections'
+        end
+
+        if is_subsection && !hash.key?('title')
+          raise ArgumentError, 'All subsections must have a title'
+        end
+
+        kwargs = {
+          body: hash.fetch('body', ''),
+          bullets: hash.fetch('bullets', [])
+        }
+        kwargs[:numbered] = hash['numbered'] if hash.key?('numbered')
+        kwargs[:numbered_bullets] = hash['numberedBullets'] if hash.key?('numberedBullets')
+
+        section = Section.new(hash['title'], **kwargs)
+
+        (hash['subsections'] || []).each do |sub|
+          section.subsections << _build_section(sub, is_subsection: true)
+        end
+        section
+      end
+
+      # Add a top-level section to the model and return the new Section.
+      #
+      # Mirrors Python's ``PromptObjectModel.add_section``. If +bullets+
+      # is a String it is wrapped into a single-element Array (Python
+      # parity). Raises ArgumentError when +title+ is nil and the model
+      # already has at least one section (only the first section may
+      # be untitled).
+      def add_section(title = nil, body: '', bullets: nil, numbered: nil, numbered_bullets: false)
+        if title.nil? && !@sections.empty?
+          raise ArgumentError, 'Only the first section can have no title'
+        end
+
+        bullets_list = bullets.is_a?(String) ? [bullets] : (bullets || [])
+
+        section = Section.new(title, body: body, bullets: bullets_list,
+                                     numbered: numbered, numbered_bullets: numbered_bullets)
+        @sections << section
+        section
+      end
+
+      # Find a section by title, recursing into subsections. Returns
+      # +nil+ when the title is not present anywhere in the tree.
+      def find_section(title)
+        recurse = lambda do |sections|
+          sections.each do |section|
+            return section if section.title == title
+
+            found = recurse.call(section.subsections)
+            return found if found
+          end
+          nil
+        end
+        recurse.call(@sections)
+      end
+
+      # Convert the model to a JSON string. Output matches Python's
+      # ``json.dumps(..., indent=2)`` byte-for-byte, with one
+      # special case: an empty model serializes to ``"[]"`` (Ruby's
+      # default ``JSON.pretty_generate([])`` emits ``"[\n\n]"``).
+      def to_json(*_args)
+        return '[]' if @sections.empty?
+
+        JSON.pretty_generate(@sections.map(&:to_h))
+      end
+
+      # Convert the model to a YAML string. Output matches Python's
+      # ``yaml.dump(..., default_flow_style=False, sort_keys=False)``
+      # byte-for-byte. Ruby's ``YAML.dump`` prepends ``---\n``; we strip
+      # it. The empty-list case (Ruby emits ``--- []\n``) is normalised
+      # to Python's ``[]\n``.
+      def to_yaml
+        return "[]\n" if @sections.empty?
+
+        yaml = YAML.dump(@sections.map(&:to_h))
+        yaml.sub(/\A---\s*\n/, '')
+      end
+
+      # Convert the model to an Array of Hash section descriptors.
+      # Mirrors Python's ``PromptObjectModel.to_dict`` (Ruby idiom uses
+      # ``to_h``).
+      def to_h
+        @sections.map(&:to_h)
+      end
+
+      # Render the entire model as Markdown. Output is byte-for-byte
+      # identical to Python's ``PromptObjectModel.render_markdown``.
+      def render_markdown
+        any_section_numbered = @sections.any? { |s| s.numbered }
+
+        if @debug
+          warn "Any section numbered: #{any_section_numbered}"
+          @sections.each_with_index do |section, idx|
+            warn "Section #{idx + 1}: #{section.title}, numbered=#{section.numbered}"
+          end
+        end
+
+        md = []
+        section_counter = 0
+        @sections.each_with_index do |section, idx|
+          if !section.title.nil?
+            section_counter += 1
+            section_number =
+              if any_section_numbered && section.numbered != false
+                [section_counter]
+              else
+                []
+              end
+          else
+            section_number = []
+          end
+
+          if @debug
+            warn "Rendering section #{idx}: #{section.title} with section_number=#{section_number.inspect}"
+          end
+
+          md << section.render_markdown(section_number: section_number)
+        end
+
+        md.join("\n")
+      end
+
+      # Render the entire model as XML. Output is byte-for-byte identical
+      # to Python's ``PromptObjectModel.render_xml``.
+      def render_xml
+        xml = ['<?xml version="1.0" encoding="UTF-8"?>', '<prompt>']
+        any_section_numbered = @sections.any? { |s| s.numbered }
+
+        section_counter = 0
+        @sections.each do |section|
+          if !section.title.nil?
+            section_counter += 1
+            section_number =
+              if any_section_numbered && section.numbered != false
+                [section_counter]
+              else
+                []
+              end
+          else
+            section_number = []
+          end
+
+          xml << section.render_xml(indent: 1, section_number: section_number)
+        end
+
+        xml << '</prompt>'
+        xml.join("\n")
+      end
+
+      # Add another PromptObjectModel as a subsection of an existing
+      # section identified either by title or by Section reference.
+      #
+      # Mirrors Python's
+      # ``PromptObjectModel.add_pom_as_subsection(target, pom_to_add)``.
+      def add_pom_as_subsection(target, pom_to_add)
+        case target
+        when String
+          target_section = find_section(target)
+          raise ArgumentError, "No section with title '#{target}' found." if target_section.nil?
+        when Section
+          target_section = target
+        else
+          raise TypeError, 'Target must be a String or a Section object.'
+        end
+
+        pom_to_add.sections.each do |section|
+          target_section.subsections << section
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/pom/section.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module SignalWire
+  module POM
+    # Represents a section in the Prompt Object Model.
+    #
+    # Each section contains a title, optional body text, optional bullet
+    # points, and can have any number of nested subsections.
+    #
+    # Mirrors Python's ``signalwire.pom.pom.Section`` exactly. See
+    # ``signalwire-python/signalwire/signalwire/pom/pom.py`` for the
+    # source-of-truth specification; rendering output (markdown / XML /
+    # JSON / YAML) must match Python byte-for-byte so cross-language POM
+    # documents are interoperable.
+    #
+    # Attributes:
+    # * +title+ — the name of the section.
+    # * +body+  — a paragraph of text associated with the section.
+    # * +bullets+ — bullet-pointed items (Array<String>).
+    # * +subsections+ — nested Section objects.
+    # * +numbered+ — whether this section should be numbered.
+    # * +numbered_bullets+ — whether bullets should be numbered (rendered
+    #   to/from the JSON/YAML key +numberedBullets+ for Python parity).
+    class Section
+      attr_accessor :title, :body, :bullets, :subsections, :numbered, :numbered_bullets
+
+      # Construct a Section.
+      #
+      # All arguments after +title+ are keyword arguments mirroring the
+      # Python ``Section.__init__`` signature. ``numbered_bullets`` is
+      # snake_case in Ruby; the camelCase ``numberedBullets`` form used
+      # by Python's JSON/YAML serialization is preserved on the wire.
+      def initialize(title = nil, body: '', bullets: nil, numbered: nil, numbered_bullets: false)
+        @title = title
+
+        unless body.is_a?(String)
+          raise TypeError,
+                "body must be a string, not #{body.class.name}. " \
+                'If you meant to pass a list of bullet points, use bullets parameter instead.'
+        end
+        @body = body
+
+        if !bullets.nil? && !bullets.is_a?(Array)
+          raise TypeError, "bullets must be an Array or nil, not #{bullets.class.name}"
+        end
+
+        @bullets = bullets || []
+        @subsections = []
+        @numbered = numbered
+        @numbered_bullets = numbered_bullets
+      end
+
+      # Add or replace the body text for this section. Mirrors Python's
+      # ``Section.add_body`` (which is documented to "Add or replace").
+      def add_body(body)
+        unless body.is_a?(String)
+          raise TypeError, "body must be a string, not #{body.class.name}"
+        end
+
+        @body = body
+      end
+
+      # Append bullet points to this section. Does not replace existing
+      # bullets — mirrors Python's ``self.bullets.extend(bullets)``.
+      def add_bullets(bullets)
+        unless bullets.is_a?(Array)
+          raise TypeError, "bullets must be an Array, not #{bullets.class.name}"
+        end
+
+        @bullets.concat(bullets)
+      end
+
+      # Add a subsection to this section, returning the new Section.
+      #
+      # Raises ArgumentError when +title+ is nil (Python raises
+      # ``ValueError("Subsections must have a title")``; Ruby idiom
+      # is ArgumentError for invalid arguments).
+      def add_subsection(title, body: '', bullets: nil, numbered: false, numbered_bullets: false)
+        raise ArgumentError, 'Subsections must have a title' if title.nil?
+
+        sub = Section.new(title, body: body, bullets: bullets || [],
+                                 numbered: numbered, numbered_bullets: numbered_bullets)
+        @subsections << sub
+        sub
+      end
+
+      # Convert the section to a Hash representation suitable for JSON or
+      # YAML serialization. Keys are emitted in the same order as Python
+      # so cross-port string comparisons line up.
+      def to_h
+        data = {}
+        data['title'] = @title unless @title.nil?
+        data['body'] = @body if @body && !@body.empty?
+        data['bullets'] = @bullets if @bullets && !@bullets.empty?
+        data['subsections'] = @subsections.map(&:to_h) if @subsections && !@subsections.empty?
+        data['numbered'] = @numbered if @numbered
+        data['numberedBullets'] = @numbered_bullets if @numbered_bullets
+        data
+      end
+
+      # Render this section and all its subsections as Markdown. The
+      # output is byte-for-byte identical to Python's
+      # ``Section.render_markdown``.
+      def render_markdown(level: 2, section_number: nil)
+        md = []
+        section_number = [] if section_number.nil?
+
+        unless @title.nil?
+          prefix = ''
+          prefix = "#{section_number.join('.')}. " unless section_number.empty?
+          md << "#{'#' * level} #{prefix}#{@title}\n"
+        end
+
+        md << "#{@body}\n" if @body && !@body.empty?
+
+        @bullets.each_with_index do |bullet, idx|
+          if @numbered_bullets
+            md << "#{idx + 1}. #{bullet}"
+          else
+            md << "- #{bullet}"
+          end
+        end
+
+        md << '' unless @bullets.empty?
+
+        any_subsection_numbered = @subsections.any? { |sub| sub.numbered }
+
+        @subsections.each_with_index do |subsection, idx|
+          if !@title.nil? || !section_number.empty?
+            new_section_number =
+              if any_subsection_numbered && subsection.numbered != false
+                section_number + [idx + 1]
+              else
+                section_number
+              end
+            next_level = level + 1
+          else
+            new_section_number = section_number
+            next_level = level
+          end
+
+          md << subsection.render_markdown(level: next_level, section_number: new_section_number)
+        end
+
+        md.join("\n")
+      end
+
+      # Render this section and all its subsections as XML. Output is
+      # byte-for-byte identical to Python's ``Section.render_xml``.
+      def render_xml(indent: 0, section_number: nil)
+        indent_str = '  ' * indent
+        xml = []
+        section_number = [] if section_number.nil?
+
+        xml << "#{indent_str}<section>"
+
+        unless @title.nil?
+          prefix = ''
+          prefix = "#{section_number.join('.')}. " unless section_number.empty?
+          xml << "#{indent_str}  <title>#{prefix}#{@title}</title>"
+        end
+
+        xml << "#{indent_str}  <body>#{@body}</body>" if @body && !@body.empty?
+
+        if @bullets && !@bullets.empty?
+          xml << "#{indent_str}  <bullets>"
+          @bullets.each_with_index do |bullet, idx|
+            if @numbered_bullets
+              xml << "#{indent_str}    <bullet id=\"#{idx + 1}\">#{bullet}</bullet>"
+            else
+              xml << "#{indent_str}    <bullet>#{bullet}</bullet>"
+            end
+          end
+          xml << "#{indent_str}  </bullets>"
+        end
+
+        if @subsections && !@subsections.empty?
+          xml << "#{indent_str}  <subsections>"
+          any_subsection_numbered = @subsections.any? { |sub| sub.numbered }
+
+          @subsections.each_with_index do |subsection, idx|
+            if !@title.nil? || !section_number.empty?
+              new_section_number =
+                if any_subsection_numbered && subsection.numbered != false
+                  section_number + [idx + 1]
+                else
+                  section_number
+                end
+            else
+              new_section_number = section_number
+            end
+            xml << subsection.render_xml(indent: indent + 2, section_number: new_section_number)
+          end
+          xml << "#{indent_str}  </subsections>"
+        end
+
+        xml << "#{indent_str}</section>"
+        xml.join("\n")
+      end
+    end
+  end
+end

data/lib/signalwire/prefabs/concierge.rb

@@ -0,0 +1,92 @@
+# 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 SignalWire
+  module Prefabs
+    # Prefab agent for providing virtual concierge services.
+    #
+    #   agent = Concierge.new(
+    #     venue_name: 'Grand Hotel',
+    #     services: ['room service', 'spa bookings'],
+    #     amenities: { 'pool' => { 'hours' => '7 AM - 10 PM', 'location' => '2nd Floor' } }
+    #   )
+    #
+    class Concierge
+      attr_reader :venue_name, :services, :amenities, :name, :route
+
+      def initialize(venue_name:, services:, amenities:, hours_of_operation: nil,
+                     special_instructions: nil, welcome_message: nil,
+                     name: 'concierge', route: '/concierge', **_opts)
+        @venue_name     = venue_name
+        @services       = services || []
+        @amenities      = (amenities || {}).transform_keys(&:to_s)
+        @hours          = hours_of_operation
+        @instructions   = special_instructions || []
+        @welcome        = welcome_message || "Welcome to #{venue_name}! How can I assist you today?"
+        @name  = name
+        @route = route
+      end
+
+      def tools
+        %w[get_amenity_info get_service_info]
+      end
+
+      def prompt_sections
+        amenity_bullets = @amenities.map { |k, v| "#{k}: #{v.is_a?(Hash) ? v.map { |a, b| "#{a}: #{b}" }.join(', ') : v}" }
+        service_bullets = @services.map { |s| s.to_s }
+
+        sections = [
+          {
+            'title' => "#{@venue_name} Concierge",
+            'body' => @welcome,
+            'bullets' => service_bullets + amenity_bullets
+          }
+        ]
+
+        if @hours
+          sections << {
+            'title' => 'Hours of Operation',
+            'body' => @hours.is_a?(Hash) ? @hours.map { |k, v| "#{k}: #{v}" }.join('; ') : @hours.to_s
+          }
+        end
+
+        sections
+      end
+
+      def global_data
+        {
+          'venue_name' => @venue_name,
+          'services'   => @services,
+          'amenities'  => @amenities
+        }
+      end
+
+      def handle_amenity_info(args, _raw_data)
+        amenity = (args['amenity'] || '').downcase
+        info = @amenities.find { |k, _v| k.downcase == amenity }&.last
+        if info
+          detail = info.is_a?(Hash) ? info.map { |k, v| "#{k}: #{v}" }.join(', ') : info.to_s
+          Swaig::FunctionResult.new("#{amenity.capitalize}: #{detail}")
+        else
+          Swaig::FunctionResult.new("I don't have information about '#{amenity}'. Available amenities: #{@amenities.keys.join(', ')}")
+        end
+      end
+
+      def handle_service_info(args, _raw_data)
+        service = (args['service'] || '').downcase
+        match = @services.find { |s| s.downcase.include?(service) }
+        if match
+          Swaig::FunctionResult.new("#{match} is available at #{@venue_name}.")
+        else
+          Swaig::FunctionResult.new("Available services: #{@services.join(', ')}")
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/prefabs/faq_bot.rb

@@ -0,0 +1,67 @@
+# 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 SignalWire
+  module Prefabs
+    # Prefab agent for answering frequently asked questions.
+    #
+    #   agent = FaqBot.new(
+    #     faqs: [
+    #       { 'question' => 'What is SignalWire?', 'answer' => 'A cloud communications platform.' }
+    #     ]
+    #   )
+    #
+    class FaqBot
+      attr_reader :faqs, :name, :route
+
+      def initialize(faqs:, suggest_related: true, persona: nil,
+                     name: 'faq_bot', route: '/faq', **_opts)
+        raise ArgumentError, 'faqs must be a non-empty Array' unless faqs.is_a?(Array) && !faqs.empty?
+
+        @faqs            = faqs.map { |f| f.transform_keys(&:to_s) }
+        @suggest_related = suggest_related
+        @persona         = persona || 'You are a helpful FAQ bot that provides accurate answers to common questions.'
+        @name  = name
+        @route = route
+      end
+
+      def tools
+        %w[search_faq]
+      end
+
+      def prompt_sections
+        bullets = @faqs.map { |f| "Q: #{f['question']}" }
+        [
+          {
+            'title' => 'FAQ Bot',
+            'body' => @persona,
+            'bullets' => bullets
+          }
+        ]
+      end
+
+      def global_data
+        {
+          'faqs' => @faqs,
+          'suggest_related' => @suggest_related
+        }
+      end
+
+      def handle_search(args, _raw_data)
+        query = (args['query'] || '').downcase
+        match = @faqs.find { |f| f['question'].downcase.include?(query) || query.include?(f['question'].downcase) }
+        if match
+          Swaig::FunctionResult.new(match['answer'])
+        else
+          Swaig::FunctionResult.new("I don't have a specific answer for that. Here are the topics I can help with: #{@faqs.map { |f| f['question'] }.join('; ')}")
+        end
+      end
+    end
+  end
+end