ask-token-usage 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f04950df36b2add93c891d335a6a924d15fb8d3624fc968d91a5799dc1b0631d
+  data.tar.gz: 1f712474ef58866ddc0da6e36b08ac1a456fcf48e53ead880a48b0bd8ecb5d48
+SHA512:
+  metadata.gz: ede62ff37ca85eb92d4280cdfc0b69ea8d48e0bbcc5b69de6cd93b7116aefd5b42d15d8a589d3b6522d608dd4b2effc6d7e6e2f8d08659eef795fad3751981f1
+  data.tar.gz: 1e3851ffa4a7edee4c29ec1c4ed230c241760608a4cad6d152b2d974de91b3a2da296640318146f0ab18d8a9d2083d7969e64436bf250d1cf3fbcdd9d14db9db

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.1.0] - 2026-08-19
+
+### Added
+- `Ask::TokenUsage` — pure-Ruby token accounting foundation. No Rails dependency.
+- Token counting via tiktoken_ruby (`count_tokens`, model-aware encoding, cl100k_base fallback).
+- Pricing via Money gem (`price`, `tokens_for`, `cents_for`) at a configurable per-million rate.
+- Activity DSL: declare fixed or dynamic costs; block receives params and returns an integer.
+- Wallet engine: `grant!`, `deduct!`, `spend!` (block form for atomic deduct-on-success), `balance`, `has?`, `estimate`, `entries`, `used_since`.
+- `LedgerEntry` immutable value object (grant/debit/adjustment/expiry).
+- `Stores::Memory` in-memory store with a reentrant monitor for concurrent access.
+- `Stores::Store` port for custom backends.
+- Callbacks: `on_grant`, `on_spend`, `on_insufficient` with `CallbackContext`.
+- Configuration: store, rounding, negatives, currency, price_per_1m, time provider.
+- Standard ask-gem infrastructure: CI matrix (Ruby 3.2–3.4), rubocop, overcommit, SimpleCov toggle.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/ask/token_usage/activity.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Ask
+  module TokenUsage
+    # A named activity with a token cost.
+    #
+    #   Ask::TokenUsage.activity(:document_render, cost: 10)
+    #   Ask::TokenUsage.activity(:chat_message) do |params|
+    #     Ask::TokenUsage.count_tokens(params[:input]) + ...
+    #   end
+    #
+    class Activity
+      attr_reader :name
+
+      def initialize(name, cost: nil, &block)
+        raise ArgumentError, "activity #{name.inspect} needs a cost or a block" if cost.nil? && block.nil?
+
+        @name = name.to_sym
+        @cost = cost
+        @block = block
+      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).
+      def cost(params = {})
+        raw = if @block
+                @block.arity.zero? ? @block.call : @block.call(params)
+              elsif @cost.respond_to?(:call)
+                @cost.arity.zero? ? @cost.call : @cost.call(params)
+              else
+                @cost
+              end
+
+        Ask::TokenUsage.config.round(raw)
+      end
+
+      def to_s
+        "Activity(#{@name})"
+      end
+
+      def inspect
+        to_s
+      end
+    end
+  end
+end

data/lib/ask/token_usage/activity_registry.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Ask
+  module TokenUsage
+    # Stores declared activities by name.
+    class ActivityRegistry
+      def initialize
+        @activities = {}
+      end
+
+      def register(name, cost: nil, &block)
+        activity = Activity.new(name, cost: cost, &block)
+        @activities[activity.name] = activity
+      end
+
+      def fetch(name)
+        @activities.fetch(name.to_sym) do
+          raise KeyError, "Unknown activity: #{name.inspect}. Registered: #{@activities.keys.inspect}"
+        end
+      end
+
+      def names
+        @activities.keys
+      end
+
+      def each(&block)
+        @activities.each_value(&block)
+      end
+
+      def clear
+        @activities.clear
+      end
+    end
+  end
+end

