ruby_llm 0.1.0.pre38 → 0.1.0.pre39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efcf5aa8692558d9214d82dbb6c053727b1b6c5e810fcd7cd224e9a909ae38ff
-  data.tar.gz: 4910f4d7dade64d20696f5af971e968ce31abf0d98eae14fa7c874efe6ac03ce
+  metadata.gz: 0c887462ad2c35c5e831991b8b6cd78095c3f286861fd4913afddd5887833f3b
+  data.tar.gz: 382a2dd05532510ed5ac8ae5deb7a81febb831e3bbd8a11376eba0ad266451c3
 SHA512:
-  metadata.gz: 31679bff69003430d7f662dfa822a640ea6863087bf9e2260b0555f7341c41d3368a2e07d7c515c78255f5b1b400a05b08c631a80ee4ed7871fd0ceedb330ca2
-  data.tar.gz: 306fbf3cc3f35688b03b73995abe962152ddcde8d438093f4b4879d8c0b271187e4c7c26b10b8393f80556b955e1c631a8b30fdd693605712353cd7d6aa5e9cb
+  metadata.gz: b8c372a54f0bb94ecf6b22ead70f34a324974f4f61ad4610ba15ffee64ed8ec226fac24a74b73667bc07ea73a14fb5ee5d813759ab60f86c54c7d00cfc3905aa
+  data.tar.gz: 868fadbdaf583aa911a98cce36b6b61208a2065d92f32c31f1a2ea0908a37aa91f2047d2ea7aa77911093a7fcbb4ae10ace87f7ddafa2d39856e67a54d5bf846

data/.github/workflows/cicd.yml

@@ -3,6 +3,12 @@ name: CI
 on:
   push:
     branches: [ "main" ]
+    paths:
+      - 'lib/**'
+      - 'spec/**'
+      - 'Gemfile'
+      - 'Rakefile'
+      - 'ruby_llm.gemspec'
   pull_request:
     branches: [ "main" ]
   workflow_call:

data/README.md

@@ -20,6 +20,8 @@ A delightful Ruby way to work with AI. Chat in text, analyze and generate images
   <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>
 
+🤺 Battle tested at [💬  Chat with Work](https://chatwithwork.com)
+
 ## Features
 
 - 💬 **Beautiful Chat Interface** - Converse with AI models as easily as `RubyLLM.chat.ask "teach me Ruby"`

data/lib/ruby_llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  VERSION = '0.1.0.pre38'
+  VERSION = '0.1.0.pre39'
 end

data/ruby_llm.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|docs)/}) }
   end
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre38
+  version: 0.1.0.pre39
 platform: ruby
 authors:
 - Carmine Paolino
@@ -111,21 +111,6 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- docs/.gitignore
-- docs/Gemfile
-- docs/_config.yml
-- docs/_data/navigation.yml
-- docs/guides/chat.md
-- docs/guides/embeddings.md
-- docs/guides/error-handling.md
-- docs/guides/getting-started.md
-- docs/guides/image-generation.md
-- docs/guides/index.md
-- docs/guides/rails.md
-- docs/guides/streaming.md
-- docs/guides/tools.md
-- docs/index.md
-- docs/installation.md
 - lib/ruby_llm.rb
 - lib/ruby_llm/active_record/acts_as.rb
 - lib/ruby_llm/chat.rb

data/docs/.gitignore

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

data/docs/Gemfile

@@ -1,11 +0,0 @@
-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

@@ -1,43 +0,0 @@
-title: RubyLLM
-description: A delightful Ruby way to work with AI
-url: https://rubyllm.com
-baseurl: /
-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

@@ -1,25 +0,0 @@
-- 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

@@ -1,206 +0,0 @@
----
-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

data/docs/guides/embeddings.md

