prompt_builder 0.1.0

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/prompt_builder/content/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Content
+    # Base class for content objects. Provides polymorphic deserialization
+    # via the +type+ field in the hash representation.
+    class Base
+      # Content type registry for polymorphic dispatch.
+      TYPES = {
+        "input_file" => "InputFile",
+        "input_image" => "InputImage",
+        "input_text" => "InputText",
+        "input_video" => "InputVideo",
+        "output_text" => "OutputText",
+        "reasoning_text" => "ReasoningText",
+        "refusal" => "RefusalContent",
+        "summary_text" => "SummaryText",
+        "text" => "Text"
+      }.freeze
+
+      class << self
+        # Deserialize a content object from a Hash by dispatching on the +type+ field.
+        #
+        # @param hash [Hash] a Hash with string keys including a +"type"+ field
+        # @return [Content::Base] the deserialized content object
+        # @raise [InvalidItemError] if the type is unknown
+        def from_h(hash)
+          type = hash["type"]
+          class_name = TYPES[type]
+          raise InvalidItemError, "Unknown content type: #{type.inspect}" unless class_name
+
+          Content.const_get(class_name).from_h(hash)
+        end
+      end
+
+      # Serialize the content object to a Hash with string keys.
+      #
+      # @return [Hash] the hash representation
+      def to_h
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/prompt_builder/content/input_file.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Content
+    # Represents file input content in a message.
+    class InputFile < Base
+      # @return [String, nil] the file URL (may be a data URL)
+      attr_reader :url
+
+      # @return [String, nil] the filename
+      attr_reader :filename
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      class << self
+        # Deserialize an InputFile from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [InputFile]
+        def from_h(hash)
+          new(
+            url: hash["url"],
+            filename: hash["filename"],
+            **hash.except("type", "url", "filename").transform_keys(&:to_sym)
+          )
+        end
+      end
+
+      # Create a new InputFile content object.
+      #
+      # @param url [String, nil] the file URL or data URL
+      # @param filename [String, nil] the filename
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(url: nil, filename: nil, **extra)
+        @filename = filename&.to_s
+        @extra = normalize_extra_kwargs(extra)
+        @url = url&.to_s
+      end
+
+      # Serialize to a Hash with string keys. Nil values are omitted.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "input_file"}
+        h["url"] = @url if @url
+        h["filename"] = @filename if @filename
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+
+      private
+
+      def normalize_extra_kwargs(extra)
+        nested = extra.delete(:extra)
+        nested = extra.delete("extra") if nested.nil?
+        nested_hash = nested.is_a?(Hash) ? nested : {}
+
+        PromptBuilder.jsonify(nested_hash.merge(extra)).transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/prompt_builder/content/input_image.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Content
+    # Represents image input content in a message.
+    class InputImage < Base
+      # @return [String, nil] the image URL (may be a fully qualified URL or a
+      #   base64-encoded data URL such as +"data:image/png;base64,..."+ )
+      attr_reader :url
+
+      # @return [String, nil] the detail level for the image
+      attr_reader :detail
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      class << self
+        # Deserialize an InputImage from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [InputImage]
+        def from_h(hash)
+          new(
+            url: hash["url"],
+            detail: hash["detail"],
+            **hash.except("type", "url", "detail").transform_keys(&:to_sym)
+          )
+        end
+      end
+
+      # Create a new InputImage content object.
+      #
+      # @param url [String, nil] the image URL or data URL
+      # @param detail [String, nil] the image detail level
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(url: nil, detail: nil, **extra)
+        @detail = detail&.to_s
+        @extra = normalize_extra_kwargs(extra)
+        @url = url&.to_s
+      end
+
+      # Serialize to a Hash with string keys. Nil values are omitted.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "input_image"}
+        h["url"] = @url if @url
+        h["detail"] = @detail if @detail
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+
+      private
+
+      def normalize_extra_kwargs(extra)
+        nested = extra.delete(:extra)
+        nested = extra.delete("extra") if nested.nil?
+        nested_hash = nested.is_a?(Hash) ? nested : {}
+
+        PromptBuilder.jsonify(nested_hash.merge(extra)).transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/prompt_builder/content/input_text.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Content
+    # Represents text input content in a message.
+    class InputText < Base
+      # @return [String] the text content
+      attr_reader :text
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new InputText content object.
+      #
+      # @param text [String] the text content
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(text:, **extra)
+        @text = text&.to_s
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize an InputText from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [InputText]
+        def from_h(hash)
+          new(text: hash["text"], **hash.except("type", "text").transform_keys(&:to_sym))
+        end
+      end
+
+      # Serialize to a Hash with string keys.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "input_text", "text" => @text}
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end

