token_hawk 0.1.0

data/lib/token_hawk/pricing.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  module Pricing
+    RATES = {
+      # Anthropic — Claude 4 family
+      "claude-opus-4-7"           => { vendor: "anthropic", input: 1.5,   output: 7.5   },
+      "claude-opus-4-8"           => { vendor: "anthropic", input: 1.5,   output: 7.5   },
+      "claude-sonnet-4-6"         => { vendor: "anthropic", input: 0.3,   output: 1.5   },
+      "claude-haiku-4-5"          => { vendor: "anthropic", input: 0.025, output: 0.125 },
+      "claude-haiku-4-5-20251001" => { vendor: "anthropic", input: 0.025, output: 0.125 },
+      # OpenAI — GPT-4o and o1 families
+      "gpt-4o"                    => { vendor: "openai",    input: 0.25,  output: 1.0   },
+      "gpt-4o-mini"               => { vendor: "openai",    input: 0.015, output: 0.06  },
+      "o1"                        => { vendor: "openai",    input: 1.5,   output: 6.0   },
+      "o1-mini"                   => { vendor: "openai",    input: 0.3,   output: 1.2   }
+    }.freeze
+
+    VENDOR_PREFIXES = {
+      "claude" => "anthropic",
+      "gpt"    => "openai",
+      "o1"     => "openai",
+      "o3"     => "openai"
+    }.freeze
+
+    def self.for_model(model)
+      entry = TokenHawk.configuration.pricing[model.to_s] || RATES[model.to_s]
+      return nil unless entry
+
+      { input: entry[:input].to_f, output: entry[:output].to_f }
+    end
+
+    def self.vendor_for_model(model)
+      entry = TokenHawk.configuration.pricing[model.to_s] || RATES[model.to_s]
+      return entry[:vendor] if entry
+
+      prefix = VENDOR_PREFIXES.keys.find { |p| model.to_s.start_with?(p) }
+      prefix ? VENDOR_PREFIXES[prefix] : "unknown"
+    end
+  end
+end

data/lib/token_hawk/recent_query.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  class RecentQuery
+    def initialize(domain: nil, limit: 50)
+      @domain = domain
+      @limit  = limit
+    end
+
+    def calls
+      scope = CallRecord.order(created_at: :desc).limit(@limit)
+      scope = scope.for_domain(@domain) if @domain
+      scope
+    end
+  end
+end

data/lib/token_hawk/response_adapter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  class ResponseAdapter
+    def extract_model(response)
+      response.model if response.respond_to?(:model)
+    end
+
+    def extract_input_tokens(response)
+      return nil unless response.respond_to?(:usage) && response.usage
+      response.usage.input_tokens
+    end
+
+    def extract_output_tokens(response)
+      return nil unless response.respond_to?(:usage) && response.usage
+      response.usage.output_tokens
+    end
+
+    def vendor_name(response)
+      Pricing.vendor_for_model(extract_model(response).to_s)
+    end
+  end
+end

data/lib/token_hawk/storage/active_record.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  module Storage
+    class ActiveRecord
+      class << self
+        def record(call)
+          CallRecord.create!(
+            domain: call.domain.to_s,
+            tags: call.tags,
+            vendor: call.vendor,
+            model: call.model,
+            input_tokens: call.input_tokens,
+            output_tokens: call.output_tokens,
+            total_cost_cents: call.total_cost_cents,
+            latency_ms: call.latency_ms,
+            created_at: call.created_at
+          )
+        end
+
+        def all
+          CallRecord.all.map { |r| to_call(r) }
+        end
+
+        def where(domain: nil, since: nil)
+          scope = CallRecord.all
+          scope = scope.for_domain(domain.to_s) if domain
+          scope = scope.since(since) if since
+          scope.map { |r| to_call(r) }
+        end
+
+        def clear
+          CallRecord.delete_all
+        end
+
+        private
+
+        def to_call(record)
+          Call.new(
+            domain: record.domain.to_sym,
+            tags: record.tags,
+            vendor: record.vendor,
+            model: record.model,
+            input_tokens: record.input_tokens,
+            output_tokens: record.output_tokens,
+            total_cost_cents: record.total_cost_cents,
+            latency_ms: record.latency_ms,
+            created_at: record.created_at
+          )
+        end
+      end
+    end
+  end
+end

