ask-core 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9500049544d02d1e7a13d939c7e1bf7a532d5d45682302e9666d0e6d63b4488
-  data.tar.gz: 9f249f01b749bda7700131ce107bc0d312477849dd6006e6a3e2ca4b814e5b31
+  metadata.gz: 07cf04e5db86d1aa2ed63aad10f47608619f320e00af7d730b0cd5b950f347ff
+  data.tar.gz: 99ef57dd70f631d3bfa024eb03b63279df7d251cab2afa68988cecd66140bc92
 SHA512:
-  metadata.gz: b5ac63d0cf689c3bc22fb4ad4bac215fbc9aa022b74e63b453a87ab7c7d7a5c781fff2fc2c9b694d6fb9e669c858ec0f81c13bf21fac50753654f8ebed2c3c58
-  data.tar.gz: 23a06ce41d67eee03322691919623dfa888e301d4607c9812dbb85a2c46ace50b16d99aa9d1c1ba879104f84f74981bbc9cf8d5c985132331211c6bcbd00509a
+  metadata.gz: 62ca489c64a4b6ef8e89603e9a4d0442d7b9a4c5c54e61cbb46dc3803046d1b120e2b5e061c6826ee0ad1b2fc8cec9618f6fe3ec5587970efdd99a29d46b89af
+  data.tar.gz: c228dc1e27f86a24eddc30b60e928dbdf2ca59ee45feb441954b07c91787ba55c825d3d537fb6cca7fba312908100d220ab63ab283d5b6736bb0fe60d1248ba3

data/CHANGELOG.md

@@ -1,8 +1,44 @@
-## [0.6.0] — 2026-07-26
+## [0.7.0] — 2026-07-26
 
 ### Added
 
