ask-guests 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47d3aa99bde7a4fba72632740871294a132d06a492d679c78d5487daa5857506
-  data.tar.gz: 6f937c5d724bd72b036faed46a1490129b37ee59380da63d8ba781b2f243b9db
+  metadata.gz: 4714198941d2dca3569099d2c4f4091bd06adcfa00b74ecbea2d06b1cc9c6977
+  data.tar.gz: 5bcfc52ebd6b29d135bd923b3392221c9342ba1057d131349c4f7f0b0d2025e8
 SHA512:
-  metadata.gz: 7691132899688d326b7014fd010a7887a107958e717ea1da66b7640fe2fb4b4ace845d0f6c5db23f483904ff13e00d19fe4510b69539a2b1ad91a0cf18c9a429
-  data.tar.gz: 7667b6be0f7ab4634020198f0e30566ea1b3338b79747017c3c7460e8910ca664bbf7222c41902f013d0a161e84481df09bf35b1e69c610ca34756e7c701b72a
+  metadata.gz: 4c921fa2484da89d6aef5f00bdf4213bef01bab9df1c25dbc167f61e32672a3b68da54f9f58a47bf7c80b2ad6dcb583dfadb0a7b4a5b187507f209d65c6bdf1f
+  data.tar.gz: 5b8755b9083f995df2adbc6a0679336f343e20d27cb38713f6fab44c2ddc2ebe510878bb08829d8e54fd6cedddab8c88cd1b30377b17294dad23b184d0837740

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.2.0] — 2026-09-16
+
+### Changed
+
+- **Budgets are now named categories instead of policy classes.** Replace
+  `config.policies = [Budget::TurnLimit.new(per_day: 40)]` with
+  `config.categories = {turns: {limit: 40, per: :day}}`. Each category is a
+  named limit with a period (`:day`, `:week`, `:month`) and optionally its
+  own usage key (`parses: {limit: 20, per: :day, usage_key: :uploads}`).
+  Any usage key is meterable — turns, tokens, uploads, messages, or your
+  own.
+- **New budget API:** `allowed?(subject, *categories)`, `remaining(subject,
+  :turns)`, `exceeded(subject)` (categories out of budget), `record!` with
+  keyword usage (`record!(session, turns: 1, tokens: 850)`).
+- `Budget::TurnLimit`, `Budget::TokenQuota`, `Budget::Unlimited`, and
+  `Budget::Policy` are gone; an empty category list means unlimited.
+
 ## [0.1.0] — 2026-09-15
 
 ### Added

data/README.md

@@ -11,7 +11,7 @@ Four concepts, one gem:
 |---|---|
 | **Identity** | A random session id behind an HMAC-signed token. No fake `User` rows, nothing to enumerate without the secret. |
 | **Ownership** | Hosts register claimable handlers; records owned by a guest carry its session id. |
-| **Metering** | Daily turn/token budgets (composable policies) with automatic rollover — bound anonymous AI spend. |
+| **Metering** | Named budget categories (`turns: 40/day`, `tokens: 10k/day`, `uploads: 5/day`, …) with automatic period rollover — bound anonymous AI spend. |
 | **Claim** | On sign-up/sign-in, transfer all guest records in one transaction, exactly once. |
 
 Plus retention: unclaimed sessions are swept after a configurable window.
@@ -46,7 +46,10 @@ the model and controller wiring.
 Ask::Guests.configure do |config|
   config.secret = ENV.fetch("GUEST_TOKEN_SECRET")
   config.store = Ask::Guests::Stores::Memory.new
-  config.policies = [Ask::Guests::Budget::TurnLimit.new(per_day: 40)]
+  config.categories = {
+    turns:  {limit: 40,     per: :day},
+    tokens: {limit: 10_000, per: :day}
+  }
   config.retention = 14 * 24 * 60 * 60 # seconds
 end
 
