llm_cost_tracker 0.9.0 → 0.11.0

data/lib/llm_cost_tracker/event.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "pricing/mode"
+require_relative "billing/line_item"
+
 module LlmCostTracker
   Event = Data.define(
     :event_id,
@@ -22,6 +25,46 @@ module LlmCostTracker
     :pricing_snapshot,
     :line_items
   ) do
+    def self.batch_from_pricing_mode?(pricing_mode)
+      pricing_mode.to_s.split("_").include?("batch")
+    end
+
+    def self.build(**attributes)
+      pricing_mode = Pricing::Mode.normalize(attributes[:pricing_mode])
+      token_usage = attributes.fetch(:token_usage)
+      batch = attributes[:batch].nil? ? batch_from_pricing_mode?(pricing_mode) : attributes[:batch]
+      line_items = attributes[:line_items] || resolve_line_items(attributes[:service_line_items], token_usage)
+
+      new(
+        event_id: attributes[:event_id],
+        provider: attributes.fetch(:provider).to_s,
+        model: attributes.fetch(:model).to_s.strip.presence || Event::UNKNOWN_MODEL,
+        token_usage: token_usage,
+        pricing_mode: pricing_mode,
+        cost: attributes[:cost],
+        tags: attributes[:tags],
+        latency_ms: attributes[:latency_ms],
+        stream: attributes[:stream] || false,
+        usage_source: attributes[:usage_source],
+        provider_response_id: attributes[:provider_response_id].to_s.strip.presence,
+        provider_project_id: attributes[:provider_project_id].to_s.strip.presence,
+        provider_api_key_id: attributes[:provider_api_key_id].to_s.strip.presence,
+        provider_workspace_id: attributes[:provider_workspace_id].to_s.strip.presence,
+        batch: batch,
+        tracked_at: attributes[:tracked_at],
+        cost_status: attributes[:cost_status],
+        pricing_snapshot: attributes[:pricing_snapshot],
+        line_items: line_items
+      )
+    end
+
+    def self.resolve_line_items(service_items, token_usage)
+      service_line_items = Array(service_items).map do |item|
+        item.is_a?(Billing::LineItem) ? item : Billing::LineItem.build(item)
+      end
+      Billing::LineItem.from_token_usage(token_usage) + service_line_items
+    end
+
     def total_cost
       cost&.fetch(:total_cost, nil)
     end
@@ -35,4 +78,8 @@ module LlmCostTracker
       )
     end
   end
+
+  class Event
+    UNKNOWN_MODEL = "unknown"
+  end
 end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/{durable_ingestion_generator.rb → async_ingestion_generator.rb}

@@ -5,18 +5,18 @@ require "rails/generators/active_record"
 
 module LlmCostTracker
   module Generators
-    class DurableIngestionGenerator < Rails::Generators::Base
+    class AsyncIngestionGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
 
       source_root File.expand_path("templates", __dir__)
 
-      desc "Creates the durable ingestion tables (llm_cost_tracker_ingestion_inbox_entries + _leases). " \
-           "Required when config.durable_ingestion = true."
+      desc "Creates the async ingestion tables (llm_cost_tracker_ingestion_inbox_entries + _leases). " \
+           "Required when config.ingestion = :async."
 
       def create_migration_file
         migration_template(
-          "create_llm_cost_tracker_durable_ingestion.rb.erb",
-          "db/migrate/create_llm_cost_tracker_durable_ingestion.rb"
+          "create_llm_cost_tracker_async_ingestion.rb.erb",
+          "db/migrate/create_llm_cost_tracker_async_ingestion.rb"
         )
       end
 
@@ -25,11 +25,11 @@ module LlmCostTracker
           After migrating, set the following in config/initializers/llm_cost_tracker.rb:
 
             LlmCostTracker.configure do |config|
-              config.durable_ingestion = true
+              config.ingestion = :async
             end
 
-          Without it the durable inbox tables stay unused and Tracker keeps writing
-          inline. The doctor check warns about unused durable tables.
+          Without it the async inbox tables stay unused and Tracker keeps writing
+          inline. The doctor check warns about unused async ingestion tables.
         MSG
       end
 

data/lib/llm_cost_tracker/generators/llm_cost_tracker/install_generator.rb

@@ -26,10 +26,10 @@ module LlmCostTracker
       end
 
       def create_initializer
