ruby_llm_community 0.0.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9007798f0f3d2c512b138292c6040aede0a135688b931e202c0c8baca10d6623
-  data.tar.gz: 8fb9a3af7a4e48d437f65dcca8a9a2d50f7f1c04c385a2b4aa38456e7efc7993
+  metadata.gz: 0d28b384f53784c1954147d9f217caff1325893f1853e6be63c60158d9c37b79
+  data.tar.gz: 3c6e66e260c1300b3b20ae730ec3755fcca19be8afc8dee754e26cc82cbee7f4
 SHA512:
-  metadata.gz: b5b5801c832fb0e0ccb2a38368b1160f22d1f31f17192e15f11cfcedde91b95a7a1ad6ccab273c29910354199643a67b66e1da38888393ca2017921c031a060b
-  data.tar.gz: f37724b8396ba64f5e50b7a64173af90d0d8e02b6029d0f07c732d3323bf2038f0adb4f8f7db13430fe42dcf25d7065b2d47568f4609a382fd74035f0d25237f
+  metadata.gz: 568f6c9a3facf5e5f721ec6e3d44862eb0988529cf72625a88220fe80f00ba89f5602f0a178d0ead3cfc3c4accca3a4b56321a3a24f84883df16bd1c72432458
+  data.tar.gz: e6336936468acfc005284a1e6f7cbffe58e55e85c760082af71569d9555371ed124b26fe0cc70d274124f4b80530881c012d10079145f0c90383f2d6e2c51ff7

data/README.md

@@ -1,99 +1,114 @@
+<div align="center">
+
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="/docs/assets/images/logotype_dark.svg">
   <img src="/docs/assets/images/logotype.svg" alt="RubyLLM" height="120" width="250">
 </picture>
 
