token_hawk 0.1.0

data/docs/dashboard.md

@@ -0,0 +1,73 @@
+# Dashboard
+
+TokenHawk ships a mountable Rails engine with a read-only browser dashboard.
+
+---
+
+## Mounting
+
+```ruby
+# config/routes.rb
+mount TokenHawk::Engine, at: "/token_hawk"
+```
+
+Visit `/token_hawk` to see the overview.
+
+---
+
+## Authentication
+
+The engine has no built-in authentication — it relies on the host app's. Protect the mount point before deploying to production.
+
+**Devise example:**
+
+```ruby
+authenticate :user, ->(u) { u.admin? } do
+  mount TokenHawk::Engine, at: "/token_hawk"
+end
+```
+
+**HTTP Basic (simple staging protection):**
+
+```ruby
+# config/initializers/token_hawk.rb
+TokenHawk::Engine.middleware.use Rack::Auth::Basic, "TokenHawk" do |u, p|
+  ActiveSupport::SecurityUtils.secure_compare(p, ENV.fetch("TOKEN_HAWK_PASSWORD"))
+end
+```
+
+---
+
+## Views
+
+### Overview (`/token_hawk`)
+
+- Total spend for the current calendar month
+- Top 3 domains by cost
+- Daily cost breakdown for the current month
+
+### Domain detail (`/token_hawk/domains/:domain`)
+
+- Total cost, call count, and average cost per call
+- Top tag key-value pairs within the domain
+- 10 most recent calls
+
+Returns 404 for domains with no recorded calls.
+
+### Recent calls (`/token_hawk/recent`)
+
+- Reverse-chronological call log
+- Columns: timestamp, domain, model, input tokens, output tokens, cost, latency
+- Supports `?domain=X` query param to filter
+
+### Pricing reference (`/token_hawk/pricing`)
+
+- All models in the built-in pricing table
+- Input and output rates per 1M tokens
+- Note on rate vintage (rates reflect the gem version release date)
+
+---
+
+## Styling
+
+The engine ships a minimal self-contained stylesheet (`token_hawk/application.css`). It uses system fonts and a neutral palette that won't clash with most host app designs. No Tailwind or external CSS framework required.

data/docs/subscribe_hooks.md

@@ -0,0 +1,81 @@
+# Subscribe Hooks
+
+TokenHawk fires events after every recorded call. Subscribe to react in real time — ship metrics, trigger alerts, or log to a secondary store.
+
+---
+
+## Usage
+
+```ruby
+TokenHawk.subscribe(:call_recorded) do |call|
+  # call is a TokenHawk::Call value object (frozen, immutable)
+end
+```
+
+Place subscriptions in an initializer so they're registered at boot.
+
+---
+
+## The `Call` object
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `domain` | Symbol | Attribution domain |
+| `tags` | Hash | Arbitrary key-value metadata |
+| `vendor` | String | `"anthropic"` or `"openai"` |
+| `model` | String | Model identifier |
+| `input_tokens` | Integer | Prompt tokens |
+| `output_tokens` | Integer | Completion tokens |
+| `total_cost_cents` | Integer | Calculated cost in cents |
+| `latency_ms` | Integer | Wall-clock time of the LLM call |
+| `created_at` | Time | When the call was recorded |
+
+---
+
+## Examples
+
+### StatsD / Datadog
+
+```ruby
+TokenHawk.subscribe(:call_recorded) do |call|
+  tags = ["domain:#{call.domain}", "vendor:#{call.vendor}", "model:#{call.model}"]
+  StatsD.increment("llm.calls", tags: tags)
+  StatsD.gauge("llm.cost_cents", call.total_cost_cents, tags: tags)
+  StatsD.timing("llm.latency_ms", call.latency_ms, tags: tags)
+end
+```
+
+### Budget alerting
+
+```ruby
+TokenHawk.subscribe(:call_recorded) do |call|
+  monthly = TokenHawk::CallRecord
+    .since(Time.now.beginning_of_month)
+    .for_domain(call.domain)
+    .sum(:total_cost_cents)
+
+  if monthly > 10_000 # $100
+    SlackNotifier.alert("#{call.domain} has exceeded $100 this month")
+  end
+end
+```
+
+### Secondary logging
+
+```ruby
+TokenHawk.subscribe(:call_recorded) do |call|
+  Rails.logger.info({
+    event:            "llm_call",
+    domain:           call.domain,
+    model:            call.model,
+    total_cost_cents: call.total_cost_cents,
+    latency_ms:       call.latency_ms
+  }.to_json)
+end
+```
+
+---
+
+## Error handling
+
+Exceptions raised inside a subscriber are rescued and do not propagate to the caller. If `config.log_failures` is true, the error message is passed to `config.failure_logger`.