data/lib/ask/token_usage/callback_context.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Ask
+  module TokenUsage
+    # Payload delivered to configured callbacks (on_grant, on_spend,
+    # on_insufficient).
+    #
+    CallbackContext = Data.define(
+      :owner,     # the wallet owner identifier
+      :event,     # :grant | :spend | :insufficient
+      :amount,    # signed integer
+      :reason,    # string
+      :metadata,  # hash
+      :entry,     # the LedgerEntry written for :grant/:spend
+      :previous_balance,
+      :new_balance
+    ) do
+      def insufficient?
+        event == :insufficient
+      end
+    end
+  end
+end

data/lib/ask/token_usage/configuration.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "money"
+
+module Ask
+  module TokenUsage
+    # Global configuration for ask-token-usage.
+    #
+    #   Ask::TokenUsage.configure do |config|
+    #     config.store          = Ask::TokenUsage::Stores::Memory.new
+    #     config.price_per_token = 0.0001   # $0.0001 per token
+    #     config.rounding       = :ceil
+    #     config.negatives      = false
+    #     config.currency       = "USD"
+    #   end
+    #
+    class Configuration
+      # The store backing every wallet. Defaults to a process-wide in-memory
+      # store; swap for an ActiveRecord-backed store via ask-token-usage-rails.
+      attr_accessor :store
+
+      # Token-cost rounding: :ceil (default), :floor, or :round.
+      attr_accessor :rounding
+
+      # Allow balances to go below zero. Defaults to false.
+      attr_accessor :negatives
+
+      # ISO currency code used by pricing. Defaults to "USD".
+      attr_accessor :currency
+
+      # Hook called after tokens are granted. Receives a CallbackContext.
+      attr_writer :on_grant
+
+      # Hook called after tokens are deducted. Receives a CallbackContext.
+      attr_writer :on_spend
+
+      # Hook called when balance is manually adjusted. Receives a CallbackContext.
+      attr_writer :on_adjust
+
+      # Hook called when a spend is rejected for insufficient balance.
+      # Receives a CallbackContext (executed before InsufficientTokens raises).
+      attr_writer :on_insufficient
+
+      # Injectable time source for deterministic expiry tests.
+      attr_writer :time
+
+      def initialize
+        @store = Stores::Memory.new
+        @rounding = :ceil
+        @negatives = false
+        @currency = "USD"
+        @on_grant = nil
+        @on_spend = nil
+        @on_adjust = nil
+        @on_insufficient = nil
+        @time = -> { Time.now }
+      end
+
+      # Set the price of a single billing token in USD (or your currency).
+      # Provide a numeric value or a Money object.
+      #
+      #   config.price_per_token = 0.0001    # $0.0001 / token
+      #   config.price_per_token = Money.from_amount(0.0001, "USD")
+      #
+      def price_per_token=(value)
+        @price_per_token = value.is_a?(Money) ? value : Money.from_amount(value.to_d, currency)
+      end
+
+      # The configured Money value of one billing token. Raises when unset.
+      def price_per_token
+        return @price_per_token if defined?(@price_per_token) && @price_per_token
+
+        raise Error, "Ask::TokenUsage.configure { |c| c.price_per_token = ... } is not set; pricing needs it"
+      end
+
+      def time(&block)
+        @time = block if block
+        @time
+      end
+
+      def on_grant(&block)
+        @on_grant = block if block
+        @on_grant
+      end
+
+      def on_spend(&block)
+        @on_spend = block if block
+        @on_spend
+      end
+
+      def on_adjust(&block)
+        @on_adjust = block if block
+        @on_adjust
+      end
+
+      def on_insufficient(&block)
+        @on_insufficient = block if block
+        @on_insufficient
+      end
+
+      def round(amount)
+        number = amount.to_d
+        case rounding
+        when :ceil then number.ceil
+        when :floor then number.floor
+        when :round then number.round
+        else number.to_i
+        end
+      end
+    end
+
+    class Error < StandardError; end
+  end
+end

