ruby_llm 0.1.0.pre49 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7a86805562863f11f52b4cc62826401774291b1a299a328d8622e8a721ffcd9
-  data.tar.gz: 7757aa1b1ad19804c508a7988dd50fe91acce3e9ab0f66f69e013eb59c5c9196
+  metadata.gz: fd4d6fd8e0894176fff57bd2a3132b965afbb912108d45d94cba3b4b3106ff7c
+  data.tar.gz: 071a8ff4dcffcba66d042d3e822c2297b8a2c4485c4ee1fb48d0a03ec49c0547
 SHA512:
-  metadata.gz: b4ce44b2baa5cc565b52f162acc8ce30517616425d7f3d320fc1357d64f9f657532f3c9f20fbbb2dc8a6cd340f5ba84bad912fbdceab184929ce971766c09071
-  data.tar.gz: 6c15ce1c00cda64980d451a470ab1007bb7914fce9da43d3a1ce2bf08950c15bdd96ab2b80d9749292561e22903acc4974c20265b58a26d4130bd86f28018a7e
+  metadata.gz: 5d995c552810743910286207c47d2342de7e2ee14b833b627267d4fcec3c02931650b499de048319de293914fd0c19689124f818e994e74de04e8c819b934e91
+  data.tar.gz: 85598c0a2b633092eb5d5fa5b13b59f03b2c3c5effd826f483d64b87f58b8caaf3637b28308d027eaeed3a03d708a0267b420556ca54206de9a9ac69ab97455c

data/.github/workflows/cicd.yml

@@ -9,10 +9,23 @@ on:
       - 'Gemfile'
       - 'Rakefile'
       - 'ruby_llm.gemspec'
+      - '.github/workflows/cicd.yml'
   pull_request:
     branches: [ "main" ]
+    paths:
+      - 'lib/**'
+      - 'spec/**'
+      - 'Gemfile'
+      - 'Rakefile'
+      - 'ruby_llm.gemspec'
+      - '.github/workflows/cicd.yml'
   workflow_call:
 
+# Define default permissions for this workflow
+permissions:
+  contents: read
+  packages: write  # Needed for publishing to GitHub Packages
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -37,6 +50,8 @@ jobs:
 
     - name: Run tests
       env:
+        # For PRs, we use VCR cassettes
+        # For main branch, we use real API keys for verification
         OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
         ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
         GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
@@ -69,7 +84,40 @@ jobs:
         ruby-version: '3.3'
         bundler-cache: true
 
