llm_cost_tracker 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93ef8bc5c6bc0e850398b7555499a4667d1cc3d8ba2328c1fb926204a794a5a7
-  data.tar.gz: e7208b7bf518332040837498b5de7d1e5e6c761a276d6fb732d14133d38d8c74
+  metadata.gz: 6952282e6f93b4e5658ef9d2b9527d2a332cb2d6f483da25540c3a0d6672ed9b
+  data.tar.gz: e66eaaeb99698abf9c0ff9e3f1305e6bb27a8b6c25355e94bce4baec5f5d3a50
 SHA512:
-  metadata.gz: 5d19b85e0a4398332a0161f75bc561b79c6ebf12546fe21013b12f2b7f5ff931179fcb8d5610faccd4d84063bf10f4297bd1688df04c24e41ffb63d4ff38b851
-  data.tar.gz: e7b4f3a2164cc9f6e9545e123fe4aeabac356ab66becfc94466f8f25d54329ed5af4056339cfda1c71e20bcba1c4de30a9922ff3b7b5664528bde515834e19f1
+  metadata.gz: '078d695498ed6f254a700ccb3381ace3feaa1f4880691a1a69be4bb435097202ecf28f2cbf065202a543186bdd3894aaedcc44bfacc2d2ffa25a54ddf6d1cc76'
+  data.tar.gz: 2638ae3c579bd2c0f71a73b06719eb0a35d7b82e8614a74c5100f41b69693babfd3b613ecf18e7f6e7ea33210222432efa5a7ca718325c4c8fd12be9b8ab806e

data/CHANGELOG.md

@@ -4,6 +4,13 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-04-22
+
+### Added
+
+- Test coverage reporting via SimpleCov with LCOV upload to Codecov from CI.
+- Repository governance files: `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CONTRIBUTING.md`, and GitHub issue templates.
+
 ## [0.3.1] - 2026-04-22
 
 ### Added

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1, as its code of conduct. The full text is available at:
+
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>
+
+## Our pledge
+
+We as contributors and maintainers pledge to make participation in this project a welcoming, respectful, and inclusive experience for everyone.
+
+## Scope
+
+This Code of Conduct applies within all project spaces (issues, pull requests, discussions, commit messages, review comments) and in public spaces when an individual is representing the project.
+
+## Reporting
+
+Instances of unacceptable behavior may be reported to the project maintainer at **sergey@mm.st**. All reports will be reviewed and investigated promptly and fairly. The maintainer is obligated to respect the privacy and safety of the reporter of any incident.
+
+## Enforcement
+
+Maintainers are responsible for clarifying and enforcing the standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, or harmful. This may include warnings, temporary bans, or permanent removal from project participation.
+
+For the full set of community standards, enforcement guidelines, and attribution, see the canonical document linked above.

data/README.md

