ruby_llm 0.1.0.pre36 → 0.1.0.pre37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed17bc0b342342484bd1e92b57f3b88a74d77cd43daeb1a569b132188025bafd
-  data.tar.gz: '0970e337a393e85cff88a449e723aa7c3e3e189b1923e16cf619f95d1bf65b03'
+  metadata.gz: 8befc508f1a0bdbaf7b113f3a2f8584f78fbe756ac07b22344af9ea90bc47f31
+  data.tar.gz: 389cb1518cacfa6448f30891d45e573536c768aa8092f8d1fbac156ff4c2d4c5
 SHA512:
-  metadata.gz: 1e8b35980c57cd61e10c50b3eb97dbedbe138e2720b11940646c74807ada4c8b260aff3cbee8ed84abfa4b998d3d2747ff5f2421731fcf73ea038306774a2dc9
-  data.tar.gz: f0211b49713b10e00f1070fa7abb00a151ee7084e3f5e14b047be2c567afe4fcd5ade1ce662697a776470ab4e6c21e98ab1c453526e36b4ec29d6f7f6b9f6c0c
+  metadata.gz: 67493fd05b3c9f0765b8d7bd72d295756e615ad6ab8b133181c8a472d28a64ce83e8aaedf48f556de8e9ddc1d39c59fdd4e7cdf4f0521eff9b9d34726a6b6bcd
+  data.tar.gz: e4569279dc890b62881c3d8da2cd03370fd8a87f6c20f112fe0bbce2d61aec0acba726d9d89252b724f4f4a2cc97ce383f229bddc8ea9d6c204fbcc66e71f6de

data/.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+          working-directory: docs
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Build with Jekyll
+        working-directory: docs
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/.rspec_status

@@ -1,35 +1,7 @@
-example_id                                         | status | run_time        |
--------------------------------------------------- | ------ | --------------- |
-./spec/integration/chat_spec.rb[1:1:1:1]           | passed | 0.84333 seconds |
-./spec/integration/chat_spec.rb[1:1:1:2]           | passed | 3.81 seconds    |
-./spec/integration/chat_spec.rb[1:1:2:1]           | passed | 0.54605 seconds |
-./spec/integration/chat_spec.rb[1:1:2:2]           | passed | 1.25 seconds    |
-./spec/integration/chat_spec.rb[1:1:3:1]           | passed | 0.66439 seconds |
-./spec/integration/chat_spec.rb[1:1:3:2]           | passed | 2.84 seconds    |
-./spec/integration/content_spec.rb[1:1:1]          | passed | 3.51 seconds    |
-./spec/integration/content_spec.rb[1:1:2]          | passed | 1.11 seconds    |
-./spec/integration/content_spec.rb[1:1:3]          | passed | 1.77 seconds    |
-./spec/integration/content_spec.rb[1:2:1]          | passed | 1.68 seconds    |
-./spec/integration/content_spec.rb[1:2:2]          | passed | 2.01 seconds    |
-./spec/integration/embeddings_spec.rb[1:1:1:1]     | passed | 0.28694 seconds |
-./spec/integration/embeddings_spec.rb[1:1:1:2]     | passed | 0.32456 seconds |
-./spec/integration/embeddings_spec.rb[1:1:2:1]     | passed | 0.85006 seconds |
-./spec/integration/embeddings_spec.rb[1:1:2:2]     | passed | 0.82832 seconds |
-./spec/integration/error_handling_spec.rb[1:1]     | passed | 0.19746 seconds |
-./spec/integration/image_generation_spec.rb[1:1:1] | passed | 10.73 seconds   |
-./spec/integration/image_generation_spec.rb[1:1:2] | passed | 16.95 seconds   |
-./spec/integration/image_generation_spec.rb[1:1:3] | passed | 0.00024 seconds |
-./spec/integration/rails_spec.rb[1:1]              | passed | 3.39 seconds    |
-./spec/integration/rails_spec.rb[1:2]              | passed | 1.74 seconds    |
-./spec/integration/streaming_spec.rb[1:1:1:1]      | passed | 0.56418 seconds |
-./spec/integration/streaming_spec.rb[1:1:1:2]      | passed | 6.33 seconds    |
-./spec/integration/streaming_spec.rb[1:1:2:1]      | passed | 0.51911 seconds |
-./spec/integration/streaming_spec.rb[1:1:2:2]      | passed | 2.31 seconds    |
-./spec/integration/streaming_spec.rb[1:1:3:1]      | passed | 0.78299 seconds |
-./spec/integration/streaming_spec.rb[1:1:3:2]      | passed | 3.82 seconds    |
-./spec/integration/tools_spec.rb[1:1:1:1]          | passed | 3.89 seconds    |
-./spec/integration/tools_spec.rb[1:1:1:2]          | passed | 7.78 seconds    |
-./spec/integration/tools_spec.rb[1:1:2:1]          | passed | 1.25 seconds    |
-./spec/integration/tools_spec.rb[1:1:2:2]          | passed | 2.1 seconds     |
-./spec/integration/tools_spec.rb[1:1:3:1]          | passed | 1.59 seconds    |
-./spec/integration/tools_spec.rb[1:1:3:2]          | passed | 3.05 seconds    |
+example_id                                  | status | run_time     |
+------------------------------------------- | ------ | ------------ |
+./spec/ruby_llm/chat_content_spec.rb[1:1:1] | passed | 3.59 seconds |
+./spec/ruby_llm/chat_content_spec.rb[1:1:2] | passed | 1.51 seconds |
+./spec/ruby_llm/chat_content_spec.rb[1:1:3] | passed | 2.29 seconds |
+./spec/ruby_llm/chat_content_spec.rb[1:2:1] | passed | 2.06 seconds |
+./spec/ruby_llm/chat_content_spec.rb[1:2:2] | passed | 2.04 seconds |

