Merge branch 'main' into prompt-caching

Author: tpaulshippy

.gitattributes

@@ -0,0 +1,5 @@
+# Binary files tracked with Git LFS
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/config.yml

@@ -5,7 +5,4 @@ contact_links:
     about: Questions about using RubyLLM, implementation approaches, or general discussion
   - name: 📖 Documentation
     url: https://rubyllm.com
-    about: Check the docs first - guides and examples
-  - name: 🚀 Priority Development
-    url: mailto:[email protected]
-    about: Need a feature implemented quickly? Paid development available
+    about: Check the docs first - guides and examples

.github/pull_request_template.md

@@ -21,6 +21,8 @@
 
 - [ ] I ran `overcommit --install` and all hooks pass
 - [ ] I tested my changes thoroughly
+  - [ ] For provider changes: Re-recorded VCR cassettes with `bundle exec rake vcr:record[provider_name]`
+  - [ ] All tests pass: `bundle exec rspec`
 - [ ] I updated documentation if needed
 - [ ] I didn't modify auto-generated files manually (`models.json`, `aliases.json`)
 

.github/workflows/cicd.yml

@@ -49,6 +49,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        lfs: true
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
@@ -97,6 +99,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        lfs: true
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

.github/workflows/docs.yml

@@ -24,6 +24,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          lfs: true
 
       - name: Setup Ruby for models guide generation (root Gemfile)
         uses: ruby/setup-ruby@v1

.overcommit.yml

@@ -24,9 +24,20 @@ PreCommit:
     description: 'Update appraisal gemfiles'
     command: ['bundle', 'exec', 'appraisal', 'update']
 
+PrePush:
+  GitLfs:
+    enabled: true
+    description: 'Push LFS objects to remote'
+    command: ['bash', '-c', 'git lfs pre-push "$@"', '--']
+
 PostCheckout:
   ALL: # Special hook name that customizes all hooks of this type
     quiet: true # Change all post-checkout hooks to only display output on failure
 
   IndexTags:
-    enabled: true # Generate a tags file with `ctags` each time HEAD changes
+    enabled: true # Generate a tags file with `ctags` each time HEAD changes
+
+  LfsInstall:
+    enabled: true
+    description: 'Ensure Git LFS files are pulled'
+    command: ['git', 'lfs', 'pull']

CONTRIBUTING.md

@@ -1,85 +1,79 @@
 # Contributing to RubyLLM
 
-Thanks for considering contributing! Here's what you need to know.
+## Did you find a bug?
 
-## Philosophy & Scope
+* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/crmne/ruby_llm/issues).
 
-RubyLLM does one thing well: **LLM communication in Ruby**.
+* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/crmne/ruby_llm/issues/new). Include a **title and clear description**, relevant information, and a **code sample** demonstrating the issue.
 
-### ✅ We Want
-- LLM provider integrations and new provider features
-- Convenience that benefits most users (Rails generators, etc.)
-- Performance and API consistency improvements
+* **Verify it's a RubyLLM bug**, not your application code, before opening an issue.
 
-### ❌ We Don't Want
-- Application architecture (testing, persistence, error tracking)
-- One-off solutions you can build in your app
-- Auxiliary features unrelated to LLM communication
+## Did you write a patch that fixes a bug?
 
