ask-core 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2d67418e2412efacf4d0b5c35d1897826f0da1c0a52c159f7503e8b794d66f1
-  data.tar.gz: 2b39ea638d11e5147058a1f35e3aa3c130650972082330e2dd30a752eeb68a36
+  metadata.gz: 3919e331460c87569013ea41f713269840945b36dca9def8d3e73476c4e9bff5
+  data.tar.gz: 3055307c6774fb7cfdb690dd1b5cc5f14dc925670d95310a302b3d361d372b94
 SHA512:
-  metadata.gz: 8910e469a984ca9f2758dc816b6b13714b5985fad2dbb0910b2d2d0b5313ff04abfcffad06e3fcf2de4a53eb2d3e34fda1292150867bae39d476b5ad4a3551e4
-  data.tar.gz: 6ed636a7ed4b15f423b5914708064e44ac286e6488b87857d271646e83fad113b8dec97a1a7082e95bbd598d1ee2c631a77bffa0d03595ebd7d10db9a965b2ab
+  metadata.gz: 51fc3c4838e5ddb98c829525fbf3840b37ddd5683f4821c58b2ec9f4d2c3a5af4d77a54a32a911550aecfac56e9847f4a5940b06b923b04eae118bf522115040
+  data.tar.gz: 4560aa7626cc24ca53292828dd1b27f0405d09cff66557533734a3475b6a97d2f8e097fd67b14de827d3b78ead92d151a322969b8c08b833087d0089a3366699

