ask-core 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76460c5c6e631cb59ed89bb8fabb48cd52dca8d6930c99e43ec34b8f4b9a0912
-  data.tar.gz: cbd34d8e2dec789316f4b7e7f1aead500dc80983c003fd6a8ef657dfa9c7a299
+  metadata.gz: e9500049544d02d1e7a13d939c7e1bf7a532d5d45682302e9666d0e6d63b4488
+  data.tar.gz: 9f249f01b749bda7700131ce107bc0d312477849dd6006e6a3e2ca4b814e5b31
 SHA512:
-  metadata.gz: bea59c9b587c6c3f00a2aa4ce4b9052e00af5d4f924eccc395fce73560a99cf7fafa586e813d7b11efbdd74a39e20dc85ca2c6627c49be63256e8485fdf5be16
-  data.tar.gz: feb067f7cc3f11bda5f942614df3717da8e06ceada1a4ad2c92fe07a8c05b613fd240cab929217bb7cebc4f273e7e5e5d7d338ecaefd579b92d3ac3bb61c6b3f
+  metadata.gz: b5ac63d0cf689c3bc22fb4ad4bac215fbc9aa022b74e63b453a87ab7c7d7a5c781fff2fc2c9b694d6fb9e669c858ec0f81c13bf21fac50753654f8ebed2c3c58
+  data.tar.gz: 23a06ce41d67eee03322691919623dfa888e301d4607c9812dbb85a2c46ace50b16d99aa9d1c1ba879104f84f74981bbc9cf8d5c985132331211c6bcbd00509a

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [0.6.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.
+
+  ```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/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,6 +65,27 @@ module Ask
         raise NotImplementedError
       end
 
+      # 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
@@ -147,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.
@@ -203,6 +241,39 @@ module Ask
         end
       end
 
+      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
+
       # -- locking --
 
       def acquire_lock(key, ttl: 10)
@@ -305,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.4.0"
+  VERSION = "0.6.0"
 end

data/lib/ask.rb

@@ -8,6 +8,7 @@ require_relative "ask/version"
 # Ask::Conversation is a message container with role normalization.
 # 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.
@@ -21,5 +22,6 @@ 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.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -65,6 +65,7 @@ files:
 - README.md
 - lib/ask.rb
 - lib/ask/conversation.rb
+- lib/ask/document.rb
 - lib/ask/errors.rb
 - lib/ask/models.rb
 - lib/ask/provider.rb