ruby_llm_community 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd050c159cde376efb60a5f9c5847687ff9a1f44a8d98f5ee93440ea65bc1f38
-  data.tar.gz: dae5536d6035f67546136f12ffe1fc52d602bdffc8dd5eeba120fec2313c4cd7
+  metadata.gz: 2a8638f12f0c6d0e811f078bdf311d3dde1bc969f6881ed64cf1a5133256b574
+  data.tar.gz: 4bba1ef73b4624fca8ef83c4cd661d9bdb3a15f209da11a3a962cab24b4fdb80
 SHA512:
-  metadata.gz: 55181d506b358aa4cc88a9e1c749694cc5d1a29c1116f0639c0a7b8d68a60599a7911dac90a1073da1d5b5188a5a519ae73907935fc558aebc1a2d0059bfa072
-  data.tar.gz: 8cf8d948c812075b068479e25737a0d43999831f2dea87a018d6d62fe8c1049d96bb27076f88173ed91d4bd4ae1939669d768402ee9e8ce8e5c215c14014d909
+  metadata.gz: e083eaa68a50b78854d780b3ddd2dc2467652aceb62fd9633b1b9a75f48b89bb8ad885800f65cb376b4f2997336284d27baf3508f3fe2bbfe920cac064f85df5
+  data.tar.gz: c068573609da8e4755201536aea1084b08b819e6d928c8624090f3a20133e253a86688d4ad5db206254be86c5795d66e3f12ffe945e308dc5cf24af479c8d403

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Carmine Paolino
+Copyright (c) 2025 Paul Shippy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,172 @@
+<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.
+
+<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>
+</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*
+
+## The problem with AI libraries
+
+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.
+
+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.
+
+## What makes it great
+
+```ruby
+# Just ask questions
+chat = RubyLLM.chat
+chat.ask "What's the best way to learn Ruby?"
+
+# Analyze images, audio, documents, and text files
+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
+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|
+  print chunk.content
+end
+
+# Generate images
+RubyLLM.paint "a sunset over mountains in watercolor style"
+
+# Create vector embeddings
+RubyLLM.embed "Ruby is elegant and expressive"
+
+# 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)"
+
+  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(Weather).ask "What's the weather in Berlin? (52.5200, 13.4050)"
+
+# Get structured output with JSON schemas
+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"
+  end
+end
+
+response = chat.with_schema(ProductSchema)
+               .ask "Analyze this product description", with: "product.txt"
+# response.content => { "name" => "...", "price" => 99.99, "features" => [...] }
+```
+
+## 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.
+
+## Installation
+
+Add to your Gemfile:
+```ruby
+gem 'ruby_llm'
+```
+Then `bundle install`.
+
+Configure your API keys (using environment variables is recommended):
+```ruby
+# config/initializers/ruby_llm.rb or similar
+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 ...
+end
+```
+See the [Installation Guide](https://rubyllm.com/installation) for full details.
+
+## Rails Integration
+
+Add persistence to your chat models effortlessly:
+
+```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
+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")
+```
+
+See the [Rails Integration Guide](https://rubyllm.com/guides/rails) for details.
+
+## Learn More
+
+Dive deeper with the official 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)
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on setup, testing, and contribution guidelines.
+
+## License
+
+Released under the MIT License.

data/lib/generators/ruby_llm/install/templates/INSTALL_INFO.md.tt

@@ -0,0 +1,108 @@
+# RubyLLM Rails Setup Complete!
+
+Thanks for installing RubyLLM in your Rails application. Here's what was created:
+
+## Models
+
+- `<%= options[:chat_model_name] %>` - Stores chat sessions and their associated model ID
+- `<%= options[:message_model_name] %>` - Stores individual messages in a chat
+- `<%= options[:tool_call_model_name] %>` - Stores tool calls made by language models
+
+**Note:** Do not add `validates :content, presence: true` to your Message model - RubyLLM creates empty assistant messages before API calls for streaming support.
+
+## Configuration Options
+
+The generator supports the following options to customize model names:
+
+```bash
+rails generate ruby_llm:install \
+  --chat-model-name=Conversation \
+  --message-model-name=ChatMessage \
+  --tool-call-model-name=FunctionCall
+```
+
+This is useful when you need to avoid namespace collisions with existing models in your application. Table names will be automatically derived from the model names following Rails conventions.
+
+## Next Steps
+
+1. **Run migrations:**
+   ```bash
+   rails db:migrate
+   ```
+
+   **Database Note:** The migrations use `jsonb` for PostgreSQL and `json` for MySQL/SQLite automatically.
+
+2. **Set your API keys** in `config/initializers/ruby_llm.rb` or using environment variables:
+   ```ruby
+   # config/initializers/ruby_llm.rb
+   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']
+     # ... add other providers as needed
+   end
+   ```
+
+3. **Start using RubyLLM in your code:**
+   ```ruby
+   # Basic usage
+   chat = <%= options[:chat_model_name] %>.create!(model_id: 'gpt-4.1-nano')
+   response = chat.ask("What is Ruby on Rails?")
+
+   # With file attachments (requires ActiveStorage setup)
+   chat.ask("What's in this file?", with: "report.pdf")
+   chat.ask("Analyze these files", with: ["image.jpg", "data.csv", "notes.txt"])
+   ```
+
+4. **For streaming responses** with Hotwire/Turbo:
+   ```ruby
+   # app/models/<%= options[:message_model_name].underscore %>.rb
+   class <%= options[:message_model_name] %> < ApplicationRecord
+     acts_as_message
+
+     # Helper to broadcast chunks during streaming
+     def broadcast_append_chunk(chunk_content)
+       broadcast_append_to [ chat, "messages" ],
+         target: dom_id(self, "content"),
+         html: chunk_content
+     end
+   end
+
+   # app/jobs/chat_stream_job.rb
+   class ChatStreamJob < ApplicationJob
+     def perform(chat_id, user_content)
+       chat = <%= options[:chat_model_name] %>.find(chat_id)
+       chat.ask(user_content) do |chunk|
+         assistant_message = chat.messages.last
+         if chunk.content && assistant_message
+           assistant_message.broadcast_append_chunk(chunk.content)
+         end
+       end
+     end
+   end
+
+   # In your controller
+   ChatStreamJob.perform_later(@chat.id, params[:content])
+   ```
+
+## Optional: ActiveStorage for Attachments
+
+If you want to use file attachments (PDFs, images, etc.), set up ActiveStorage:
+
+```bash
+rails active_storage:install
+rails db:migrate
+```
+
+Then add to your Message model:
+```ruby
+class <%= options[:message_model_name] %> < ApplicationRecord
+  acts_as_message
+  has_many_attached :attachments
+end
+```
+
+## Learn More
+
+- See the [Rails Integration Guide](https://rubyllm.com/guides/rails) for detailed examples
+- Visit the [RubyLLM Documentation](https://rubyllm.com) for full API reference

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

@@ -0,0 +1,3 @@
+class <%= options[:chat_model_name] %> < ApplicationRecord
+  <%= acts_as_chat_declaration %>
+end

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

@@ -0,0 +1,8 @@
+class Create<%= options[:chat_model_name].pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= options[:chat_model_name].tableize %> do |t|
+      t.string :model_id
+      t.timestamps
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# Migration for creating messages table with references to chats and tool_calls
+class Create<%= options[:message_model_name].pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= options[:message_model_name].tableize %> do |t|
+      t.references :<%= options[:chat_model_name].tableize.singularize %>, null: false, foreign_key: true
+      t.string :role
+      t.text :content
+      t.string :model_id
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.references :<%= options[:tool_call_model_name].tableize.singularize %>
+      t.timestamps
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+<%#- # Migration for creating tool_calls table with database-specific JSON handling -%>
+class Create<%= options[:tool_call_model_name].pluralize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= options[:tool_call_model_name].tableize %> do |t|
+      t.references :<%= options[:message_model_name].tableize.singularize %>, null: false, foreign_key: true
+      t.string :tool_call_id, null: false
+      t.string :name, null: false
+      t.<%= postgresql? ? 'jsonb' : 'json' %> :arguments, default: {}
+      t.timestamps
+    end
+
+    add_index :<%= options[:tool_call_model_name].tableize %>, :tool_call_id
+  end
+end

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

@@ -0,0 +1,6 @@
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV["OPENAI_API_KEY"]
+  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+
+  # config.default_model = "gpt-4.1-nano"
+end

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

@@ -0,0 +1,3 @@
+class <%= options[:message_model_name] %> < ApplicationRecord
+  <%= acts_as_message_declaration %>
+end

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

@@ -0,0 +1,3 @@
+class <%= options[:tool_call_model_name] %> < ApplicationRecord
+  <%= acts_as_tool_call_declaration %>
+end

data/lib/generators/ruby_llm/install_generator.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module RubyLLM
+  # Generator for RubyLLM Rails models and migrations
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    namespace 'ruby_llm:install'
+
+    source_root File.expand_path('install/templates', __dir__)
+
+    class_option :chat_model_name, type: :string, default: 'Chat',
+                                   desc: 'Name of the Chat model class'
+    class_option :message_model_name, type: :string, default: 'Message',
+                                      desc: 'Name of the Message model class'
+    class_option :tool_call_model_name, type: :string, default: 'ToolCall',
+                                        desc: 'Name of the ToolCall model class'
+
+    desc 'Creates model files for Chat, Message, and ToolCall, and creates migrations for RubyLLM Rails integration'
+
+    def self.next_migration_number(dirname)
+      ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+
+    def migration_version
+      "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+    end
+
+    def postgresql?
+      ::ActiveRecord::Base.connection.adapter_name.downcase.include?('postgresql')
+    rescue StandardError
+      false
+    end
+
+    def acts_as_chat_declaration
+      acts_as_chat_params = []
+      if options[:message_model_name] != 'Message'
+        acts_as_chat_params << "message_class: \"#{options[:message_model_name]}\""
+      end
+      if options[:tool_call_model_name] != 'ToolCall'
+        acts_as_chat_params << "tool_call_class: \"#{options[:tool_call_model_name]}\""
+      end
+      if acts_as_chat_params.any?
+        "acts_as_chat #{acts_as_chat_params.join(', ')}"
+      else
+        'acts_as_chat'
+      end
+    end
+
+    def acts_as_message_declaration
+      acts_as_message_params = []
+      acts_as_message_params << "chat_class: \"#{options[:chat_model_name]}\"" if options[:chat_model_name] != 'Chat'
+      if options[:tool_call_model_name] != 'ToolCall'
+        acts_as_message_params << "tool_call_class: \"#{options[:tool_call_model_name]}\""
+      end
+      if acts_as_message_params.any?
+        "acts_as_message #{acts_as_message_params.join(', ')}"
+      else
+        'acts_as_message'
+      end
+    end
+
+    def acts_as_tool_call_declaration
+      acts_as_tool_call_params = []
+      if options[:message_model_name] != 'Message'
+        acts_as_tool_call_params << "message_class: \"#{options[:message_model_name]}\""
+      end
+      if acts_as_tool_call_params.any?
+        "acts_as_tool_call #{acts_as_tool_call_params.join(', ')}"
+      else
+        'acts_as_tool_call'
+      end
+    end
+
+    def create_migration_files
+      # Create migrations with timestamps to ensure proper order
+      # First create chats table
+      migration_template 'create_chats_migration.rb.tt',
+                         "db/migrate/create_#{options[:chat_model_name].tableize}.rb"
+
+      # Then create messages table (must come before tool_calls due to foreign key)
+      sleep 1 # Ensure different timestamp
+      migration_template 'create_messages_migration.rb.tt',
+                         "db/migrate/create_#{options[:message_model_name].tableize}.rb"
+
+      # Finally 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"
+    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"
+    end
+
+    def create_initializer
+      template 'initializer.rb.tt', 'config/initializers/ruby_llm.rb'
+    end
+
+    def show_install_info
+      say "\n  ✅ RubyLLM installed!", :green
+
+      say "\n  Next steps:", :yellow
+      say '     1. Run: rails db:migrate'
+      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!')"
+
+      say "\n  📚 Full docs: https://rubyllm.com", :cyan
+
+      say "\n  ❤️  Love RubyLLM?", :magenta
+      say '     • ⭐ Star on GitHub: https://github.com/crmne/ruby_llm'
+      say '     • 💖 Sponsor: https://github.com/sponsors/crmne'
+      say "\n"
+    end
+  end
+end