data/lib/ask/token_usage/counting.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "tiktoken_ruby"
+
+module Ask
+  module TokenUsage
+    # Real token measurement via tiktoken_ruby (OpenAI's BPE tokenizer).
+    # This is what turns "a page of text" into a countable, sellable number.
+    #
+    module Counting
+      DEFAULT_ENCODING = "cl100k_base"
+
+      module_function
+
+      # Count the tokens in +text+. Pass +model:+ for a model-aware encoding.
+      # Unknown models fall back to the default encoding; if even tiktoken
+      # fails we estimate at ~4 chars per token rather than blowing up.
+      def count(text, model: nil)
+        encoding_for(model).encode(text.to_s).length
+      rescue StandardError
+        estimate(text.to_s)
+      end
+
+      def encoding_for(model)
+        if model
+          enc = Tiktoken.encoding_for_model(model)
+          return enc if enc
+        end
+
+        Tiktoken.get_encoding(DEFAULT_ENCODING)
+      end
+
+      # Coarse fallback estimate (~4 characters per token).
+      def estimate(text)
+        (text.to_s.length / 4.0).ceil
+      end
+    end
+  end
+end

data/lib/ask/token_usage/instrumentation.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Ask
+  module TokenUsage
+    # Optional bridge to ask-instrumentation events. When installed, every
+    # LLM chat completion (chat.ask / chat.stream.ask) automatically deducts
+    # the measured token cost from the caller's wallet.
+    #
+    #   require "ask/token_usage/instrumentation"
+    #
+    #   Ask::TokenUsage::Instrumentation.install do |event|
+    #     # Return the owner (wallet key) for this LLM call, or nil to skip.
+    #     event.payload[:workspace]   # whatever object/identifier you key wallets on
+    #   end
+    #
+    # The block receives every matching instrumentation event and must return
+    # either the wallet owner or nil. Token cost is computed from the
+    # +input_tokens+/+output_tokens+ reported in the event payload.
+    #
+    # Requires ask-instrumentation as a runtime dependency. The gem works
+    # without it; this file is only loaded when explicitly required.
+    #
+    module Instrumentation
+      PATTERNS = %w[chat.ask chat.stream.ask].freeze
+
+      module_function
+
+      # Subscribe to ask-instrumentation chat events. +&block+ receives
+      # each event and must return the wallet owner (for the wallet) or nil
+      # to skip deduction. Idempotent — calling install twice is safe.
+      def install(&block)
+        return if @installed
+
+        raise ArgumentError, "block is required — it maps each event to a wallet owner" unless block
+
+        @owner_resolver = block
+        @installed = true
+
+        ActiveSupport::Notifications.subscribe(/chat(\.stream)?\.ask/) do |_name, _start, _finish, _id, payload|
+          handle_event(payload)
+        end
+      end
+
+      def uninstall
+        ActiveSupport::Notifications.unsubscribe(/chat(\.stream)?\.ask/)
+        @owner_resolver = nil
+        @installed = false
+      end
+
+      def installed?
+        @installed
+      end
+
+      def handle_event(payload)
+        owner = @owner_resolver.call(payload)
+        return unless owner
+
+        wallet = Ask::TokenUsage.wallet_for(owner)
+        input  = payload[:usage] ? payload[:usage][:input_tokens].to_i : payload[:input_tokens].to_i
+        output = payload[:usage] ? payload[:usage][:output_tokens].to_i : payload[:output_tokens].to_i
+        tokens = input + output
+        return if tokens <= 0
+
+        model    = payload[:model] || payload[:model_id]
+        provider = payload[:provider]
+
+        wallet.deduct!(tokens,
+          reason: :llm_call,
+          metadata: {
+            input_tokens: input,
+            output_tokens: output,
+            model_id: model,
+            provider: provider
+          })
+      rescue InsufficientTokens
+        # let the caller handle insufficient — this module only auto-deducts
+        # when the wallet can cover the cost.
+      rescue StandardError => e
+        warn "[ask-token-usage instrumentation] failed to deduct: #{e.class}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ask/token_usage/insufficient_tokens.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Ask
+  module TokenUsage
+    # Raised when a spend is attempted but the wallet has insufficient tokens.
+    # Also fired to the configured on_insufficient callback before raising.
+    #
+    class InsufficientTokens < StandardError
+      attr_reader :required, :available
+
+      def initialize(required:, available:)
+        @required = required
+        @available = available
+        super("Insufficient tokens: need #{required}, have #{available}")
+      end
+    end
+  end
+end