data/lib/prompt_builder/content/input_video.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Content
+    # Represents video input content in a message.
+    class InputVideo < Base
+      # @return [String, nil] the video URL
+      attr_reader :url
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      class << self
+        # Deserialize an InputVideo from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [InputVideo]
+        def from_h(hash)
+          new(url: hash["url"], **hash.except("type", "url").transform_keys(&:to_sym))
+        end
+      end
+
+      # Create a new InputVideo content object.
+      #
+      # @param url [String, nil] the video URL
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(url: nil, **extra)
+        @url = url&.to_s
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      # Serialize to a Hash with string keys. Nil values are omitted.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "input_video"}
+        h["url"] = @url if @url
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end

data/lib/prompt_builder/content/output_text.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Content
+    # Represents text output content in an assistant message.
+    class OutputText < Base
+      # @return [String] the text content
+      attr_reader :text
+
+      # @return [Array<Hash>] annotations on the text
+      attr_reader :annotations
+
+      # @return [Array<Hash>] token log probabilities for the text
+      attr_reader :logprobs
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new OutputText content object.
+      #
+      # @param text [String] the text content
+      # @param annotations [Array<Hash>] annotations on the text
+      # @param logprobs [Array<Hash>] token log probabilities on the text
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(text:, annotations: [], logprobs: [], **extra)
+        @text = text&.to_s
+        @annotations = PromptBuilder.jsonify(annotations)
+        @logprobs = PromptBuilder.jsonify(logprobs)
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize an OutputText from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [OutputText]
+        def from_h(hash)
+          new(
+            text: hash["text"],
+            annotations: hash["annotations"] || [],
+            logprobs: hash["logprobs"] || [],
+            **hash.except("type", "text", "annotations", "logprobs").transform_keys(&:to_sym)
+          )
+        end
+      end
+
+      # Serialize to a Hash with string keys. Empty annotations are omitted.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "output_text", "text" => @text}
+        h["annotations"] = @annotations unless @annotations.empty?
+        h["logprobs"] = @logprobs unless @logprobs.empty?
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end

data/lib/prompt_builder/content/reasoning_text.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Content
+    # Represents reasoning text content from the model.
+    class ReasoningText < Base
+      # @return [String] the reasoning text content
+      attr_reader :text
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new ReasoningText content object.
+      #
+      # @param text [String] the reasoning text content
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(text:, **extra)
+        @text = text&.to_s
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize a ReasoningText from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [ReasoningText]
+        def from_h(hash)
+          new(text: hash["text"], **hash.except("type", "text").transform_keys(&:to_sym))
+        end
+      end
+
+      # Serialize to a Hash with string keys.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "reasoning_text", "text" => @text}
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end

data/lib/prompt_builder/content/refusal_content.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Content
+    # Represents a refusal content block returned by the model.
+    class RefusalContent < Base
+      # @return [String] the refusal message
+      attr_reader :refusal
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new RefusalContent object.
+      #
+      # @param refusal [String] the refusal message
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(refusal:, **extra)
+        @refusal = refusal&.to_s
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize a RefusalContent from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [RefusalContent]
+        def from_h(hash)
+          new(refusal: hash["refusal"], **hash.except("type", "refusal").transform_keys(&:to_sym))
+        end
+      end
+
+      # Serialize to a Hash with string keys.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "refusal", "refusal" => @refusal}
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end

data/lib/prompt_builder/content/summary_text.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Content
+    # Represents a summary text content from the model's reasoning.
+    class SummaryText < Base
+      # @return [String] the summary text content
+      attr_reader :text
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new SummaryText content object.
+      #
+      # @param text [String] the summary text content
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(text:, **extra)
+        @text = text&.to_s
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize a SummaryText from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [SummaryText]
+        def from_h(hash)
+          new(text: hash["text"], **hash.except("type", "text").transform_keys(&:to_sym))
+        end
+      end
+
+      # Serialize to a Hash with string keys.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "summary_text", "text" => @text}
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end

data/lib/prompt_builder/content/text.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Content
+    # Represents generic text content in a message or reasoning item.
+    class Text < Base
+      # @return [String] the text content
+      attr_reader :text
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new Text content object.
+      #
+      # @param text [String] the text content
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(text:, **extra)
+        @text = text&.to_s
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize a Text from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [Text]
+        def from_h(hash)
+          new(text: hash["text"], **hash.except("type", "text").transform_keys(&:to_sym))
+        end
+      end
+
+      # Serialize to a Hash with string keys.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "text", "text" => @text}
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end