-- **`Ask::Document`** — a new frozen value object representing text content with metadata. Used as the universal currency in RAG pipelines: loaded by document loaders, split by text splitters, embedded and retrieved by vector stores. Immutable, equality-checked by content+metadata, and JSON-serializable.
+- **Multi-modal content types** — `Ask::Content` module with `Text`, `Image`, `Audio`, `Video`, and `File` value objects. Each is frozen, comparable, and serializable via `#to_h`.
+
+  ```ruby
+  Ask::Content::Text.new("What's in this image?")
+  Ask::Content::Image.new(url: "https://example.com/photo.jpg", mime_type: "image/jpeg")
+  Ask::Content::Audio.new(url: "https://example.com/audio.mp3", mime_type: "audio/mpeg")
+  Ask::Content::Video.new(url: "https://example.com/video.mp4", mime_type: "video/mp4")
+  Ask::Content::File.new(data: "file content", mime_type: "text/plain", filename: "notes.txt")
+  ```
+
+- **`Ask::Message#content_blocks`** — `Message` now accepts an Array of `Ask::Content` objects as `content:`. The `#content` accessor still returns the plain text for backward compatibility. `#content_blocks` returns the structured blocks, `#multimodal?` checks for non-text blocks.
+
+  ```ruby
+  msg = Ask::Message.new(role: :user, content: [
+    Ask::Content::Text.new("What's in this image?"),
+    Ask::Content::Image.new(url: "https://example.com/photo.jpg", mime_type: "image/jpeg")
+  ])
+  msg.multimodal?      # => true
+  msg.content_blocks   # => [Text("What's in this image?"), Image(...)]
+  msg.content          # => "What's in this image?"
+  ```
+
+- **`Ask::Conversation`** — `#user` and `#system` now accept arrays of content blocks directly. `#dup` correctly handles content blocks.
+
+- **`Ask::Content::Block`** — shared base module for all content types. Content blocks respond to `#to_h` for serialization.
+
+### Changed
+
+- `Ask::Message#to_h` now serializes content blocks as an array of typed hashes (`{ type: "text", text: "..." }`, `{ type: "image", url: "...", mime_type: "..." }`, etc.) when the message has content_blocks.
+- `Ask::Message#inspect` updated to show `multimodal`, `rich`, or `text` label.
+
+### Tested
+
+- 311 tests, 611 assertions, 0 failures
+- 69 new tests for Content types, multi-modal messages, serialization, equality, and Conversation integration
+
+## [0.6.0] — 2026-07-26: loaded by document loaders, split by text splitters, embedded and retrieved by vector stores. Immutable, equality-checked by content+metadata, and JSON-serializable.
 
   ```ruby
   doc = Ask::Document.new(

data/lib/ask/content.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Ask
+  # Content types for multi-modal messages.
+  #
+  # These are frozen value objects representing different kinds of content
+  # that can appear in an {Ask::Message}. A message's {Message#content_blocks
+  # content_blocks} may contain multiple content objects of different types,
+  # allowing text, images, audio, video, and files to be interleaved naturally.
+  #
+  # All content types are frozen value objects with structural equality.
+  # They carry the minimum fields needed for provider-agnostic use; each
+  # provider serializes them to its own wire format.
+  #
+  # @example Text
+  #   Ask::Content::Text.new("What's in this image?")
+  #
+  # @example Image from URL
+  #   Ask::Content::Image.new(url: "https://example.com/photo.jpg",
+  #                           mime_type: "image/jpeg")
+  #
+  # @example Multi-modal message
+  #   msg = Ask::Message.new(role: :user, content: [
+  #     Ask::Content::Text.new("What's in this image?"),
+  #     Ask::Content::Image.new(url: "https://example.com/photo.jpg",
+  #                             mime_type: "image/jpeg")
+  #   ])
+  #
+  module Content
+    # Base module for all content types.
+    module Block
+      def to_h
+        raise NotImplementedError
+      end
+
+      def inspect
+        "#<#{self.class.name}#{inspect_fields}>"
+      end
+
+      private
+
+      def inspect_fields
+        ""
+      end
+    end
+
+    # A text block within a multi-modal message.
+    class Text
+      include Block
+
+      # @return [String] the text content
+      attr_reader :text
+
+      # @param text [String] the text content
+      def initialize(text)
+        @text = text
+        freeze
+      end
+
+      def ==(other)
+        other.is_a?(Text) && @text == other.text
+      end
+      alias eql? ==
+
+      def hash
+        @text.hash
+      end
+
+      def to_h
+        { type: "text", text: @text }
+      end
+
+      private
+
+      def inspect_fields
+        " #{@text.inspect}"
+      end
+    end
+
+    # Base class for media content types (Image, Audio, Video).
+    # All have optional +url+, +base64+, +mime_type+, and +file_id+ fields.
+    class Media
+      include Block
+
+      # @return [String, nil] URL of the media
+      attr_reader :url
+
+      # @return [String, nil] Base64-encoded media data
+      attr_reader :base64
+
+      # @return [String, nil] MIME type
+      attr_reader :mime_type
+
+      # @return [String, nil] Provider-managed file ID
+      attr_reader :file_id
+
+      # @param url [String, nil] URL of the media
+      # @param base64 [String, nil] Base64-encoded data
+      # @param mime_type [String, nil] MIME type
+      # @param file_id [String, nil] Provider-managed file ID
+      def initialize(url: nil, base64: nil, mime_type: nil, file_id: nil)
+        @url = url
+        @base64 = base64
+        @mime_type = mime_type
+        @file_id = file_id
+        freeze
+      end
+
+      def ==(other)
+        other.is_a?(Media) && @url == other.url && @base64 == other.base64 &&
+          @mime_type == other.mime_type && @file_id == other.file_id
+      end
+      alias eql? ==
+
+      def hash
+        [@url, @base64, @mime_type, @file_id].hash
+      end
+
+      def to_h
+        h = { type: media_type }
+        h[:url] = @url if @url
+        h[:base64] = @base64 if @base64
+        h[:mime_type] = @mime_type if @mime_type
+        h[:file_id] = @file_id if @file_id
+        h
+      end
+
+      private
+
+      def media_type
+        raise NotImplementedError
+      end
+    end
+
+    # An image block within a multi-modal message.
+    class Image < Media
+      private
+
+      def media_type
+        "image"
+      end
+    end
+
+    # An audio block within a multi-modal message.
+    class Audio < Media
+      private
+
+      def media_type
+        "audio"
+      end
+    end
+
+    # A video block within a multi-modal message.
+    class Video < Media
+      private
+
+      def media_type
+        "video"
+      end
+    end
+
+    # An inline file block within a multi-modal message.
+    class File
+      include Block
+
+      # @return [String] the file content
+      attr_reader :data
+
+      # @return [String, nil] MIME type
+      attr_reader :mime_type
+
+      # @return [String, nil] original filename
+      attr_reader :filename
+
+      # @param data [String] the file content
+      # @param mime_type [String, nil] MIME type
+      # @param filename [String, nil] original filename
+      def initialize(data:, mime_type: nil, filename: nil)
+        @data = data
+        @mime_type = mime_type
+        @filename = filename
+        freeze
+      end
+
+      def ==(other)
+        other.is_a?(File) && @data == other.data &&
+          @mime_type == other.mime_type && @filename == other.filename
+      end
+      alias eql? ==
+
+      def hash
+        [@data, @mime_type, @filename].hash
+      end
+
+      def to_h
+        { type: "file", data: @data, mime_type: @mime_type, filename: @filename }
+      end
+    end
+  end
+end

data/lib/ask/conversation.rb

@@ -9,9 +9,16 @@ module Ask
     # @return [Symbol] message role (:system, :user, :assistant, :tool)
     attr_reader :role
 
-    # @return [String, nil] message text content
+    # @return [String, nil] message text content. For multi-modal messages
+    #   this is the concatenation of all text blocks. See {#content_blocks}
+    #   for the full structured content.
     attr_reader :content
 
+    # @return [Array<Ask::Content::Text, Ask::Content::Image, ...>, nil]
+    #   structured content blocks for multi-modal messages. +nil+ when the
+    #   message was created with a plain string +content:+ (backward compatible).
+    attr_reader :content_blocks
+
     # @return [String, nil] optional participant name (for multi-agent scenarios)
     attr_reader :name
 
@@ -24,17 +31,45 @@ module Ask
     # @return [Hash] arbitrary metadata attached to this message
     attr_reader :metadata
 
+    # Create a new message.
+    #
+    # @param role [Symbol, String] message role
+    # @param content [String, Array<Ask::Content>, nil] message text or array
+    #   of content blocks. When an Array is given, each element must be one of
+    #   the {Ask::Content} types. +content+ will be set to the plain text
+    #   representation; use {#content_blocks} to access the structured blocks.
+    # @param name [String, nil] participant name
+    # @param tool_call_id [String, nil] tool call ID this message responds to
+    # @param tool_calls [Array<Hash>, nil] tool call invocations
+    # @param metadata [Hash] arbitrary metadata
     def initialize(role:, content: nil, name: nil, tool_call_id: nil, tool_calls: nil, metadata: {})
       @role = normalize_role!(role)
-      @content = content
       @name = normalize_name(name)
       @tool_call_id = tool_call_id
       @tool_calls = tool_calls
       @metadata = metadata.dup.freeze
+
+      if content.is_a?(Array)
+        validate_content_blocks!(content)
+        @content_blocks = content.map(&:freeze).freeze
+        @content = extract_text_from_blocks(@content_blocks)
+      else
+        @content = content
+        @content_blocks = nil
+      end
+
       validate!
       freeze
     end
 
+    # @return [Boolean] true if this message contains non-text content blocks
+    #   (images, audio, video, or files).
+    def multimodal?
+      return false unless @content_blocks
+
+      @content_blocks.any? { |b| !b.is_a?(Content::Text) && b.is_a?(Content::Block) }
+    end
+
     # @return [Boolean] true if this message contains tool calls
     def tool_call? = @tool_calls&.any? == true
 
@@ -54,16 +89,24 @@ module Ask
     def tool? = @role == :tool
 
     # Convert to a hash suitable for provider wire format serialization.
-    # Omits nil-valued keys. Tool calls are converted from internal Hash format
-    # ({id => object with .id, .name, .arguments}) to the provider API Array format
-    # ([{id:, type:, function: {name:, arguments:}}]).
+    # For multi-modal messages, +:content+ is an array of content block hashes.
+    # For plain text messages, +:content+ is a string (backward compatible).
+    #
+    # Each content block hash includes a +:type+ key for discrimination.
+    # Providers can use these to build their wire format.
+    #
     # @return [Hash]
     def to_h
       base = { role: @role }
-      base[:content] = @content if @content
       base[:name] = @name if @name
       base[:tool_call_id] = @tool_call_id if @tool_call_id
 
+      if @content_blocks
+        base[:content] = @content_blocks.map(&method(:serialize_content_block))
+      else
+        base[:content] = @content if @content
+      end
+
       if @tool_calls
         base[:tool_calls] = @tool_calls.is_a?(Array) ? @tool_calls : @tool_calls.map do |id_val, tc|
           tc_id = if tc.respond_to?(:id)
@@ -98,27 +141,62 @@ module Ask
       base
     end
 
-    # @return [Boolean] true if role, content, name, and tool metadata all match
+    # @return [Boolean] true if role, content/block, name, and tool metadata all match
     def ==(other)
       return false unless other.is_a?(Message)
 
       @role == other.role && @content == other.content &&
+        @content_blocks == other.content_blocks &&
         @name == other.name && @tool_call_id == other.tool_call_id &&
         @tool_calls == other.tool_calls
     end
     alias eql? ==
 
     def hash
-      [@role, @content, @name, @tool_call_id, @tool_calls].hash
+      [@role, @content, @content_blocks, @name, @tool_call_id, @tool_calls].hash
     end
 
     # @return [String]
     def inspect
-      "#<Ask::Message role=#{@role.inspect} content=#{@content && @content.length > 57 ? @content[0,57].inspect + "..." : @content.inspect}>"
+      label = multimodal? ? "multimodal" : (@content_blocks ? "rich" : "text")
+      preview = if @content_blocks
+        blk = @content_blocks.find { |b| b.is_a?(Content::Text) }
+        blk ? preview_text(blk.text) : label
+      elsif @content
+        @content.length > 57 ? "#{@content[0,57]}..." : @content
+      end
+      "#<Ask::Message role=#{@role.inspect} #{label} #{preview.inspect}>"
+    end
+
+    def preview_text(text)
+      text.length > 57 ? "#{text[0, 57]}..." : text
     end
 
     private
 
+    def serialize_content_block(block)
+      block.respond_to?(:to_h) ? block.to_h : { type: "unknown", data: block.to_s }
+    end
+
+    def validate_content_blocks!(blocks)
+      raise ArgumentError, "Content blocks must be an Array" unless blocks.is_a?(Array)
+      raise ArgumentError, "Content blocks cannot be empty" if blocks.empty?
+
+      blocks.each_with_index do |block, idx|
+        next if block.is_a?(Content::Block)
+
+        raise ArgumentError,
+              "Invalid content block at index #{idx}: " \
+              "expected an Ask::Content type (Text, Image, Audio, Video, or File), " \
+              "got #{block.class}"
+      end
+    end
+
+    def extract_text_from_blocks(blocks)
+      texts = blocks.select { |b| b.is_a?(Content::Text) }.map(&:text)
+      texts.empty? ? nil : texts.join("\n")
+    end
+
     def normalize_role!(role)
       sym = role.to_s.downcase.to_sym
       raise InvalidRole, "Invalid role: #{role.inspect}. Valid: #{VALID_ROLES.join(', ')}" unless VALID_ROLES.include?(sym)
@@ -164,15 +242,23 @@ module Ask
     alias add <<
 
     # Add a system message.
-    # @param text [String] message content
+    # @param text [String, Array<Ask::Content>] message content or content blocks
     # @return [self]
     def system(text, **options)
       self << Message.new(role: :system, content: text, **options)
     end
 
     # Add a user message.
-    # @param text [String] message content
+    # @param text [String, Array<Ask::Content>] message content or content blocks.
+    #   Pass an Array of {Ask::Content} objects for multi-modal messages.
     # @return [self]
+    # @example Plain text
+    #   conv.user("Hello")
+    # @example Multi-modal
+    #   conv.user([
+    #     Ask::Content::Text.new("What's in this image?"),
+    #     Ask::Content::Image.new(url: "https://example.com/photo.jpg", mime_type: "image/jpeg")
+    #   ])
     def user(text, **options)
       self << Message.new(role: :user, content: text, **options)
     end
@@ -260,7 +346,16 @@ module Ask
     # Deep copy of this conversation.
     # @return [Ask::Conversation]
     def dup
-      Conversation.new(@messages.map { |m| Message.new(**m.to_h) })
+      Conversation.new(@messages.map { |m|
+        opts = { role: m.role, name: m.name, tool_call_id: m.tool_call_id,
+                 tool_calls: m.tool_calls, metadata: m.metadata }
+        if m.content_blocks
+          opts[:content] = m.content_blocks.dup
+        else
+          opts[:content] = m.content
+        end
+        Message.new(**opts)
+      })
     end
 
     # @return [String]
@@ -271,7 +366,13 @@ module Ask
     private
 
     def build_message(attrs)
-      attrs.is_a?(Hash) ? Message.new(**attrs) : Message.new(role: :user, content: attrs.to_s)
+      if attrs.is_a?(Hash)
+        Message.new(**attrs)
+      elsif attrs.is_a?(Array)
+        Message.new(role: :user, content: attrs)
+      else
+        Message.new(role: :user, content: attrs.to_s)
+      end
     end
   end
 end

data/lib/ask/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ask
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/ask.rb

@@ -6,6 +6,7 @@ require_relative "ask/version"
 #
 # Ask::Provider is the abstract base class for LLM providers.
 # Ask::Conversation is a message container with role normalization.
+# Ask::Content provides multi-modal content types (Text, Image, Audio, Video, File).
 # Ask::Stream provides streaming primitives for incremental responses.
 # Ask::ModelCatalog resolves model names to provider metadata.
 # Ask::Document is a text+metadata value object for RAG pipelines.
@@ -16,6 +17,7 @@ module Ask
 end
 
 require_relative "ask/errors"
+require_relative "ask/content"
 require_relative "ask/tool_def"
 require_relative "ask/result"
 require_relative "ask/stream"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-core
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -64,6 +64,7 @@ files:
 - LICENSE
 - README.md
 - lib/ask.rb
+- lib/ask/content.rb
 - lib/ask/conversation.rb
 - lib/ask/document.rb
 - lib/ask/errors.rb