rubycanusellm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7068367ffebce32580d14b9eaf62427bb7bd268fa6a0a0ad3832428e5598e351
+  data.tar.gz: ed05039faee7b98d6d3a929033484ab5b0a02c6c8fc22cf4b88ed7fe2ba79fa6
+SHA512:
+  metadata.gz: 253341456facb5a986eede001e24b8d23cacc66de282da73d8f3101221ad497edc33523b18af07bff92c9e1dd025b81a375874fbade5f2f5e82307f87fdb4ec0
+  data.tar.gz: 2dc6f75656c1f7800f50cb7a55debbd29b8ea3230f74959a222c219d7f4757a57614af61b36447880f1b37375f02e57c225c318305eb0115a4c0f27c1363fd8c

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.1.0] - 2025-04-01
+
+### Added
+
+- Unified client interface for LLM providers
+- OpenAI provider (chat completions)
+- Anthropic provider (chat completions)
+- Configuration module with validation
+- Unified Response object with token tracking
+- Error handling: AuthenticationError, RateLimitError, TimeoutError, ProviderError
+- CLI with generators:
+  - `generate:config` — scaffolds configuration file
+  - `generate:completion` — scaffolds completion service object
+- Rails and plain Ruby project detection for generators

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Juan Manuel Guzman Nava
+
+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,161 @@
+# RubyCanUseLLM
+
+A unified Ruby client for multiple LLM providers with generators. One interface, every LLM.
+
+## The Problem
+
+Every time a Ruby developer wants to add LLMs to their app, they start from scratch: pick a provider gem, learn its API, write a service object, handle errors, parse responses. Switch providers? Rewrite everything.
+
+## The Solution
+
+RubyCanUseLLM gives you two things:
+
+1. **Unified client** — One interface that works the same across OpenAI, Anthropic, and more. Switch providers by changing a string, not your code.
+2. **Generators** — Commands that scaffold ready-to-use boilerplate. You don't start from zero, you start with something that works.
+
+## Installation
+```bash
+gem install rubycanusellm
+```
+
+Or add to your Gemfile:
+```ruby
+gem "rubycanusellm"
+```
+
+## Quick Start
+
+### 1. Generate configuration
+```bash
+rubycanusellm generate:config
+```
+
+This creates a config file with your provider and API key. In Rails it goes to `config/initializers/rubycanusellm.rb`, otherwise to `config/llm.rb`.
+
+### 2. Generate a completion service
+```bash
+rubycanusellm generate:completion
+```
+
+This creates a ready-to-use service object. In Rails it goes to `app/services/`, otherwise to `lib/`.
+
+### 3. Use it
+```ruby
+RubyCanUseLLM.configure do |config|
+  config.provider = :openai
+  config.api_key = ENV["LLM_API_KEY"]
+end
+
+response = RubyCanUseLLM.chat([
+  { role: :user, content: "What is Ruby?" }
+])
+
+puts response.content
+puts "Tokens: #{response.total_tokens}"
+```
+
+### Switch providers in one line
+```ruby
+config.provider = :anthropic
+```
+
+That's it. Same code, different provider.
+
+## Supported Providers
+
+| Provider | Models | Status |
+|----------|--------|--------|
+| OpenAI | gpt-4o-mini, gpt-4o, etc. | ✅ |
+| Anthropic | claude-sonnet-4-20250514, etc. | ✅ |
+
+## API Reference
+
+### Configuration
+```ruby
+RubyCanUseLLM.configure do |config|
+  config.provider = :openai          # :openai or :anthropic
+  config.api_key = "your-key"        # required
+  config.model = "gpt-4o-mini"       # optional, has sensible defaults
+  config.timeout = 30                # optional, default 30s
+end
+```
+
+### Chat
+```ruby
+response = RubyCanUseLLM.chat(messages, **options)
+```
+
+**messages** — Array of hashes with `:role` and `:content`:
+```ruby
+messages = [
+  { role: :system, content: "You are helpful." },
+  { role: :user, content: "Hello" }
+]
+```
+
+**options** — Override config per request:
+```ruby
+RubyCanUseLLM.chat(messages, model: "gpt-4o", temperature: 0.5)
+```
+
+### Response
+```ruby
+response.content       # "Hello! How can I help?"
+response.model         # "gpt-4o-mini"
+response.input_tokens  # 10
+response.output_tokens # 5
+response.total_tokens  # 15
+response.raw           # original provider response
+```
+
+### Error Handling
+```ruby
+begin
+  RubyCanUseLLM.chat(messages)
+rescue RubyCanUseLLM::AuthenticationError
+  # invalid API key
+rescue RubyCanUseLLM::RateLimitError
+  # too many requests
+rescue RubyCanUseLLM::TimeoutError
+  # request timed out
+rescue RubyCanUseLLM::ProviderError => e
+  # other provider error
+end
+```
+
+## Generators
+
+| Command | Description |
+|---------|-------------|
+| `rubycanusellm generate:config` | Configuration file with provider setup |
+| `rubycanusellm generate:completion` | Completion service object |
+
+## Roadmap
+
+- [x] Project setup
+- [x] Configuration module
+- [x] OpenAI provider
+- [x] Anthropic provider
+- [x] `generate:config` command
+- [x] `generate:completion` command
+- [x] v0.1.0 release
+- [ ] Streaming support
+- [ ] Embeddings + `generate:embedding`
+- [ ] Mistral and Ollama providers
+- [ ] Tool calling
+
+## Development
+```bash
+git clone https://github.com/mgznv/rubycanusellm.git
+cd rubycanusellm
+bin/setup
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mgznv/rubycanusellm.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/exe/rubycanusellm

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rubycanusellm"
+require_relative "../lib/rubycanusellm/cli"
+
+RubyCanUseLLM::CLI.start(ARGV)

data/lib/rubycanusellm/cli.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+require "fileutils"
+
+module RubyCanUseLLM
+  class CLI
+    COMMANDS = {
+      "generate:config" => :generate_config,
+      "generate:completion" => :generate_completion
+    }.freeze
+
+    def self.start(args)
+      command = args.first
+
+      if COMMANDS.key?(command)
+        new.send(COMMANDS[command])
+      else
+        puts "Usage: rubycanusellm <command>"
+        puts ""
+        puts "Commands:"
+        puts "  generate:config      Generate configuration file"
+        puts "  generate:completion  Generate completion service object"
+      end
+    end
+
+    def generate_config
+      if rails?
+        path = "config/initializers/rubycanusellm.rb"
+      else
+        FileUtils.mkdir_p("config")
+        path = "config/llm.rb"
+      end
+
+      write_template("config", path)
+    end
+
+    def generate_completion
+      if rails?
+        FileUtils.mkdir_p("app/services")
+        path = "app/services/completion_service.rb"
+      else
+        FileUtils.mkdir_p("lib")
+        path = "lib/completion_service.rb"
+      end
+
+      write_template("completion", path)
+    end
+
+    private
+
+    def rails?
+      File.exist?("config/application.rb")
+    end
+
+    def write_template(name, destination)
+      if File.exist?(destination)
+        puts "  exists  #{destination}"
+        return
+      end
+
+      template = File.read(template_path(name))
+      File.write(destination, template)
+      puts "  create  #{destination}"
+    end
+
+    def template_path(name)
+      File.join(File.dirname(__FILE__), "templates", "#{name}.rb.tt")
+    end
+  end
+end

data/lib/rubycanusellm/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyCanUseLLM
+  class Configuration
+    SUPPORTED_PROVIDERS = %i[openai anthropic].freeze
+
+    attr_accessor :provider, :api_key, :model, :timeout
+
+    def initialize
+      @provider = nil
+      @api_key = nil
+      @model = nil
+      @timeout = 30
+    end
+
+    def validate!
+      raise Error, "provider is required. Use :openai or :anthropic" if provider.nil?
+      raise Error, "api_key is required" if api_key.nil? || api_key.empty?
+      raise Error, "Unknown provider: #{provider}. Supported: #{SUPPORTED_PROVIDERS.join(", ")}" unless SUPPORTED_PROVIDERS.include?(provider)
+    end
+  end
+end

data/lib/rubycanusellm/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RubyCanUseLLM
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class RateLimitError < Error; end
+  class TimeoutError < Error; end
+  class ProviderError < Error; end
+end

data/lib/rubycanusellm/providers/anthropic.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module RubyCanUseLLM
+  module Providers
+    class Anthropic < Base
+      API_URL = "https://api.anthropic.com/v1/messages"
+
+      def chat(messages, **options)
+        system, user_messages = extract_system(messages)
+        body = build_body(system, user_messages, options)
+        response = request(body)
+        parse_response(response)
+      end
+
+      private
+
+      def extract_system(messages)
+        system = nil
+        user_messages = []
+
+        messages.each do |msg|
+          if msg[:role].to_s == "system"
+            system = msg[:content]
+          else
+            user_messages << msg
+          end
+        end
+
+        [system, user_messages]
+      end
+
+      def build_body(system, messages, options)
+        body = {
+          model: options[:model] || config.model || "claude-sonnet-4-20250514",
+          messages: format_messages(messages),
+          max_tokens: options[:max_tokens] || 1024
+        }
+        body[:system] = system if system
+        body
+      end
+
+      def format_messages(messages)
+        messages.map do |msg|
+          { role: msg[:role].to_s, content: msg[:content] }
+        end
+      end
+
+      def request(body)
+        uri = URI(API_URL)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = config.timeout
+
+        req = Net::HTTP::Post.new(uri)
+        req["x-api-key"] = config.api_key
+        req["anthropic-version"] = "2023-06-01"
+        req["Content-Type"] = "application/json"
+        req.body = body.to_json
+
+        handle_response(http.request(req))
+      rescue Net::ReadTimeout, Net::OpenTimeout
+        raise TimeoutError, "Request to Anthropic timed out after #{config.timeout}s"
+      end
+
+      def handle_response(response)
+        case response.code.to_i
+        when 200
+          JSON.parse(response.body)
+        when 401
+          raise AuthenticationError, "Invalid Anthropic API key"
+        when 429
+          raise RateLimitError, "Anthropic rate limit exceeded"
+        else
+          raise ProviderError, "Anthropic error (#{response.code}): #{response.body}"
+        end
+      end
+
+      def parse_response(data)
+        content = data.dig("content", 0, "text")
+        usage = data["usage"]
+
+        Response.new(
+          content: content,
+          model: data["model"],
+          input_tokens: usage["input_tokens"],
+          output_tokens: usage["output_tokens"],
+          raw: data
+        )
+      end
+    end
+  end
+end

data/lib/rubycanusellm/providers/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubyCanUseLLM
+  module Providers
+    class Base
+      def initialize(config)
+        @config = config
+      end
+
+      def chat(messages, **options)
+        raise NotImplementedError, "#{self.class} must implement #chat"
+      end
+
+      private
+
+      attr_reader :config
+    end
+  end
+end

data/lib/rubycanusellm/providers/openai.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module RubyCanUseLLM
+  module Providers
+    class OpenAI < Base
+      API_URL = "https://api.openai.com/v1/chat/completions"
+
+      def chat(messages, **options)
+        body = build_body(messages, options)
+        response = request(body)
+        parse_response(response)
+      end
+
+      private
+
+      def build_body(messages, options)
+        {
+          model: options[:model] || config.model || "gpt-4o-mini",
+          messages: format_messages(messages),
+          temperature: options[:temperature] || 0.7
+        }
+      end
+
+      def format_messages(messages)
+        messages.map do |msg|
+          { role: msg[:role].to_s, content: msg[:content] }
+        end
+      end
+
+      def request(body)
+        uri = URI(API_URL)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = config.timeout
+
+        req = Net::HTTP::Post.new(uri)
+        req["Authorization"] = "Bearer #{config.api_key}"
+        req["Content-Type"] = "application/json"
+        req.body = body.to_json
+
+        handle_response(http.request(req))
+      rescue Net::ReadTimeout, Net::OpenTimeout
+        raise TimeoutError, "Request to OpenAI timed out after #{config.timeout}s"
+      end
+
+      def handle_response(response)
+        case response.code.to_i
+        when 200
+          JSON.parse(response.body)
+        when 401
+          raise AuthenticationError, "Invalid OpenAI API key"
+        when 429
+          raise RateLimitError, "OpenAI rate limit exceeded"
+        else
+          raise ProviderError, "OpenAI error (#{response.code}): #{response.body}"
+        end
+      end
+
+      def parse_response(data)
+        choice = data.dig("choices", 0, "message")
+        usage = data["usage"]
+
+        Response.new(
+          content: choice["content"],
+          model: data["model"],
+          input_tokens: usage["prompt_tokens"],
+          output_tokens: usage["completion_tokens"],
+          raw: data
+        )
+      end
+    end
+  end
+end

data/lib/rubycanusellm/response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubyCanUseLLM
+  class Response
+    attr_reader :content, :model, :input_tokens, :output_tokens, :raw
+
+    def initialize(content:, model:, input_tokens:, output_tokens:, raw:)
+      @content = content
+      @model = model
+      @input_tokens = input_tokens
+      @output_tokens = output_tokens
+      @raw = raw
+    end
+
+    def total_tokens
+      input_tokens + output_tokens
+    end
+  end
+end

data/lib/rubycanusellm/templates/completion.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CompletionService
+  def call(prompt, **options)
+    messages = [
+      { role: :user, content: prompt }
+    ]
+
+    # Add a system message if needed
+    # messages.unshift({ role: :system, content: "You are a helpful assistant." })
+
+    RubyCanUseLLM.chat(messages, **options)
+  end
+end
+
+# Usage:
+#   service = CompletionService.new
+#   response = service.call("What is Ruby?")
+#   puts response.content
+#   puts "Tokens used: #{response.total_tokens}"

data/lib/rubycanusellm/templates/config.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+RubyCanUseLLM.configure do |config|
+  # Choose your provider: :openai or :anthropic
+  config.provider = :openai
+
+  # Your API key (use environment variables in production)
+  config.api_key = ENV["LLM_API_KEY"]
+
+  # Default model (optional, each provider has a sensible default)
+  # OpenAI: "gpt-4o-mini", Anthropic: "claude-sonnet-4-20250514"
+  # config.model = "gpt-4o-mini"
+
+  # Request timeout in seconds (default: 30)
+  # config.timeout = 30
+end

data/lib/rubycanusellm/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rubycanusellm
+  VERSION = "0.1.0"
+end

data/lib/rubycanusellm.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "rubycanusellm/version"
+require_relative "rubycanusellm/configuration"
+require_relative "rubycanusellm/errors"
+require_relative "rubycanusellm/response"
+require_relative "rubycanusellm/providers/base"
+require_relative "rubycanusellm/providers/openai"
+require_relative "rubycanusellm/providers/anthropic"
+
+module RubyCanUseLLM
+  PROVIDERS = {
+    openai: Providers::OpenAI,
+    anthropic: Providers::Anthropic
+  }.freeze
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset!
+      @configuration = Configuration.new
+      @client = nil
+    end
+
+    def client
+      configuration.validate!
+      @client ||= PROVIDERS.fetch(configuration.provider) do
+        raise Error, "Unknown provider: #{configuration.provider}"
+      end.new(configuration)
+    end
+
+    def chat(messages, **options)
+      client.chat(messages, **options)
+    end
+  end
+end

data/sig/rubycanusellm.rbs

@@ -0,0 +1,4 @@
+module Rubycanusellm
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: rubycanusellm
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Juan Manuel Guzman Nava
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-04-01 00:00:00.000000000 Z
+dependencies: []
+description: One interface, every LLM. Rubycanusellm provides a unified client for
+  OpenAI, Anthropic, and more, plus generators that scaffold the boilerplate so you
+  go from zero to completions in 60 seconds.
+email:
+- juan.guzman3@flex.com
+executables:
+- rubycanusellm
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/rubycanusellm
+- lib/rubycanusellm.rb
+- lib/rubycanusellm/cli.rb
+- lib/rubycanusellm/configuration.rb
+- lib/rubycanusellm/errors.rb
+- lib/rubycanusellm/providers/anthropic.rb
+- lib/rubycanusellm/providers/base.rb
+- lib/rubycanusellm/providers/openai.rb
+- lib/rubycanusellm/response.rb
+- lib/rubycanusellm/templates/completion.rb.tt
+- lib/rubycanusellm/templates/config.rb.tt
+- lib/rubycanusellm/version.rb
+- sig/rubycanusellm.rbs
+homepage: https://github.com/mgznv/rubycanusellm
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mgznv/rubycanusellm
+  source_code_uri: https://github.com/mgznv/rubycanusellm
+  changelog_uri: https://github.com/mgznv/rubycanusellm/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: A unified Ruby client for multiple LLM providers with generators
+test_files: []