data/lib/ask/token_usage/ledger_entry.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Ask
+  module TokenUsage
+    # An immutable entry in a wallet's ledger.
+    #
+    # +kind+ is one of:
+    #   :grant       — tokens added (carries +expires_at+ when expiring)
+    #   :debit       — tokens spent (negative +amount+)
+    #   :adjustment  — manual correction
+    #   :expiry      — tokens removed because their grant expired
+    #
+    # +amount+ is signed: positive for grants/adjustments, negative for
+    # debits and expiries. +balance+ is the wallet's running balance after
+    # the entry.
+    #
+    LedgerEntry = Data.define(:id, :kind, :amount, :reason, :expires_at, :metadata, :balance, :created_at) do
+      def grant?
+        kind == :grant
+      end
+
+      def debit?
+        kind == :debit
+      end
+
+      def adjustment?
+        kind == :adjustment
+      end
+
+      def expiry?
+        kind == :expiry
+      end
+
+      def credit?
+        amount.positive?
+      end
+
+      def debit_amount
+        amount.negative? ? amount.abs : 0
+      end
+    end
+  end
+end

data/lib/ask/token_usage/pricing.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "money"
+
+module Ask
+  module TokenUsage
+    # Price conversions built on the configured per-token rate.
+    #
+    #   Ask::TokenUsage.configure { |c| c.price_per_token = 0.0001 }
+    #   Ask::TokenUsage.price_per_token   # => Money($0.0001)
+    #   Ask::TokenUsage.price_per(1_000)  # => Money($0.10)
+    #   Ask::TokenUsage.tokens_for(10)    # => 100_000
+    #
+    module Pricing
+      module_function
+
+      # Price of +count+ tokens at the configured rate.
+      #
+      #   Ask::TokenUsage.price_per(1_000)      # => Money($0.10)
+      #   Ask::TokenUsage.price_per(1_000_000)   # => Money($100.00)
+      #
+      def price_of(count)
+        Ask::TokenUsage.config.price_per_token * count.to_i
+      end
+
+      # How many billing tokens a Money (or numeric dollar) amount buys.
+      def tokens_for(money)
+        amount = money.is_a?(Money) ? money : Money.from_amount(money.to_d, Ask::TokenUsage.config.currency)
+        return 0 if amount.negative? || amount.zero?
+
+        (amount / Ask::TokenUsage.config.price_per_token).to_i
+      end
+
+      # The price of +count+ tokens in the currency's minor units (cents).
+      def cents_for(count, currency: nil)
+        price_of(count).cents.to_i
+      end
+    end
+  end
+end

data/lib/ask/token_usage/stores/memory.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "store"
+require "monitor"
+
+module Ask
+  module TokenUsage
+    module Stores
+      # In-memory store: per-process state keyed by owner, guarded by one
+      # reentrant monitor. Perfect for scripts, tests, and demos. Every wallet
+      # built without a configured store shares this class's process state via
+      # the default Configuration store.
+      class Memory < Store
+        def initialize
+          @monitor = Monitor.new
+          @balances = Hash.new(0)
+          @ledgers = Hash.new { |hash, key| hash[key] = [] }
+          @next_id = 0
+        end
+
+        def balance(owner)
+          @balances[owner]
+        end
+
+        def entries(owner, kind: nil, since: nil)
+          result = @ledgers[owner]
+          result = result.select { |entry| entry.kind == kind } if kind
+          result = result.select { |entry| entry.created_at >= since } if since
+          result
+        end
+
+        def with_lock(owner)
+          @monitor.synchronize { yield }
+        end
+
+        def append(owner, entry)
+          with_lock(owner) do
+            @next_id += 1
+            persisted = entry.with(id: @next_id)
+            @ledgers[owner] << persisted
+            persisted
+          end
+        end
+
+        def write_balance(owner, balance)
+          with_lock(owner) do
+            @balances[owner] = balance
+          end
+        end      end
+    end
+  end
+end