@@ -77,14 +80,26 @@ response = agent.run(prompt)
 budget.record!(guest_session, turns: 1, tokens: response.input_tokens + response.output_tokens)
 ```
 
-Policies compose — a guest is allowed only while every policy has budget
-left, and counters roll over daily with no scheduled work:
+Categories compose — a guest is allowed only while every category has
+budget left in its period, and counters roll over with no scheduled work.
+Periods are `:day`, `:week`, or `:month`; any usage key can be metered,
+including your own (uploads, parses, messages):
 
 ```ruby
-config.policies = [
-  Ask::Guests::Budget::TurnLimit.new(per_day: 40),
-  Ask::Guests::Budget::TokenQuota.new(per_day: 10_000)
-]
+config.categories = {
+  turns:    {limit: 40,     per: :day},
+  tokens:   {limit: 10_000, per: :day},
+  uploads:  {limit: 5,      per: :day},
+  messages: {limit: 100,    per: :month},
+  parses:   {limit: 20,     per: :day, usage_key: :uploads} # meter one key as another category
+}
+
+budget = Ask::Guests.budget
+budget.allowed?(guest)                    # all categories
+budget.allowed?(guest, :turns)            # one category
+budget.remaining(guest, :turns)           # => 12
+budget.exceeded(guest)                    # => [:tokens]
+budget.record!(guest, turns: 1, tokens: 850)
 ```
 
 ### Claiming on sign-up
@@ -121,7 +136,7 @@ end
 Ask::Guests.configure do |config|
   config.secret = Rails.application.secret_key_base
   config.store = Ask::Guests::ActiveRecord::SessionStore.new(model: GuestSession)
-  config.policies = [Ask::Guests::Budget::TurnLimit.new(per_day: 40)]
+  config.categories = {turns: {limit: 40, per: :day}}
 end
 ```
 

data/lib/ask/guests/budget/category.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    class Budget
+      # A named budget line: a limit on one usage category per period.
+      #
+      #   Category.new(:turns,   limit: 40,     per: :day)
+      #   Category.new(:tokens,  limit: 10_000, per: :day)
+      #   Category.new(:uploads, limit: 5,      per: :day)
+      #   Category.new(:messages, limit: 100,   per: :month)
+      #
+      # Usage is recorded by keyword and consumed by the category with the
+      # same name:
+      #
+      #   budget.record!(session, turns: 1, tokens: 850, uploads: 1)
+      #
+      # A category may meter a different usage key with +usage_key+ (for
+      # example, counting "parses" while the call site reports uploads).
+      #
+      # Counters live on the subject and store a period bucket alongside
+      # the count ("day" resets at midnight UTC, "week" on ISO weeks,
+      # "month" on calendar months), so rollover is automatic and needs no
+      # scheduled work.
+      class Category
+        PERIODS = %i[day week month].freeze
+
+        attr_reader :name, :limit, :period, :usage_key
+
+        def initialize(name, limit:, per: :day, usage_key: nil)
+          @name = name.to_sym
+          @limit = limit.to_i
+          @period = per.to_sym
+          @usage_key = (usage_key || name).to_sym
+
+          unless PERIODS.include?(@period)
+            raise ArgumentError, "unknown period #{per.inspect} (expected one of #{PERIODS.inspect})"
+          end
+        end
+
+        # @return [Integer] how much this usage costs the category
+        def amount_for(usage)
+          usage.fetch(@usage_key, 0).to_i
+        end
+
+        # @return [Integer] remaining budget for the current period
+        def remaining(subject, time)
+          value = subject.counter_value(counter_key, bucket(time))
+          [@limit - value, 0].max
+        end
+
+        def exceeded?(subject, time)
+          remaining(subject, time).zero?
+        end
+
+        # Records usage on the subject (without persisting — the budget
+        # persists through the store).
+        def record!(subject, usage, time)
+          amount = amount_for(usage)
+          return subject if amount.zero?
+
+          count = subject.counter_value(counter_key, bucket(time)) + amount
+          subject.set_counter!(counter_key, count, bucket(time))
+        end
+
+        # Counter name on the subject.
+        def counter_key
+          @name.to_s
+        end
+
+        # Period bucket key for +time+; a different bucket reads as zero.
+        def bucket(time)
+          utc = time.utc
+          case @period
+          when :day then utc.strftime("%Y-%m-%d")
+          when :week then utc.strftime("%G-W%V")
+          when :month then utc.strftime("%Y-%m")
+          end
+        end
+
+        def to_h
+          {name: name, limit: limit, period: period, usage_key: usage_key}
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/budget.rb