data/lib/token_hawk/storage/memory.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  module Storage
+    class Memory
+      @calls = []
+      @mutex = Mutex.new
+
+      class << self
+        def record(call)
+          @mutex.synchronize { @calls << call }
+        end
+
+        def all
+          @mutex.synchronize { @calls.dup }
+        end
+
+        def where(domain: nil, since: nil)
+          @mutex.synchronize do
+            @calls.select do |call|
+              (domain.nil? || call.domain == domain) &&
+                (since.nil? || call.created_at >= since)
+            end
+          end
+        end
+
+        def clear
+          @mutex.synchronize { @calls.clear }
+        end
+      end
+    end
+  end
+end

data/lib/token_hawk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  VERSION = "0.1.0"
+end

data/lib/token_hawk.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "token_hawk/version"
+require_relative "token_hawk/configuration"
+require_relative "token_hawk/engine" if defined?(Rails)
+require_relative "token_hawk/call"
+require_relative "token_hawk/pricing"
+require_relative "token_hawk/cost"
+require_relative "token_hawk/adapters/base"
+require_relative "token_hawk/response_adapter"
+require_relative "token_hawk/storage/memory"
+require_relative "token_hawk/storage/active_record"
+require_relative "token_hawk/call_record"
+require_relative "token_hawk/dashboard_query"
+require_relative "token_hawk/domain_query"
+require_relative "token_hawk/recent_query"
+
+module TokenHawk
+  class Error < StandardError; end
+
+  @subscribers    = Hash.new { |h, k| h[k] = [] }
+  @configuration  = Configuration.new
+
+  def self.configuration
+    @configuration
+  end
+
+  def self.configure
+    yield @configuration
+  end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+
+  def self.subscribe(event, &block)
+    @subscribers[event] << block
+  end
+
+  def self.clear_subscribers
+    @subscribers.clear
+  end
+
+  def self.track(domain:, tags: {})
+    start_time = Time.now
+    response = yield
+    elapsed_ms = ((Time.now - start_time) * 1000).round
+
+    begin
+      record_call(domain: domain, tags: tags, response: response, elapsed_ms: elapsed_ms)
+    rescue => e
+      configuration.failure_logger.call("[TokenHawk] Failed to record telemetry: #{e.message}") if configuration.log_failures
+    end
+
+    response
+  end
+
+  def self.record(domain:, model:, input_tokens:, output_tokens:, latency_ms:, tags: {})
+    call = Call.new(
+      domain: domain.to_sym,
+      tags: tags,
+      vendor: Pricing.vendor_for_model(model.to_s),
+      model: model.to_s,
+      input_tokens: input_tokens.to_i,
+      output_tokens: output_tokens.to_i,
+      total_cost_cents: Cost.calculate(model: model.to_s, input_tokens: input_tokens.to_i, output_tokens: output_tokens.to_i),
+      latency_ms: latency_ms.to_i,
+      created_at: Time.now
+    )
+
+    storage_backend.record(call)
+
+    @subscribers[:call_recorded].each do |subscriber|
+      subscriber.call(call)
+    rescue => e
+      configuration.failure_logger.call("[TokenHawk] Subscriber error: #{e.message}") if configuration.log_failures
+    end
+  rescue => e
+    configuration.failure_logger.call("[TokenHawk] Failed to record telemetry: #{e.message}") if configuration.log_failures
+  end
+
+  def self.record_call(domain:, tags:, response:, elapsed_ms:)
+    adapter = ResponseAdapter.new
+    model = adapter.extract_model(response)
+    input_tokens = adapter.extract_input_tokens(response)
+    output_tokens = adapter.extract_output_tokens(response)
+
+    if model.nil? && input_tokens.nil?
+      configuration.failure_logger.call("[TokenHawk] Could not extract telemetry from response — skipping record.") if configuration.log_failures
+      return
+    end
+
+    call = Call.new(
+      domain: domain,
+      tags: tags,
+      vendor: adapter.vendor_name(response),
+      model: model.to_s,
+      input_tokens: input_tokens.to_i,
+      output_tokens: output_tokens.to_i,
+      total_cost_cents: Cost.calculate(model: model.to_s, input_tokens: input_tokens.to_i, output_tokens: output_tokens.to_i),
+      latency_ms: elapsed_ms,
+      created_at: Time.now
+    )
+
+    storage_backend.record(call)
+
+    @subscribers[:call_recorded].each do |subscriber|
+      subscriber.call(call)
+    rescue => e
+      configuration.failure_logger.call("[TokenHawk] Subscriber error: #{e.message}") if configuration.log_failures
+    end
+  end
+  def self.storage_backend
+    case configuration.storage
+    when :memory        then Storage::Memory
+    when :active_record then Storage::ActiveRecord
+    else raise Error, "Unknown storage backend: #{configuration.storage.inspect}"
+    end
+  end
+
+  private_class_method :record_call, :storage_backend
+end

