ask-core 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 384e1b71886280e9db2a3a6d737bc8e272522543715a3b307518eb71ab735957
-  data.tar.gz: 8c66d39ca24f2b7fb8aec39aa5855f3862e2f3f7456c619b11c04903cafb4398
+  metadata.gz: 07cf04e5db86d1aa2ed63aad10f47608619f320e00af7d730b0cd5b950f347ff
+  data.tar.gz: 99ef57dd70f631d3bfa024eb03b63279df7d251cab2afa68988cecd66140bc92
 SHA512:
-  metadata.gz: 10ada0c35161dabb17005329f643a7514df4e67922b8b086728b88207afa670eb7d35e4bc5d10378431d8ff732ed4f44ce24806c5872ae43e8f0e5275c5f52b8
-  data.tar.gz: be4235f9c942e894c83e14859835a43b4017815fc68f5dd11edffe60f46c717fa563fe9fdd3c8160d73d485571f3190fa4c18e8c0d862db6e62bf4b197677a41
+  metadata.gz: 62ca489c64a4b6ef8e89603e9a4d0442d7b9a4c5c54e61cbb46dc3803046d1b120e2b5e061c6826ee0ad1b2fc8cec9618f6fe3ec5587970efdd99a29d46b89af
+  data.tar.gz: c228dc1e27f86a24eddc30b60e928dbdf2ca59ee45feb441954b07c91787ba55c825d3d537fb6cca7fba312908100d220ab63ab283d5b6736bb0fe60d1248ba3

data/CHANGELOG.md

