Merge branch 'main' into bugfix/fix-dynamic-tool-loading

Author: crmne

.github/workflows/_test-matrix.yml

@@ -52,6 +52,9 @@ jobs:
           bundle install
           bundle exec appraisal ${{ matrix.rails-version }} bundle install
 
+      - name: Run eager-load guard (appraisal)
+        run: bundle exec appraisal ${{ matrix.rails-version }} ruby -e "require 'ruby_llm'; Zeitwerk::Loader.eager_load_all"
+
       - name: Run tests
         if: matrix.ruby-version != '4.0' || matrix.rails-version != 'rails-8.1'
         run: bundle exec appraisal ${{ matrix.rails-version }} bin/rspec-queue

.github/workflows/pr-fast.yml

@@ -0,0 +1,29 @@
+name: PR
+
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pr-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  gitleaks:
+    uses: ./.github/workflows/_gitleaks.yml
+
+  lint:
+    name: RuboCop
+    uses: ./.github/workflows/_lint.yml
+    with:
+      ruby-version: "4.0"
+      bundler-cache: false
+
+  test:
+    uses: ./.github/workflows/_test-matrix.yml
+    with:
+      bundler-cache: false
+    secrets: inherit

.github/workflows/pr-heavy.yml

@@ -6,6 +6,12 @@ PreCommit:
 
   Flay:
     enabled: true
+    include:
+     - 'lib/ruby_llm/**/*.rb'
+    exclude:
+     - 'lib/ruby_llm/providers/**/*.rb'
+     - 'lib/ruby_llm/active_record/acts_as_legacy.rb'
+    mass_threshold: 70
 
   RSpec:
     enabled: true

.github/workflows/pr.yml

@@ -86,9 +86,7 @@ RubyLLM.moderate "Check if this text is safe"
 ```ruby
 # Let AI use your code
 class Weather < RubyLLM::Tool
-  description "Get current weather"
-  param :latitude
-  param :longitude
+  desc "Get current weather"
 
   def execute(latitude:, longitude:)
     url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"

.overcommit.yml

@@ -9,6 +9,7 @@ group :jekyll_plugins do
   gem 'jekyll-remote-theme'
   gem 'jekyll-seo-tag'
   gem 'jekyll-sitemap'
-  gem 'jekyll-og-image', git: 'https://github.com/crmne/jekyll-og-image'
+  gem 'jekyll-og-image'
   gem 'jekyll-redirect-from'
+  gem 'jekyll-ai-visible-content'
 end

README.md

@@ -46,6 +46,8 @@ The registry stores crucial information about each model, including:
 *   **`supports_functions`**: If it can use [Tools]({% link _core_features/tools.md %}).
 *   **`input_price_per_million`**: Cost in USD per 1 million input tokens.
 *   **`output_price_per_million`**: Cost in USD per 1 million output tokens.
+*   **`cache_read_input_price_per_million`**: Cost in USD per 1 million cache read tokens, when available. v1.15+
+*   **`cache_write_input_price_per_million`**: Cost in USD per 1 million cache write tokens, when available. v1.15+
 *   **`family`**: A broader classification (e.g., `gpt4o`).
 
 This registry allows RubyLLM to validate models, route requests correctly, provide capability information, and offer convenient filtering.
@@ -206,6 +208,46 @@ model_bedrock = RubyLLM.models.find('{{ site.models.anthropic_current }}', :bedr
 
 When you pass a provider, RubyLLM resolves aliases first. For Bedrock, it then applies region/inference-profile resolution (for example `us.` prefixes) before falling back to an exact ID match.
 
+## Calculating Costs
+{: .d-inline-block }
+
+v1.15+
+{: .label .label-green }
+
+Models can turn token usage into a `RubyLLM::Cost` object:
+
+```ruby
+model = RubyLLM.models.find('{{ site.models.default_chat }}')
+response = RubyLLM.chat(model: model.id, provider: model.provider).ask("Summarize Ruby's object model.")
+
+cost = model.cost_for(response.tokens)
+puts cost.input
+puts cost.output
+puts cost.cache_read
+puts cost.cache_write
+puts cost.thinking
+puts cost.total
+```
+
+Costs use RubyLLM's normalized token buckets: standard input, billable output, cache read, cache write, and separately priced thinking when the model registry exposes a distinct reasoning-token price. See [Tracking Token Usage]({% link _core_features/chat.md %}#tracking-token-usage) for the provider comparison table and what RubyLLM exposes consistently across providers.
+
+Most applications use the shorter helpers on messages, chats, and agents:
+
+```ruby
+response.cost.total
+chat.cost.total
+agent.cost.total
+```
+
+To combine several cost objects yourself, use `RubyLLM::Cost.aggregate`:
+
+```ruby
+cost = RubyLLM::Cost.aggregate(messages.map(&:cost))
+cost.total
+```
+
+If pricing is incomplete for tokens that were used, the affected cost and `cost.total` return `nil`. Cost helpers cover token-priced conversation usage; provider-specific add-ons such as search-query charges remain available in the provider's raw usage payload.
+
 ## Connecting to Custom Endpoints & Using Unlisted Models
 {: .d-inline-block }