data/sig/token_hawk.rbs

@@ -0,0 +1,4 @@
+module TokenHawk
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,172 @@
+--- !ruby/object:Gem::Specification
+name: token_hawk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rockwell Windsor Rice
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-09-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Wrap LLM API calls with a single block to capture token counts, latency,
+  and cost per call — attributed by domain and tagged with arbitrary metadata. Persists
+  to your own Postgres database. No SaaS required.
+email:
+- rockwellwindsor@gmail.com
+executables:
+- token_hawk
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/stylesheets/token_hawk/application.css
+- app/controllers/token_hawk/application_controller.rb
+- app/controllers/token_hawk/dashboard_controller.rb
+- app/controllers/token_hawk/domains_controller.rb
+- app/controllers/token_hawk/pricing_controller.rb
+- app/controllers/token_hawk/recent_controller.rb
+- app/views/layouts/token_hawk/application.html.erb
+- app/views/token_hawk/dashboard/index.html.erb
+- app/views/token_hawk/domains/show.html.erb
+- app/views/token_hawk/pricing/index.html.erb
+- app/views/token_hawk/recent/index.html.erb
+- config/routes.rb
+- db/migrate/01_create_token_hawk_calls.rb
+- db/migrate/02_create_token_hawk_llm_rates.rb
+- docs/cli.md
+- docs/configuration.md
+- docs/dashboard.md
+- docs/subscribe_hooks.md
+- exe/token_hawk
+- lib/generators/token_hawk/install/install_generator.rb
+- lib/generators/token_hawk/install/templates/create_token_hawk_calls.rb
+- lib/generators/token_hawk/install/templates/token_hawk.rb
+- lib/token_hawk.rb
+- lib/token_hawk/adapters/base.rb
+- lib/token_hawk/call.rb
+- lib/token_hawk/call_record.rb
+- lib/token_hawk/cli.rb
+- lib/token_hawk/cli/commands/costs.rb
+- lib/token_hawk/cli/commands/efficiency.rb
+- lib/token_hawk/cli/commands/recent.rb
+- lib/token_hawk/cli/formatter.rb
+- lib/token_hawk/configuration.rb
+- lib/token_hawk/cost.rb
+- lib/token_hawk/dashboard_query.rb
+- lib/token_hawk/domain_query.rb
+- lib/token_hawk/engine.rb
+- lib/token_hawk/pricing.rb
+- lib/token_hawk/recent_query.rb
+- lib/token_hawk/response_adapter.rb
+- lib/token_hawk/storage/active_record.rb
+- lib/token_hawk/storage/memory.rb
+- lib/token_hawk/version.rb
+- sig/token_hawk.rbs
+homepage: https://github.com/rockwellwindsor/token_hawk
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rockwellwindsor/token_hawk
+  source_code_uri: https://github.com/rockwellwindsor/token_hawk
+  changelog_uri: https://github.com/rockwellwindsor/token_hawk/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Code-native LLM cost attribution for Rails applications.
+test_files: []