-        template(
-          "initializer.rb.erb",
-          "config/initializers/llm_cost_tracker.rb"
-        )
+        destination = "config/initializers/llm_cost_tracker.rb"
+        return if File.exist?(File.join(destination_root, destination))
+
+        template("initializer.rb.erb", destination)
       end
 
       def create_prices_file
@@ -42,7 +42,6 @@ module LlmCostTracker
       def mount_engine
         return unless options[:dashboard]
 
-        add_engine_require
         say(<<~MSG, :yellow)
           The LLM Cost Tracker dashboard ships without authentication.
           Mount it in config/routes.rb behind your app's admin auth, e.g.:
@@ -61,24 +60,6 @@ module LlmCostTracker
       def migration_version
         "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
       end
-
-      def add_engine_require
-        return unless File.exist?("config/application.rb")
-
-        contents = File.read("config/application.rb")
-        return if contents.include?(%(require "llm_cost_tracker/engine"))
-
-        unless contents.include?(%(require "rails/all"\n))
-          prepend_to_file("config/application.rb", %(require "llm_cost_tracker/engine"\n))
-          return
-        end
-
-        inject_into_file(
-          "config/application.rb",
-          %(require "llm_cost_tracker/engine"\n),
-          after: %(require "rails/all"\n)
-        )
-      end
     end
   end
 end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/{create_llm_cost_tracker_durable_ingestion.rb.erb → create_llm_cost_tracker_async_ingestion.rb.erb}

@@ -1,14 +1,14 @@
-class CreateLlmCostTrackerDurableIngestion < ActiveRecord::Migration<%= migration_version %>
+class CreateLlmCostTrackerAsyncIngestion < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :llm_cost_tracker_ingestion_inbox_entries do |t|
       t.string   :event_id, null: false
       t.decimal  :total_cost, precision: 20, scale: 8
       t.datetime :tracked_at, null: false
-      t.text     :payload, null: false
+      t.text     :payload, null: false, limit: 16.megabytes
       t.datetime :locked_at
       t.string   :locked_by
       t.integer  :attempts, null: false, default: 0
-      t.text     :last_error
+      t.text     :last_error, limit: 16.megabytes
 
       t.timestamps
     end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/create_llm_cost_tracker_reconciliation.rb.erb

@@ -23,6 +23,7 @@ class CreateLlmCostTrackerReconciliation < ActiveRecord::Migration<%= migration_
 
     create_table :llm_cost_tracker_provider_invoice_imports, if_not_exists: true do |t|
       t.string :source, null: false
+      t.string :provider, null: false, default: ""
       t.string :cursor
       t.date :window_start
       t.date :window_end
@@ -39,7 +40,11 @@ class CreateLlmCostTrackerReconciliation < ActiveRecord::Migration<%= migration_
               if_not_exists: true
     add_index :llm_cost_tracker_provider_invoices, %i[source currency period_start],
               if_not_exists: true
-    add_index :llm_cost_tracker_provider_invoice_imports, %i[source started_at],
+    if postgresql?
+      add_index :llm_cost_tracker_provider_invoices, :metadata, using: :gin,
+                if_not_exists: true
+    end
+    add_index :llm_cost_tracker_provider_invoice_imports, %i[source provider started_at],
               if_not_exists: true
   end
 

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/initializer.rb.erb

@@ -22,7 +22,9 @@ LlmCostTracker.configure do |config|
   # config.instrument :ruby_llm
 
   # Pricing — local file refreshed via bin/rails llm_cost_tracker:prices:refresh
-  # plus inline overrides. Prices are USD per 1M tokens.
+  # plus inline overrides. Rates are per 1M tokens; the snapshot's currency
+  # is read from your prices_file's `metadata.currency` (USD in the bundled
+  # snapshot — set a different code per file if you maintain non-USD prices).
 <% if options[:prices] -%>
   config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
 <% else -%>
@@ -37,8 +39,9 @@ LlmCostTracker.configure do |config|
 
   # Budget guardrails — cumulative monthly/daily and per-call ceilings in USD,
   # plus behavior on crossing (:notify default fires on_budget_exceeded; :raise
-  # raises after recording; :block_requests preflights supported requests) and
-  # an optional callback. Cap evaluation reads from llm_cost_tracker_calls live;
+  # raises after recording; :block_requests preflights supported requests, also
+  # estimating the current call's input cost via chars/4 so it can block before
+  # send) and an optional callback. Cap evaluation reads from llm_cost_tracker_calls live;
   # flip cache_rollups to true at high volume so reads hit the rollups table
   # instead — generate the table with `bin/rails generate llm_cost_tracker:call_rollups`.
   # config.monthly_budget = 100.00