@@ -2,66 +2,104 @@
 
 module Ask
   module Guests
-    # Meters guest usage against one or more policies and records usage
-    # afterwards. Policies are checked collectively: a guest is allowed only
-    # while every policy has budget remaining.
+    # Meters usage against named category budgets and records usage
+    # afterwards. Categories are checked collectively: a subject is allowed
+    # only while every category has budget remaining in its period.
     #
     #   budget = Ask::Guests.budget
-    #   budget.allowed?(session) # => true/false
-    #   budget.remaining(session) # => Integer (minimum across policies)
+    #   budget.allowed?(session)                 # => true/false
+    #   budget.allowed?(session, :turns)         # => one category
+    #   budget.remaining(session, :turns)        # => 12
+    #   budget.exceeded(session)                 # => [:tokens]
     #   budget.record!(session, turns: 1, tokens: 850)
     #
-    # Counters live on the session and roll over daily, so "per day" limits
+    # Counters live on the subject and roll over per period, so limits
     # reset without any scheduled work.
     class Budget
-      attr_reader :policies, :store
+      attr_reader :categories, :store
 
-      def initialize(policies: nil, store: Guests.store, clock: Guests.configuration.clock)
-        @policies = normalize(policies)
+      # @param categories [Array<Category>, Hash, nil] Category objects or
+      #   a hash of +name => {limit:, per:, usage_key:}+. Empty/nil means
+      #   unlimited.
+      def initialize(categories: nil, store: Guests.store, clock: Guests.configuration.clock)
+        @categories = normalize(categories)
         @store = store
         @clock = clock
       end
 
-      # @return [Boolean] true while every policy has budget left
-      def allowed?(session)
-        return true if session.nil?
+      # @param names [Array<Symbol>] restrict the check to these categories
+      # @return [Boolean] true while every checked category has budget left
+      def allowed?(subject, *names)
+        return true if subject.nil?
 
-        policies.all? { |policy| policy.remaining(session, today) > 0 }
+        selected(names).all? { |category| category.remaining(subject, now) > 0 }
       end
 
-      # Minimum remaining budget across policies (Float::INFINITY when no
-      # policy limits usage).
-      def remaining(session)
-        return Float::INFINITY if session.nil?
+      # Remaining budget for one category, or the minimum across all
+      # categories (Float::INFINITY when unlimited).
+      def remaining(subject, name = nil)
+        return Float::INFINITY if subject.nil?
 
-        policies.map { |policy| policy.remaining(session, today) }.min
+        if name
+          category(name).remaining(subject, now)
+        else
+          categories.map { |category| category.remaining(subject, now) }.min || Float::INFINITY
+        end
+      end
+
+      # @return [Array<Symbol>] categories with no budget left this period
+      def exceeded(subject)
+        return [] if subject.nil?
+
+        categories.select { |category| category.exceeded?(subject, now) }.map(&:name)
       end
 
-      # Records usage, persists the session through the store, and returns it.
-      def record!(session, turns: 0, tokens: 0)
-        return session if session.nil?
+      # Records usage, persists the subject through the store, and returns
+      # it. Usage is keyed by category name (or the category's usage_key):
+      #
+      #   budget.record!(session, turns: 1, tokens: 850, uploads: 2)
+      def record!(subject, **usage)
+        return subject if subject.nil?
 