data/lib/ask/attachment.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Ask
+  # A file a user attached to a message.
+  #
+  # Sources (exactly one per attachment):
+  #   path:     local file path
+  #   url:      http(s) or data: URI
+  #   data:     raw bytes
+  #   io:       an IO/StringIO (read at render time)
+  #   blob:     a duck-typed object with +download+/+path+/+read+
+  #             (e.g. an ActiveStorage blob)
+  #   file_id:  a provider-managed file reference (no bytes here)
+  #
+  # Delivery modes:
+  #   :inline (default) — the bytes are sent to the model (via the
+  #     provider's serializers) so it can read the file. Provider
+  #     capability gates apply.
+  #   :context — only a manifest line reaches the model:
+  #     "[Attached file: name (mime, N bytes)]". The model knows the file
+  #     exists but never receives its content. Provider-agnostic — right
+  #     for agents that must not read uploaded files (e.g. a
+  #     requirements-gathering assistant).
+  #
+  # @example Inline image from a local path
+  #   Ask::Attachment.new(path: "receipt.png")
+  #
+  # @example Context-only (know it exists, don't read it)
+  #   Ask::Attachment.new(path: "invoice.csv", delivery: :context)
+  #
+  # @example ActiveStorage blob
+  #   Ask::Attachment.new(blob: work_request.source_files.first)
+  class Attachment
+    DELIVERY_MODES = %i[inline context].freeze
+
+    # @return [String, nil] original filename
+    attr_reader :filename
+
+    # @return [String] MIME type
+    attr_reader :mime_type
+
+    # @return [Integer, nil] size in bytes
+    attr_reader :size
+
+    # @return [Symbol] :inline or :context
+    attr_reader :delivery
+
+    # @return [String, nil] URL (http(s) or data: URI) when given
+    attr_reader :url
+
+    # @return [String, nil] provider-managed file ID when given
+    attr_reader :file_id
+
+    # @param path [String, nil] local file path
+    # @param url [String, nil] http(s) or data: URI
+    # @param data [String, nil] raw bytes
+    # @param io [IO, StringIO, nil]
+    # @param blob [Object, nil] duck-typed blob (+download+/+path+/+read+)
+    # @param file_id [String, nil] provider-managed file reference
+    # @param filename [String, nil] override the derived filename
+    # @param mime_type [String, nil] override the derived MIME type
+    # @param delivery [Symbol] :inline (default) or :context
+    def initialize(path: nil, url: nil, data: nil, io: nil, blob: nil, file_id: nil,
+                   filename: nil, mime_type: nil, delivery: :inline)
+      sources = { path: path, url: url, data: data, io: io, blob: blob, file_id: file_id }
+      given = sources.count { |_, value| !value.nil? }
+      raise ArgumentError, "Provide exactly one attachment source" unless given == 1
+
+      @delivery = delivery.to_sym
+      raise ArgumentError, "Unknown delivery mode: #{delivery.inspect}" unless DELIVERY_MODES.include?(@delivery)
+
+      @path = path
+      @io = io
+      @blob = blob
+      @url = url
+      @file_id = file_id
+      @raw_data = data
+      @filename = filename || derive_filename
+      @mime_type = mime_type || derive_mime_type
+      @size = derive_size
+      freeze
+    end
+
+    # Raw bytes, when the source can provide them (path/io/data/blob/data
+    # URIs). nil for URLs and provider file references — those are passed
+    # to the provider as-is.
+    #
+    # @return [String, nil]
+    def data
+      return @raw_data unless @raw_data.nil?
+      return nil if @file_id
+      return decode_data_uri if data_uri?
+
+      if @path
+        File.binread(@path)
+      elsif @io
+        @io.rewind if @io.respond_to?(:rewind)
+        @io.read
+      elsif @blob
+        if @blob.respond_to?(:download)
+          @blob.download
+        elsif @blob.respond_to?(:read)
+          @blob.read
+        end
+      end
+    end
+
+    # Base64-encoded bytes, when available.
+    #
+    # @return [String, nil]
+    def base64
+      bytes = data
+      bytes && Base64.strict_encode64(bytes)
+    end
+
+    # Broad category of the file (see {Mime.classify}).
+    #
+    # @return [Symbol]
+    def type
+      Mime.classify(mime_type)
+    end
+
+    # The manifest line rendered for {delivery: :context} attachments.
+    #
+    # @return [String]
+    def manifest_line
+      details = [mime_type, (size ? "#{size} bytes" : nil)].compact.join(", ")
+      "[Attached file: #{filename || "file"} (#{details})]"
+    end
+
+    # Convert to the content block carried by the message.
+    #
+    # :context attachments become a plain {Content::Text} manifest line;
+    # :inline attachments become the matching media/file block so the
+    # provider serializers can send the bytes.
+    #
+    # @return [Content::Block]
+    def to_content
+      return Content::Text.new(manifest_line) if context?
+
+      case type
+      when :image
+        Content::Image.new(url: url, base64: base64, mime_type: mime_type, file_id: file_id)
+      when :audio
+        Content::Audio.new(url: url, base64: base64, mime_type: mime_type, file_id: file_id)
+      when :video
+        Content::Video.new(url: url, base64: base64, mime_type: mime_type, file_id: file_id)
+      else
+        Content::File.new(data: data, mime_type: mime_type, filename: filename,
+                          url: url, file_id: file_id)
+      end
+    end
+
+    # @return [Boolean] whether only context (a manifest line) is sent
+    def context?
+      @delivery == :context
+    end
+
+    # @return [Boolean] whether the bytes are sent to the model
+    def inline?
+      @delivery == :inline
+    end
+
+    # Coerce a single value into an {Attachment}:
+    #   Attachment → itself
+    #   Content::Block → itself (already a block)
+    #   String → treated as a local file path
+    #   Hash → keyword constructor arguments
+    #   duck-typed blob (+download+/+path+/+read+) → blob source
+    #
+    # @param value [Object]
+    # @return [Attachment, Content::Block]
+    def self.wrap(value)
+      case value
+      when Attachment, Content::Block
+        value
+      when String
+        new(path: value)
+      when Hash
+        new(**value.transform_keys(&:to_sym))
+      else
+        if value.respond_to?(:download) || value.respond_to?(:path) || value.respond_to?(:read)
+          new(blob: value)
+        else
+          raise ArgumentError, "Cannot use #{value.class} as an attachment"
+        end
+      end
+    end
+
+    # Coerce a value or array of values into an array of attachments
+    # (and/or content blocks).
+    #
+    # @param values [Object, Array<Object>]
+    # @return [Array<Attachment, Content::Block>]
+    def self.wrap_all(values)
+      Array(values).map { |value| wrap(value) }
+    end
+
+    private
+
+    attr_reader :path, :io, :blob
+
+    def derive_filename
+      case
+      when @path then File.basename(@path)
+      when @url
+        if data_uri?
+          nil
+        else
+          File.basename(URI.parse(@url).path)
+        end
+      when @io
+        @io.respond_to?(:path) ? File.basename(@io.path.to_s) : nil
+      when @blob
+        if @blob.respond_to?(:filename)
+          @blob.filename.to_s
+        elsif @blob.respond_to?(:name)
+          @blob.name.to_s
+        end
+      end
+    end
+
+    def derive_mime_type
+      bytes = sniffable_bytes
+      Mime.detect(filename: filename, bytes: bytes)
+    end
+
+    # Bytes we can afford to sniff without reading the whole file.
+    # Missing files resolve to nil (data/size raise at render time).
+    def sniffable_bytes
+      return @raw_data[0, 16] if @raw_data
+      return nil if @file_id || url && !data_uri?
+
+      if @path
+        File.binread(@path, 16) rescue nil
+      elsif @io
+        data&.to_s[0, 16]
+      elsif @blob
+        if @blob.respond_to?(:download)
+          @blob.download.to_s[0, 16]
+        elsif @blob.respond_to?(:read)
+          data&.to_s[0, 16]
+        end
+      end
+    end
+
+    def derive_size
+      return @raw_data.bytesize if @raw_data
+      return nil if @file_id
+      return decode_data_uri.bytesize if data_uri?
+
+      if @path
+        File.size(@path) rescue nil
+      elsif @blob && @blob.respond_to?(:byte_size)
+        @blob.byte_size
+      end
+    end
+
+    def data_uri?
+      @url.to_s.start_with?("data:")
+    end
+
+    def decode_data_uri
+      DataURI.decode(@url).last
+    end
+  end
+end