@@ -4,14 +4,70 @@
 
 [![Gem Version](https://img.shields.io/gem/v/llm_cost_tracker.svg)](https://rubygems.org/gems/llm_cost_tracker)
 [![CI](https://github.com/sergey-homenko/llm_cost_tracker/actions/workflows/ruby.yml/badge.svg)](https://github.com/sergey-homenko/llm_cost_tracker/actions)
+[![codecov](https://codecov.io/gh/sergey-homenko/llm_cost_tracker/branch/main/graph/badge.svg)](https://codecov.io/gh/sergey-homenko/llm_cost_tracker)
+
+Requires Ruby 3.3+, Rails/ActiveRecord 7.1+, and Faraday 2.0+.
+Core tracking works without Rails; the mounted dashboard requires Rails 7.1+.
 
 ## Why
 
 Every Rails app with LLM integrations eventually runs into the same question: where did that invoice come from? Full observability platforms like Langfuse and Helicone solve a broader set of problems; sometimes you just need a small Rails-native ledger in your own database.
 
-`llm_cost_tracker` is built for that. It plugs into Faraday or lets you record usage explicitly with `track` / `track_stream`, looks up pricing locally, and writes an event. You end up with a ledger you can query with plain ActiveRecord, slice by any tag dimension, and optionally surface on a built-in dashboard. No proxy, no SaaS, no separate service to run.
+## What You Get
+
+- A local ActiveRecord ledger of provider, model, tokens, cost, latency, tags, streaming usage, and provider response IDs
+- Faraday middleware plus explicit `track` / `track_stream` helpers for non-Faraday clients
+- Server-rendered Rails dashboard with overview, calls, tags, CSV export, and data-quality pages
+- Local pricing snapshots, price sync tasks, and budget guardrails
+- Prompt and response bodies are never persisted
+
+## Dashboard
+
+LLM Cost Tracker ships with an optional server-rendered Rails Engine dashboard for spend review, attribution, and data quality checks.
+
+![LLM Cost Tracker dashboard](docs/dashboard-overview.png)
+
+The overview page includes spend trend, budget status, provider breakdown, top models, and filterable slices. The engine also includes Calls, Tags, and Data Quality pages. Plain ERB, no JavaScript bundle.
+
+## Quickstart
+
+```ruby
+gem "llm_cost_tracker"
+```
+
+```bash
+bin/rails generate llm_cost_tracker:install
+bin/rails db:migrate
+```
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.storage_backend = :active_record
+  config.default_tags = { app: "my_app", environment: Rails.env }
+end
+
+OpenAI.configure do |config|
+  config.access_token = ENV["OPENAI_API_KEY"]
+  config.faraday do |f|
+    f.use :llm_cost_tracker, tags: -> { { user_id: Current.user&.id, feature: "chat" } }
+  end
+end
+```
+
+```ruby
+mount LlmCostTracker::Engine => "/llm-costs"
+```
 
-It is not a tracing platform, prompt CMS, eval system, or gateway. The goal is to answer _"what did this app spend on LLM APIs, and where did that spend come from?"_ clearly enough to make spend review routine.
+After that, LLM Cost Tracker starts recording calls into `llm_api_calls` and the dashboard becomes available at `/llm-costs`.
+Protect the mounted engine with your application's authentication before exposing it outside development.
+
+## Tradeoffs
+
+- Self-hosted ledger first: no proxy, no SaaS, no separate service to operate
+- Best-effort pricing for spend review and attribution, not invoice-grade billing
+- No prompt or response body storage
+- No built-in auth on the mounted dashboard
+- Use `:active_record` when you want shared dashboards and budget checks across Puma workers and Sidekiq processes
 
 ## Installation
 
@@ -293,7 +349,7 @@ bin/rails generate llm_cost_tracker:add_latency_ms
 bin/rails db:migrate
 ```
 
-## Dashboard (optional)
+## Mounting the dashboard
 
 Optional Rails Engine. Plain ERB, no JavaScript framework, no asset pipeline required. Requires Rails 7.1+; the core middleware works without Rails.
 
@@ -315,7 +371,7 @@ Routes (GET-only; CSV export included):
 - `/llm-costs/tags/:key` — breakdown by values of a given tag key
 - `/llm-costs/data_quality` — unknown pricing share, untagged calls, missing latency
 
-> ⚠️ **No built-in auth.** Tags carry whatever your app puts in them. Protect the mount point with your application's authentication.
+No built-in auth is included. Tags carry whatever your app puts in them, so protect the mount point with your application's authentication.
 
 ### Basic auth
 
@@ -381,20 +437,26 @@ Configured hosts are parsed using the OpenAI-compatible usage shape (`prompt_tok
 For providers with a non-OpenAI usage shape:
 
 ```ruby
+require "uri"
+
 class AcmeParser < LlmCostTracker::Parsers::Base
   def match?(url)
-    url.to_s.include?("api.acme-llm.example")
+    uri = URI.parse(url.to_s)
+    uri.host == "api.acme-llm.example" && uri.path == "/v1/generate"
+  rescue URI::InvalidURIError
+    false
   end
 
   def parse(request_url, request_body, response_status, response_body)
     return nil unless response_status == 200
 
-    usage = safe_json_parse(response_body)&.dig("usage")
+    payload = safe_json_parse(response_body)
+    usage = payload&.dig("usage")
     return nil unless usage
 
     LlmCostTracker::ParsedUsage.build(
       provider: "acme",
-      model: safe_json_parse(response_body)["model"],
+      model: payload["model"],
       input_tokens: usage["input"] || 0,
       output_tokens: usage["output"] || 0
     )
@@ -420,9 +482,12 @@ Endpoints: OpenAI Chat Completions / Responses / Completions / Embeddings; OpenA
 
 ## Safety
 
+**By design, `llm_cost_tracker` never persists prompt or response content.** The only data stored per call is the metadata needed for a cost ledger (provider, model, token counts, cost, latency, tags, provider response ID, HTTP status, and a timestamp). Tags carry whatever your application passes in — treat them as user-controlled input and avoid putting request bodies, completions, or secrets into them.
+
 - No external HTTP calls at request-tracking time.
 - No prompt or response bodies stored.
 - Faraday responses not modified.
+- Authorization headers and API keys are never stored or logged.
 - Storage failures non-fatal by default (`storage_error_behavior = :warn`).
 - Budget and unknown-pricing errors are raised only when you opt in.
 

data/SECURITY.md

@@ -0,0 +1,36 @@
+# Security Policy
+
+## Supported versions
+
+The gem is pre-1.0. Only the latest released version receives security fixes — please upgrade rather than expecting backports to older releases.
+
+## Reporting a vulnerability
+
+Please **do not open a public GitHub issue** for security reports.
+
+Email **sergey@mm.st** with:
+
+- A description of the issue and its potential impact
+- Steps to reproduce (a minimal proof-of-concept is ideal)
+- The affected version(s)
+- Any suggested mitigation or fix
+
+You will receive an acknowledgment within **72 hours**. I will work with you on a disclosure timeline — typically a fix plus a coordinated release within 14 days for confirmed vulnerabilities, longer if the issue is complex.
+
+## Scope
+
+In scope:
+
+- Vulnerabilities in the gem's middleware, parsers, storage adapters, dashboard controllers, or generators
+- Data-exposure issues (unintended persistence of prompt content, API keys, or response bodies)
+- Injection, auth-bypass, or privilege-escalation in the mounted dashboard
+
+Out of scope:
+
+- Issues in third-party dependencies (report those upstream; mention them here only if this gem's usage pattern creates the vulnerability)
+- Missing security hardening recommendations that are not vulnerabilities (open a regular issue instead)
+- Social engineering or physical attacks
+
+## Credit
+
+Reporters who follow this policy will be credited in the release notes for the fix unless they request anonymity.

data/app/controllers/llm_cost_tracker/assets_controller.rb

@@ -2,8 +2,6 @@
 
 module LlmCostTracker
   class AssetsController < ActionController::Base
-    skip_forgery_protection if respond_to?(:skip_forgery_protection)
-
     def stylesheet
       response.set_header("Cache-Control", "public, max-age=31536000, immutable")
       send_file LlmCostTracker::Assets::STYLESHEET_PATH, type: "text/css", disposition: "inline"

data/lib/llm_cost_tracker/railtie.rb

@@ -4,6 +4,8 @@ module LlmCostTracker
   class Railtie < Rails::Railtie
     generators do
       require_relative "generators/llm_cost_tracker/add_latency_ms_generator"
+      require_relative "generators/llm_cost_tracker/add_provider_response_id_generator"
+      require_relative "generators/llm_cost_tracker/add_streaming_generator"
       require_relative "generators/llm_cost_tracker/install_generator"
       require_relative "generators/llm_cost_tracker/prices_generator"
       require_relative "generators/llm_cost_tracker/upgrade_cost_precision_generator"

data/lib/llm_cost_tracker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmCostTracker
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/llm_cost_tracker.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
       (File.expand_path(f) == __FILE__) ||
-        f.start_with?("bin/", "test/", "spec/", ".git", ".github", "gemfiles/", ".rubocop", "Gemfile")
+        f.start_with?("bin/", "docs/", "test/", "spec/", ".git", ".github", "gemfiles/", ".rubocop", "Gemfile")
     end
   end
 
@@ -43,6 +43,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rubocop", "~> 1.0"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "simplecov-lcov", "~> 0.8"
   spec.add_development_dependency "sqlite3", ">= 1.4", "< 3.0"
   spec.add_development_dependency "webmock", "~> 3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm_cost_tracker
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Sergii Khomenko
@@ -146,6 +146,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -192,9 +220,11 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - CHANGELOG.md
+- CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- SECURITY.md
 - app/assets/llm_cost_tracker/application.css
 - app/controllers/llm_cost_tracker/application_controller.rb
 - app/controllers/llm_cost_tracker/assets_controller.rb