data/.rubocop.yml

@@ -1,5 +1,10 @@
-require:
+plugins:
   - rubocop-rake
+  - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 3.1
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  Exclude:
+    - docs/**/*
+    - vendor/**/*

data/.yardopts

@@ -0,0 +1,12 @@
+--markup markdown
+--markup-provider redcarpet
+--title "RubyLLM API Documentation"
+--protected
+--private
+--embed-mixins
+--output-dir doc/yard
+--readme README.md
+lib/**/*.rb
+-
+LICENSE
+

data/Gemfile

@@ -3,3 +3,30 @@
 source 'https://rubygems.org'
 
 gemspec
+
+group :development do
+  # Rails integration dependencies
+  gem 'activerecord', '>= 6.0', '< 9.0'
+  gem 'activesupport', '>= 6.0', '< 9.0'
+
+  # Development dependencies
+  gem 'bundler', '>= 2.0'
+  gem 'codecov'
+  gem 'dotenv'
+  gem 'irb'
+  gem 'nokogiri'
+  gem 'overcommit', '>= 0.66'
+  gem 'pry', '>= 0.14'
+  gem 'rake', '>= 13.0'
+  gem 'rdoc'
+  gem 'reline'
+  gem 'rspec', '~> 3.12'
+  gem 'rubocop', '>= 1.0'
+  gem 'rubocop-rake', '>= 0.6'
+  gem 'rubocop-rspec'
+  gem 'simplecov', '>= 0.21'
+  gem 'simplecov-cobertura'
+  gem 'sqlite3'
+  gem 'webmock', '~> 3.18'
+  gem 'yard', '>= 0.9'
+end

data/bin/console

@@ -8,10 +8,10 @@ require 'dotenv/load'
 require 'irb'
 
 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']
+  config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
+  config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY', nil)
+  config.gemini_api_key = ENV.fetch('GEMINI_API_KEY', nil)
+  config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY', nil)
 end
 
 IRB.start(__FILE__)

data/docs/.gitignore

@@ -0,0 +1,7 @@
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+# Ignore folders generated by Bundler
+.bundle/
+vendor/