data/lib/prompt_builder/content.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Content
+    autoload :Base, File.expand_path("content/base", __dir__)
+    autoload :InputFile, File.expand_path("content/input_file", __dir__)
+    autoload :InputImage, File.expand_path("content/input_image", __dir__)
+    autoload :InputText, File.expand_path("content/input_text", __dir__)
+    autoload :InputVideo, File.expand_path("content/input_video", __dir__)
+    autoload :OutputText, File.expand_path("content/output_text", __dir__)
+    autoload :ReasoningText, File.expand_path("content/reasoning_text", __dir__)
+    autoload :RefusalContent, File.expand_path("content/refusal_content", __dir__)
+    autoload :SummaryText, File.expand_path("content/summary_text", __dir__)
+    autoload :Text, File.expand_path("content/text", __dir__)
+
+    class << self
+      # Construct a base64-encoded data URL from raw binary data and a content type.
+      # Delegates to {PromptBuilder.data_url}.
+      #
+      # @param data [String] the raw binary data
+      # @param content_type [String] the MIME content type (e.g. "image/png", "application/pdf")
+      # @return [String] a data URL in the form "data:<content_type>;base64,<encoded_data>"
+      def data_url(data, content_type)
+        PromptBuilder.data_url(data, content_type)
+      end
+    end
+  end
+end

data/lib/prompt_builder/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  # Base error class for all PromptBuilder errors.
+  class Error < StandardError; end
+
+  # Raised when a format conversion is not supported.
+  class UnsupportedFormatError < Error; end
+
+  # Raised when an invalid item type is encountered.
+  class InvalidItemError < Error; end
+
+  # Raised when a tool is not found in the registry.
+  class ToolNotFoundError < Error; end
+
+  # Raised when an operation is invalid for the current session state.
+  class InvalidStateError < Error; end
+end

data/lib/prompt_builder/items/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Items
+    # Base class for conversation items. Provides polymorphic deserialization
+    # via the +type+ field in the hash representation.
+    class Base
+      # Item type registry for polymorphic dispatch.
+      TYPES = {
+        "compaction" => "Compaction",
+        "function_call" => "FunctionCall",
+        "function_call_output" => "FunctionCallOutput",
+        "item_reference" => "ItemReference",
+        "message" => "Message",
+        "reasoning" => "Reasoning"
+      }.freeze
+
+      class << self
+        # Deserialize an item from a Hash by dispatching on the +type+ field.
+        #
+        # @param hash [Hash] a Hash with string keys including a +"type"+ field
+        # @return [Items::Base] the deserialized item
+        # @raise [InvalidItemError] if the type is unknown
+        def from_h(hash)
+          type = hash["type"]
+          class_name = TYPES[type]
+          raise InvalidItemError, "Unknown item type: #{type.inspect}" unless class_name
+
+          Items.const_get(class_name).from_h(hash)
+        end
+      end
+
+      # Serialize the item to a Hash with string keys.
+      #
+      # @return [Hash] the hash representation
+      def to_h
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/prompt_builder/items/compaction.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Items
+    # Represents a compaction item that summarizes earlier conversation history.
+    class Compaction < Base
+      # @return [String, nil] the compaction item identifier
+      attr_reader :id
+
+      # @return [String, nil] encrypted compacted content
+      attr_reader :encrypted_content
+
+      # @return [String, nil] who created the compaction (e.g. "user" or "assistant")
+      attr_reader :created_by
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new Compaction item.
+      #
+      # @param id [String, nil] the compaction item identifier
+      # @param encrypted_content [String, nil] encrypted compacted content
+      # @param created_by [String, nil] who created the compaction
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(id: nil, encrypted_content: nil, created_by: nil, **extra)
+        @id = id&.to_s
+        @encrypted_content = encrypted_content&.to_s
+        @created_by = created_by&.to_s
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize a Compaction item from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [Compaction]
+        def from_h(hash)
+          new(
+            id: hash["id"],
+            encrypted_content: hash["encrypted_content"],
+            created_by: hash["created_by"],
+            **hash.except("type", "id", "encrypted_content", "created_by").transform_keys(&:to_sym)
+          )
+        end
+      end
+
+      # Serialize to a Hash with string keys. Nil values are omitted.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "compaction"}
+        h["id"] = @id if @id
+        h["encrypted_content"] = @encrypted_content if @encrypted_content
+        h["created_by"] = @created_by if @created_by
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end