ruby_llm-text 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb717f8d64403316c14b7da6ae2354f5f72d60a2caae6c892ca3f9fe109343d8
+  data.tar.gz: 286d134ed832cee3a0289052b5b81693a6b70822080dc9f4fa3535c492f73198
+SHA512:
+  metadata.gz: 7227c8ae62491a00d308d3d59751435f404d5ee1e405b71db323a3b4edab832dac23bbc7162ef530562bae28d58ef5a765ba89f790d0f4e07469b99964519873
+  data.tar.gz: bb9eea87d7aafb8251a49ea5137f073fc5eea5a0ffcf29a699c2251bde7cfd31131afb81d51f293befa5faba8e1f397ca0080cd0626f6c394db4fcd2729a5f25

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-02-16
+
+### Added
+- Initial release of ruby_llm-text gem
+- Core functionality for LLM text operations:
+  - `summarize` - Condense text into shorter summaries with configurable length
+  - `translate` - Translate text between languages
+  - `extract` - Extract structured data from unstructured text using schemas
+  - `classify` - Classify text into predefined categories
+- Configuration system with per-method model overrides
+- String extensions for Rails-like method chaining (optional)
+- Integration with ruby_llm ecosystem
+- Comprehensive test suite with 100% coverage
+- GitHub Actions CI/CD pipeline
+- Complete documentation and API reference
+
+### Dependencies
+- ruby_llm ~> 1.0 (core dependency)
+- Ruby >= 3.2.0
+
+[Unreleased]: https://github.com/patrols/ruby_llm-text/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/patrols/ruby_llm-text/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Patrick Rendal Olsen
+
+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,312 @@
+# ruby_llm-text
+
+ActiveSupport-style LLM utilities for Ruby that make AI operations feel like native Ruby.
+
+[![Gem Version](https://badge.fury.io/rb/ruby_llm-text.svg)](https://badge.fury.io/rb/ruby_llm-text)
+[![CI](https://github.com/patrols/ruby_llm-text/workflows/CI/badge.svg)](https://github.com/patrols/ruby_llm-text/actions)
+
+## Overview
+
+`ruby_llm-text` provides intuitive one-liner utility methods for common LLM tasks like summarizing text, translation, data extraction, and classification. It integrates seamlessly with the [ruby_llm](https://github.com/crmne/ruby_llm) ecosystem, providing a simple interface without requiring chat objects, message arrays, or configuration boilerplate.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby_llm-text'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install ruby_llm-text
+```
+
+## Quick Start
+
+```ruby
+require 'ruby_llm/text'
+
+# Configure ruby_llm with your API key
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV["OPENAI_API_KEY"]
+end
+
+# Summarize text
+long_article = "This is a very long article about..."
+summary = RubyLLM::Text.summarize(long_article)
+
+# Translate text
+greeting = RubyLLM::Text.translate("Bonjour le monde", to: "en")
+
+# Extract structured data
+text = "My name is John and I am 30 years old."
+data = RubyLLM::Text.extract(text, schema: { name: :string, age: :integer })
+
+# Classify text
+review = "This product is amazing!"
+sentiment = RubyLLM::Text.classify(review, categories: ["positive", "negative", "neutral"])
+```
+
+## API Reference
+
+### Summarize
+
+Condense text into a shorter summary.
+
+```ruby
+RubyLLM::Text.summarize(text, length: :medium, max_words: nil, model: nil)
+```
+
+**Parameters:**
+- `text` (String): The text to summarize
+- `length` (Symbol|String): Predefined length (`:short`, `:medium`, `:detailed`) or custom description
+- `max_words` (Integer, optional): Maximum word count for summary
+- `model` (String, optional): Specific model to use
+
+**Examples:**
+```ruby
+# Basic usage
+RubyLLM::Text.summarize("Long article text...")
+
+# With length option
+RubyLLM::Text.summarize(text, length: :short)
+
+# With word limit
+RubyLLM::Text.summarize(text, length: :medium, max_words: 50)
+
+# Custom length description
+RubyLLM::Text.summarize(text, length: "bullet points")
+```
+
+### Translate
+
+Translate text between languages.
+
+```ruby
+RubyLLM::Text.translate(text, to:, from: nil, model: nil)
+```
+
+**Parameters:**
+- `text` (String): The text to translate
+- `to` (String): Target language (e.g., "en", "spanish", "français")
+- `from` (String, optional): Source language for better accuracy
+- `model` (String, optional): Specific model to use
+
+**Examples:**
+```ruby
+# Basic translation
+RubyLLM::Text.translate("Bonjour", to: "en")
+
+# With source language specified
+RubyLLM::Text.translate("Hola mundo", to: "en", from: "es")
+
+# Natural language specifications
+RubyLLM::Text.translate("Hello", to: "french")
+```
+
+### Extract
+
+Extract structured data from unstructured text.
+
+```ruby
+RubyLLM::Text.extract(text, schema:, model: nil)
+```
+
+**Parameters:**
+- `text` (String): The text to extract data from
+- `schema` (Hash): Data structure specification
+- `model` (String, optional): Specific model to use
+
+**Schema Types:**
+- `:string` - Text fields
+- `:integer`, `:number` - Numeric fields
+- `:boolean` - True/false fields
+- `:array` - List fields
+
+**Examples:**
+```ruby
+# Extract person details
+text = "John Smith is 30 years old and works as a software engineer in San Francisco."
+schema = {
+  name: :string,
+  age: :integer,
+  profession: :string,
+  location: :string
+}
+data = RubyLLM::Text.extract(text, schema: schema)
+
+# Extract product information
+product_text = "iPhone 15 Pro costs $999 and has excellent reviews"
+product_schema = {
+  name: :string,
+  price: :number,
+  currency: :string,
+  reviews: :array
+}
+product_data = RubyLLM::Text.extract(product_text, schema: product_schema)
+```
+
+### Classify
+
+Classify text into predefined categories.
+
+```ruby
+RubyLLM::Text.classify(text, categories:, model: nil)
+```
+
+**Parameters:**
+- `text` (String): The text to classify
+- `categories` (Array): List of possible categories
+- `model` (String, optional): Specific model to use
+
+**Examples:**
+```ruby
+# Sentiment analysis
+review = "This product exceeded my expectations!"
+sentiment = RubyLLM::Text.classify(review,
+  categories: ["positive", "negative", "neutral"]
+)
+
+# Topic classification
+article = "The stock market reached new highs today..."
+topic = RubyLLM::Text.classify(article,
+  categories: ["technology", "finance", "sports", "politics"]
+)
+
+# Priority classification
+email = "URGENT: Server is down and customers can't access the site"
+priority = RubyLLM::Text.classify(email,
+  categories: ["low", "medium", "high", "critical"]
+)
+```
+
+## Configuration
+
+This gem uses `ruby_llm`'s configuration for API keys and default models:
+
+```ruby
+# Configure ruby_llm (API keys, default model, etc.)
+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-mini"
+end
+```
+
+Optionally configure text-specific settings:
+
+```ruby
+RubyLLM::Text.configure do |config|
+  # Temperature for text operations (default: 0.3)
+  config.temperature = 0.3
+
+  # Method-specific model overrides (falls back to RubyLLM.config.default_model)
+  config.summarize_model = "gpt-4.1-mini"
+  config.translate_model = "claude-sonnet-4-5"  # Use Claude for translation
+  config.extract_model = "gpt-4.1"              # Use GPT-4 for extraction
+  config.classify_model = "gpt-4.1-mini"
+end
+```
+
+**Per-call overrides:**
+```ruby
+# Override model for specific calls
+RubyLLM::Text.summarize(text, model: "claude-sonnet-4-5")
+
+# Pass additional options (passed through to ruby_llm)
+RubyLLM::Text.translate(text, to: "es", temperature: 0.1)
+```
+
+## String Extensions (Optional)
+
+For a more Rails-like experience, you can enable String monkey-patching:
+
+```ruby
+require 'ruby_llm/text/string_ext'
+
+# Now you can call methods directly on strings
+"Long article text...".summarize
+"Bonjour".translate(to: "en")
+"John is 30".extract(schema: { name: :string, age: :integer })
+"Great product!".classify(categories: ["positive", "negative"])
+```
+
+## Integration with ruby_llm
+
+This gem builds on top of [ruby_llm](https://github.com/crmne/ruby_llm) and inherits its configuration and model support:
+
+- **Models**: Supports all ruby_llm models (OpenAI GPT, Anthropic Claude, etc.)
+- **Configuration**: Uses ruby_llm's underlying configuration system
+- **Error handling**: Inherits ruby_llm's robust error handling
+
+## Error Handling
+
+The gem provides clear error messages for common issues:
+
+```ruby
+# Missing required parameters
+RubyLLM::Text.extract("text")  # ArgumentError: schema is required
+
+RubyLLM::Text.classify("text", categories: [])  # ArgumentError: categories are required
+
+# API errors are wrapped with context
+RubyLLM::Text.summarize("text")  # RubyLLM::Text::Error: LLM call failed: [original error]
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bin/setup      # Install dependencies
+rake test      # Run tests
+rake rubocop   # Run linter
+rake           # Run tests and linter
+```
+
+## Testing
+
+The test suite uses Mocha for mocking LLM API calls, ensuring reliable and fast tests without requiring API keys:
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run tests with linting
+bundle exec rake
+
+# Run linting only
+bundle exec rubocop
+```
+
+### Manual Testing
+
+For manual testing with real API calls, use the provided test script:
+
+```bash
+# Set up your API key
+export OPENAI_API_KEY="your-key"
+# or
+export ANTHROPIC_API_KEY="your-key"
+
+# Run manual tests
+bin/manual-test
+```
+
+This script tests all four methods with real LLM APIs and provides helpful output for verification.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/patrols/ruby_llm-text.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/ruby_llm/text/base.rb

@@ -0,0 +1,27 @@
+module RubyLLM
+  module Text
+    module Base
+      def self.call_llm(prompt, model: nil, temperature: nil, schema: nil, **options)
+        model ||= RubyLLM.config.default_model
+        temperature ||= RubyLLM::Text.config.temperature
+
+        chat = RubyLLM.chat(model: model)
+        chat = chat.with_temperature(temperature)
+        chat = chat.with_schema(schema) if schema
+
+        # Apply any additional options
+        options.each do |key, value|
+          method_name = "with_#{key}"
+          chat = chat.send(method_name, value) if chat.respond_to?(method_name)
+        end
+
+        response = chat.ask(prompt)
+        response.content
+      rescue => e
+        raise RubyLLM::Text::Error, "LLM call failed: #{e.message}"
+      end
+    end
+
+    class Error < StandardError; end
+  end
+end

data/lib/ruby_llm/text/classify.rb

@@ -0,0 +1,29 @@
+module RubyLLM
+  module Text
+    module Classify
+      def self.call(text, categories:, model: nil, **options)
+        model ||= RubyLLM::Text.config.model_for(:classify)
+        raise ArgumentError, "categories are required" if categories.empty?
+
+        prompt = build_prompt(text, categories)
+        Base.call_llm(prompt, model: model, **options)
+      end
+
+      private
+
+      def self.build_prompt(text, categories)
+        category_list = categories.map { |c| "- #{c}" }.join("\n")
+
+        <<~PROMPT
+          Classify the following text into one of these categories:
+          #{category_list}
+
+          Return only the category name, nothing else.
+
+          Text:
+          #{text}
+        PROMPT
+      end
+    end
+  end
+end

data/lib/ruby_llm/text/configuration.rb

@@ -0,0 +1,25 @@
+module RubyLLM
+  module Text
+    class Configuration
+      # Method-specific model overrides (optional)
+      # If not set, falls back to RubyLLM.config.default_model
+      attr_accessor :summarize_model, :translate_model,
+                    :extract_model, :classify_model
+
+      # Default temperature for text operations
+      attr_accessor :temperature
+
+      def initialize
+        @temperature = 0.3
+        @summarize_model = nil
+        @translate_model = nil
+        @extract_model = nil
+        @classify_model = nil
+      end
+
+      def model_for(method_name)
+        instance_variable_get("@#{method_name}_model") || RubyLLM.config.default_model
+      end
+    end
+  end
+end

data/lib/ruby_llm/text/extract.rb

@@ -0,0 +1,55 @@
+require "ruby_llm/schema"
+
+module RubyLLM
+  module Text
+    module Extract
+      def self.call(text, schema: nil, model: nil, **options)
+        model ||= RubyLLM::Text.config.model_for(:extract)
+        raise ArgumentError, "schema is required for extraction" unless schema
+
+        # Convert simple hash schema to RubyLLM::Schema
+        schema_obj = build_schema(schema)
+        prompt = build_prompt(text, schema)
+
+        Base.call_llm(prompt, model: model, schema: schema_obj, **options)
+      end
+
+      private
+
+      def self.build_schema(schema)
+        # If already a schema object, return as-is
+        return schema if schema.respond_to?(:schema)
+
+        # Build dynamic schema class from hash
+        schema_class = Class.new(RubyLLM::Schema)
+        schema.each do |field, type|
+          case type
+          when :string
+            schema_class.string field
+          when :integer, :number
+            schema_class.number field
+          when :boolean
+            schema_class.boolean field
+          when :array
+            schema_class.array field
+          else
+            schema_class.string field # fallback to string
+          end
+        end
+        schema_class
+      end
+
+      def self.build_prompt(text, schema)
+        fields = schema.keys.join(", ")
+
+        <<~PROMPT
+          Extract the following information from the text: #{fields}
+          Return the data as structured JSON matching the provided schema.
+
+          Text:
+          #{text}
+        PROMPT
+      end
+    end
+  end
+end

data/lib/ruby_llm/text/string_ext.rb

@@ -0,0 +1,18 @@
+# Optional String monkey-patching
+class String
+  def summarize(**options)
+    RubyLLM::Text.summarize(self, **options)
+  end
+
+  def translate(**options)
+    RubyLLM::Text.translate(self, **options)
+  end
+
+  def extract(**options)
+    RubyLLM::Text.extract(self, **options)
+  end
+
+  def classify(**options)
+    RubyLLM::Text.classify(self, **options)
+  end
+end

data/lib/ruby_llm/text/summarize.rb

@@ -0,0 +1,34 @@
+module RubyLLM
+  module Text
+    module Summarize
+      LENGTHS = {
+        short: "1-2 sentences",
+        medium: "3-5 sentences",
+        detailed: "1-2 paragraphs"
+      }.freeze
+
+      def self.call(text, length: :medium, max_words: nil, model: nil, **options)
+        model ||= RubyLLM::Text.config.model_for(:summarize)
+
+        prompt = build_prompt(text, length: length, max_words: max_words)
+        Base.call_llm(prompt, model: model, **options)
+      end
+
+      private
+
+      def self.build_prompt(text, length:, max_words:)
+        length_instruction = LENGTHS[length] || length.to_s
+        word_limit = max_words ? " (maximum #{max_words} words)" : ""
+
+        <<~PROMPT
+          Summarize the following text.
+          Length: #{length_instruction}#{word_limit}
+          Return only the summary, no preamble or explanation.
+
+          Text:
+          #{text}
+        PROMPT
+      end
+    end
+  end
+end

data/lib/ruby_llm/text/translate.rb

@@ -0,0 +1,26 @@
+module RubyLLM
+  module Text
+    module Translate
+      def self.call(text, to:, from: nil, model: nil, **options)
+        model ||= RubyLLM::Text.config.model_for(:translate)
+
+        prompt = build_prompt(text, to: to, from: from)
+        Base.call_llm(prompt, model: model, **options)
+      end
+
+      private
+
+      def self.build_prompt(text, to:, from:)
+        from_instruction = from ? "from #{from} " : ""
+
+        <<~PROMPT
+          Translate the following text #{from_instruction}to #{to}.
+          Return only the translated text, no explanation or notes.
+
+          Text:
+          #{text}
+        PROMPT
+      end
+    end
+  end
+end

data/lib/ruby_llm/text/version.rb

@@ -0,0 +1,5 @@
+module RubyLLM
+  module Text
+    VERSION = "0.1.0"
+  end
+end

data/lib/ruby_llm/text.rb

@@ -0,0 +1,40 @@
+require "ruby_llm"
+require_relative "text/version"
+require_relative "text/configuration"
+require_relative "text/base"
+require_relative "text/summarize"
+require_relative "text/translate"
+require_relative "text/extract"
+require_relative "text/classify"
+
+module RubyLLM
+  module Text
+    class << self
+      def configure(&block)
+        config.instance_eval(&block) if block_given?
+        config
+      end
+
+      def config
+        @config ||= Configuration.new
+      end
+
+      # Module-style API methods
+      def summarize(text, **options)
+        Summarize.call(text, **options)
+      end
+
+      def translate(text, **options)
+        Translate.call(text, **options)
+      end
+
+      def extract(text, **options)
+        Extract.call(text, **options)
+      end
+
+      def classify(text, **options)
+        Classify.call(text, **options)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-text
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Patrick Rendal Olsen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails-omakase
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Intuitive one-liner utility methods for common LLM tasks like summarize,
+  translate, extract, and classify.
+email:
+- patrick@rendal.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ruby_llm/text.rb
+- lib/ruby_llm/text/base.rb
+- lib/ruby_llm/text/classify.rb
+- lib/ruby_llm/text/configuration.rb
+- lib/ruby_llm/text/extract.rb
+- lib/ruby_llm/text/string_ext.rb
+- lib/ruby_llm/text/summarize.rb
+- lib/ruby_llm/text/translate.rb
+- lib/ruby_llm/text/version.rb
+homepage: https://github.com/patrols/ruby_llm-text
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/patrols/ruby_llm-text
+  source_code_uri: https://github.com/patrols/ruby_llm-text.git
+  changelog_uri: https://github.com/patrols/ruby_llm-text/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: ActiveSupport-style LLM utilities for Ruby
+test_files: []