data/exe/token_hawk

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "token_hawk"
+require "token_hawk/cli"
+
+rails_env = File.expand_path("config/environment.rb", Dir.pwd)
+if File.exist?(rails_env)
+  require rails_env
+elsif ENV["DATABASE_URL"]
+  require "active_record"
+  ActiveRecord::Base.establish_connection(ENV["DATABASE_URL"])
+end
+
+TokenHawk::CLI.start(ARGV)

data/lib/generators/token_hawk/install/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+require "active_record"
+
+module TokenHawk
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Install TokenHawk: copies migrations, creates initializer, mounts engine."
+
+      def self.next_migration_number(path)
+        next_migration_number = current_migration_number(path) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def create_migrations
+        migration_template "create_token_hawk_calls.rb", "db/migrate/create_token_hawk_calls.rb"
+      end
+
+      def create_initializer
+        template "token_hawk.rb", "config/initializers/token_hawk.rb"
+      end
+
+      def mount_engine
+        route 'mount TokenHawk::Engine => "/token_hawk"'
+      end
+
+      def show_readme
+        say "\n✅ TokenHawk installed. Next steps:", :green
+        say "  1. bin/rails db:migrate"
+        say "  2. Attribute LLM calls — two interfaces:"
+        say "       TokenHawk.track(domain: :my_feature) { client.messages.create(...) }"
+        say "       TokenHawk.record(domain: :my_feature, model: \"...\", input_tokens: N, output_tokens: N, latency_ms: N)"
+        say "  3. Visit /token_hawk for the dashboard\n"
+      end
+    end
+  end
+end

data/lib/generators/token_hawk/install/templates/create_token_hawk_calls.rb

@@ -0,0 +1,18 @@
+class CreateTokenHawkCalls < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :token_hawk_calls do |t|
+      t.string  :domain,           null: false
+      t.text    :tags,             null: false, default: "{}"
+      t.string  :vendor,           null: false
+      t.string  :model,            null: false
+      t.integer :input_tokens,     null: false
+      t.integer :output_tokens,    null: false
+      t.integer :total_cost_cents, null: false
+      t.integer :latency_ms,       null: false
+      t.timestamps
+    end
+
+    add_index :token_hawk_calls, :domain
+    add_index :token_hawk_calls, :created_at
+  end
+end

data/lib/generators/token_hawk/install/templates/token_hawk.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+TokenHawk.configure do |config|
+  # Storage backend: :active_record (default) or :memory
+  # config.storage = :active_record
+
+  # Log telemetry failures — set to false to silence them entirely
+  # config.log_failures = true
+
+  # Custom failure logger — must respond to #call
+  # config.failure_logger = ->(msg) { Rails.logger.warn(msg) }
+end

data/lib/token_hawk/adapters/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  module Adapters
+    class Base
+      def vendor_name
+        raise NotImplementedError, "#{self.class} must implement vendor_name"
+      end
+
+      def extract_model(response)
+        raise NotImplementedError, "#{self.class} must implement extract_model"
+      end
+
+      def extract_input_tokens(response)
+        raise NotImplementedError, "#{self.class} must implement extract_input_tokens"
+      end
+
+      def extract_output_tokens(response)
+        raise NotImplementedError, "#{self.class} must implement extract_output_tokens"
+      end
+    end
+  end
+end

data/lib/token_hawk/call.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  Call = Data.define(
+    :domain,
+    :tags,
+    :vendor,
+    :model,
+    :input_tokens,
+    :output_tokens,
+    :total_cost_cents,
+    :latency_ms,
+    :created_at
+  )
+end

data/lib/token_hawk/call_record.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module TokenHawk
+  class CallRecord < ActiveRecord::Base
+    self.table_name = "token_hawk_calls"
+
+    serialize :tags, coder: JSON
+
+    scope :for_domain, ->(name) { where(domain: name) }
+    scope :since,      ->(time) { where("created_at >= ?", time) }
+
+    def self.with_tag(key, value)
+      all.select { |r| r.tags[key.to_s] == value }
+    end
+  end
+end