-**One *beautiful* Ruby API for GPT, Claude, Gemini, and more.** Easily build chatbots, AI agents, RAG applications, and content generators. Features chat (text, images, audio, PDFs), image generation, embeddings, tools (function calling), structured output, Rails integration, and streaming. Works with OpenAI, Anthropic, Google Gemini, AWS Bedrock, DeepSeek, Mistral, Ollama (local models), OpenRouter, Perplexity, GPUStack, and any OpenAI-compatible API.
+<strong>One *beautiful* Ruby API for GPT, Claude, Gemini, and more.</strong>
+
+Battle tested at [<picture><source media="(prefers-color-scheme: dark)" srcset="https://chatwithwork.com/logotype-dark.svg"><img src="https://chatwithwork.com/logotype.svg" alt="Chat with Work" height="30" align="absmiddle"></picture>](https://chatwithwork.com) — *Claude Code for your documents*
+
+[![Gem Version](https://badge.fury.io/rb/ruby_llm.svg?a=7)](https://badge.fury.io/rb/ruby_llm)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+[![Gem Downloads](https://img.shields.io/gem/dt/ruby_llm)](https://rubygems.org/gems/ruby_llm)
+[![codecov](https://codecov.io/gh/crmne/ruby_llm/branch/main/graph/badge.svg?a=2)](https://codecov.io/gh/crmne/ruby_llm)
 
-<div class="badge-container">
-  <a href="https://badge.fury.io/rb/ruby_llm"><img src="https://badge.fury.io/rb/ruby_llm.svg?a=5" 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>
+<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>
 
-Battle tested at [<picture><source media="(prefers-color-scheme: dark)" srcset="https://chatwithwork.com/logotype-dark.svg"><img src="https://chatwithwork.com/logotype.svg" alt="Chat with Work" height="30" align="absmiddle"></picture>](https://chatwithwork.com) — *Claude Code for your documents*
+---
+
+Build chatbots, AI agents, RAG applications. Works with OpenAI, Anthropic, Google, AWS, local models, and any OpenAI-compatible API.
 
-## The problem with AI libraries
+## Why RubyLLM?
 
-Every AI provider comes with its own client library, its own response format, its own conventions for streaming, and its own way of handling errors. Want to use multiple providers? Prepare to juggle incompatible APIs and bloated dependencies.
+Every AI provider ships their own bloated client. Different APIs. Different response formats. Different conventions. It's exhausting.
 
-RubyLLM fixes all that. One beautiful API for everything. One consistent format. Minimal dependencies — just Faraday, Zeitwerk, and [Marcel](https://github.com/rails/marcel). Because working with AI should be a joy, not a chore.
+RubyLLM gives you one beautiful API for all of them. Same interface whether you're using GPT, Claude, or your local Ollama. Just three dependencies: [Faraday](https://github.com/lostisland/faraday), [Zeitwerk](https://github.com/fxn/zeitwerk), and [Marcel](https://github.com/rails/marcel). That's it.
 
-## What makes it great
+## Show me the code
 
 ```ruby
 # Just ask questions
 chat = RubyLLM.chat
 chat.ask "What's the best way to learn Ruby?"
+```
 
-# Analyze images, audio, documents, and text files
+```ruby
+# Analyze any file type
 chat.ask "What's in this image?", with: "ruby_conf.jpg"
 chat.ask "Describe this meeting", with: "meeting.wav"
 chat.ask "Summarize this document", with: "contract.pdf"
 chat.ask "Explain this code", with: "app.rb"
+```
 
-# Multiple files at once - types automatically detected
+```ruby
+# Multiple files at once
 chat.ask "Analyze these files", with: ["diagram.png", "report.pdf", "notes.txt"]
+```
 
-# Stream responses in real-time
-chat.ask "Tell me a story about a Ruby programmer" do |chunk|
+```ruby
+# Stream responses
+chat.ask "Tell me a story about Ruby" do |chunk|
   print chunk.content
 end
+```
 
+```ruby
 # Generate images
 RubyLLM.paint "a sunset over mountains in watercolor style"
+```
 
-# Create vector embeddings
+```ruby
+# Create embeddings
 RubyLLM.embed "Ruby is elegant and expressive"
+```
 
+```ruby
 # Let AI use your code
 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)"
+  description "Get current weather"
+  param :latitude
+  param :longitude
 
   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 }
+    JSON.parse(Faraday.get(url).body)
   end
 end
 
-chat.with_tool(Weather).ask "What's the weather in Berlin? (52.5200, 13.4050)"
+chat.with_tool(Weather).ask "What's the weather in Berlin?"
+```
 
-# Get structured output with JSON schemas
+```ruby
+# Get structured output
 class ProductSchema < RubyLLM::Schema
-  string :name, description: "Product name"
-  number :price, description: "Price in USD"
-  array :features, description: "Key features" do
-    string description: "Feature description"
+  string :name
+  number :price
+  array :features do
+    string
   end
 end
 
-response = chat.with_schema(ProductSchema)
-               .ask "Analyze this product description", with: "product.txt"
-# response.content => { "name" => "...", "price" => 99.99, "features" => [...] }
+response = chat.with_schema(ProductSchema).ask "Analyze this product", with: "product.txt"
 ```
 
-## Core Capabilities
-
-*   💬 **Unified Chat:** Converse with models from OpenAI, Anthropic, Gemini, Bedrock, OpenRouter, DeepSeek, Perplexity, Mistral, Ollama, or any OpenAI-compatible API using `RubyLLM.chat`.
-*   👁️ **Vision:** Analyze images within chats.
-*   🔊 **Audio:** Transcribe and understand audio content.
-*   📄 **Document Analysis:** Extract information from PDFs, text files, CSV, JSON, XML, Markdown, and code files.
-*   🖼️ **Image Generation:** Create images with `RubyLLM.paint`.
-*   📊 **Embeddings:** Generate text embeddings for vector search with `RubyLLM.embed`.
-*   🔧 **Tools (Function Calling):** Let AI models call your Ruby code using `RubyLLM::Tool`.
-*   📋 **Structured Output:** Guarantee responses conform to JSON schemas with `RubyLLM::Schema`.
-*   🚂 **Rails Integration:** Easily persist chats, messages, and tool calls using `acts_as_chat` and `acts_as_message`.
-*   🌊 **Streaming:** Process responses in real-time with idiomatic Ruby blocks.
-*   ⚡ **Async Support:** Built-in fiber-based concurrency for high-performance operations.
-*   🎯 **Smart Configuration:** Global and scoped configs with automatic retries and proxy support.
-*   📚 **Model Registry:** Access 500+ models with capability detection and pricing info.
+## Features
+
+* **Chat:** Conversational AI with `RubyLLM.chat`
+* **Vision:** Analyze images and screenshots
+* **Audio:** Transcribe and understand speech
+* **Documents:** Extract from PDFs, CSVs, JSON, any file type
+* **Image generation:** Create images with `RubyLLM.paint`
+* **Embeddings:** Vector search with `RubyLLM.embed`
+* **Tools:** Let AI call your Ruby methods
+* **Structured output:** JSON schemas that just work
+* **Streaming:** Real-time responses with blocks
+* **Rails:** ActiveRecord integration with `acts_as_chat`
+* **Async:** Fiber-based concurrency
+* **Model registry:** 500+ models with capability detection and pricing
+* **Providers:** OpenAI, Anthropic, Gemini, VertexAI, Bedrock, DeepSeek, Mistral, Ollama, OpenRouter, Perplexity, GPUStack, and any OpenAI-compatible API
 
 ## Installation
 
@@ -103,69 +118,36 @@ gem 'ruby_llm_community'
 ```
 Then `bundle install`.
 
-Configure your API keys (using environment variables is recommended):
+Configure your API keys:
 ```ruby
-# config/initializers/ruby_llm.rb or similar
+# config/initializers/ruby_llm.rb
 RubyLLM.configure do |config|
-  config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
-  # Add keys ONLY for providers you intend to use
-  # config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY', nil)
-  # ... see Configuration guide for all options ...
+  config.openai_api_key = ENV['OPENAI_API_KEY']
 end
 ```
-See the [Installation Guide](https://rubyllm.com/installation) for full details.
 
-## Rails Integration
-
-Add persistence to your chat models effortlessly:
+## Rails
 
 ```bash
-# Generate models and migrations
 rails generate ruby_llm:install
 ```
 
 ```ruby
-# Or add to existing models
 class Chat < ApplicationRecord
-  acts_as_chat # Automatically saves messages & tool calls
-end
-
-class Message < ApplicationRecord
-  acts_as_message
+  acts_as_chat
 end
 
-class ToolCall < ApplicationRecord
-  acts_as_tool_call
-end
-
-# Now chats persist automatically
-chat = Chat.create!(model_id: "gpt-4.1-nano")
-chat.ask("What's in this file?", with: "report.pdf")
+chat = Chat.create! model_id: "claude-sonnet-4"
+chat.ask "What's in this file?", with: "report.pdf"
 ```
 
-See the [Rails Integration Guide](https://rubyllm.com/guides/rails) for details.
-
-## Learn More
-
-Dive deeper with the official documentation:
+## Documentation
 
--   [Installation](https://rubyllm.com/installation)
--   [Configuration](https://rubyllm.com/configuration)
--   **Guides:**
-    -   [Getting Started](https://rubyllm.com/guides/getting-started)
-    -   [Chatting with AI Models](https://rubyllm.com/guides/chat)
-    -   [Using Tools](https://rubyllm.com/guides/tools)
-    -   [Streaming Responses](https://rubyllm.com/guides/streaming)
-    -   [Rails Integration](https://rubyllm.com/guides/rails)
-    -   [Image Generation](https://rubyllm.com/guides/image-generation)
-    -   [Embeddings](https://rubyllm.com/guides/embeddings)
-    -   [Working with Models](https://rubyllm.com/guides/models)
-    -   [Error Handling](https://rubyllm.com/guides/error-handling)
-    -   [Available Models](https://rubyllm.com/guides/available-models)
+[rubyllm.com](https://rubyllm.com)
 
 ## Contributing
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on setup, testing, and contribution guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

data/lib/generators/ruby_llm/install/templates/create_models_migration.rb.tt

@@ -0,0 +1,34 @@
+class Create<%= options[:model_model_name].pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= options[:model_model_name].tableize %> do |t|
+      t.string :model_id, null: false
+      t.string :name, null: false
+      t.string :provider, null: false
+      t.string :family
+      t.datetime :model_created_at
+      t.integer :context_window
+      t.integer :max_output_tokens
+      t.date :knowledge_cutoff
+<% if postgresql? %>
+      t.jsonb :modalities, default: {}
+      t.jsonb :capabilities, default: []
+      t.jsonb :pricing, default: {}
+      t.jsonb :metadata, default: {}
+<% else %>
+      t.json :modalities, default: {}
+      t.json :capabilities, default: []
+      t.json :pricing, default: {}
+      t.json :metadata, default: {}
+<% end %>
+      t.timestamps
+
+      t.index [:provider, :model_id], unique: true
+      t.index :provider
+      t.index :family
+<% if postgresql? %>
+      t.index :capabilities, using: :gin
+      t.index :modalities, using: :gin
+<% end %>
+    end
+  end
+end

data/lib/generators/ruby_llm/install/templates/initializer.rb.tt

@@ -3,4 +3,9 @@ RubyLLM.configure do |config|
   config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
 
   # config.default_model = "gpt-4.1-nano"
+<% unless options[:skip_model] %>
+
+  # Model registry persistence
+  config.model_registry_class = "<%= options[:model_model_name] %>"
+<% end %>
 end

data/lib/generators/ruby_llm/install/templates/model_model.rb.tt

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Model registry persistence
+class <%= options[:model_model_name] %> < ApplicationRecord
+  <%= acts_as_model_declaration %>
+end

data/lib/generators/ruby_llm/install_generator.rb

@@ -18,8 +18,12 @@ module RubyLLM
                                       desc: 'Name of the Message model class'
     class_option :tool_call_model_name, type: :string, default: 'ToolCall',
                                         desc: 'Name of the ToolCall model class'
+    class_option :model_model_name, type: :string, default: 'Model',
+                                    desc: 'Name of the Model model class (for model registry)'
+    class_option :skip_model, type: :boolean, default: false,
+                              desc: 'Skip creating Model model for model registry persistence'
 
-    desc 'Creates model files for Chat, Message, and ToolCall, and creates migrations for RubyLLM Rails integration'
+    desc 'Creates models and migrations for RubyLLM Rails integration'
 
     def self.next_migration_number(dirname)
       ::ActiveRecord::Generators::Base.next_migration_number(dirname)
@@ -75,6 +79,10 @@ module RubyLLM
       end
     end
 
+    def acts_as_model_declaration
+      'acts_as_model'
+    end
+
     def create_migration_files
       # Create migrations with timestamps to ensure proper order
       # First create chats table
@@ -86,16 +94,27 @@ module RubyLLM
       migration_template 'create_messages_migration.rb.tt',
                          "db/migrate/create_#{options[:message_model_name].tableize}.rb"
 
-      # Finally create tool_calls table (references messages)
+      # Then create tool_calls table (references messages)
       sleep 1 # Ensure different timestamp
       migration_template 'create_tool_calls_migration.rb.tt',
                          "db/migrate/create_#{options[:tool_call_model_name].tableize}.rb"
+
+      # Finally create models table (for model registry)
+      return if options[:skip_model]
+
+      sleep 1 # Ensure different timestamp
+      migration_template 'create_models_migration.rb.tt',
+                         "db/migrate/create_#{options[:model_model_name].tableize}.rb"
     end
 
     def create_model_files
       template 'chat_model.rb.tt', "app/models/#{options[:chat_model_name].underscore}.rb"
       template 'message_model.rb.tt', "app/models/#{options[:message_model_name].underscore}.rb"
       template 'tool_call_model.rb.tt', "app/models/#{options[:tool_call_model_name].underscore}.rb"
+
+      return if options[:skip_model]
+
+      template 'model_model.rb.tt', "app/models/#{options[:model_model_name].underscore}.rb"
     end
 
     def create_initializer
@@ -110,6 +129,12 @@ module RubyLLM
       say '     2. Set your API keys in config/initializers/ruby_llm.rb'
       say "     3. Start chatting: #{options[:chat_model_name]}.create!(model_id: 'gpt-4.1-nano').ask('Hello!')"
 
+      unless options[:skip_model]
+        say "     4. Sync models: #{options[:model_model_name]}.sync!"
+        say "\n  🚀 Model registry is database-backed!", :cyan
+        say '     Models will automatically load from the database'
+      end
+
       say "\n  📚 Full docs: https://rubyllm.com", :cyan
 
       say "\n  ❤️  Love RubyLLM?", :magenta