@@ -50,11 +53,15 @@ LlmCostTracker.configure do |config|
   # }
   # config.cache_rollups = true
 
-  # Ingestion path — false (default) writes events synchronously from the request
-  # thread. Flip to true for a write-ahead inbox + background worker that batches
+  # Ingestion path — :inline (default) writes events synchronously from the request
+  # thread. Set to :async for a write-ahead inbox + background worker that batches
   # inserts and survives caller transaction rollbacks. Requires the optional
-  # inbox/leases tables created by `bin/rails generate llm_cost_tracker:durable_ingestion`.
-  # config.durable_ingestion = true
+  # inbox/leases tables created by `bin/rails generate llm_cost_tracker:async_ingestion`.
+  # The worker uses a dedicated ActiveRecord pool (defaults to 2 connections) so it
+  # doesn't compete with request threads — bump ingestion_pool_size if your Puma
+  # worker count outgrows that.
+  # config.ingestion          = :async
+  # config.ingestion_pool_size = 5
 
   # Register OpenAI-compatible gateway hosts and choose extra tag breakdowns
   # for bin/rails llm_cost_tracker:report.

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/upgrade_call_rollups_provider.rb.erb

@@ -1,20 +1,39 @@
+require "llm_cost_tracker/ledger/schema/adapter"
+
 class UpgradeLlmCostTrackerCallRollupsProvider < ActiveRecord::Migration<%= migration_version %>
+  disable_ddl_transaction!
+
   TABLE = :llm_cost_tracker_call_rollups
   OLD_INDEX = %i[period period_start currency].freeze
   NEW_INDEX = %i[period period_start currency provider].freeze
 
   def up
-    unless column_exists?(TABLE, :provider)
-      execute "DELETE FROM #{TABLE}"
-      add_column TABLE, :provider, :string, null: false, default: ""
-    end
-    remove_index TABLE, column: OLD_INDEX, unique: true if index_exists?(TABLE, OLD_INDEX, unique: true)
-    add_index TABLE, NEW_INDEX, unique: true unless index_exists?(TABLE, NEW_INDEX, unique: true)
+    return unless table_exists?(TABLE)
+
+    add_column TABLE, :provider, :string, null: false, default: "" unless column_exists?(TABLE, :provider)
+    add_unique_index NEW_INDEX
+    remove_index TABLE, column: OLD_INDEX, unique: true, if_exists: true
   end
 
   def down
-    remove_index TABLE, column: NEW_INDEX, unique: true if index_exists?(TABLE, NEW_INDEX, unique: true)
-    add_index TABLE, OLD_INDEX, unique: true unless index_exists?(TABLE, OLD_INDEX, unique: true)
+    return unless table_exists?(TABLE)
+
+    add_unique_index OLD_INDEX
+    remove_index TABLE, column: NEW_INDEX, unique: true, if_exists: true
     remove_column TABLE, :provider if column_exists?(TABLE, :provider)
   end
+
+  private
+
+  def add_unique_index(columns)
+    if postgresql?
+      add_index TABLE, columns, unique: true, algorithm: :concurrently, if_not_exists: true
+    else
+      add_index TABLE, columns, unique: true, if_not_exists: true
+    end
+  end
+
+  def postgresql?
+    LlmCostTracker::Ledger::Schema::Adapter.postgresql?(connection)
+  end
 end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/upgrade_call_tags_key_value_index.rb.erb

@@ -1,23 +1,23 @@
 require "llm_cost_tracker/ledger/schema/adapter"
 
 class UpgradeLlmCostTrackerCallTagsKeyValueIndex < ActiveRecord::Migration<%= migration_version %>
+  disable_ddl_transaction!
+
   TABLE = :llm_cost_tracker_call_tags
   INDEX_COLUMNS = %i[key value].freeze
 
   def up
-    return if index_exists?(TABLE, INDEX_COLUMNS)
-
     if postgresql?
-      add_index TABLE, INDEX_COLUMNS
+      add_index TABLE, INDEX_COLUMNS, algorithm: :concurrently, if_not_exists: true
     elsif mysql?
-      add_index TABLE, INDEX_COLUMNS, length: { value: 191 }
+      add_index TABLE, INDEX_COLUMNS, length: { value: 191 }, if_not_exists: true
     else
       raise "LLM Cost Tracker supports PostgreSQL and MySQL only"
     end
   end
 
   def down
