open_router_usage_tracker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2942349a31ca24bfb080791b3dba9bcb36eaf6fc9709718fe989e65c968ee489
+  data.tar.gz: 57459071b36f2873e5dedf5f4c4d9d98bd1327527edeca2ff9c7bfaff7c14098
+SHA512:
+  metadata.gz: 961ca4017ed1159fb13920d86a07ad4ca78b7bea40f2d105893bdc57653a3deed4164c047b858c0cb5a779419deebd0cdc0a1f0e65d87dab232052b27558f44f
+  data.tar.gz: 3c538fda52c54f226498c6f845d84f7fdd0e42ee78c582062a42fd529d54946ecb10ea470cc2ec7a59a68648358c7d454fbe771661454107f25d21e7a600a436

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright MclPio
+
+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/README.md

@@ -0,0 +1,102 @@
+# OpenRouterUsageTracker
+[![Gem Version](https://badge.fury.io/rb/open_router_usage_tracker.svg)](https://badge.fury.io/rb/open_router_usage_tracker)
+[![Build Status](https://github.com/mclpio/open_router_usage_tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/mclpio/open_router_usage_tracker/actions)
+
+An effortless Rails engine to track API token usage and cost from [OpenRouter.io](https://openrouter.ai/), enabling easy rate-limiting and monitoring for your users.
+
+## Motivation
+Managing Large Language Model (LLM) API costs is crucial for any application that provides AI features to users. This gem provides simple, out-of-the-box tools to log every OpenRouter API call, associate it with a user, and query their usage over time. This allows you to easily implement spending caps, rate limits, or usage-based billing tiers.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "open_router_usage_tracker"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install open_router_usage_tracker
+```
+
+## Setup
+
+1. **Run the Install Generator**: This will create a migration file in your application to add the open_router_usage_logs table.
+    ```bash
+    bin/rails g open_router_usage_tracker:install
+    ```
+
+1. **Run the Database Migration**:
+    ```bash
+    bin/rails db:migrate
+    ```
+
+1. **Include the `Trackable` Concern**: To add the usage tracking methods (`usage_in_period`, etc.) to your user model, include the concern. This works with any user-like model (e.g., `User`, `Account`).
+    ```ruby
+    # app/models/user.rb
+    class User < ApplicationRecord
+      include OpenRouterUsageTracker::Trackable
+
+      # ... rest of your model
+    end
+    ```
+
+## Usage
+Using the gem involves two parts: logging new requests and tracking existing usage.
+
+### Logging a Request
+In your application where you receive a successful response from the OpenRouter API, call the `log` method. It's designed to be simple and fail loudly if the data is invalid.
+
+```ruby
+# Assume `api_response` is the parsed JSON hash from OpenRouter
+# and `current_user` is your authenticated user object.
+
+begin
+  OpenRouterUsageTracker.log(response: api_response, user: current_user)
+rescue ActiveRecord::RecordInvalid => e
+  # This can happen if the response hash is missing required keys
+  # (e.g., 'id', 'model', 'usage').
+  logger.error "Failed to log OpenRouter usage: #{e.message}"
+end
+```
+
+### Tracking Usage
+The `Trackable` concern adds powerful querying methods to your user model.
+
+The main method is `usage_in_period(range)`, which returns a hash containing the total tokens and cost for a given time range.
+
+**Example: Implementing a rate limit**
+
+Imagine you want to prevent users from using more than 100,000 tokens in a 24-hour period.
+
+```ruby
+# somewhere in a controller or before_action
+
+def check_usage_limit
+  usage = current_user.usage_in_last_24_hours
+
+  if usage[:tokens] > 100_000
+    render json: { error: "You have exceeded your daily usage limit." }, status: :too_many_requests
+    return
+  end
+end
+```
+
+The gem also provides `usage_in_last_24_hours` as a convenience method and you can always get all the data using `usage_logs`.
+
+## Contributing
+Open an issue first.
+
+1. Fork the repository.
+1. Create your feature branch (git checkout -b my-new-feature).
+1. Commit your changes (git commit -am 'Add some feature').
+1. Push to the branch (git push origin my-new-feature).
+1. Create a new Pull Request.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/app/models/concerns/open_router_usage_tracker/trackable.rb

@@ -0,0 +1,32 @@
+require "active_support/concern"
+
+module OpenRouterUsageTracker
+  module Trackable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :usage_logs, as: :user, class_name: "OpenRouterUsageTracker::UsageLog", dependent: :destroy
+    end
+
+    # A flexible method to query usage within any time period.
+    #
+    # Example:
+    #   user.usage_in_period(24.hours.ago..Time.current)
+    #   => { tokens: 1500, cost: 0.025 }
+    #
+    def usage_in_period(range)
+      logs_in_range = self.usage_logs.where(created_at: range)
+
+      # Use .to_i and .to_d to handle cases where there are no logs (sum returns nil)
+      total_tokens = logs_in_range.sum(:total_tokens).to_i
+      total_cost = logs_in_range.sum(:cost).to_d
+
+      { tokens: total_tokens, cost: total_cost }
+    end
+
+    # A convenience method for checking the last 24 hours.
+    def usage_in_last_24_hours
+      usage_in_period(24.hours.ago..Time.current)
+    end
+  end
+end

data/app/models/open_router_usage_tracker/usage_log.rb

@@ -0,0 +1,17 @@
+module OpenRouterUsageTracker
+  # This class represents a single entry of an OpenRouter API call.
+  class UsageLog < ApplicationRecord
+    self.table_name = "open_router_usage_logs"
+
+    belongs_to :user, polymorphic: true
+
+    validates :model, presence: true
+    validates :prompt_tokens, presence: true
+    validates :completion_tokens, presence: true
+    validates :total_tokens, presence: true
+    validates :cost, presence: true
+    validates :raw_usage_response, presence: true
+
+    validates :request_id, presence: true, uniqueness: true
+  end
+end

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

@@ -0,0 +1,18 @@
+require "rails/generators"
+require "rails/generators/migration"
+
+module OpenRouterUsageTracker
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    source_root File.expand_path("templates", __dir__)
+
+    def self.next_migration_number(dir)
+      Time.now.utc.strftime("%Y%m%d%H%M%S")
+    end
+
+    def create_files
+      migration_template "migration.rb", "db/migrate/create_open_router_usage_logs.rb"
+    end
+  end
+end

data/lib/generators/open_router_usage_tracker/install/templates/migration.rb

@@ -0,0 +1,22 @@
+class CreateOpenRouterUsageLogs < ActiveRecord::Migration[8.0]
+  def change
+    create_table :open_router_usage_logs do |t|
+      t.string :model, null: false
+      t.integer :prompt_tokens, null: false
+      t.integer :completion_tokens, null: false
+      t.integer :total_tokens, null: false
+      t.decimal :cost, precision: 10, scale: 5, null: false
+      t.references :user, null: false, polymorphic: true
+      t.string :request_id, null: false
+
+      # Storing the raw API response is recommended for auditing and future-proofing.
+      # If you are using PostgreSQL, you can change `t.json` to `t.jsonb` for
+      # better performance and indexing capabilities.
+      t.json :raw_usage_response, null: false, default: {}
+
+      t.timestamps
+    end
+
+    add_index :open_router_usage_logs, :request_id, unique: true
+  end
+end

data/lib/open_router_usage_tracker/engine.rb

@@ -0,0 +1,15 @@
+# lib/open_router_usage_tracker/engine.rb
+
+require "rails/engine"
+
+module OpenRouterUsageTracker
+  class Engine < ::Rails::Engine
+    initializer "open_router_usage_tracker.migrations" do |app|
+      unless app.root.to_s.match root.to_s
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path
+        end
+      end
+    end
+  end
+end

data/lib/open_router_usage_tracker/railtie.rb

@@ -0,0 +1,4 @@
+module OpenRouterUsageTracker
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/open_router_usage_tracker/version.rb

@@ -0,0 +1,3 @@
+module OpenRouterUsageTracker
+  VERSION = "0.1.0"
+end

data/lib/open_router_usage_tracker.rb

@@ -0,0 +1,24 @@
+require "open_router_usage_tracker/version"
+require "open_router_usage_tracker/railtie"
+require "open_router_usage_tracker/engine"
+
+module OpenRouterUsageTracker
+  class << self
+    attr_writer :configuration
+
+    def log(response:, user:)
+      attributes = {
+        model: response["model"],
+        prompt_tokens: response.dig("usage", "prompt_tokens"),
+        completion_tokens: response.dig("usage", "completion_tokens"),
+        total_tokens: response.dig("usage", "total_tokens"),
+        cost: response.dig("usage", "cost"),
+        request_id: response["id"],
+        raw_usage_response: response,
+        user: user
+      }
+
+      OpenRouterUsageTracker::UsageLog.create!(attributes)
+    end
+  end
+end

data/lib/tasks/open_router_usage_tracker_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :open_router_usage_tracker do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: open_router_usage_tracker
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- MclPio
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.2
+description: This gem is your rocket launch to managing you web app's LLM usage and
+  rate limiting users with built in methods!
+email:
+- mclpious@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/models/concerns/open_router_usage_tracker/trackable.rb
+- app/models/open_router_usage_tracker/usage_log.rb
+- lib/generators/open_router_usage_tracker/install/install_generator.rb
+- lib/generators/open_router_usage_tracker/install/templates/migration.rb
+- lib/open_router_usage_tracker.rb
+- lib/open_router_usage_tracker/engine.rb
+- lib/open_router_usage_tracker/railtie.rb
+- lib/open_router_usage_tracker/version.rb
+- lib/tasks/open_router_usage_tracker_tasks.rake
+homepage: https://github.com/MclPio/open_router_usage_tracker
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MclPio/open_router_usage_tracker
+  source_code_uri: https://github.com/MclPio/open_router_usage_tracker
+  changelog_uri: https://github.com/MclPio/open_router_usage_tracker/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Track API token usage and cost from OpenRouter
+test_files: []