@@ -1,325 +0,0 @@
----
-layout: default
-title: Embeddings
-parent: Guides
-nav_order: 7
-permalink: /guides/embeddings
----
-
-# Embeddings
-
-Text embeddings are numerical representations of text that capture semantic meaning. RubyLLM makes it easy to generate embeddings for a variety of applications, including semantic search, clustering, and recommendation systems.
-
-## Basic Embedding Generation
-
-The simplest way to create an embedding is with the global `embed` method:
-
-```ruby
-# Create an embedding for a single text
-embedding = RubyLLM.embed("Ruby is a programmer's best friend")
-
-# The vector representation
-vector = embedding.vectors
-puts "Vector dimension: #{vector.length}"  # => 1536 for text-embedding-3-small
-```
-
-## Embedding Multiple Texts
-
-You can efficiently embed multiple texts at once:
-
-```ruby
-# Create embeddings for multiple texts
-texts = ["Ruby", "Python", "JavaScript"]
-embeddings = RubyLLM.embed(texts)
-
-# Each text gets its own vector
-puts "Number of vectors: #{embeddings.vectors.length}"  # => 3
-puts "First vector dimensions: #{embeddings.vectors.first.length}"
-```
-
-## Choosing Models
-
-By default, RubyLLM uses OpenAI's `text-embedding-3-small`, but you can specify a different model:
-
-```ruby
-# Use a specific model
-embedding = RubyLLM.embed(
-  "This is a test sentence",
-  model: "text-embedding-3-large"
-)
-
-# Or use a Google model
-google_embedding = RubyLLM.embed(
-  "This is a test sentence",
-  model: "text-embedding-004"
-)
-```
-
-You can configure the default embedding model globally:
-
-```ruby
-RubyLLM.configure do |config|
-  config.default_embedding_model = "text-embedding-3-large"
-end
-```
-
-## Using Embedding Results
-
-### Vector Properties
-
-The embedding result contains useful information:
-
-```ruby
-embedding = RubyLLM.embed("Example text")
-
-# The vector representation
-puts embedding.vectors.class  # => Array
-puts embedding.vectors.first.class  # => Float
-
-# The model used
-puts embedding.model  # => "text-embedding-3-small"
-
-# Token usage
-puts embedding.input_tokens  # => 3
-```
-
-### Calculating Similarity
-
-Embeddings are commonly used to calculate similarity between texts:
-
-```ruby
-require 'matrix'
-
-# Create embeddings for two texts
-embedding1 = RubyLLM.embed("I love Ruby programming")
-embedding2 = RubyLLM.embed("Ruby is my favorite language")
-
-# Convert to Vector objects
-vector1 = Vector.elements(embedding1.vectors)
-vector2 = Vector.elements(embedding2.vectors)
-
-# Calculate cosine similarity
-similarity = vector1.inner_product(vector2) / (vector1.norm * vector2.norm)
-puts "Similarity: #{similarity}"  # Higher values (closer to 1) mean more similar
-```
-
-### Simple Semantic Search
-
-```ruby
-# Create a simple search index
-class SearchIndex
-  def initialize(texts, model: nil)
-    @texts = texts
-    @embeddings = RubyLLM.embed(texts, model: model).vectors
-  end
-
-  def search(query, top_k: 3)
-    query_embedding = RubyLLM.embed(query).vectors
-    query_vector = Vector.elements(query_embedding)
-
-    # Calculate similarities
-    similarities = @embeddings.map.with_index do |embedding, idx|
-      vector = Vector.elements(embedding)
-      similarity = query_vector.inner_product(vector) / (query_vector.norm * vector.norm)
-      [idx, similarity]
-    end
-
-    # Return top results
-    similarities.sort_by { |_, similarity| -similarity }
-                .take(top_k)
-                .map { |idx, similarity| { text: @texts[idx], similarity: similarity } }
-  end
-end
-
-# Create an index
-documents = [
-  "Ruby is a dynamic, interpreted language",
-  "Python is known for its readability",
-  "JavaScript runs in the browser",
-  "Ruby on Rails is a web framework",
-  "Django is a Python web framework"
-]
-
-index = SearchIndex.new(documents)
-
-# Search for similar documents
-results = index.search("web development frameworks")
-results.each do |result|
-  puts "#{result[:text]} (Similarity: #{result[:similarity].round(4)})"
-end
-```
-
-## Error Handling
-
-Handle errors that may occur during embedding generation:
-
-```ruby
-begin
-  embedding = RubyLLM.embed("Example text")
-rescue RubyLLM::UnauthorizedError
-  puts "Please check your API key"
-rescue RubyLLM::BadRequestError => e
-  puts "Invalid request: #{e.message}"
-rescue RubyLLM::Error => e
-  puts "Error generating embedding: #{e.message}"
-end
-```
-
-## Performance Considerations
-
-When working with embeddings, keep these best practices in mind:
-
-1. **Batch processing** - Embedding multiple texts at once is more efficient than making separate calls
-2. **Caching** - Store embeddings in your database rather than regenerating them
-3. **Dimensionality** - Different models produce embeddings with different dimensions
-4. **Normalization** - Consider normalizing vectors to improve similarity calculations
-
-## Working with Large Datasets
-
-For larger datasets, process embeddings in batches:
-
-```ruby
-def embed_in_batches(texts, batch_size: 100, model: nil)
-  all_embeddings = []
-
-  texts.each_slice(batch_size) do |batch|
-    batch_embeddings = RubyLLM.embed(batch, model: model).vectors
-    all_embeddings.concat(batch_embeddings)
-
-    # Optional: add a small delay to avoid rate limiting
-    sleep(0.1)
-  end
-
-  all_embeddings
-end
-
-# Usage
-documents = File.readlines("documents.txt", chomp: true)
-embeddings = embed_in_batches(documents)
-```
-
-## Rails Integration
-
-In a Rails application, you might integrate embeddings like this:
-
-```ruby
-class Document < ApplicationRecord
-  serialize :embedding, Array
-
-  before_save :generate_embedding, if: -> { content_changed? }
-
-  def self.search(query, limit: 10)
-    # Generate query embedding
-    query_embedding = RubyLLM.embed(query).vectors
-
-    # Convert to SQL for similarity search
-    where.not(embedding: nil)
-         .select("*, (embedding <=> ?) AS similarity", query_embedding)
-         .order("similarity DESC")
-         .limit(limit)
-  end
-
-  private
-
-  def generate_embedding
-    return if content.blank?
-
-    self.embedding = RubyLLM.embed(content).vectors
-  rescue RubyLLM::Error => e
-    errors.add(:base, "Failed to generate embedding: #{e.message}")
-    throw :abort
-  end
-end
-```
-
-Note: The above example assumes you're using PostgreSQL with the `pgvector` extension for vector similarity search.
-
-## Example Use Cases
-
-### Document Classification
-
-```ruby
-# Train a simple classifier
-class SimpleClassifier
-  def initialize
-    @categories = {}
-  end
-
-  def train(text, category)
-    @categories[category] ||= []
-    @categories[category] << RubyLLM.embed(text).vectors
-  end
-
-  def classify(text)
-    # Get embedding for the query text
-    query_embedding = RubyLLM.embed(text).vectors
-    query_vector = Vector.elements(query_embedding)
-
-    # Find the closest category
-    best_similarity = -1
-    best_category = nil
-
-    @categories.each do |category, embeddings|
-      # Calculate average similarity to this category
-      similarity = embeddings.map do |embedding|
-        vector = Vector.elements(embedding)
-        query_vector.inner_product(vector) / (query_vector.norm * vector.norm)
-      end.sum / embeddings.size
-
-      if similarity > best_similarity
-        best_similarity = similarity
-        best_category = category
-      end
-    end
-
-    { category: best_category, confidence: best_similarity }
-  end
-end
-
-# Usage
-classifier = SimpleClassifier.new
-
-# Train with examples
-classifier.train("How do I install Ruby?", :installation)
-classifier.train("Setting up Ruby environment", :installation)
-classifier.train("What are blocks in Ruby?", :language_features)
-classifier.train("Understanding Ruby modules", :language_features)
-
-# Classify new queries
-puts classifier.classify("How to install Ruby on Ubuntu?")
-# => {:category=>:installation, :confidence=>0.92}
-```
-
-### Content Recommendation
-
-```ruby
-def recommend_similar_content(content_id, library, count: 3)
-  # Get the target content
-  target = library.find(content_id)
-  target_embedding = RubyLLM.embed(target.description).vectors
-  target_vector = Vector.elements(target_embedding)
-
-  # Compare with all other content
-  similarities = library.reject { |item| item.id == content_id }.map do |item|
-    next if item.embedding.nil?
-
-    item_vector = Vector.elements(item.embedding)
-    similarity = target_vector.inner_product(item_vector) / (target_vector.norm * item_vector.norm)
-
-    [item, similarity]
-  end.compact
-
-  # Return top matches
-  similarities.sort_by { |_, similarity| -similarity }
-              .take(count)
-              .map { |item, similarity| { item: item, similarity: similarity } }
-end
-```
-
-## Next Steps
-
-Now that you understand embeddings, you might want to explore:
-
-- [Chat]({% link guides/chat.md %}) for interactive AI conversations
-- [Tools]({% link guides/tools.md %}) to extend AI capabilities
-- [Error Handling]({% link guides/error-handling.md %}) for robust applications