data/lib/ask/content.rb

@@ -159,11 +159,14 @@ module Ask
       end
     end
 
-    # An inline file block within a multi-modal message.
+    # A file block within a multi-modal message.
+    #
+    # Carries inline +data+ by default; +url+ or +file_id+ can be used
+    # instead when the file lives somewhere the provider can reach.
     class File
       include Block
 
-      # @return [String] the file content
+      # @return [String, nil] raw file content
       attr_reader :data
 
       # @return [String, nil] MIME type
@@ -172,29 +175,76 @@ module Ask
       # @return [String, nil] original filename
       attr_reader :filename
 
-      # @param data [String] the file content
+      # @return [String, nil] URL of the file
+      attr_reader :url
+
+      # @return [String, nil] Provider-managed file ID
+      attr_reader :file_id
+
+      # @param data [String, nil] raw file content
       # @param mime_type [String, nil] MIME type
       # @param filename [String, nil] original filename
-      def initialize(data:, mime_type: nil, filename: nil)
+      # @param url [String, nil] URL of the file
+      # @param file_id [String, nil] Provider-managed file ID
+      def initialize(data: nil, mime_type: nil, filename: nil, url: nil, file_id: nil)
         @data = data
         @mime_type = mime_type
         @filename = filename
+        @url = url
+        @file_id = file_id
         freeze
       end
 
       def ==(other)
-        other.is_a?(File) && @data == other.data &&
-          @mime_type == other.mime_type && @filename == other.filename
+        other.is_a?(File) && @data == other.data && @mime_type == other.mime_type &&
+          @filename == other.filename && @url == other.url && @file_id == other.file_id
       end
       alias eql? ==
 
       def hash
-        [@data, @mime_type, @filename].hash
+        [@data, @mime_type, @filename, @url, @file_id].hash
       end
 
       def to_h
-        { type: "file", data: @data, mime_type: @mime_type, filename: @filename }
+        h = { type: "file" }
+        h[:data] = @data if @data
+        h[:mime_type] = @mime_type if @mime_type
+        h[:filename] = @filename if @filename
+        h[:url] = @url if @url
+        h[:file_id] = @file_id if @file_id
+        h
+      end
+    end
+
+    # Rebuild a content block from a +to_h+ hash (persistence round-trips).
+    #
+    # @param hash [Hash] a hash produced by {Block#to_h}
+    # @return [Block]
+    def self.from_h(hash)
+      hash = hash.transform_keys(&:to_s)
+      case hash["type"]
+      when "text"
+        Text.new(hash["text"].to_s)
+      when "image"
+        Image.new(**media_args(hash))
+      when "audio"
+        Audio.new(**media_args(hash))
+      when "video"
+        Video.new(**media_args(hash))
+      when "file"
+        File.new(
+          data: hash["data"], mime_type: hash["mime_type"], filename: hash["filename"],
+          url: hash["url"], file_id: hash["file_id"]
+        )
+      else
+        raise ArgumentError, "Unknown content block type: #{hash["type"].inspect}"
       end
     end