-    remove_index TABLE, column: INDEX_COLUMNS if index_exists?(TABLE, INDEX_COLUMNS)
+    remove_index TABLE, column: INDEX_COLUMNS, if_exists: true
   end
 
   private

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/upgrade_provider_invoice_imports_provider.rb.erb

@@ -0,0 +1,36 @@
+require "llm_cost_tracker/ledger/schema/adapter"
+
+class UpgradeLlmCostTrackerProviderInvoiceImportsProvider < ActiveRecord::Migration<%= migration_version %>
+  disable_ddl_transaction!
+
+  TABLE = :llm_cost_tracker_provider_invoice_imports
+  OLD_INDEX = %i[source started_at].freeze
+  NEW_INDEX = %i[source provider started_at].freeze
+
+  def up
+    return unless table_exists?(TABLE)
+
+    add_column TABLE, :provider, :string, null: false, default: "" unless column_exists?(TABLE, :provider)
+    if postgresql?
+      remove_index TABLE, column: OLD_INDEX, algorithm: :concurrently, if_exists: true
+      add_index TABLE, NEW_INDEX, algorithm: :concurrently, if_not_exists: true
+    else
+      remove_index TABLE, column: OLD_INDEX, if_exists: true
+      add_index TABLE, NEW_INDEX, if_not_exists: true
+    end
+  end
+
+  def down
+    return unless table_exists?(TABLE)
+
+    remove_index TABLE, column: NEW_INDEX, if_exists: true
+    add_index TABLE, OLD_INDEX, if_not_exists: true
+    remove_column TABLE, :provider if column_exists?(TABLE, :provider)
+  end
+
+  private
+
+  def postgresql?
+    LlmCostTracker::Ledger::Schema::Adapter.postgresql?(connection)
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/upgrade_provider_invoices_metadata_index.rb.erb

@@ -0,0 +1,27 @@
+require "llm_cost_tracker/ledger/schema/adapter"
+
+class UpgradeLlmCostTrackerProviderInvoicesMetadataIndex < ActiveRecord::Migration<%= migration_version %>
+  disable_ddl_transaction!
+
+  TABLE = :llm_cost_tracker_provider_invoices
+
+  def up
+    return unless postgresql?
+    return unless table_exists?(TABLE)
+
+    add_index TABLE, :metadata, using: :gin, algorithm: :concurrently, if_not_exists: true
+  end
+
+  def down
+    return unless postgresql?
+    return unless table_exists?(TABLE)
+
+    remove_index TABLE, column: :metadata, if_exists: true
+  end
+
+  private
+
+  def postgresql?
+    LlmCostTracker::Ledger::Schema::Adapter.postgresql?(connection)
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/upgrade_call_rollups_provider_generator.rb

@@ -19,15 +19,6 @@ module LlmCostTracker
         )
       end
 
-      def warn_about_rollups_truncation
-        say(<<~MSG, :yellow)
-          The migration clears existing llm_cost_tracker_call_rollups rows before adding the
-          provider column. Budget reads fall back to live aggregation from
-          llm_cost_tracker_calls until new events repopulate the rollups under their provider
-          keys. See docs/upgrading.md for details.
-        MSG
-      end
-
       private
 
       def migration_version

data/lib/llm_cost_tracker/generators/llm_cost_tracker/upgrade_provider_invoice_imports_provider_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module LlmCostTracker
+  module Generators
+    class UpgradeProviderInvoiceImportsProviderGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Adds a provider column to llm_cost_tracker_provider_invoice_imports and a " \
+           "(source, provider, started_at) index so resume_cursor_for and " \
+           "last_completed_window_for can isolate per-provider state on shared sources (e.g. csv)."
+
+      def create_migration_file
+        migration_template(
+          "upgrade_provider_invoice_imports_provider.rb.erb",
+          "db/migrate/upgrade_llm_cost_tracker_provider_invoice_imports_provider.rb"
+        )
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/upgrade_provider_invoices_metadata_index_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module LlmCostTracker
+  module Generators
+    class UpgradeProviderInvoicesMetadataIndexGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Adds a GIN index on llm_cost_tracker_provider_invoices.metadata for PostgreSQL " \
+           "so Reconciliation::Diff queries that filter on metadata->>'provider' / 'row_type' / " \
+           "'match_basis' hit an index instead of a sequential scan. No-op on MySQL."
+
+      def create_migration_file
+        migration_template(
+          "upgrade_provider_invoices_metadata_index.rb.erb",
+          "db/migrate/upgrade_llm_cost_tracker_provider_invoices_metadata_index.rb"
+        )
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/ingestion/batch.rb