+    - name: Check if version has changed
+      id: check_version
+      run: |
+        VERSION=$(ruby -r ./lib/ruby_llm/version.rb -e "puts RubyLLM::VERSION")
+        echo "Current version: $VERSION"
+
+        # Try to fetch from RubyGems
+        PUBLISHED_VERSION=$(gem list ruby_llm -r | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+' || echo "0.0.0")
+        echo "Published version: $PUBLISHED_VERSION"
+
+        if [ "$VERSION" = "$PUBLISHED_VERSION" ]; then
+          echo "Version has not changed, skipping publish"
+          echo "version_changed=false" >> $GITHUB_OUTPUT
+        else
+          echo "Version has changed from $PUBLISHED_VERSION to $VERSION"
+          echo "version_changed=true" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Test with real APIs before publishing
+      if: steps.check_version.outputs.version_changed == 'true'
+      run: |
+        echo "Removing all VCR cassettes to test against real APIs..."
+        rm -rf spec/fixtures/vcr_cassettes
+
+        echo "Running tests with real API calls..."
+        env -u CI bundle exec rspec
+      env:
+        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+        DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+
     - name: Publish to GPR
+      if: steps.check_version.outputs.version_changed == 'true'
       run: |
         mkdir -p $HOME/.gem
         touch $HOME/.gem/credentials
@@ -90,6 +138,7 @@ jobs:
         OWNER: ${{ github.repository_owner }}
 
     - name: Publish to RubyGems
+      if: steps.check_version.outputs.version_changed == 'true'
       run: |
         mkdir -p $HOME/.gem
         touch $HOME/.gem/credentials

data/.gitignore

@@ -9,6 +9,7 @@
 /test/tmp/
 /test/version_tmp/
 /tmp/
+.rspec_status
 
 # Used by dotenv library to load environment variables.
 .env
@@ -55,4 +56,4 @@ Gemfile.lock
 # Used by RuboCop. Remote config files pulled in from inherit_from directive.
 # .rubocop-https?--*
 
-repomix-output.txt
+repomix-output.*

data/.overcommit.yml

@@ -8,7 +8,7 @@ PreCommit:
     enabled: true
 
   RSpec:
-    enabled: false
+    enabled: true
     command: ['bundle', 'exec', 'rspec']
     on_warn: fail
 

data/CONTRIBUTING.md

@@ -0,0 +1,207 @@
+# Contributing to RubyLLM
+
+First off, thank you for considering contributing to RubyLLM! It's people like you that make RubyLLM such a great tool.
+
+## Development Setup
+
+Here's how to get started:
+
+```bash
+# Clone the repository
+gh repo clone crmne/ruby_llm
+cd ruby_llm
+
+# Install dependencies
+bundle install
+
+# Set up git hooks
+overcommit --install
+
+# Run the tests (uses VCR cassettes)
+bundle exec rspec
+```
+
+## Development Workflow
+
+We recommend using GitHub CLI to simplify the workflow:
+
+```bash
+# Create a new branch for your feature
+gh repo fork crmne/ruby_llm --clone
+cd ruby_llm
+
+# Find or make an issue for the feature on GitHub and then:
+gh issue develop 123 --checkout  # Substitute 123 with the issue number
+
+# Make your changes and test them
+# ...
+
+# Commit your changes
+git commit
+
+# Create a PR
+gh pr create --web
+```
+
+## Model Naming Convention & Provider Strategy
+
+When adding new providers to RubyLLM, please follow these guidelines:
+
+### Normalized Model IDs
+
+We use a consistent approach separating **what** (model) from **where** (provider):
+
+```ruby
+# Default way (from the native provider)
+chat = RubyLLM.chat(model: "claude-3-5-sonnet")
+
+# Same model via different provider
+chat = RubyLLM.chat(model: "claude-3-5-sonnet", provider: :bedrock)
+```
+
+### Implementing a Provider
+
+If you're adding a new provider:
+
+1. **Use normalized model IDs** - Don't include provider prefixes in the model ID itself
+2. **Add provider mapping** - Map the normalized IDs to your provider's specific format internally
+3. **Preserve capabilities** - Ensure models accessed through your provider report the same capabilities as their native counterparts
+4. **Update models.json** - Include your provider's models in models.json
+5. **Update aliases.json** - Add entries to aliases.json for models accessible through your provider
+6. **Implement refresh mechanism** - Ensure your provider supports the `list_models` method for refreshing
+
+### Model Aliases
+
+For providers that use complex model identifiers (like Bedrock's `anthropic.claude-3-5-sonnet-20241022-v2:0:200k`), add mappings to the global aliases.json file:
+
+```json
+{
+  "claude-3-5-sonnet": {
+    "anthropic": "claude-3-5-sonnet-20241022",
+    "bedrock": "anthropic.claude-3-5-sonnet-20241022-v2:0:200k",
+    "openrouter": "anthropic/claude-3.5-sonnet"
+  },
+  "gpt-4o": {
+    "openai": "gpt-4o-2024-05-13",
+    "bedrock": "anthropic.gpt-4o-2024-05-13",
+    "openrouter": "openai/gpt-4o"
+  }
+}
+```
+
+If a model can't be found with the provided ID and provider, a `ModelNotFoundError` will be raised with an informative message. Your implementation should make this error helpful by suggesting available alternatives.
+
+When the same model has multiple versions and context windows e.g.
+
+```
+anthropic.claude-3-5-sonnet-20240620-v1:0
+anthropic.claude-3-5-sonnet-20240620-v1:0:18k
+anthropic.claude-3-5-sonnet-20240620-v1:0:200k
+anthropic.claude-3-5-sonnet-20240620-v1:0:51k
+anthropic.claude-3-5-sonnet-20241022-v2:0
+anthropic.claude-3-5-sonnet-20241022-v2:0:18k
+anthropic.claude-3-5-sonnet-20241022-v2:0:200k
+anthropic.claude-3-5-sonnet-20241022-v2:0:51k
+```
+
+We default all aliases to the biggest context window, and the main alias (without date) to the latest version:
+
+```json
+  "claude-3-5-sonnet": {
+    "anthropic": "claude-3-5-sonnet-20241022",
+    "bedrock": "anthropic.claude-3-5-sonnet-20241022-v2:0:200k",
+    "openrouter": "anthropic/claude-3.5-sonnet"
+  },
+  "claude-3-5-sonnet-20241022": {
+    "anthropic": "claude-3-5-sonnet-20241022",
+    "bedrock": "anthropic.claude-3-5-sonnet-20241022-v2:0:200k",
+    "openrouter": "anthropic/claude-3.5-sonnet"
+  },
+  "claude-3-5-sonnet-20240620": {
+    "anthropic": "claude-3-5-sonnet-20240620",
+    "bedrock": "anthropic.claude-3-5-sonnet-20240620-v1:0:200k"
+  },
+```
+
+## Running Tests
+
+Tests automatically use VCR to record and replay HTTP interactions, so you don't need real API keys for testing:
+
+```bash
+# Run all tests (using existing VCR cassettes)
+bundle exec rspec
+
+# Run a specific test file
+bundle exec rspec spec/ruby_llm/chat_spec.rb
+```
+
+### Recording VCR Cassettes
+
+When you make changes that affect API interactions, you can record new VCR cassettes.
+
+If you have keys for all providers:
+
+```bash
+# Re-record all cassettes
+bundle exec rake vcr:record[all]
+```
+
+If you only have keys for specific providers (e.g., just OpenAI):
+
+```bash
+# Set the API keys you have
+export OPENAI_API_KEY=your_openai_key
+
+# Find and remove only cassettes for OpenAI, then run tests to re-record them
+bundle exec rake vcr:record[openai]
+
+# You can also specify multiple providers
+bundle exec rake vcr:record[openai,anthropic]
+```
+
+Important: After recording new cassettes, please **manually check** them for any sensitive information that might have been missed by the automatic filters.
+
+## Adding New Tests
+
+Tests automatically create VCR cassettes based on their descriptions, so make sure your test descriptions are unique and descriptive.
+
+## Coding Style
+
+We follow the [Standard Ruby](https://github.com/testdouble/standard) style. Please ensure your contributions adhere to this style.
+
+```bash
+# Check your code style
+bundle exec rubocop
+
+# Auto-fix style issues where possible
+bundle exec rubocop -A
+```
+
+## Documentation
+
+When adding new features, please include documentation updates:
+
+- Update relevant guides in the `docs/guides/` directory
+- Add inline documentation using YARD comments
+- Keep the README clean and focused on helping new users get started quickly
+
+## Philosophy
+
+RubyLLM follows certain design philosophies and conventions. Please refer to our [Philosophy Guide](https://rubyllm.com/philosophy) to ensure your contributions align with the project's vision.
+
+## Discussions and Issues
+
+- For questions and discussions, please use [GitHub Discussions](https://github.com/crmne/ruby_llm/discussions)
+- For bugs and feature requests, please use [GitHub Issues](https://github.com/crmne/ruby_llm/issues)
+
+## Release Process
+
+Gem versioning follows [Semantic Versioning](https://semver.org/):
+
+1. MAJOR version for incompatible API changes
+2. MINOR version for backwards-compatible functionality
+3. PATCH version for backwards-compatible bug fixes
+
+Releases are handled by the maintainers through the CI/CD pipeline.
+
+Thanks for helping make RubyLLM better!

data/Gemfile

@@ -27,6 +27,7 @@ group :development do
   gem 'simplecov', '>= 0.21'
   gem 'simplecov-cobertura'
   gem 'sqlite3'
+  gem 'vcr'
   gem 'webmock', '~> 3.18'
   gem 'yard', '>= 0.9'
 end

data/README.md

@@ -1,8 +1,8 @@
-# RubyLLM
+<img src="/docs/assets/images/logotype.svg" alt="RubyLLM" height="120" width="250">
 
 A delightful Ruby way to work with AI. No configuration madness, no complex callbacks, no handler hell – just beautiful, expressive Ruby code.
 
-<p align="center">
+<div style="display: flex; align-items: center; flex-wrap: wrap; gap: 4px;">
   <img src="https://upload.wikimedia.org/wikipedia/commons/4/4d/OpenAI_Logo.svg" alt="OpenAI" height="40" width="120">
   &nbsp;&nbsp;&nbsp;&nbsp;
   <img src="https://upload.wikimedia.org/wikipedia/commons/7/78/Anthropic_logo.svg" alt="Anthropic" height="40" width="120">
@@ -10,14 +10,12 @@ A delightful Ruby way to work with AI. No configuration madness, no complex call
   <img src="https://upload.wikimedia.org/wikipedia/commons/8/8a/Google_Gemini_logo.svg" alt="Google" height="40" width="120">
   &nbsp;&nbsp;&nbsp;&nbsp;
   <img src="https://upload.wikimedia.org/wikipedia/commons/e/ec/DeepSeek_logo.svg" alt="DeepSeek" height="40" width="120">
-</p>
+</div>
 
-<p align="center">
-  <a href="https://badge.fury.io/rb/ruby_llm"><img src="https://badge.fury.io/rb/ruby_llm.svg" alt="Gem Version" /></a>
-  <a href="https://github.com/testdouble/standard"><img src="https://img.shields.io/badge/code_style-standard-brightgreen.svg" alt="Ruby Style Guide" /></a>
-  <a href="https://rubygems.org/gems/ruby_llm"><img alt="Gem Downloads" src="https://img.shields.io/gem/dt/ruby_llm"></a>
-  <a href="https://codecov.io/gh/crmne/ruby_llm"><img src="https://codecov.io/gh/crmne/ruby_llm/branch/main/graph/badge.svg" alt="codecov" /></a>
-</p>
+<a href="https://badge.fury.io/rb/ruby_llm"><img src="https://badge.fury.io/rb/ruby_llm.svg?dummy=unused" alt="Gem Version" /></a>
+<a href="https://github.com/testdouble/standard"><img src="https://img.shields.io/badge/code_style-standard-brightgreen.svg" alt="Ruby Style Guide" /></a>
+<a href="https://rubygems.org/gems/ruby_llm"><img alt="Gem Downloads" src="https://img.shields.io/gem/dt/ruby_llm"></a>
+<a href="https://codecov.io/gh/crmne/ruby_llm"><img src="https://codecov.io/gh/crmne/ruby_llm/branch/main/graph/badge.svg" alt="codecov" /></a>
 
 🤺 Battle tested at [💬  Chat with Work](https://chatwithwork.com)
 
@@ -27,6 +25,17 @@ Every AI provider comes with its own client library, its own response format, it
 
 RubyLLM fixes all that. One beautiful API for everything. One consistent format. Minimal dependencies — just Faraday and Zeitwerk. Because working with AI should be a joy, not a chore.
 
+## Features
+
+- 💬 **Chat** with OpenAI, Anthropic, Gemini, and DeepSeek models
+- 👁️ **Vision and Audio** understanding
+- 📄 **PDF Analysis** for analyzing documents
+- 🖼️ **Image generation** with DALL-E and other providers
+- 📊 **Embeddings** for vector search and semantic analysis
+- 🔧 **Tools** that let AI use your Ruby code
+- 🚂 **Rails integration** to persist chats and messages with ActiveRecord
+- 🌊 **Streaming** responses with proper Ruby patterns
+
 ## What makes it great
 
 ```ruby
@@ -43,6 +52,11 @@ chat.ask "Describe this meeting", with: { audio: "meeting.wav" }
 # Analyze documents
 chat.ask "Summarize this document", with: { pdf: "contract.pdf" }
 
+# Stream responses in real-time
+chat.ask "Tell me a story about a Ruby programmer" do |chunk|
+  print chunk.content
+end
+
 # Generate images
 RubyLLM.paint "a sunset over mountains in watercolor style"
 
@@ -50,16 +64,22 @@ RubyLLM.paint "a sunset over mountains in watercolor style"
 RubyLLM.embed "Ruby is elegant and expressive"
 
 # Let AI use your code
-class Calculator < RubyLLM::Tool
-  description "Performs calculations"
-  param :expression, type: :string, desc: "Math expression to evaluate"
-
-  def execute(expression:)
-    eval(expression).to_s
+class Weather < RubyLLM::Tool
+  description "Gets current weather for a location"
+  param :latitude, desc: "Latitude (e.g., 52.5200)"
+  param :longitude, desc: "Longitude (e.g., 13.4050)"
+
+  def execute(latitude:, longitude:)
+    url = "https://api.open-meteo.com/v1/forecast?latitude=#{latitude}&longitude=#{longitude}&current=temperature_2m,wind_speed_10m"
+
+    response = Faraday.get(url)
+    data = JSON.parse(response.body)
+  rescue => e
+    { error: e.message }
   end
 end
 
-chat.with_tool(Calculator).ask "What's 123 * 456?"
+chat.with_tool(Weather).ask "What's the weather in Berlin? (52.5200, 13.4050)"
 ```
 
 ## Installation
@@ -82,7 +102,7 @@ RubyLLM.configure do |config|
   config.openai_api_key = ENV['OPENAI_API_KEY']
   config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
   config.gemini_api_key = ENV['GEMINI_API_KEY']
-  config.deepseek_api_key = ENV['DEEPSEEK_API_KEY'] # Optional
+  config.deepseek_api_key = ENV['DEEPSEEK_API_KEY']
 end
 ```
 
@@ -173,6 +193,18 @@ chat.with_tool(Search).ask "Find documents about Ruby 3.3 features"
 
 Check out the guides at https://rubyllm.com for deeper dives into conversations with tools, streaming responses, embedding generations, and more.
 
+## Contributing
+
+We welcome contributions to RubyLLM!
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions on how to:
+- Run the test suite
+- Add new features
+- Update documentation
+- Re-record VCR cassettes when needed
+
+We appreciate your help making RubyLLM better!
+
 ## License
 
-Released under the MIT License.
+Released under the MIT License.

data/lib/ruby_llm/chat.rb

@@ -16,7 +16,7 @@ module RubyLLM
     def initialize(model: nil)
       model_id = model || RubyLLM.config.default_model
       self.model = model_id
-      @temperature = @model.metadata['family'] == 'o1' ? 1 : 0.7
+      @temperature = 0.7
       @messages = []
       @tools = {}
       @on = {