data/lib/token_hawk/cli/commands/costs.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../formatter"
+
+module TokenHawk
+  class CLI
+    module Commands
+      class Costs
+        include Formatter
+        def initialize(options = {})
+          @options = options
+        end
+
+        def run
+          results = grouped_results(scoped_records)
+          @options["format"] == "json" ? print_json(results) : print_table(results)
+        end
+
+        private
+
+        def scoped_records
+          scope = CallRecord.all
+          scope = scope.for_domain(@options["domain"]) if @options["domain"]
+          scope = scope.since(Time.parse(@options["since"])) if @options["since"]
+          scope
+        end
+
+        def grouped_results(scope)
+          return ruby_grouped_results(scope.to_a) if ruby_path?
+
+          sql_grouped_results(scope)
+        end
+
+        def ruby_path?
+          @options["by"] == "tag" || tag_filter?
+        end
+
+        def tag_filter?
+          @options["tag"] && !@options["tag"].empty? && @options["by"] != "tag"
+        end
+
+        def ruby_grouped_results(records)
+          records = filter_by_tag(records) if tag_filter?
+          return [] if records.empty?
+
+          grouped = if @options["by"] == "tag"
+            records.group_by { |r| r.tags[@options["tag"].to_s].to_s }
+          else
+            records.group_by(&:domain)
+          end
+
+          grouped
+            .map { |key, recs| { "group" => key.to_s, "total_cost_cents" => recs.sum(&:total_cost_cents), "call_count" => recs.size } }
+            .sort_by { |r| -r["total_cost_cents"] }
+        end
+
+        def filter_by_tag(records)
+          key, value = @options["tag"].split("=", 2)
+          records.select { |r| r.tags[key.to_s] == value }
+        end
+
+        def sql_grouped_results(scope)
+          grouped = scope.group(group_expression)
+          costs   = grouped.sum(:total_cost_cents)
+          counts  = grouped.count
+
+          costs
+            .map { |key, total| { "group" => key.to_s, "total_cost_cents" => total, "call_count" => counts[key] || 0 } }
+            .sort_by { |r| -r["total_cost_cents"] }
+        end
+
+        def group_expression
+          @options["by"] == "day" ? Arel.sql("DATE(created_at)") : :domain
+        end
+
+        def print_table(results)
+          return puts("No records found.") if results.empty?
+
+          width = results.map { |r| r["group"].length }.max + 2
+          results.each do |row|
+            puts format("%-#{width}s %8s  %4d calls", row["group"], format_cost(row["total_cost_cents"]), row["call_count"])
+          end
+        end
+
+        def print_json(results)
+          puts JSON.generate(results)
+        end
+      end
+    end
+  end
+end

data/lib/token_hawk/cli/commands/efficiency.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../formatter"
+
+module TokenHawk
+  class CLI
+    module Commands
+      class Efficiency
+        include Formatter
+        def initialize(options = {})
+          @options = options
+        end
+
+        def run
+          results = ranked_results
+          @options["format"] == "json" ? print_json(results) : print_table(results)
+        end
+
+        private
+
+        def ranked_results
+          costs  = CallRecord.group(:domain).sum(:total_cost_cents)
+          counts = CallRecord.group(:domain).count
+
+          costs
+            .map do |domain, total|
+              count = counts[domain] || 1
+              {
+                "domain"              => domain.to_s,
+                "cost_per_call_cents" => (total.to_f / count).round(2),
+                "call_count"          => count
+              }
+            end
+            .sort_by { |r| -r["cost_per_call_cents"] }
+        end
+
+        def print_table(results)
+          return puts("No records found.") if results.empty?
+
+          width = results.map { |r| r["domain"].length }.max + 2
+          results.each do |row|
+            puts format("%-#{width}s %8s/call  %4d calls",
+                        row["domain"], format_cost(row["cost_per_call_cents"].ceil), row["call_count"])
+          end
+        end
+
+        def print_json(results)
+          puts JSON.generate(results)
+        end
+      end
+    end
+  end
+end

data/lib/token_hawk/cli/commands/recent.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../formatter"
+
+module TokenHawk
+  class CLI
+    module Commands
+      class Recent
+        include Formatter
+        def initialize(options = {})
+          @options = options
+        end
+
+        def run
+          records = CallRecord.order(created_at: :desc).limit(limit)
+          @options["format"] == "json" ? print_json(records) : print_table(records)
+        end
+
+        private
+
+        def limit
+          @options.fetch("limit", 20).to_i
+        end
+
+        def print_table(records)
+          return puts("No records found.") if records.empty?
+
+          records.each do |r|
+            puts format("%s  %-24s  %-30s  %s",
+                        r.created_at.strftime("%Y-%m-%d %H:%M:%S"),
+                        r.domain,
+                        r.model,
+                        format_cost(r.total_cost_cents))
+          end
+        end
+
+        def print_json(records)
+          rows = records.map do |r|
+            {
+              "domain"            => r.domain,
+              "model"             => r.model,
+              "total_cost_cents"  => r.total_cost_cents,
+              "created_at"        => r.created_at.iso8601
+            }
+          end
+          puts JSON.generate(rows)
+        end
+      end
+    end
+  end
+end