@@ -1,3 +1,61 @@
+## [0.7.0] — 2026-07-26
+
+### Added
+
+- **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(
+    content: "Ruby was created by Matz in 1995.",
+    metadata: { source: "history.pdf", page: 3 }
+  )
+  doc.content   # => "Ruby was created by Matz in 1995."
+  doc.metadata  # => { source: "history.pdf", page: 3 }
+  doc.to_h      # => { content: "...", metadata: { source: "history.pdf", page: 3 } }
+  ```
+
+## [0.5.0] — 2026-07-22
+
+### Added
+
+- `Ask::CostCalculator` — compute API costs from model pricing data.
+
 ## [0.4.0] — 2026-07-21
 
 ### Added

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/document.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Ask
+  # A piece of text content with associated metadata.
+  #
+  # Document is the universal value object for the RAG pipeline. It flows
+  # through every stage: loaded from files by {Ask::Loader::Base loaders},
+  # split into smaller pieces by {Ask::TextSplitter::Base splitters},
+  # embedded and stored by vector stores, and returned by retrieval queries.
+  #
+  # Immutable after creation. Two documents are equal when their content and
+  # metadata match.
+  #
+  # @example
+  #   doc = Ask::Document.new(
+  #     content: "Ruby was created by Matz in 1995.",
+  #     metadata: { source: "history.pdf", page: 3 }
+  #   )
+  #   doc.content   # => "Ruby was created by Matz in 1995."
+  #   doc.metadata  # => { source: "history.pdf", page: 3 }
+  #   doc.id        # => nil
+  #
+  class Document
+    # @return [String] the text content of this document
+    attr_reader :content
+
+    # @return [Hash] arbitrary metadata (source, page, chunk index, etc.)
+    attr_reader :metadata
+
+    # @return [String, nil] optional unique identifier
+    attr_reader :id
+
+    # @param content [String] the text content
+    # @param metadata [Hash] arbitrary metadata (default: {})
+    # @param id [String, nil] optional identifier
+    def initialize(content:, metadata: {}, id: nil)
+      @content = content.to_s
+      @metadata = metadata.dup.freeze
+      @id = id
+      freeze
+    end
+
+    # @return [Hash] serializable representation
+    def to_h
+      { content: @content, metadata: @metadata, id: @id }.compact
+    end
+
+    # @return [String] JSON representation
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Two documents are equal if their content and metadata match.
+    def ==(other)
+      return false unless other.is_a?(Document)
+
+      @content == other.content && @metadata == other.metadata
+    end
+    alias eql? ==
+
+    def hash
+      [@content, @metadata].hash
+    end
+
+    # @return [String]
+    def inspect
+      preview = @content.length > 60 ? "#{@content[0, 60]}..." : @content
+      "#<Ask::Document content=#{preview.inspect}>"
+    end
+  end
+end

data/lib/ask/state.rb

@@ -65,11 +65,27 @@ module Ask
         raise NotImplementedError
       end
 
-      # Remove all keys from the store.
+      # Remove all keys from the store (key-value only by default).
+      # Subclasses should override to also clear locks, queues, and lists.
       def clear
         raise NotImplementedError
       end
 
+      # Check if a key exists and has not expired.
+      # @param key [String] the key
+      # @return [Boolean] true if the key exists and is not expired
+      def exists?(key)
+        !get(key).nil?
+      end
+
+      # Return all non-expired keys, optionally filtered by a glob pattern.
+      # Glob syntax: * matches any sequence, ? matches any single character.
+      # @param pattern [String, nil] optional glob pattern (e.g., "session:*")
+      # @return [Array<String>] matching keys
+      def keys(pattern: nil)
+        raise NotImplementedError
+      end
+
       # Atomically set a value only if the key does not already exist.
       # @param key [String] the key
       # @param value [Object] the value
@@ -152,6 +168,23 @@ module Ask
       def close
         # no-op by default
       end
+
+      # -- Glob pattern helpers --
+
+      # Convert a glob pattern (*, ?) to a SQL LIKE pattern.
+      # @param pattern [String] glob pattern (e.g., "session:*")
+      # @return [String] LIKE pattern (e.g., "session:%")
+      def self.glob_to_like(pattern)
+        pattern.gsub("*", "%").gsub("?", "_")
+      end
+
+      # Convert a glob pattern (*, ?) to a Regexp.
+      # @param pattern [String] glob pattern (e.g., "session:*")
+      # @return [Regexp] matching regex (e.g., /\Asession:.*\z/)
+      def self.glob_to_regex(pattern)
+        escaped = Regexp.escape(pattern)
+        Regexp.new("\\A#{escaped.gsub("\\*", ".*").gsub("\\?", ".")}\\z")
+      end
     end
 
     # In-process state backend backed by a Hash.
@@ -211,6 +244,33 @@ module Ask
       def clear
         @mutex.synchronize do
           @data.clear
+          @locks.clear
+          @queues.clear
+          @lists.clear
+        end
+      end
+
+      def exists?(key)
+        @mutex.synchronize do
+          expiry = @data[key]&.dig(:expires_at)
+          return false if expiry && Time.now >= expiry
+          @data.key?(key)
+        end
+      end
+
+      def keys(pattern: nil)
+        @mutex.synchronize do
+          # Filter out expired keys
+          active = @data.select do |_k, v|
+            expiry = v[:expires_at]
+            expiry.nil? || Time.now < expiry
+          end
+
+          keys = active.keys.map(&:to_s)
+          return keys unless pattern
+
+	          regex = self.class.glob_to_regex(pattern)
+          keys.select { |k| k.match?(regex) }
         end
       end
 
@@ -316,6 +376,14 @@ module Ask
           @lists.clear
         end
       end
+
+      private
+
+      # Convert a glob pattern (*, ?) to a Regexp.
+      # Delegates to the shared class method for consistency.
+      def glob_to_regex(pattern)
+        self.class.glob_to_regex(pattern)
+      end
     end
   end
 end

data/lib/ask/version.rb

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

data/lib/ask.rb

@@ -6,8 +6,10 @@ 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.
 # Ask::ToolDef is an immutable tool definition struct.
 # Ask::Result standardizes tool execution return values.
 # Ask::Error provides structured error types.
@@ -15,11 +17,13 @@ module Ask
 end
 
 require_relative "ask/errors"
+require_relative "ask/content"
 require_relative "ask/tool_def"
 require_relative "ask/result"
 require_relative "ask/stream"
 require_relative "ask/conversation"
 require_relative "ask/provider"
 require_relative "ask/models"
+require_relative "ask/document"
 require_relative "ask/state"
 require_relative "ask/provider_tool"

metadata

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