ask-core 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27b1acea84966d56137426aa88ddc1cda8f61dd277a37c9c9961f79540c156f2
-  data.tar.gz: 5096b62044dd0110ba21e59642a2af4d2ce149cf7a3e24bf6235cbe025f9412d
+  metadata.gz: 6f85f689da590da523c0fcf5ead1b02469865eaf957720c8965084d439f69f74
+  data.tar.gz: dec0a975ed1b82346e98a9d84820e8cad192db0f0e308d97a1dcbdc5303ebee9
 SHA512:
-  metadata.gz: 5d92e48754c546c5904f3fec07d398569dadf4c8d70ba8068a098e3e9d2ee363133f5466c08e50402325054241df2b815cf4d53435bca121f6941a92eb20a6d7
-  data.tar.gz: 00752dace3a9a4d017e0af32c8caaf0cbbd2e57af89b9cd797e54a275458ef6e30be7c255c5bc3d39eef7bb0089b67243e40ae0327cce1cfa981034827e3470d
+  metadata.gz: 4cb0d8b10f05b778fd66717cb54571d486d21cc93ba95334d5ecd3517d8aa4ccacd92b78fa7dfdc26893d89f5871d18593584cf204967f34d64d1545add1efc0
+  data.tar.gz: f00616ed87027aedb9eeadc69445078dd203dee9910dcd014c1c89f6461544241bd1b0e08f6a39c30d60c40452b38f529424c09775e098ed6900aad4b9988279

data/CHANGELOG.md

@@ -1,3 +1,42 @@
+## [0.3.0] — 2026-07-21
+
+### Added
+
+- **Pluggable state abstraction** — `Ask::State::Adapter` defines a unified interface for key-value storage, distributed locking, message queues, and ordered lists. `Ask::State::Memory` provides an in-process, thread-safe implementation backed by Hash.
+
+  ```ruby
+  store = Ask::State::Memory.new
+
+  # Key-value with optional TTL
+  store.set("key", "value", ttl: 60)
+  store.get("key")
+
+  # Distributed locking
+  lock = store.acquire_lock("resource", ttl: 10)
+  store.release_lock("resource", lock)
+
+  # Message queues
+  store.enqueue("queue", { task: "check" })
+  store.dequeue("queue")
+
+  # Ordered lists
+  store.list_append("list", "item", max_length: 100)
+  store.list_range("list", 0, -1)
+  store.list_remove("list", "item")
+  ```
+
+  The adapter pattern mirrors `Ask::Provider` — define the contract in ask-core, provide implementations in separate gems. Production backends (Redis, PostgreSQL) can be added by any gem without modifying ask-core.
+
+  Data types: `Ask::State::Lock` (with `#expired?`), `Ask::State::QueueEntry`.
+
+### Changed
+
+- **ask-agent's `Persistence::Base` now wraps `Ask::State::Adapter`** — session persistence is backed by the unified state interface instead of a standalone abstract class. `Persistence::InMemory` delegates to `Ask::State::Memory`. Backward compatible — no API changes for users.
+
+### Tested
+
+- 34 new tests for `Ask::State::Adapter` + `Ask::State::Memory`: key-value operations, TTL expiry, thread safety, locking semantics, queue FIFO order, list management, adapter subclassing, and the base class contract.
+
 ## [0.2.4] — 2026-07-17
 
 ### Added