data/docs/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+gem 'jekyll', '~> 4.3'
+gem 'just-the-docs', '~> 0.7.0'
+gem 'webrick', '~> 1.8'
+
+# GitHub Pages plugins
+group :jekyll_plugins do
+  gem 'jekyll-remote-theme'
+  gem 'jekyll-seo-tag'
+end

data/docs/_config.yml

@@ -0,0 +1,43 @@
+title: RubyLLM
+description: A delightful Ruby way to work with AI
+url: https://crmne.github.io/ruby_llm
+baseurl: /ruby_llm
+remote_theme: just-the-docs/just-the-docs
+
+# Enable search
+search_enabled: true
+search:
+  heading_level: 2
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: false
+
+# Navigation structure
+nav_external_links:
+  - title: RubyLLM on GitHub
+    url: https://github.com/crmne/ruby_llm
+    hide_icon: false
+
+# Footer content
+footer_content: "Copyright &copy; 2025 <a href='https://paolino.me'>Carmine Paolino</a>. Distributed under an <a href=\"https://github.com/crmne/ruby_llm/tree/main/LICENSE\">MIT license.</a>"
+
+# Enable copy button on code blocks
+enable_copy_code_button: true
+
+# Make Anchor links show on hover
+heading_anchors: true
+
+# Color scheme
+color_scheme: light
+
+# Google Analytics
+ga_tracking:
+ga_tracking_anonymize_ip: true
+
+# Custom plugins (GitHub Pages allows these)
+plugins:
+  - jekyll-remote-theme
+  - jekyll-seo-tag

data/docs/_data/navigation.yml

@@ -0,0 +1,25 @@
+- title: Home
+  url: /
+- title: Installation
+  url: /installation
+- title: Guides
+  url: /guides/
+  subfolderitems:
+    - title: Getting Started
+      url: /guides/getting-started
+    - title: Chat
+      url: /guides/chat
+    - title: Tools
+      url: /guides/tools
+    - title: Streaming
+      url: /guides/streaming
+    - title: Rails Integration
+      url: /guides/rails
+    - title: Image Generation
+      url: /guides/image-generation
+    - title: Embeddings
+      url: /guides/embeddings
+    - title: Error Handling
+      url: /guides/error-handling
+- title: GitHub
+  url: https://github.com/crmne/ruby_llm

data/docs/guides/chat.md