-        policies.each { |policy| policy.record!(session, turns: turns, tokens: tokens, today: today) }
-        store.update(session)
-        session
+        categories.each { |category| category.record!(subject, usage, now) }
+        store.update(subject)
+        subject
       end
 
       def unlimited?
-        policies.all? { |policy| policy.remaining(Session.new(id: "probe"), today) == Float::INFINITY }
+        categories.empty?
+      end
+
+      # @return [Category]
+      def category(name)
+        categories.find { |category| category.name == name.to_sym } ||
+          raise(ArgumentError, "unknown budget category #{name.inspect}")
       end
 
       private
 
-      def normalize(policies)
-        case policies
-        when nil then [Budget::Unlimited.new]
-        when Array then policies
-        else [policies]
-        end
+      def selected(names)
+        return categories if names.nil? || names.empty?
+
+        names.map { |name| category(name) }
+      end
+
+      def now
+        @clock.call
+      end
+
+      def normalize(categories)
+        case categories
+        when nil then []
+        when Hash then categories.flat_map { |name, options| build(name, options) }
+        when Array then categories.flat_map { |entry| entry.is_a?(Hash) ? normalize(entry) : [entry] }
+        else [categories]
+        end.map { |entry| entry.is_a?(Category) ? entry : build(entry, {}) }
       end
 
-      def today
-        @clock.call.utc.strftime("%Y-%m-%d")
+      def build(name, options)
+        options = options.to_h.transform_keys(&:to_sym)
+        [Category.new(name, **options)]
       end
     end
   end

data/lib/ask/guests/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Guests
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/ask/guests.rb

@@ -7,10 +7,7 @@ require_relative "guests/session"
 require_relative "guests/stores/base"
 require_relative "guests/stores/memory"
 require_relative "guests/budget"
-require_relative "guests/budget/policy"
-require_relative "guests/budget/unlimited"
-require_relative "guests/budget/turn_limit"
-require_relative "guests/budget/token_quota"
+require_relative "guests/budget/category"
 require_relative "guests/claim"
 require_relative "guests/sweep"
 
@@ -79,7 +76,7 @@ module Ask
       # so configuration changes (and test resets) always take effect.
       def budget
         Budget.new(
-          policies: configuration.policies,
+          categories: configuration.categories,
           store: configuration.store,
           clock: configuration.clock
         )
@@ -121,8 +118,8 @@ module Ask
       attr_accessor :secret
       # Persistence adapter (see Stores::Base). Defaults to in-memory.
       attr_accessor :store
-      # Usage policies (see Budget::TurnLimit, Budget::TokenQuota).
-      attr_accessor :policies
+      # Budget categories (see Budget::Category): named limits per period.
+      attr_accessor :categories
       # Unclaimed sessions older than this many seconds are swept.
       attr_accessor :retention
       # Injectable clock returning a Time (used for daily counter rollover
@@ -141,7 +138,7 @@ module Ask
       def initialize
         @secret = nil
         @store = Stores::Memory.new
-        @policies = [Budget::Unlimited.new]
+        @categories = []
         @retention = 14 * 24 * 60 * 60
         @clock = -> { Time.now.utc }
         @cookie_name = "guest_session_token"

data/lib/generators/ask/guests/install/templates/initializer.rb

@@ -19,12 +19,15 @@ Ask::Guests.configure do |config|
   #   end
   config.store = Ask::Guests::ActiveRecord::SessionStore.new(model: GuestSession)
 