data/lib/ask/state.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "forwardable"
+
+module Ask
+  # Pluggable state backend for agent sessions, channel providers, and
+  # any other ask-rb component that needs durable key-value storage,
+  # distributed locking, message queues, or ordered lists.
+  #
+  # The {State::Adapter} abstract base defines the contract.
+  # {State::Memory} provides an in-process implementation backed by Hash.
+  # Production apps can provide Redis, PostgreSQL, or other backends by
+  # subclassing {State::Adapter}.
+  #
+  # @example Using the in-memory adapter
+  #   store = Ask::State::Memory.new
+  #   store.set("key", "value")
+  #   store.get("key")     # => "value"
+  #   store.delete("key")
+  #
+  # @example Acquiring a distributed lock
+  #   lock = store.acquire_lock("resource-1", ttl: 10)
+  #   if lock
+  #     begin
+  #       # critical section
+  #     ensure
+  #       store.release_lock("resource-1", lock)
+  #     end
+  #   end
+  #
+  # @example Using a message queue
+  #   store.enqueue("queue-name", { task: "check_health" })
+  #   entry = store.dequeue("queue-name")
+  #   # => { id: "uuid", value: { task: "check_health" }, enqueued_at: timestamp }
+  module State
+    Lock = Data.define(:id, :token, :expires_at) do
+      def expired?(now = Time.now)
+        expires_at && now >= expires_at
+      end
+    end
+
+    QueueEntry = Data.define(:id, :value, :enqueued_at)
+
+    # Abstract base class for state backends.
+    # Subclasses must implement all methods.
+    class Adapter
+      # Key-value storage
+
+      # @param key [String] the key
+      # @return [Object, nil] the stored value, or nil if not found
+      def get(key)
+        raise NotImplementedError
+      end
+
+      # @param key [String] the key
+      # @param value [Object] the value (must be JSON-serializable)
+      # @param ttl [Integer, nil] time-to-live in seconds (nil = no expiry)
+      def set(key, value, ttl: nil)
+        raise NotImplementedError
+      end
+
+      # @param key [String] the key
+      def delete(key)
+        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
+      # @return [Boolean] true if the value was set, false if the key already exists
+      def set_if_not_exists(key, value, ttl: nil)
+        raise NotImplementedError
+      end
+
+      # Distributed locking
+
+      # Acquire a lock for a key. Returns nil if the lock is held by another owner.
+      # @param key [String] the resource to lock
+      # @param ttl [Integer] lock time-to-live in seconds (default 10)
+      # @return [Lock, nil] the lock if acquired, nil if already held
+      def acquire_lock(key, ttl: 10)
+        raise NotImplementedError
+      end
+
+      # Release a lock. Only the lock owner can release it.
+      # @param key [String] the resource to unlock
+      # @param lock [Lock] the lock returned by {#acquire_lock}
+      # @return [Boolean] true if released, false if lock was already expired or not held
+      def release_lock(key, lock)
+        raise NotImplementedError
+      end
+
+      # Message queues
+
+      # Push an item onto a named queue.
+      # @param queue [String] the queue name
+      # @param value [Object] the value to enqueue
+      # @return [QueueEntry] the enqueued entry
+      def enqueue(queue, value)
+        raise NotImplementedError
+      end
+
+      # Pop the next item from a named queue.
+      # @param queue [String] the queue name
+      # @return [QueueEntry, nil] the next entry, or nil if the queue is empty
+      def dequeue(queue)
+        raise NotImplementedError
+      end
+
+      # @param queue [String] the queue name
+      # @return [Integer] the number of items in the queue
+      def queue_depth(queue)
+        raise NotImplementedError
+      end
+
+      # Ordered lists
+
+      # Append a value to an ordered list. Trims to max_length (keeps newest).
+      # @param key [String] the list key
+      # @param value [Object] the value to append
+      # @param max_length [Integer, nil] maximum list length (nil = no limit)
+      def list_append(key, value, max_length: nil)
+        raise NotImplementedError
+      end
+
+      # Return a slice of the list.
+      # @param key [String] the list key
+      # @param start [Integer] starting index (0-based)
+      # @param stop [Integer] ending index (inclusive, -1 for all)
+      # @return [Array<Object>] the list slice
+      def list_range(key, start = 0, stop = -1)
+        raise NotImplementedError
+      end
+
+      # Remove all occurrences of a value from a list.
+      # @param key [String] the list key
+      # @param value [Object] the value to remove
+      # @return [Integer] number of removed elements
+      def list_remove(key, value)
+        raise NotImplementedError
+      end
+
+      # Lifecycle
+
+      # Optional: called when the adapter is no longer needed.
+      def close
+        # no-op by default
+      end
+    end
+
+    # In-process state backend backed by a Hash.
+    # All operations are thread-safe via a Mutex.
+    # Data is not persisted — lost on process exit.
+    class Memory < Adapter
+      def initialize
+        @data = {}
+        @locks = {}
+        @queues = {}
+        @lists = {}
+        @mutex = Mutex.new
+      end
+
+      # -- key-value --
+
+      def get(key)
+        @mutex.synchronize do
+          expiry = @data[key]&.dig(:expires_at)
+          return nil if expiry && Time.now >= expiry
+
+          @data[key]&.dig(:value)
+        end
+      end
+
+      def set(key, value, ttl: nil)
+        @mutex.synchronize do
+          @data[key] = {
+            value: value,
+            expires_at: ttl ? Time.now + ttl : nil
+          }
+        end
+      end
+
+      def delete(key)
+        @mutex.synchronize { @data.delete(key) }
+      end
+
+      def set_if_not_exists(key, value, ttl: nil)
+        @mutex.synchronize do
+          if @data.key?(key)
+            expiry = @data[key][:expires_at]
+            return false if expiry.nil? || Time.now < expiry
+
+            # Key expired — treat as nonexistent
+            @data.delete(key)
+          end
+
+          @data[key] = {
+            value: value,
+            expires_at: ttl ? Time.now + ttl : nil
+          }
+          true
+        end
+      end
+
+      # -- locking --
+
+      def acquire_lock(key, ttl: 10)
+        @mutex.synchronize do
+          existing = @locks[key]
+          if existing.nil? || existing.expired?
+            lock = Lock.new(
+              id: key,
+              token: SecureRandom.hex(16),
+              expires_at: Time.now + ttl
+            )
+            @locks[key] = lock
+            lock
+          end
+        end
+      end
+
+      def release_lock(key, lock)
+        @mutex.synchronize do
+          current = @locks[key]
+          if current && current.token == lock.token && !current.expired?
+            @locks.delete(key)
+            true
+          else
+            false
+          end
+        end
+      end
+
+      # -- queues --
+
+      def enqueue(queue, value)
+        @mutex.synchronize do
+          @queues[queue] ||= []
+          entry = QueueEntry.new(
+            id: SecureRandom.uuid,
+            value: value,
+            enqueued_at: Time.now
+          )
+          @queues[queue] << entry
+          entry
+        end
+      end
+
+      def dequeue(queue)
+        @mutex.synchronize do
+          q = @queues[queue]
+          return nil unless q&.any?
+
+          q.shift
+        end
+      end
+
+      def queue_depth(queue)
+        @mutex.synchronize do
+          (@queues[queue] || []).length
+        end
+      end
+
+      # -- lists --
+
+      def list_append(key, value, max_length: nil)
+        @mutex.synchronize do
+          @lists[key] ||= []
+          @lists[key] << value
+          @lists[key].shift if max_length && @lists[key].length > max_length
+        end
+      end
+
+      def list_range(key, start = 0, stop = -1)
+        @mutex.synchronize do
+          list = @lists[key] || []
+          return list if start == 0 && stop == -1
+
+          stop = list.length - 1 if stop == -1 || stop >= list.length
+          return [] if start > stop
+
+          list[start..stop] || []
+        end
+      end
+
+      def list_remove(key, value)
+        @mutex.synchronize do
+          list = @lists[key]
+          return 0 unless list
+
+          before = list.length
+          list.delete(value)
+          before - list.length
+        end
+      end
+
+      # -- lifecycle --
+
+      def close
+        @mutex.synchronize do
+          @data.clear
+          @locks.clear
+          @queues.clear
+          @lists.clear
+        end
+      end
+    end
+  end
+end

data/lib/ask/version.rb

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

data/lib/ask.rb

@@ -21,3 +21,4 @@ require_relative "ask/stream"
 require_relative "ask/conversation"
 require_relative "ask/provider"
 require_relative "ask/models"
+require_relative "ask/state"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-core
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -69,6 +69,7 @@ files:
 - lib/ask/models.rb
 - lib/ask/provider.rb
 - lib/ask/result.rb
+- lib/ask/state.rb
 - lib/ask/stream.rb
 - lib/ask/tool_def.rb
 - lib/ask/version.rb