data/lib/token_hawk/cli/formatter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  class CLI
+    module Formatter
+      def format_cost(cents)
+        return "$#{"%.2f" % (cents / 100.0)}" if cents >= 100
+
+        "#{cents}¢"
+      end
+    end
+  end
+end

data/lib/token_hawk/cli.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module TokenHawk
+  class CLI < Thor
+    desc "costs", "Show LLM costs grouped by domain, day, or tag"
+    method_option :by,     type: :string,  default: "domain", desc: "Group by: domain, day, or tag"
+    method_option :domain, type: :string,  desc: "Filter to a specific domain"
+    method_option :since,  type: :string,  desc: "Filter to records since a time (e.g. '30 days ago')"
+    method_option :tag,    type: :string,  desc: "Filter by tag key=value"
+    method_option :format, type: :string,  default: "text", desc: "Output format: text or json"
+    def costs
+      Commands::Costs.new(options).run
+    end
+
+    desc "efficiency", "Show cost per call by domain, descending"
+    method_option :format, type: :string, default: "text", desc: "Output format: text or json"
+    def efficiency
+      Commands::Efficiency.new(options).run
+    end
+
+    desc "recent", "Show recent LLM calls"
+    method_option :limit,  type: :numeric, default: 20, desc: "Number of records to show"
+    method_option :format, type: :string,  default: "text", desc: "Output format: text or json"
+    def recent
+      Commands::Recent.new(options).run
+    end
+  end
+end
+
+require_relative "cli/commands/costs"
+require_relative "cli/commands/efficiency"
+require_relative "cli/commands/recent"

data/lib/token_hawk/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  # Configuration options for TokenHawk
+  #
+  # @attr storage [Symbol] Storage backend (:active_record, :memory)
+  # @attr log_failures [Boolean] Whether to log failures
+  # @attr failure_logger [Proc] Callable that receives error messages
+  class Configuration
+    attr_accessor :storage, :log_failures, :failure_logger, :pricing
+
+    def initialize
+      @storage        = :active_record
+      @log_failures   = true
+      @failure_logger = ->(msg) { warn msg }
+      @pricing        = {}
+    end
+  end
+end

data/lib/token_hawk/cost.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  module Cost
+    def self.calculate(model:, input_tokens:, output_tokens:)
+      rates = Pricing.for_model(model)
+
+      unless rates
+        warn "[TokenHawk] Looks like you may need to add an entry for #{model.inspect} — " \
+             "cost recorded as 0 and vendor set to \"unknown\". " \
+             "In your initializer: config.pricing[#{model.inspect}] = { vendor: \"anthropic\", input: 0.0, output: 0.0 }"
+        return 0
+      end
+
+      ((input_tokens * rates[:input] + output_tokens * rates[:output]) / 1000.0).round
+    end
+  end
+end

data/lib/token_hawk/dashboard_query.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  class DashboardQuery
+    def initialize(since:)
+      @since = since
+    end
+
+    def monthly_total
+      scope.sum(:total_cost_cents)
+    end
+
+    def top_domains
+      scope.group(:domain)
+           .sum(:total_cost_cents)
+           .sort_by { |_, cost| -cost }
+           .first(3)
+    end
+
+    def daily_costs
+      scope.group(Arel.sql("DATE(created_at)"))
+           .sum(:total_cost_cents)
+           .sort_by { |date, _| date }
+    end
+
+    private
+
+    def scope
+      CallRecord.since(@since)
+    end
+  end
+end

data/lib/token_hawk/domain_query.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  class DomainQuery
+    def initialize(domain:)
+      @domain = domain.to_s
+      @scope  = CallRecord.for_domain(@domain)
+      raise ActiveRecord::RecordNotFound, "No records for domain: #{@domain}" if @scope.empty?
+    end
+
+    def total_cost
+      @scope.sum(:total_cost_cents)
+    end
+
+    def call_count
+      @scope.count
+    end
+
+    def cost_per_call
+      (total_cost.to_f / call_count).round(2)
+    end
+
+    def top_tags
+      @scope.to_a
+            .flat_map { |r| r.tags.to_a }
+            .tally
+            .sort_by { |_, count| -count }
+            .map(&:first)
+    end
+
+    def recent_calls
+      @scope.order(created_at: :desc).limit(10)
+    end
+  end
+end

data/lib/token_hawk/engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module TokenHawk
+  class Engine < ::Rails::Engine
+    isolate_namespace TokenHawk
+  end
+end