data/lib/ask/token_usage/stores/store.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Ask
+  module TokenUsage
+    module Stores
+      # The persistence port the wallet engine talks to. The wallet never
+      # touches a database — it goes through this small interface, so the
+      # engine is testable with Stores::Memory and portable to any backend.
+      #
+      # Implementations must be safe under concurrent access: two wallets
+      # mutating the same owner must never corrupt the balance.
+      #
+      class Store
+        # Current balance (Integer) for +owner+, or 0.
+        def balance(owner)
+          raise NotImplementedError
+        end
+
+        # Ledger entries for +owner+, oldest first, filtered by kind and time.
+        def entries(owner, kind: nil, since: nil)
+          raise NotImplementedError
+        end
+
+        # Yields once with exclusive access to +owner+'s balance. All
+        # read-check-write sequences must happen inside this block.
+        def with_lock(owner)
+          raise NotImplementedError
+        end
+
+        # Persist +entry+ (an unpersisted LedgerEntry) for +owner+ and return
+        # the persisted copy (with id/created_at). Must be called inside
+        # with_lock.
+        def append(owner, entry)
+          raise NotImplementedError
+        end
+
+        # Persist the owner's cached balance. Must be called inside with_lock.
+        def write_balance(owner, balance)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/ask/token_usage/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module TokenUsage
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask/token_usage/wallet.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Ask
+  module TokenUsage
+    # The wallet engine: all the business logic of token accounting, written
+    # once against the Store port. No database knowledge lives here.
+    #
+    #   wallet = Ask::TokenUsage.wallet_for("user:42")
+    #   wallet.grant!(1000, reason: :signup, expires_at: 7.days.from_now)
+    #   wallet.spend!(:chat_message, input: "hi", output: "yo") { LLM.chat(...) }
+    #   wallet.balance   # => 998
+    #
+    class Wallet
+      attr_reader :owner
+
+      def initialize(owner:, store:, time: -> { Time.now })
+        @owner = owner
+        @store = store
+        @time = time
+      end
+
+      # ---- Reads -----------------------------------------------------------
+
+      # Current token balance.
+      def balance
+        @store.balance(owner).to_i
+      end
+
+      # Ledger entries, oldest first. Filter by :kind (grant/debit/...) and
+      # :since (Time).
+      def entries(**filters)
+        @store.entries(owner, **filters)
+      end
+
+      # True when the balance covers +amount+.
+      def has?(amount)
+        balance >= amount.to_i
+      end
+
+      # Estimated token cost of running +activity+ with +params+.
+      def estimate(activity_name, params = {})
+        Ask::TokenUsage.estimate(activity_name, params)
+      end
+
+      # True when the balance covers the estimated cost of an activity.
+      def enough_for?(activity_name, params = {})
+        has?(estimate(activity_name, params))
+      end
+
+      # Total tokens debited since +time+ (absolute value). Useful for
+      # monthly-usage reports.
+      def used_since(time)
+        entries(kind: :debit, since: time).sum(&:amount).abs
+      end
+
+      # ---- Mutations -------------------------------------------------------
+
+      # Add +amount+ tokens. +expires_at+ marks the grant as expiring.
+      # Returns the written LedgerEntry.
+      def grant!(amount, reason:, expires_at: nil, metadata: {})
+        amount = amount.to_i
+        raise ArgumentError, "grant amount must be positive (got #{amount})" unless amount.positive?
+
+        mutate(:grant, amount, reason, expires_at: expires_at, metadata: metadata) do |current|
+          previous = current
+          [previous + amount, previous, amount]
+        end
+      end
+
+      # Deduct +amount+ tokens, raising InsufficientTokens when the balance
+      # is too low (unless negatives are allowed). With a block, the block
+      # runs first and tokens are charged only when it succeeds.
+      def deduct!(amount, reason:, metadata: {}, &block)
+        amount = amount.to_i
+        raise ArgumentError, "deduct amount must be positive (got #{amount})" unless amount.positive?
+
+        if block
+          spend_after_success(amount, reason, metadata, &block)
+        else
+          charge(amount, reason, metadata)
+        end
+      end
+
+      # 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)
+        deduct!(amount, reason: activity_name.to_s, metadata: params.dup, &block)
+      end
+
+      # Deduct an exact token cost (same as deduct!, but stays at wallet
+      # level for callers that prefer namespacing).
+      def spend_amount!(amount, reason:, metadata: {}, &block)
+        deduct!(amount, reason: reason, metadata: metadata, &block)
+      end
+
+      # Set the balance to an exact amount, recording the delta as an
+      # adjustment entry. Used by billing systems to reset monthly
+      # allowances (replace remaining balance) or fix incorrect totals.
+      #
+      #   wallet.adjust_balance_to!(10_000, reason: :monthly_reset)
+      #
+      def adjust_balance_to!(amount, reason:, metadata: {})
+        amount = amount.to_i
+        raise ArgumentError, "balance cannot be negative (got #{amount})" if amount.negative? && !Ask::TokenUsage.config.negatives
+
+        @store.with_lock(owner) do
+          previous = @store.balance(owner).to_i
+          delta = amount - previous
+          return nil if delta.zero?
+
+          entry = record(:adjustment, delta, reason.to_s, amount, expires_at: nil, metadata: metadata)
+          dispatch(:on_adjust, :adjustment, delta, reason, metadata, entry, previous, amount)
+          entry
+        end
+      end
+
+      private
+
+      def charge(amount, reason, metadata)
+        @store.with_lock(owner) do
+          previous = @store.balance(owner).to_i
+          ensure_sufficient!(amount, previous)
+
+          new_balance = previous - amount
+          entry = record(:debit, -amount, reason, new_balance, expires_at: nil, metadata: metadata)
+          dispatch(:on_spend, :spend, -amount, reason, metadata, entry, previous, new_balance)
+          entry
+        end
+      end
+
+      # Run the work first, then charge only on success. The pre-check is a
+      # cheap fast path; the authoritative check happens again under the
+      # store lock in #charge, so two concurrent spends can never overspend
+      # even though neither holds the lock while their block runs.
+      def spend_after_success(amount, reason, metadata)
+        ensure_sufficient!(amount, @store.balance(owner).to_i)
+        result = yield
+        charge(amount, reason, metadata)
+        result
+      end
+
+      def mutate(kind, signed_amount, reason, expires_at:, metadata:)
+        @store.with_lock(owner) do
+          previous = @store.balance(owner).to_i
+          new_balance, _, _ = yield(previous)
+
+          entry = record(kind, signed_amount, reason, new_balance, expires_at: expires_at, metadata: metadata)
+          dispatch(:on_grant, kind, signed_amount, reason, metadata, entry, previous, new_balance) if kind == :grant
+          entry
+        end
+      end
+
+      def record(kind, signed_amount, reason, new_balance, expires_at:, metadata: {})
+        entry = LedgerEntry.new(
+          id: nil,
+          kind: kind,
+          amount: signed_amount,
+          reason: reason.to_s,
+          expires_at: expires_at,
+          metadata: metadata,
+          balance: new_balance,
+          created_at: @time.call
+        )
+        persisted = @store.append(owner, entry)
+        @store.write_balance(owner, new_balance)
+        persisted
+      end
+
+      def ensure_sufficient!(amount, available)
+        return if Ask::TokenUsage.config.negatives
+
+        return if available >= amount
+
+        dispatch(:on_insufficient, :insufficient, -amount, nil, {}, nil, available, available)
+        raise InsufficientTokens.new(required: amount, available: available)
+      end
+
+      def dispatch(event, event_name, signed_amount, reason, metadata, entry, previous, new_balance)
+        hook = Ask::TokenUsage.config.public_send(event)
+        return unless hook
+
+        context = CallbackContext.new(
+          owner: owner,
+          event: event_name,
+          amount: signed_amount,
+          reason: reason,
+          metadata: metadata,
+          entry: entry,
+          previous_balance: previous,
+          new_balance: new_balance
+        )
+        hook.call(context)
+      rescue StandardError => e
+        warn "ask-token-usage: #{event} callback raised #{e.class}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ask/token_usage.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "money"
+require "date"
+
+Money.default_infinite_precision = true
+
+require_relative "token_usage/version"
+require_relative "token_usage/configuration"
+require_relative "token_usage/insufficient_tokens"
+require_relative "token_usage/ledger_entry"
+require_relative "token_usage/callback_context"
+require_relative "token_usage/activity"
+require_relative "token_usage/activity_registry"
+require_relative "token_usage/stores/memory"
+require_relative "token_usage/pricing"
+require_relative "token_usage/counting"
+require_relative "token_usage/wallet"
+
+module Ask
+  # Token accounting for anything you sell by measured tokens.
+  #
+  # The gem is Railless by design: it counts real tokens (tiktoken), prices
+  # them against a per-million rate (money), and runs a wallet/ledger engine
+  # on top of a pluggable store. Persistence is the host's job — ship the
+  # in-memory store for scripts/tests, or hand in an ActiveRecord-backed
+  # store (ask-token-usage-rails) inside Rails.
+  #
+  #   Ask::TokenUsage.configure do |c|
+  #     c.price_per_1m = Money.from_amount(100, "USD")
+  #   end
+  #
+  #   Ask::TokenUsage.activity(:chat_message) do |params|
+  #     Ask::TokenUsage.count_tokens(params[:input]) +
+  #       Ask::TokenUsage.count_tokens(params[:output])
+  #   end
+  #
+  #   wallet = Ask::TokenUsage.wallet_for("user:42")
+  #   wallet.grant!(1000, reason: :signup)
+  #   wallet.spend!(:chat_message, input: "hi", output: "yo") do
+  #     LLM.chat(...)   # only charged when the block succeeds
+  #   end
+  #   wallet.balance   # => 996
+  #
+  module TokenUsage
+    class << self
+      # Global configuration.
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config
+      end
+
+      # Count the tokens in +text+ using tiktoken. Pass +model:+ for a
+      # model-aware encoding; unknown models fall back to cl100k_base.
+      def count_tokens(text, model: nil)
+        Counting.count(text, model: model)
+      end
+
+      # Price of +count+ tokens at the configured per-token rate.
+      #
+      #   Ask::TokenUsage.price_per(1_000)      # => Money($0.10)
+      #   Ask::TokenUsage.price_per(1_000_000)   # => Money($100.00)
+      #
+      def price_per(count)
+        Pricing.price_of(count)
+      end
+
+      # The configured Money value of one billing token.
+      def price_per_token
+        config.price_per_token
+      end
+
+      # How many billing tokens a Money amount buys at the configured rate.
+      def tokens_for(money)
+        Pricing.tokens_for(money)
+      end
+
+      # The price of +count+ tokens expressed in cents.
+      def cents_for(count, currency: nil)
+        Pricing.cents_for(count, currency: currency)
+      end
+
+      # 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)
+      end
+
+      # The estimated token cost of running +activity+ with +params+, without
+      # spending anything.
+      def estimate(activity_name, params = {})
+        activities.fetch(activity_name).cost(params)
+      end
+
+      def activities
+        @activities ||= ActivityRegistry.new
+      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)
+      end
+
+      # Reset configuration and activity registry (mainly for tests).
+      def reset!
+        @config = Configuration.new
+        @activities = ActivityRegistry.new
+      end
+    end
+  end
+end