@@ -40,7 +40,10 @@ module LlmCostTracker
         Ingestion::InboxEntry
           .where(id: rows.map(&:id), locked_by: identity)
           .update_all(last_error: message, locked_at: now, locked_by: nil, updated_at: now)
-      rescue StandardError
+      rescue StandardError => e
+        LlmCostTracker::Logging.warn(
+          "Inbox mark_failed failed for #{rows.size} rows: #{e.class}: #{e.message} (original error: #{error.class})"
+        )
         nil
       end
 
@@ -77,7 +80,7 @@ module LlmCostTracker
 
       def persist(rows, events)
         LlmCostTracker::Call.transaction do
-          Ledger::Store.insert_many(events)
+          Ledger::Store.insert(events)
           Ingestion::InboxEntry.where(id: rows.map(&:id), locked_by: identity).delete_all
         end
       end

data/lib/llm_cost_tracker/ingestion/inbox.rb

@@ -15,8 +15,6 @@ module LlmCostTracker
       class << self
         def save(event)
           insert_row(row_for(event))
-          Ingestion::Worker.ensure_started
-          event
         end
 
         def event_from_row(row)
@@ -40,7 +38,7 @@ module LlmCostTracker
             provider: payload.fetch(:provider),
             model: payload.fetch(:model),
             token_usage: token_usage,
-            pricing_mode: Pricing.normalize_mode(payload[:pricing_mode]),
+            pricing_mode: Pricing::Mode.normalize(payload[:pricing_mode]),
             cost: cost,
             tags: payload.fetch(:tags),
             latency_ms: payload[:latency_ms],
@@ -54,14 +52,10 @@ module LlmCostTracker
             tracked_at: Time.iso8601(payload.fetch(:tracked_at)),
             cost_status: payload.fetch(:cost_status),
             pricing_snapshot: payload[:pricing_snapshot],
-            line_items: line_items_from(payload)
+            line_items: (payload[:line_items] || []).map { |attrs| Billing::LineItem.build(attrs) }
           }
         end
 
-        def line_items_from(payload)
-          (payload[:line_items] || []).map { |attributes| Billing::LineItem.build(attributes) }
-        end
-
         def row_for(event)
           now = Time.now.utc
           {
@@ -86,25 +80,10 @@ module LlmCostTracker
         end
 
         def insert_row(row)
-          connection = LlmCostTracker::Call.connection
-          if connection.transaction_open?
-            insert_with_separate_connection(row)
-          else
-            execute_insert(connection, row)
-          end
+          Pool.with_connection { |connection| execute_insert(connection, row) }
         rescue ActiveRecord::ConnectionTimeoutError => e
           raise LlmCostTracker::Error,
-                "ledger inbox could not checkout a separate database connection: #{e.message}"
-        end
-
-        def insert_with_separate_connection(row)
-          pool = LlmCostTracker::Call.connection_pool
-          connection = pool.checkout
-          begin
-            connection.transaction(requires_new: true) { execute_insert(connection, row) }
-          ensure
-            pool.checkin(connection)
-          end
+                "ledger inbox could not checkout a database connection: #{e.message}"
         end
 
         def execute_insert(connection, row)

data/lib/llm_cost_tracker/ingestion/pool.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Ingestion
+    module Pool
+      DEFAULT_POOL_SIZE = 2
+      MUTEX = Mutex.new
+
+      class << self
+        def with_connection(&)
+          pool.with_connection(&)
+        end
+
+        def pool
+          @pool || MUTEX.synchronize { @pool ||= connect! }
+        end
+
+        def reset!
+          MUTEX.synchronize do
+            @pool&.disconnect!
+            @pool = nil
+            @handler = nil
+          end
+        end
+
+        private
+
+        def connect!
+          @handler = ActiveRecord::ConnectionAdapters::ConnectionHandler.new
+          @handler.establish_connection(connection_config)
+        end
+
+        def connection_config
+          LlmCostTracker::Call.connection_db_config.configuration_hash.merge(pool: pool_size)
+        end
+
+        def pool_size
+          configured = LlmCostTracker.configuration.ingestion_pool_size.to_i
+          configured.positive? ? configured : DEFAULT_POOL_SIZE
+        end
+      end
+    end
+  end
+end