-### Requests We'll Close
-- **RAG support** → Use dedicated libraries
-- **Prompt templates** → Use ERB/Mustache in your app
-- **Model data fixes** → File with [Parsera](https://github.com/parsera-labs/api-llm-specs/issues)
-- **Auto-failover** → Use `.with_model()` (works mid-conversation, even across providers)
-- **Tool interface changes** → Handle in your tool's initializer
-- **Testing helpers** → Use dependency injection
+* Open a new GitHub pull request with the patch.
 
-**The rule:** If you can solve it in application code, you should.
+* Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
 
-## Response Times & Paid Work
+* Run `overcommit --install` before committing - it handles code style and tests automatically.
 
-This is unpaid work I do between other priorities. I respond when I can.
+## Do you intend to add a new feature or change an existing one?
 
-**Need something fast?** Email **[email protected]** for paid development. $200/hour, 10-hour minimum ($2000).
+* **First check if this belongs in RubyLLM or your application:**
+  - ✅ Core LLM communication (provider integrations, streaming, cost tracking)
+  - ❌ Application architecture (RAG, agents, prompt templates, testing helpers)
+
+* Features we'll reject:
+  - Multi-agent orchestration
+  - RAG pipelines
+  - Prompt management systems
+  - Vector database integrations
+  - Testing frameworks
+  - Anything you can implement in 5-10 lines of application code
+
+* Start by opening an issue to discuss the feature and its design. We want to keep RubyLLM simple and focused.
 
 ## Quick Start
 
 ```bash
 gh repo fork crmne/ruby_llm --clone && cd ruby_llm
 bundle install
-overcommit --install
+overcommit --install  # Required - sets up git hooks
 gh issue develop 123 --checkout  # or create your own branch
 # make changes, add tests
 gh pr create --web
 ```
 
-## Essential Rules
-
-1. **Run `overcommit --install` before doing anything** - it auto-fixes style, runs tests, and updates model files on commit
-2. **Don't edit `models.json` or `aliases.json`** - overcommit regenerates them automatically
-3. **Write clear PR descriptions** - explain what and why
-
-The git hooks handle style, tests, and file generation for you. No excuses for broken commits.
-
 ## Testing
 
-Run linting: `bundle exec rubocop`
-
-Run tests: `bundle exec rspec`
-
-**Re-recording VCR cassettes?** Set API keys and run:
 ```bash
-bundle exec rake vcr:record[openai,anthropic]  # specific providers
-bundle exec rake vcr:record[all]               # everything
+overcommit --run
+
+# Re-recording VCR cassettes (requires API keys):
+rake vcr:record[openai,anthropic]  # Specific providers
+rake vcr:record[all]               # Everything
 ```
 
-**Then inspect the YAML files** - make sure no API keys leaked.
+Always check cassettes for leaked API keys before committing.
+
+## Important Notes
+
+* **Never edit `models.json`, `aliases.json`, or `available-models.md`** - they're auto-generated by `rake models`
+* **Write tests** for any new functionality
+* **Keep it simple** - if it needs extensive documentation, reconsider the approach
+* Model data comes from [Parsera](https://parsera.org). Firstly, go say thanks for their free service to the LLM dev community! They scrape LLM documentation and make it available to all of us in JSON. Secondly, [file model data issues with them](https://github.com/parsera-labs/api-llm-specs/issues).
 
-## Model Registry
+## Response Times
 
-**Don't touch these files directly:**
-- `models.json` - auto-generated from provider APIs + [Parsera](https://api.parsera.org/v1/llm-specs)
-- `aliases.json` - auto-generated from models.json
+This is my gift to the Ruby community.
 
-**To update model info:**
-- Public model issues → File with [Parsera](https://github.com/parsera-labs/api-llm-specs/issues)
+Gifts don't come with SLAs. I respond when I can.
 
-## Support the Project
+## Support
 
-Consider [sponsoring RubyLLM](https://github.com/sponsors/crmne) to help with ongoing costs. Sponsorship supports general maintenance - for priority features, use paid development above.
+If RubyLLM helps you, consider [sponsoring](https://github.com/sponsors/crmne).
 
----
+Sponsorship is just a way to say thanks - it doesn't buy priority support or feature requests.
 
-That's it. Let's make Ruby the best AI development experience possible.
+Go ship AI apps!
 
 — Carmine

README.md

@@ -17,6 +17,9 @@ Battle tested at [<picture><source media="(prefers-color-scheme: dark)" srcset="
 <a href="https://trendshift.io/repositories/13640" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13640" alt="crmne%2Fruby_llm | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </div>
 
+> [!NOTE]
+> Using RubyLLM in production? [Share your story](https://tally.so/r/3Na02p)! Takes 5 minutes.
+
 ---
 
 Build chatbots, AI agents, RAG applications. Works with OpenAI, Anthropic, Google, AWS, local models, and any OpenAI-compatible API.

docs/_advanced/agentic-workflows.md

@@ -40,11 +40,11 @@ class ModelRouter < RubyLLM::Tool
 
     case task_type
     when :code
-      RubyLLM.chat(model: 'claude-3-5-sonnet').ask(query).content
+      RubyLLM.chat(model: '{{ site.models.best_for_code }}').ask(query).content
     when :creative
-      RubyLLM.chat(model: 'gpt-4o').ask(query).content
+      RubyLLM.chat(model: '{{ site.models.best_for_creative }}').ask(query).content
     when :factual
-      RubyLLM.chat(model: 'gemini-1.5-pro').ask(query).content
+      RubyLLM.chat(model: '{{ site.models.best_for_factual }}').ask(query).content
     else
       RubyLLM.chat.ask(query).content
     end
@@ -53,7 +53,7 @@ class ModelRouter < RubyLLM::Tool
   private
 
   def classify_task(query)
-    classifier = RubyLLM.chat(model: 'gpt-4o-mini')
+    classifier = RubyLLM.chat(model: '{{ site.models.openai_mini }}')
                      .with_instructions("Classify: code, creative, or factual. One word only.")
     classifier.ask(query).content.downcase.to_sym
   end
@@ -154,7 +154,7 @@ class ResearchAgent < RubyLLM::Tool
   param :topic, desc: "Topic to research"
 
   def execute(topic:)
-    RubyLLM.chat(model: 'gemini-1.5-pro')
+    RubyLLM.chat(model: '{{ site.models.gemini_current }}')
            .ask("Research #{topic}. List key facts.")
            .content
   end
@@ -165,7 +165,7 @@ class WriterAgent < RubyLLM::Tool
   param :research, desc: "Research findings"
 
   def execute(research:)
-    RubyLLM.chat(model: 'claude-3-5-sonnet')
+    RubyLLM.chat(model: '{{ site.models.anthropic_current }}')
            .ask("Write an article:\n#{research}")
            .content
   end
@@ -227,19 +227,19 @@ class CodeReviewSystem
     Async do |task|
       # Run reviews in parallel
       task.async do
-        reviews[:security] = RubyLLM.chat(model: 'claude-3-5-sonnet')
+        reviews[:security] = RubyLLM.chat(model: '{{ site.models.anthropic_current }}')
           .ask("Security review:\n#{code}")
           .content
       end
 
       task.async do
-        reviews[:performance] = RubyLLM.chat(model: 'gpt-4o')
+        reviews[:performance] = RubyLLM.chat(model: '{{ site.models.openai_tools }}')
           .ask("Performance review:\n#{code}")
           .content
       end
 
       task.async do
-        reviews[:style] = RubyLLM.chat(model: 'gpt-4o-mini')
+        reviews[:style] = RubyLLM.chat(model: '{{ site.models.openai_mini }}')
           .ask("Style review (Ruby conventions):\n#{code}")
           .content
       end

docs/_advanced/error-handling.md

@@ -110,7 +110,7 @@ Instances of `RubyLLM::Error` (and its subclasses related to API responses) hold
 
 ```ruby
 begin
-  chat = RubyLLM.chat(model: 'gpt-4.1-nano') # Assume this requires a specific org sometimes
+  chat = RubyLLM.chat(model: '{{ site.models.default_chat }}') # Assume this requires a specific org sometimes
   response = chat.ask "Some specific query"
 rescue RubyLLM::ForbiddenError => e
   puts "Access forbidden: #{e.message}"