+
+    # @api private
+    def self.media_args(hash)
+      { url: hash["url"], base64: hash["base64"], mime_type: hash["mime_type"], file_id: hash["file_id"] }
+    end
+    private_class_method :media_args
   end
 end

data/lib/ask/conversation.rb

@@ -141,6 +141,26 @@ module Ask
       base
     end
 
+    # Rebuild a message from a +to_h+ hash (persistence round-trips).
+    # Content-block arrays are reconstructed via {Content.from_h}.
+    #
+    # @param hash [Hash] a hash produced by {#to_h}
+    # @return [Message]
+    def self.from_h(hash)
+      hash = hash.transform_keys(&:to_s)
+      content = hash["content"]
+      content = content.map { |block| Content.from_h(block) } if content.is_a?(Array)
+
+      new(
+        role: hash["role"].to_sym,
+        content: content,
+        name: hash["name"],
+        tool_call_id: hash["tool_call_id"],
+        tool_calls: hash["tool_calls"],
+        metadata: hash["metadata"] || {}
+      )
+    end
+
     # @return [Boolean] true if role, content/block, name, and tool metadata all match
     def ==(other)
       return false unless other.is_a?(Message)

data/lib/ask/data_uri.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "base64"
+require "uri"
+
+module Ask
+  # Build and parse data: URIs (RFC 2397).
+  #
+  # @example
+  #   Ask::DataURI.encode("hello", mime_type: "text/plain")
+  #   # => "data:text/plain;base64,aGVsbG8="
+  #
+  #   Ask::DataURI.decode("data:text/plain;base64,aGVsbG8=")
+  #   # => ["text/plain", "hello"]
+  module DataURI
+    module_function
+
+    # Encode raw bytes as a data URI.
+    #
+    # @param data [String] raw bytes
+    # @param mime_type [String] MIME type
+    # @return [String]
+    def encode(data, mime_type: "application/octet-stream")
+      from_base64(Base64.strict_encode64(data), mime_type: mime_type)
+    end
+
+    # Build a data URI from already-encoded base64 (e.g. content blocks
+    # that carry a +base64+ field).
+    #
+    # @param base64 [String] base64-encoded data
+    # @param mime_type [String] MIME type
+    # @return [String]
+    def from_base64(base64, mime_type: "application/octet-stream")
+      "data:#{mime_type};base64,#{base64}"
+    end
+
+    # Parse a data URI into [mime_type, raw bytes].
+    #
+    # @param uri [String] a data: URI
+    # @return [Array(String, String)]
+    # @raise [ArgumentError] when +uri+ is not a data URI
+    def decode(uri)
+      match = uri.to_s.match(%r{\Adata:([^;,]*)((?:;[^,]*)*),(.*)\z}m)
+      raise ArgumentError, "Not a data URI: #{uri.to_s[0, 60].inspect}..." unless match
+
+      mime = match[1].empty? ? "text/plain" : match[1]
+      params = match[2]
+      payload = match[3]
+      if params.include?(";base64")
+        [mime, Base64.strict_decode64(payload)]
+      else
+        [mime, URI.decode_www_form_component(payload)]
+      end
+    end
+  end
+end

