ask-tokens 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae96192b20e70ac88fb98af984b5a13cf749c7d7bf73fc786d59fc89e27002c1
-  data.tar.gz: e48974d2d1998878c63579e788a6882757bc39aaa524b71c99c1fde426e939d9
+  metadata.gz: ceb47fceedf25098c5bc27e2c544feaad5226839b337a87d1cf1503fcc5331d9
+  data.tar.gz: 928470bc83407814f4a8aa8f78b24170a23789cde42ea21b63b9c8b22c160118
 SHA512:
-  metadata.gz: 52b0688ccb3e4ef1c0983b6a642937981c7ffd8fad2380fc8385781c371c773e33387dbb11ef953627338aedcefeb11e60a8a88245e8ef00fccd6be46602eeaf
-  data.tar.gz: e5244ed51b9567605caa139c29b200372f3327fbd1950cf3b051e4b081a9c23656067dbbac0195a3e95942400edd1bfcf5982e9dd4861b93eb25b1f1db4c23d3
+  metadata.gz: e073422cdd0e0ef386a2532382644abcb77d4161b8d3e49b03983c9d13185a7dfac3743ad485acf12aa5cd3748f298f6d73d5a8c7425456e288c9596a6dc657c
+  data.tar.gz: 4acccaf24b0afe5597978ef93ad8f75117d77980be674b441b6764df95f5ab182ee1d225035e4e861d8d58af4e8ca6e631c1404ab3b51c22ead52cd58682a776

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.3.0] - 2026-10-20
+
+### Added
+- Activity namespacing: `Activity#namespace` and `#qualified_name` so multiple projects sharing one registry never collide on common names like `:compute_hour`. `Ask::Tokens.activity(name, namespace:, ...)` and `Ask::Tokens.estimate(name, namespace:)` resolve scoped activities.
+- `ActivityRegistry#fetch(name, namespace:)`, `#names(namespace:)`, `#each(namespace:)`, `#clear(namespace:)`, and `#registered?(name, namespace:)` for scoped access.
+- `Ask::Tokens#wallet_for(owner, store:)` override, so a billing service can route different owners to different backends (useful for tests and multi-tenant routing).
+- `Wallet#estimate`, `#enough_for?`, and `#spend!` accept `namespace:` plus keyword params that are merged into the params hash.
+
+### Changed
+- `Ask::Tokens#estimate` and `Wallet#estimate/#spend!` accept keyword arguments in addition to a positional params Hash.
+
+
 ## [0.1.0] - 2026-08-19
 
 ### Added

data/lib/ask/tokens/activity.rb

@@ -10,16 +10,25 @@ module Ask
     #   end
     #
     class Activity
-      attr_reader :name
+      attr_reader :name, :namespace
 
-      def initialize(name, cost: nil, &block)
+      def initialize(name, cost: nil, namespace: nil, &block)
         raise ArgumentError, "activity #{name.inspect} needs a cost or a block" if cost.nil? && block.nil?
 
         @name = name.to_sym
+        @namespace = namespace&.to_sym
         @cost = cost
         @block = block
       end
 
+      # The fully-qualified name, including namespace when present.
+      # Used as the registry key so scoped and unscoped activities never
+      # collide. A billing service serving multiple projects can namespace
+      # each project's activities (e.g. :ship) without collisions.
+      def qualified_name
+        @namespace ? :"#{@namespace}:#{@name}" : @name
+      end
+
       # The token cost of running this activity with +params+. Always returns
       # an Integer, rounded per configuration. A fixed cost ignores params; a
       # block receives them (zero-arity blocks are called with no arguments).
@@ -36,7 +45,7 @@ module Ask
       end
 
       def to_s
-        "Activity(#{@name})"
+        @namespace ? "Activity(#{@namespace}:#{@name})" : "Activity(#{@name})"
       end
 
       def inspect

data/lib/ask/tokens/activity_registry.rb

@@ -3,32 +3,63 @@
 module Ask
   module Tokens
     # Stores declared activities by name.
+    #
+    # Activities can be scoped to a namespace (e.g. a project or service
+    # name) so that multiple projects sharing one registry never collide
+    # on a common name like :compute_hour. The registry key is the
+    # activity's qualified name (namespace:name when namespaced).
     class ActivityRegistry
       def initialize
         @activities = {}
       end
 
-      def register(name, cost: nil, &block)
-        activity = Activity.new(name, cost: cost, &block)
-        @activities[activity.name] = activity
+      def register(name, cost: nil, namespace: nil, &block)
+        activity = Activity.new(name, cost: cost, namespace: namespace, &block)
+        @activities[activity.qualified_name] = activity
       end
 
-      def fetch(name)
-        @activities.fetch(name.to_sym) do
-          raise KeyError, "Unknown activity: #{name.inspect}. Registered: #{@activities.keys.inspect}"
+      def fetch(name, namespace: nil)
+        key = namespace ? :"#{namespace}:#{name}" : name.to_sym
+        @activities.fetch(key) do
+          raise KeyError, "Unknown activity: #{name.inspect} (namespace: #{namespace.inspect}). Registered: #{@activities.keys.inspect}"
         end
       end
 