data/lib/ask-token-usage.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "ask/token_usage"

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: ask-token-usage
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: money
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.13'
+- !ruby/object:Gem::Dependency
+  name: tiktoken_ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.5
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A Rails-free foundation for token-based usage tracking. Count real tokens
+  with tiktoken, price them per million, declare activity costs, and run a wallet/ledger
+  engine against a pluggable store. Pair with ask-token-usage-rails for ActiveRecord
+  persistence.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- lib/ask-token-usage.rb
+- lib/ask/token_usage.rb
+- lib/ask/token_usage/activity.rb
+- lib/ask/token_usage/activity_registry.rb
+- lib/ask/token_usage/callback_context.rb
+- lib/ask/token_usage/configuration.rb
+- lib/ask/token_usage/counting.rb
+- lib/ask/token_usage/instrumentation.rb
+- lib/ask/token_usage/insufficient_tokens.rb
+- lib/ask/token_usage/ledger_entry.rb
+- lib/ask/token_usage/pricing.rb
+- lib/ask/token_usage/stores/memory.rb
+- lib/ask/token_usage/stores/store.rb
+- lib/ask/token_usage/version.rb
+- lib/ask/token_usage/wallet.rb
+homepage: https://github.com/ask-rb/ask-token-usage
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-token-usage
+  source_code_uri: https://github.com/ask-rb/ask-token-usage
+  changelog_uri: https://github.com/ask-rb/ask-token-usage/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: 'Pure-Ruby token accounting: count, price, and track token usage'
+test_files: []