sage-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e5380b93f9b4d73ec594e712e1a7421d72c749c7e4fb2a0216deee2be1606aae
+  data.tar.gz: 877373c5133fcd9e29fd48fad8c0df533df8c2cfcf5881feef187b72523daea4
+SHA512:
+  metadata.gz: 6c5d49d69fe7122f3e41308bf8f28ef25ab8e626d4de9a2f35fa68ec616c8ef3e182506790f4418a580fdf2e136ff3f9007e243cc2a172e13c1dd6a7c736ea10
+  data.tar.gz: 4542f512d8198653dc7b4fc83345830e5e83294e115ffd395abc4cf144ad81517acf2c9e794ed3295b4da9c58b13c35eb66c60b5a936a4653afce6949fc6cd09

data/README.md

@@ -0,0 +1,265 @@
+# sage-rb
+
+A lightweight, provider-agnostic Ruby gem for calling LLM APIs. One interface for OpenAI, Anthropic, and Ollama — with profiles to switch between models without changing your code.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "sage-rb"
+```
+
+Or install directly:
+
+```bash
+gem install sage-rb
+```
+
+## Quick Start (Rails)
+
+Generate the initializer:
+
+```bash
+rails generate sage:install
+```
+
+Edit `config/initializers/sage.rb`:
+
+```ruby
+Sage.configure do |config|
+  config.provider :openai, api_key: Rails.application.credentials.dig(:openai, :api_key)
+
+  config.profile :default, provider: :openai, model: "gpt-4o"
+  config.default_profile :default
+end
+```
+
+Use it anywhere in your app:
+
+```ruby
+response = Sage.complete(prompt: "Summarize this article")
+response.content  # => "The article discusses..."
+```
+
+## Quick Start (Ruby)
+
+```ruby
+require "sage"
+
+Sage.configure do |config|
+  config.provider :openai, api_key: ENV["OPENAI_API_KEY"]
+
+  config.profile :default, provider: :openai, model: "gpt-4o"
+  config.default_profile :default
+end
+
+response = Sage.complete(prompt: "Hello!")
+puts response.content
+```
+
+## Configuration
+
+### Providers
+
+Register providers with their credentials. sage-rb never stores credentials — it receives API keys as strings and passes them to the provider API.
+
+```ruby
+Sage.configure do |config|
+  # OpenAI (or any OpenAI-compatible API)
+  config.provider :openai,
+    api_key: ENV["OPENAI_API_KEY"],
+    base_url: "https://api.openai.com/v1"  # optional, this is the default
+
+  # Anthropic
+  config.provider :anthropic,
+    api_key: ENV["ANTHROPIC_API_KEY"]
+
+  # Ollama (local, no API key required)
+  config.provider :ollama,
+    endpoint: "http://localhost:11434"  # optional, this is the default
+
+  # Ollama with authentication (remote deployment)
+  config.provider :ollama,
+    endpoint: "https://ollama.example.com",
+    api_key: ENV["OLLAMA_API_KEY"]
+end
+```
+
+### Profiles
+
+Profiles are named combinations of provider + model + default parameters. Define them once, use them everywhere.
+
+```ruby
+Sage.configure do |config|
+  config.provider :openai, api_key: ENV["OPENAI_API_KEY"]
+  config.provider :ollama, endpoint: "http://localhost:11434"
+
+  config.profile :small_brain, provider: :ollama, model: "hermes3"
+  config.profile :code_expert, provider: :openai, model: "gpt-4o",
+                 temperature: 0.2, max_tokens: 4096
+  config.profile :creative,    provider: :openai, model: "gpt-4o",
+                 temperature: 0.9
+
+  config.default_profile :small_brain
+end
+```
+
+Use different profiles for different tasks:
+
+```ruby
+Sage.complete(:code_expert, prompt: "Review this function")
+Sage.complete(:creative, prompt: "Write a haiku about Ruby")
+Sage.complete(prompt: "Hello")  # uses default profile (:small_brain)
+```
+
+### Environment-based defaults
+
+```ruby
+config.default_profile Rails.env.production? ? :code_expert : :small_brain
+```
+
+## Usage
+
+### Blocking completion
+
+Returns a `Sage::Response` with the full response:
+
+```ruby
+response = Sage.complete(:code_expert, prompt: "Explain recursion", system: "You are a teacher")
+
+response.content       # => "Recursion is when a function calls itself..."
+response.model         # => "gpt-4o"
+response.usage         # => { prompt_tokens: 15, completion_tokens: 42 }
+```
+
+### Streaming completion
+
+Pass a block to stream chunks as they arrive:
+
+```ruby
+Sage.complete(:code_expert, prompt: "Explain recursion") do |chunk|
+  if chunk.done?
+    puts "\n[Done]"
+  else
+    print chunk.content
+  end
+end
+```
+
+### Per-call parameter overrides
+
+Override profile defaults for a single call:
+
+```ruby
+# Profile has temperature: 0.2, but this call uses 0.9
+Sage.complete(:code_expert, prompt: "Be creative", temperature: 0.9)
+```
+
+### System prompts
+
+```ruby
+Sage.complete(:default,
+  prompt: "What is 2+2?",
+  system: "You are a math tutor. Show your work."
+)
+```
+
+## Providers Reference
+
+| Provider | Config key | Required fields | Optional fields |
+|----------|-----------|----------------|-----------------|
+| OpenAI | `:openai` | `api_key` | `base_url` |
+| Anthropic | `:anthropic` | `api_key` | `base_url` |
+| Ollama | `:ollama` | — | `endpoint`, `api_key` |
+
+### Provider notes
+
+**OpenAI** — Newer models (o1, o3, gpt-4o, gpt-5) automatically use `max_completion_tokens` instead of `max_tokens`. The `base_url` option supports OpenAI-compatible APIs (Azure, local proxies).
+
+**Anthropic** — System prompts are sent as a separate field (not in the messages array), matching the Anthropic API spec. `max_tokens` defaults to 1024 if not specified (Anthropic requires this field).
+
+**Ollama** — Runs locally by default at `http://localhost:11434`. API key is optional — only needed for authenticated remote deployments.
+
+## Error Handling
+
+```ruby
+begin
+  Sage.complete(prompt: "Hello")
+rescue Sage::AuthenticationError => e
+  # Invalid API key (401)
+rescue Sage::ProviderError => e
+  # Rate limited (429), server error (500), or other provider issues
+rescue Sage::ConnectionError => e
+  # Could not connect (e.g., Ollama not running)
+rescue Sage::ProfileNotFound => e
+  # Referenced a profile that doesn't exist
+rescue Sage::ProviderNotConfigured => e
+  # Profile references a provider that isn't configured
+rescue Sage::NoDefaultProfile => e
+  # Called Sage.complete without a profile name and no default is set
+rescue Sage::Error => e
+  # Catch-all for any sage-rb error
+end
+```
+
+## Response Objects
+
+### Sage::Response
+
+Returned by blocking `Sage.complete` calls.
+
+```ruby
+response.content       # String — the generated text
+response.model         # String — the model that generated it
+response.usage         # Hash — { prompt_tokens: Integer, completion_tokens: Integer }
+```
+
+### Sage::Chunk
+
+Yielded during streaming `Sage.complete` calls.
+
+```ruby
+chunk.content          # String — text fragment
+chunk.done?            # Boolean — true for the final chunk
+```
+
+## Security
+
+sage-rb never stores credentials — API keys are received as strings and passed directly to provider HTTP headers.
+
+### Provider URLs
+
+The `base_url` and `endpoint` configuration options control where HTTP requests are sent. These must only come from trusted sources:
+
+```ruby
+# Safe — from environment or Rails credentials
+config.provider :openai,
+  api_key: ENV["OPENAI_API_KEY"],
+  base_url: ENV["OPENAI_BASE_URL"]
+
+# Unsafe — NEVER use user input for provider URLs
+config.provider :openai,
+  api_key: current_user.api_key,
+  base_url: params[:base_url]  # DO NOT do this
+```
+
+Allowing user-controlled URLs could enable Server-Side Request Forgery (SSRF) against internal services.
+
+## Relationship to sage
+
+sage-rb is a companion to [sage](https://github.com/not-emily/sage), the Go CLI and library. They share the same core concepts:
+
+| Concept | sage (Go CLI) | sage-rb (Ruby gem) |
+|---------|--------------|-------------------|
+| **Providers** | Configured via `sage provider add` | Configured in initializer |
+| **Profiles** | Configured via `sage profile add` | Configured in initializer |
+| **Complete** | `sage complete --profile name` | `Sage.complete(:name, ...)` |
+| **Credentials** | Encrypted in `~/.config/sage/` | From ENV vars or Rails credentials |
+| **Streaming** | Default behavior | Pass a block to `Sage.complete` |
+
+Both make HTTP calls directly to provider APIs. They are independent implementations — sage-rb does not require or wrap the sage Go binary.
+
+## License
+
+MIT

data/lib/generators/sage/install_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Sage
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    desc "Creates a sage-rb initializer at config/initializers/sage.rb"
+
+    def create_initializer
+      template "initializer.rb.tt", "config/initializers/sage.rb"
+    end
+  end
+end

data/lib/sage/chunk.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Sage
+  class Chunk
+    attr_reader :content
+
+    def initialize(content:, done: false)
+      @content = content
+      @done = done
+    end
+
+    def done?
+      @done
+    end
+  end
+end

data/lib/sage/client.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Sage
+  class Client
+    PROVIDERS = {}
+
+    def self.register_provider(name, klass)
+      PROVIDERS[name.to_sym] = klass
+    end
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def complete(profile_name = nil, prompt:, system: nil, **params, &block)
+      profile = resolve_profile(profile_name)
+      provider = build_provider(profile)
+      merged_params = profile.params.merge(params)
+
+      if block
+        provider.stream(model: profile.model, prompt: prompt, system: system, **merged_params, &block)
+      else
+        provider.complete(model: profile.model, prompt: prompt, system: system, **merged_params)
+      end
+    end
+
+    private
+
+    attr_reader :configuration
+
+    def resolve_profile(name)
+      name = name&.to_sym || configuration.default_profile
+
+      raise NoDefaultProfile, "No default profile configured. Call Sage.configure { |c| c.default_profile :name }" if name.nil?
+
+      profile = configuration.profiles[name]
+
+      raise ProfileNotFound, "Profile '#{name}' is not configured" if profile.nil?
+
+      profile
+    end
+
+    def build_provider(profile)
+      provider_config = configuration.providers[profile.provider]
+
+      raise ProviderNotConfigured, "Provider '#{profile.provider}' referenced by profile '#{profile.name}' is not configured" if provider_config.nil?
+
+      provider_class = PROVIDERS[profile.provider]
+
+      raise ProviderNotConfigured, "No provider adapter registered for '#{profile.provider}'" if provider_class.nil?
+
+      provider_class.new(provider_config)
+    end
+  end
+end

data/lib/sage/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "profile"
+
+module Sage
+  class Configuration
+    attr_reader :providers, :profiles
+
+    def initialize
+      @providers = {}
+      @profiles = {}
+      @default_profile_name = nil
+    end
+
+    def provider(name, **options)
+      @providers[name.to_sym] = options
+    end
+
+    def profile(name, provider:, model:, **params)
+      @profiles[name.to_sym] = Profile.new(name: name, provider: provider, model: model, **params)
+    end
+
+    def default_profile(name = nil)
+      if name.nil?
+        @default_profile_name
+      else
+        @default_profile_name = name.to_sym
+      end
+    end
+  end
+end

data/lib/sage/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Sage
+  class Error < StandardError; end
+  class ProfileNotFound < Error; end
+  class ProviderNotConfigured < Error; end
+  class NoDefaultProfile < Error; end
+  class ConnectionError < Error; end
+  class AuthenticationError < Error; end
+  class ProviderError < Error; end
+end

data/lib/sage/profile.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Sage
+  class Profile
+    attr_reader :name, :provider, :model, :params
+
+    def initialize(name:, provider:, model:, **params)
+      @name = name.to_sym
+      @provider = provider.to_sym
+      @model = model.to_s
+      @params = params
+    end
+  end
+end

data/lib/sage/providers/anthropic.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Sage
+  module Providers
+    class Anthropic < Base
+      DEFAULT_BASE_URL = "https://api.anthropic.com/v1"
+      ANTHROPIC_VERSION = "2023-06-01"
+      DEFAULT_MAX_TOKENS = 1024
+
+      def complete(model:, prompt:, system: nil, **params)
+        body = build_request_body(model, prompt, system, stream: false, **params)
+        response = post(body)
+
+        parsed = JSON.parse(response.body)
+        content = extract_content(parsed)
+        usage = parsed.fetch("usage", {})
+
+        Response.new(
+          content: content,
+          model: model,
+          usage: {
+            prompt_tokens: usage["input_tokens"] || 0,
+            completion_tokens: usage["output_tokens"] || 0
+          }
+        )
+      end
+
+      def stream(model:, prompt:, system: nil, **params, &block)
+        body = build_request_body(model, prompt, system, stream: true, **params)
+        uri = endpoint_uri
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          request = build_http_request(uri, body)
+
+          http.request(request) do |response|
+            handle_error_response(response) unless response.is_a?(Net::HTTPSuccess)
+
+            current_event = nil
+
+            response.read_body do |chunk_data|
+              chunk_data.each_line do |line|
+                line = line.strip
+
+                if line.start_with?("event: ")
+                  current_event = line.delete_prefix("event: ")
+                  next
+                end
+
+                next if line.empty?
+                next unless line.start_with?("data: ")
+
+                if current_event == "message_stop"
+                  block.call(Chunk.new(content: "", done: true))
+                  return
+                end
+
+                next unless current_event == "content_block_delta"
+
+                data = line.delete_prefix("data: ")
+                parsed = JSON.parse(data)
+                delta = parsed["delta"]
+
+                next unless delta && delta["type"] == "text_delta" && !delta["text"].empty?
+
+                block.call(Chunk.new(content: delta["text"]))
+              end
+            end
+          end
+        end
+      end
+
+      private
+
+      def build_request_body(model, prompt, system, stream:, **params)
+        max_tokens = params.delete(:max_tokens) || DEFAULT_MAX_TOKENS
+
+        body = {
+          model: model,
+          messages: [{ role: "user", content: prompt }],
+          max_tokens: max_tokens
+        }
+
+        body[:system] = system if system
+        body[:stream] = true if stream
+        body.merge!(params)
+        body
+      end
+
+      def extract_content(parsed)
+        content_blocks = parsed["content"] || []
+        text_block = content_blocks.find { |block| block["type"] == "text" }
+        text_block ? text_block["text"] : ""
+      end
+
+      def endpoint_uri
+        base = config[:base_url]
+        base = DEFAULT_BASE_URL if base.nil? || base.empty?
+        URI("#{base.chomp("/")}/messages")
+      end
+
+      def post(body)
+        uri = endpoint_uri
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.read_timeout = 300
+
+        request = build_http_request(uri, body)
+        response = http.request(request)
+
+        handle_error_response(response) unless response.is_a?(Net::HTTPSuccess)
+
+        response
+      end
+
+      def build_http_request(uri, body)
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request["x-api-key"] = config[:api_key]
+        request["anthropic-version"] = ANTHROPIC_VERSION
+        request.body = JSON.generate(body)
+        request
+      end
+
+      def handle_error_response(response)
+        message = extract_error_message(response)
+
+        case response.code.to_i
+        when 401
+          raise AuthenticationError, "Invalid API key: #{message}"
+        when 429
+          raise ProviderError, "Rate limited: #{message}"
+        else
+          raise ProviderError, "API error (#{response.code}): #{message}"
+        end
+      end
+
+      def extract_error_message(response)
+        parsed = JSON.parse(response.body)
+        parsed.dig("error", "message") || response.body
+      rescue JSON::ParserError
+        response.body
+      end
+    end
+  end
+end

data/lib/sage/providers/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Sage
+  module Providers
+    class Base
+      def initialize(config)
+        @config = config
+      end
+
+      def complete(model:, prompt:, system: nil, **params)
+        raise NotImplementedError, "#{self.class}#complete is not implemented"
+      end
+
+      def stream(model:, prompt:, system: nil, **params, &block)
+        raise NotImplementedError, "#{self.class}#stream is not implemented"
+      end
+
+      private
+
+      attr_reader :config
+    end
+  end
+end

data/lib/sage/providers/ollama.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Sage
+  module Providers
+    class Ollama < Base
+      DEFAULT_BASE_URL = "http://localhost:11434"
+
+      def complete(model:, prompt:, system: nil, **params)
+        body = build_request_body(model, prompt, system, stream: false)
+        response = post(body)
+
+        parsed = JSON.parse(response.body)
+
+        raise ProviderError, "Ollama error: #{parsed["error"]}" if parsed["error"] && !parsed["error"].empty?
+
+        content = parsed.dig("message", "content") || ""
+
+        Response.new(
+          content: content,
+          model: model,
+          usage: {
+            prompt_tokens: parsed["prompt_eval_count"] || 0,
+            completion_tokens: parsed["eval_count"] || 0
+          }
+        )
+      rescue Errno::ECONNREFUSED
+        raise ConnectionError, "Could not connect to Ollama at #{endpoint_uri}. Is Ollama running?"
+      end
+
+      def stream(model:, prompt:, system: nil, **params, &block)
+        body = build_request_body(model, prompt, system, stream: true)
+        uri = endpoint_uri
+
+        ssl = uri.scheme == "https"
+        Net::HTTP.start(uri.host, uri.port, use_ssl: ssl) do |http|
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER if ssl
+          request = build_http_request(uri, body)
+
+          http.request(request) do |response|
+            handle_error_response(response) unless response.is_a?(Net::HTTPSuccess)
+
+            response.read_body do |chunk_data|
+              chunk_data.each_line do |line|
+                line = line.strip
+                next if line.empty?
+
+                parsed = JSON.parse(line)
+
+                if parsed["done"]
+                  block.call(Chunk.new(content: "", done: true))
+                  return
+                end
+
+                content = parsed.dig("message", "content")
+                next if content.nil? || content.empty?
+
+                block.call(Chunk.new(content: content))
+              end
+            end
+          end
+        end
+      rescue Errno::ECONNREFUSED
+        raise ConnectionError, "Could not connect to Ollama at #{endpoint_uri}. Is Ollama running?"
+      end
+
+      private
+
+      def build_request_body(model, prompt, system, stream:)
+        messages = []
+        messages << { role: "system", content: system } if system
+        messages << { role: "user", content: prompt }
+
+        {
+          model: model,
+          messages: messages,
+          stream: stream
+        }
+      end
+
+      def post(body)
+        uri = endpoint_uri
+        http = Net::HTTP.new(uri.host, uri.port)
+        ssl = uri.scheme == "https"
+        http.use_ssl = ssl
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER if ssl
+        http.read_timeout = 300
+
+        request = build_http_request(uri, body)
+        response = http.request(request)
+
+        handle_error_response(response) unless response.is_a?(Net::HTTPSuccess)
+
+        response
+      end
+
+      def build_http_request(uri, body)
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+
+        api_key = config[:api_key]
+        request["Authorization"] = "Bearer #{api_key}" if api_key && !api_key.empty?
+
+        request.body = JSON.generate(body)
+        request
+      end
+
+      def endpoint_uri
+        base = config[:endpoint]
+        base = DEFAULT_BASE_URL if base.nil? || base.empty?
+        URI("#{base.chomp("/")}/api/chat")
+      end
+
+      def handle_error_response(response)
+        message = extract_error_message(response)
+        raise ProviderError, "Ollama error (#{response.code}): #{message}"
+      end
+
+      def extract_error_message(response)
+        parsed = JSON.parse(response.body)
+        parsed["error"] || response.body
+      rescue JSON::ParserError
+        response.body
+      end
+    end
+  end
+end

data/lib/sage/providers/openai.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Sage
+  module Providers
+    class OpenAI < Base
+      DEFAULT_BASE_URL = "https://api.openai.com/v1"
+
+      def complete(model:, prompt:, system: nil, **params)
+        body = build_request_body(model, prompt, system, stream: false, **params)
+        response = post(body)
+
+        parsed = JSON.parse(response.body)
+        content = parsed.dig("choices", 0, "message", "content") || ""
+        usage = parsed.fetch("usage", {})
+
+        Response.new(
+          content: content,
+          model: model,
+          usage: {
+            prompt_tokens: usage["prompt_tokens"] || 0,
+            completion_tokens: usage["completion_tokens"] || 0
+          }
+        )
+      end
+
+      def stream(model:, prompt:, system: nil, **params, &block)
+        body = build_request_body(model, prompt, system, stream: true, **params)
+        uri = endpoint_uri
+
+        ssl = uri.scheme == "https"
+        Net::HTTP.start(uri.host, uri.port, use_ssl: ssl) do |http|
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER if ssl
+          request = build_http_request(uri, body)
+
+          http.request(request) do |response|
+            handle_error_response(response) unless response.is_a?(Net::HTTPSuccess)
+
+            response.read_body do |chunk_data|
+              chunk_data.each_line do |line|
+                line = line.strip
+                next if line.empty?
+                next unless line.start_with?("data: ")
+
+                data = line.delete_prefix("data: ")
+
+                if data == "[DONE]"
+                  block.call(Chunk.new(content: "", done: true))
+                  return
+                end
+
+                parsed = JSON.parse(data)
+                content = parsed.dig("choices", 0, "delta", "content")
+                next if content.nil? || content.empty?
+
+                block.call(Chunk.new(content: content))
+              end
+            end
+          end
+        end
+      end
+
+      private
+
+      def build_request_body(model, prompt, system, stream:, **params)
+        messages = []
+        messages << { role: "system", content: system } if system
+        messages << { role: "user", content: prompt }
+
+        body = {
+          model: model,
+          messages: messages,
+          stream: stream
+        }
+
+        if params[:max_tokens]
+          if use_max_completion_tokens?(model)
+            body[:max_completion_tokens] = params.delete(:max_tokens)
+          else
+            body[:max_tokens] = params.delete(:max_tokens)
+          end
+        end
+
+        body.merge!(params.except(:max_tokens))
+        body
+      end
+
+      def use_max_completion_tokens?(model)
+        model.start_with?("o1", "o3") ||
+          model.include?("gpt-4o") ||
+          model.include?("gpt-5")
+      end
+
+      def post(body)
+        uri = endpoint_uri
+        http = Net::HTTP.new(uri.host, uri.port)
+        ssl = uri.scheme == "https"
+        http.use_ssl = ssl
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER if ssl
+        http.read_timeout = 300
+
+        request = build_http_request(uri, body)
+        response = http.request(request)
+
+        handle_error_response(response) unless response.is_a?(Net::HTTPSuccess)
+
+        response
+      end
+
+      def build_http_request(uri, body)
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request["Authorization"] = "Bearer #{config[:api_key]}"
+        request.body = JSON.generate(body)
+        request
+      end
+
+      def endpoint_uri
+        base = config[:base_url]
+        base = DEFAULT_BASE_URL if base.nil? || base.empty?
+        URI("#{base.chomp("/")}/chat/completions")
+      end
+
+      def handle_error_response(response)
+        message = extract_error_message(response)
+
+        case response.code.to_i
+        when 401
+          raise AuthenticationError, "Invalid API key: #{message}"
+        when 429
+          raise ProviderError, "Rate limited: #{message}"
+        else
+          raise ProviderError, "API error (#{response.code}): #{message}"
+        end
+      end
+
+      def extract_error_message(response)
+        parsed = JSON.parse(response.body)
+        parsed.dig("error", "message") || response.body
+      rescue JSON::ParserError
+        response.body
+      end
+    end
+  end
+end

data/lib/sage/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Sage
+  class Railtie < Rails::Railtie
+    generators do
+      require "generators/sage/install_generator"
+    end
+  end
+end

data/lib/sage/response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Sage
+  class Response
+    attr_reader :content, :model, :usage
+
+    def initialize(content:, model:, usage: {})
+      @content = content
+      @model = model
+      @usage = usage
+    end
+  end
+end

data/lib/sage/version.rb

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

data/lib/sage.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "sage/version"
+require_relative "sage/errors"
+require_relative "sage/configuration"
+require_relative "sage/response"
+require_relative "sage/chunk"
+require_relative "sage/providers/base"
+require_relative "sage/providers/openai"
+require_relative "sage/providers/anthropic"
+require_relative "sage/providers/ollama"
+require_relative "sage/client"
+
+module Sage
+  class << self
+    def configure
+      @configuration = Configuration.new
+      yield(@configuration)
+      @configuration
+    end
+
+    def configuration
+      @configuration
+    end
+
+    def complete(profile_name = nil, **params, &block)
+      client = Client.new(configuration)
+      client.complete(profile_name, **params, &block)
+    end
+  end
+end
+
+Sage::Client.register_provider(:openai, Sage::Providers::OpenAI)
+Sage::Client.register_provider(:anthropic, Sage::Providers::Anthropic)
+Sage::Client.register_provider(:ollama, Sage::Providers::Ollama)
+
+require_relative "sage/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: sage-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Emily
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-13 00:00:00.000000000 Z
+dependencies: []
+description: A lightweight, provider-agnostic interface for calling LLM APIs (OpenAI,
+  Anthropic, Ollama) from any Ruby application.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/generators/sage/install_generator.rb
+- lib/sage.rb
+- lib/sage/chunk.rb
+- lib/sage/client.rb
+- lib/sage/configuration.rb
+- lib/sage/errors.rb
+- lib/sage/profile.rb
+- lib/sage/providers/anthropic.rb
+- lib/sage/providers/base.rb
+- lib/sage/providers/ollama.rb
+- lib/sage/providers/openai.rb
+- lib/sage/railtie.rb
+- lib/sage/response.rb
+- lib/sage/version.rb
+homepage: https://github.com/not-emily/sage-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/not-emily/sage-rb
+  source_code_uri: https://github.com/not-emily/sage-rb
+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.22
+signing_key:
+specification_version: 4
+summary: Unified LLM adapter for Ruby
+test_files: []