@@ -0,0 +1,206 @@
+---
+layout: default
+title: Chat
+parent: Guides
+nav_order: 2
+permalink: /guides/chat
+---
+
+# Chatting with AI Models
+
+RubyLLM's chat interface provides a natural way to interact with various AI models. This guide covers everything from basic chatting to advanced features like multimodal inputs and streaming responses.
+
+## Basic Chat
+
+Creating a chat and asking questions is straightforward:
+
+```ruby
+# Create a chat with the default model
+chat = RubyLLM.chat
+
+# Ask a question
+response = chat.ask "What's the best way to learn Ruby?"
+
+# The response is a Message object
+puts response.content
+puts "Role: #{response.role}"
+puts "Model: #{response.model_id}"
+puts "Tokens: #{response.input_tokens} input, #{response.output_tokens} output"
+```
+
+## Choosing Models
+
+You can specify which model to use when creating a chat:
+
+```ruby
+# Create a chat with a specific model
+chat = RubyLLM.chat(model: 'gpt-4o-mini')
+
+# Use Claude instead
+claude_chat = RubyLLM.chat(model: 'claude-3-5-sonnet-20241022')
+
+# Or change the model for an existing chat
+chat.with_model('gemini-2.0-flash')
+```
+
+## Multi-turn Conversations
+
+Chats maintain conversation history automatically:
+
+```ruby
+chat = RubyLLM.chat
+
+# Start a conversation
+chat.ask "What's your favorite programming language?"
+
+# Follow up
+chat.ask "Why do you like that language?"
+
+# Continue the conversation
+chat.ask "What are its weaknesses?"
+
+# Access the conversation history
+chat.messages.each do |message|
+  puts "#{message.role}: #{message.content[0..50]}..."
+end
+```
+
+## Working with Images
+
+Vision-capable models can understand images:
+
+```ruby
+chat = RubyLLM.chat
+
+# Ask about an image (local file)
+chat.ask "What's in this image?", with: { image: "path/to/image.jpg" }
+
+# Or use an image URL
+chat.ask "Describe this picture", with: { image: "https://example.com/image.jpg" }
+
+# Include multiple images
+chat.ask "Compare these two charts", with: {
+  image: ["chart1.png", "chart2.png"]
+}
+
+# Combine text and image
+chat.ask "Is this the Ruby logo?", with: { image: "logo.png" }
+```
+
+## Working with Audio
+
+Models with audio capabilities can process spoken content:
+
+```ruby
+chat = RubyLLM.chat(model: 'gpt-4o-audio-preview')
+
+# Analyze audio content
+chat.ask "What's being said in this recording?", with: {
+  audio: "meeting.wav"
+}
+
+# Ask follow-up questions about the audio
+chat.ask "Summarize the key points mentioned"
+```
+
+## Streaming Responses
+
+For a more interactive experience, you can stream responses as they're generated:
+
+```ruby
+chat = RubyLLM.chat
+
+# Stream the response with a block
+chat.ask "Tell me a story about a Ruby programmer" do |chunk|
+  # Each chunk is a partial response
+  print chunk.content
+  $stdout.flush # Ensure output is displayed immediately
+end
+
+# Useful for long responses or real-time displays
+chat.ask "Write a detailed essay about programming paradigms" do |chunk|
+  add_to_ui(chunk.content) # Your method to update UI
+end
+```
+
+## Temperature Control
+
+Control the creativity and randomness of AI responses:
+
+```ruby
+# Higher temperature (more creative)
+creative_chat = RubyLLM.chat.with_temperature(0.9)
+creative_chat.ask "Write a poem about Ruby programming"
+
+# Lower temperature (more deterministic)
+precise_chat = RubyLLM.chat.with_temperature(0.1)
+precise_chat.ask "Explain how Ruby's garbage collector works"
+```
+
+## Access Token Usage
+
+RubyLLM automatically tracks token usage for billing and quota management:
+
+```ruby
+chat = RubyLLM.chat
+response = chat.ask "Explain quantum computing"
+
+# Check token usage
+puts "Input tokens: #{response.input_tokens}"
+puts "Output tokens: #{response.output_tokens}"
+puts "Total tokens: #{response.input_tokens + response.output_tokens}"
+
+# Estimate cost (varies by model)
+model = RubyLLM.models.find(response.model_id)
+input_cost = response.input_tokens * model.input_price_per_million / 1_000_000
+output_cost = response.output_tokens * model.output_price_per_million / 1_000_000
+puts "Estimated cost: $#{(input_cost + output_cost).round(6)}"
+```
+
+## Registering Event Handlers
+
+You can register callbacks for chat events:
+
+```ruby
+chat = RubyLLM.chat
+
+# Called when a new assistant message starts
+chat.on_new_message do
+  puts "Assistant is typing..."
+end
+
+# Called when a message is complete
+chat.on_end_message do |message|
+  puts "Response complete!"
+  puts "Used #{message.input_tokens + message.output_tokens} tokens"
+end
+
+# These callbacks work with both streaming and non-streaming responses
+chat.ask "Tell me about Ruby's history"
+```
+
+## Multiple Parallel Chats
+
+You can maintain multiple separate chat instances:
+
+```ruby
+# Create multiple chat instances
+ruby_chat = RubyLLM.chat
+python_chat = RubyLLM.chat
+
+# Each has its own conversation history
+ruby_chat.ask "What's great about Ruby?"
+python_chat.ask "What's great about Python?"
+
+# Continue separate conversations
+ruby_chat.ask "How does Ruby handle metaprogramming?"
+python_chat.ask "How does Python handle decorators?"
+```
+
+## Next Steps
+
+Now that you understand chat basics, you might want to explore:
+
+- [Using Tools]({% link guides/tools.md %}) to let AI use your Ruby code
+- [Streaming Responses]({% link guides/streaming.md %}) for real-time interactions
+- [Rails Integration]({% link guides/rails.md %}) to persist conversations in your apps