-      def names
-        @activities.keys
+      # All registered activity names. Pass +namespace:+ to filter to one
+      # namespace; omit for every activity.
+      def names(namespace: nil)
+        if namespace
+          ns = namespace.to_sym
+          @activities.keys.select { |k| k.to_s.start_with?("#{ns}:") }
+        else
+          @activities.keys
+        end
       end
 
-      def each(&block)
-        @activities.each_value(&block)
+      # Iterate activities. Pass +namespace:+ to scope.
+      def each(namespace: nil, &block)
+        if namespace
+          ns = namespace.to_sym
+          @activities.each_value { |a| block.call(a) if a.namespace == ns }
+        else
+          @activities.each_value(&block)
+        end
+      end
+
+      # Remove all activities, or only those in a namespace.
+      def clear(namespace: nil)
+        if namespace
+          ns = namespace.to_sym
+          @activities.delete_if { |_, a| a.namespace == ns }
+        else
+          @activities.clear
+        end
       end
 
-      def clear
-        @activities.clear
+      # True when an activity (optionally in a namespace) is registered.
+      def registered?(name, namespace: nil)
+        key = namespace ? :"#{namespace}:#{name}" : name.to_sym
+        @activities.key?(key)
       end
     end
   end

data/lib/ask/tokens/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Tokens
-    VERSION = "0.2.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/ask/tokens/wallet.rb

@@ -38,13 +38,17 @@ module Ask
       end
 
       # Estimated token cost of running +activity+ with +params+.
-      def estimate(activity_name, params = {})
-        Ask::Tokens.estimate(activity_name, params)
+      # Pass +namespace:+ to resolve a namespaced activity.
+      # Params may be passed positionally as a Hash or as keyword arguments.
+      def estimate(activity_name, params = {}, namespace: nil, **extra)
+        params = params.merge(extra) unless extra.empty?
+        Ask::Tokens.estimate(activity_name, params, namespace: namespace)
       end
 
       # True when the balance covers the estimated cost of an activity.
-      def enough_for?(activity_name, params = {})
-        has?(estimate(activity_name, params))
+      def enough_for?(activity_name, params = {}, namespace: nil, **extra)
+        params = params.merge(extra) unless extra.empty?
+        has?(estimate(activity_name, params, namespace: namespace))
       end
 
       # Total tokens debited since +time+ (absolute value). Useful for
@@ -84,8 +88,11 @@ module Ask
       # Spend the estimated token cost of +activity+ given +params+. With a
       # block, charge only if the block succeeds — the standard wrapper for
       # LLM calls and render jobs.
-      def spend!(activity_name, params = {}, &block)
-        amount = estimate(activity_name, params)
+      #
+      # Pass +namespace:+ to resolve a namespaced activity.
+      def spend!(activity_name, params = {}, namespace: nil, **extra, &block)
+        params = params.merge(extra) unless extra.empty?
+        amount = estimate(activity_name, params, namespace: namespace)
         deduct!(amount, reason: activity_name.to_s, metadata: params.dup, &block)
       end
 

data/lib/ask/tokens.rb

@@ -85,14 +85,23 @@ module Ask
 
       # Register an activity. +cost:+ is a fixed integer; without it the block
       # receives params and must return an integer token count.
-      def activity(name, cost: nil, &block)
-        activities.register(name, cost: cost, &block)
+      #
+      # Pass +namespace:+ to scope the activity to a project or service so
+      # that multiple projects sharing one registry never collide on a
+      # common name like :compute_hour:
+      #
+      #   Ask::Tokens.activity(:compute_hour, namespace: :ship, cost: 34)
+      #
+      def activity(name, cost: nil, namespace: nil, &block)
+        activities.register(name, cost: cost, namespace: namespace, &block)
       end
 
       # The estimated token cost of running +activity+ with +params+, without
-      # spending anything.
-      def estimate(activity_name, params = {})
-        activities.fetch(activity_name).cost(params)
+      # spending anything. Pass +namespace:+ to resolve a scoped activity.
+      # Params may be passed positionally as a Hash or as keyword arguments.
+      def estimate(activity_name, params = {}, namespace: nil, **extra)
+        params = params.merge(extra) unless extra.empty?
+        activities.fetch(activity_name, namespace: namespace).cost(params)
       end
 
       def activities
@@ -100,9 +109,11 @@ module Ask
       end
 
       # Build a wallet for +owner+. +owner+ is an opaque identifier the store
-      # keys on.
-      def wallet_for(owner)
-        Wallet.new(owner: owner, store: config.store, time: config.time)
+      # keys on. Pass +store:+ to override the configured store — useful for
+      # tests and for a billing service that routes different owners to
+      # different backends.
+      def wallet_for(owner, store: nil)
+        Wallet.new(owner: owner, store: (store || config.store), time: config.time)
       end
 
       # Reset configuration and activity registry (mainly for tests).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-tokens
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Kaka Ruto