data/lib/ask/mime.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Ask
+  # Lightweight, dependency-free MIME detection and classification.
+  #
+  # Sniffs magic bytes for common binary formats and maps extensions for
+  # text/documents; everything else falls back to
+  # +application/octet-stream+. Kept deliberately small — ask-core has no
+  # runtime dependencies.
+  module Mime
+    # Common binary signatures → MIME type. Each entry may carry an extra
+    # proc that must also match (e.g. RIFF…WEBP for webp).
+    MAGIC = [
+      ["\x89PNG\r\n\x1a\n", "image/png"],
+      ["\xFF\xD8\xFF", "image/jpeg"],
+      ["GIF87a", "image/gif"],
+      ["GIF89a", "image/gif"],
+      ["RIFF", "image/webp", ->(bytes) { bytes[8, 4] == "WEBP" }],
+      ["%PDF-", "application/pdf"],
+      ["OggS", "audio/ogg"]
+    ].freeze
+
+    # Extension → MIME type.
+    EXTENSIONS = {
+      "txt" => "text/plain",
+      "csv" => "text/csv",
+      "json" => "application/json",
+      "xml" => "application/xml",
+      "md" => "text/markdown",
+      "html" => "text/html",
+      "rb" => "text/x-ruby",
+      "py" => "text/x-python",
+      "js" => "text/javascript",
+      "ts" => "text/typescript",
+      "pdf" => "application/pdf",
+      "png" => "image/png",
+      "jpg" => "image/jpeg",
+      "jpeg" => "image/jpeg",
+      "gif" => "image/gif",
+      "webp" => "image/webp",
+      "mp3" => "audio/mpeg",
+      "wav" => "audio/wav",
+      "ogg" => "audio/ogg",
+      "mp4" => "video/mp4",
+      "mov" => "video/quicktime",
+      "webm" => "video/webm",
+      "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    }.freeze
+
+    module_function
+
+    # Detect a MIME type from a filename and/or raw bytes.
+    #
+    # A known extension wins (docx/xlsx are zip containers and would
+    # otherwise sniff as application/zip); magic bytes are used when the
+    # extension is unknown.
+    #
+    # @param filename [String, nil]
+    # @param bytes [String, nil]
+    # @param default [String] fallback MIME type
+    # @return [String]
+    def detect(filename: nil, bytes: nil, default: "application/octet-stream")
+      from_extension = from_extension(filename) if filename
+      return from_extension if from_extension
+
+      sniff(bytes) || default
+    end
+
+    # Sniff magic bytes. Returns a MIME type or nil.
+    #
+    # @param bytes [String] raw bytes
+    # @return [String, nil]
+    def sniff(bytes)
+      return nil if bytes.nil? || bytes.empty?
+
+      MAGIC.each do |(signature, mime, extra)|
+        next unless bytes.start_with?(signature)
+        next if extra && !extra.call(bytes)
+
+        return mime
+      end
+      nil
+    end
+
+    # Map a filename's extension to a MIME type, or nil.
+    #
+    # @param filename [String, nil]
+    # @return [String, nil]
+    def from_extension(filename)
+      extension = filename.to_s.split(".").last&.downcase
+      EXTENSIONS[extension]
+    end
+
+    # Classify a MIME type into a broad category.
+    #
+    # @param mime_type [String, nil]
+    # @return [Symbol] one of :image, :audio, :video, :pdf, :document,
+    #   :text, :unknown
+    def classify(mime_type)
+      case mime_type.to_s
+      when %r{\Aimage/} then :image
+      when %r{\Aaudio/} then :audio
+      when %r{\Avideo/} then :video
+      when "application/pdf" then :pdf
+      when %r{\Atext/}, "application/json", "application/xml",
+           "application/javascript",
+           "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+           "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+           "application/msword", "application/vnd.ms-excel"
+        then :document
+      else
+        :unknown
+      end
+    end
+  end
+end

data/lib/ask/version.rb

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

data/lib/ask.rb

@@ -17,7 +17,10 @@ module Ask
 end
 
 require_relative "ask/errors"
+require_relative "ask/mime"
+require_relative "ask/data_uri"
 require_relative "ask/content"
+require_relative "ask/attachment"
 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.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -64,10 +64,13 @@ files:
 - LICENSE
 - README.md
 - lib/ask.rb
+- lib/ask/attachment.rb
 - lib/ask/content.rb
 - lib/ask/conversation.rb
+- lib/ask/data_uri.rb
 - lib/ask/document.rb
 - lib/ask/errors.rb
+- lib/ask/mime.rb
 - lib/ask/models.rb
 - lib/ask/provider.rb
 - lib/ask/provider_tool.rb