-  # Usage caps for anonymous visitors. Signing up lifts them because a
-  # signed-in request never touches the guest budget.
-  config.policies = [
-    Ask::Guests::Budget::TurnLimit.new(per_day: 40)
-    # Ask::Guests::Budget::TokenQuota.new(per_day: 10_000)
-  ]
+  # Usage caps for anonymous visitors, one entry per category. Signing up
+  # lifts them because a signed-in request never touches the guest budget.
+  # Periods are :day, :week, or :month; counters roll over automatically.
+  config.categories = {
+    turns:  {limit: 40, per: :day}
+    # tokens:  {limit: 10_000, per: :day},
+    # uploads: {limit: 5,      per: :day},
+    # messages: {limit: 100,   per: :month}
+  }
 
   # Unclaimed sessions inactive for this long are swept (seconds).
   config.retention = 14 * 24 * 60 * 60

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-guests
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -114,10 +114,7 @@ files:
 - lib/ask/guests/active_record/session_base.rb
 - lib/ask/guests/active_record/session_store.rb
 - lib/ask/guests/budget.rb
-- lib/ask/guests/budget/policy.rb
-- lib/ask/guests/budget/token_quota.rb
-- lib/ask/guests/budget/turn_limit.rb
-- lib/ask/guests/budget/unlimited.rb
+- lib/ask/guests/budget/category.rb
 - lib/ask/guests/claim.rb
 - lib/ask/guests/errors.rb
 - lib/ask/guests/rails/claim_on_authentication.rb

data/lib/ask/guests/budget/policy.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  module Guests
-    class Budget
-      # Base class for usage policies. A policy owns one counter key (for
-      # example "turns" or "tokens") and a daily limit for it.
-      #
-      # Subclasses implement +counter_key+, +limit+, and +amount_for+.
-      class Policy
-        # @return [String] counter name on the session
-        def counter_key
-          raise NotImplementedError
-        end
-
-        # @return [Integer, Float::INFINITY] daily limit
-        def limit
-          raise NotImplementedError
-        end
-
-        # @return [Integer] how much this usage costs in counter units
-        def amount_for(turns:, tokens:)
-          raise NotImplementedError
-        end
-
-        # @return [Integer, Float] remaining budget for today
-        def remaining(session, today)
-          value = session.counter_value(counter_key, today)
-          [limit - value, 0].max
-        end
-
-        def record!(session, turns:, tokens:, today:)
-          amount = amount_for(turns: turns, tokens: tokens)
-          return session if amount.to_i.zero?
-
-          count = session.counter_value(counter_key, today) + amount.to_i
-          session.set_counter!(counter_key, count, today)
-        end
-      end
-    end
-  end
-end

data/lib/ask/guests/budget/token_quota.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  module Guests
-    class Budget
-      # Limits tokens per day, for apps that meter actual consumption
-      # (input + output tokens) instead of turns.
-      #
-      #   Budget::TokenQuota.new(per_day: 10_000)
-      class TokenQuota < Policy
-        attr_reader :per_day
-
-        def initialize(per_day:)
-          super()
-          @per_day = per_day.to_i
-        end
-
-        def counter_key = "tokens"
-        def limit = per_day
-        def amount_for(turns:, tokens:) = tokens
-      end
-    end
-  end
-end

data/lib/ask/guests/budget/turn_limit.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  module Guests
-    class Budget
-      # Limits agent turns per day. One "turn" is one agent run — the unit
-      # Kawibot meters.
-      #
-      #   Budget::TurnLimit.new(per_day: 40)
-      class TurnLimit < Policy
-        attr_reader :per_day
-
-        def initialize(per_day:)
-          super()
-          @per_day = per_day.to_i
-        end
-
-        def counter_key = "turns"
-        def limit = per_day
-        def amount_for(turns:, tokens:) = turns
-      end
-    end
-  end
-end

data/lib/ask/guests/budget/unlimited.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  module Guests
-    class Budget
-      # No limits — the default policy. Useful for development and for apps
-      # that meter elsewhere.
-      class Unlimited < Policy
-        def counter_key = "unlimited"
-        def limit = Float::INFINITY
-        def amount_for(turns:, tokens:) = 0
-        def remaining(session, today) = Float::INFINITY
-      end
-    end
-  end
-end