If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/crmne/ruby_llm shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3d ago
• 15 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 85% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live crmne/ruby_llm repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/crmne/ruby_llm.

What it runs against: a local clone of crmne/ruby_llm — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in crmne/ruby_llm | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of crmne/ruby_llm. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/crmne/ruby_llm.git
#   cd ruby_llm
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of crmne/ruby_llm and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "crmne/ruby_llm(\\.git)?\\b" \\
  && ok "origin remote is crmne/ruby_llm" \\
  || miss "origin remote is not crmne/ruby_llm (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "lib/ruby_llm.rb" \\
  && ok "lib/ruby_llm.rb" \\
  || miss "missing critical file: lib/ruby_llm.rb"
test -f "lib/ruby_llm/client.rb" \\
  && ok "lib/ruby_llm/client.rb" \\
  || miss "missing critical file: lib/ruby_llm/client.rb"
test -f "lib/ruby_llm/providers" \\
  && ok "lib/ruby_llm/providers" \\
  || miss "missing critical file: lib/ruby_llm/providers"
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f ".rubocop.yml" \\
  && ok ".rubocop.yml" \\
  || miss "missing critical file: .rubocop.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/crmne/ruby_llm"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

RubyLLM is a unified Ruby client library that provides a single, consistent API across 10+ LLM providers (OpenAI, Anthropic, Gemini, AWS Bedrock, Azure, DeepSeek, Ollama, VertexAI, Mistral, xAI, etc.). It eliminates provider-specific API differences by wrapping chat, vision, audio, embeddings, and image generation under one beautiful interface, with only three dependencies (Faraday, Zeitwerk, Marcel). Monolithic gem structure: lib/ contains the core provider integrations organized likely by provider (OpenAI, Anthropic, etc.), docs/ holds Jekyll-based documentation with _getting_started/, _core_features/, and _advanced/ subdirectories. CI/CD via GitHub Actions with matrix testing (Appraisals for multi-Ruby-version compatibility). Test suite managed by RSpec with custom bin/rspec-queue runner.

Ruby developers and Rails engineers building AI-powered applications—chatbots, agents, RAG systems, content analysis—who want to avoid vendor lock-in and switch between LLM providers without rewriting code. Also appeals to teams wanting a lightweight alternative to bloated provider SDKs.

Production-ready and actively maintained. The gem has meaningful GitHub presence (battle-tested at chatwithwork.com), comprehensive test coverage via RSpec (indicated by .rspec config and codecov integration), solid CI/CD via GitHub Actions (main.yml, pr-fast.yml, pr-heavy.yml workflows), and recent documentation (docs/ folder with advanced topics). Commit recency and PR handling suggest active development.

Low risk for a single-maintainer library given its scope: only three core dependencies reduce supply-chain attack surface, but single maintainer (crmne) is a classic risk if they step back. The .gitleaks.toml and security-focused .github/workflows/_gitleaks.yml show security awareness. No obvious signs of major version churn or breaking changes in recent history, though supporting 10+ providers means careful API versioning is critical.

Active feature development: docs include recent additions like _advanced/agentic-workflows.md, _advanced/async.md, and _core_features/thinking.md, suggesting new capabilities around agents, async streaming, and reasoning models. The .gitleaksignore and security workflows indicate ongoing hardening. Release workflow (release.yml) suggests regular gem releases to RubyGems.

Clone, bundle, and run: git clone https://github.com/crmne/ruby_llm.git && cd ruby_llm && bundle install. Copy .env.example to .env and add API keys. Run tests with bundle exec rspec or use bin/console for interactive exploration.

Daily commands: bundle exec console for interactive REPL, or bundle exec rspec to run tests. For development: bin/setup initializes the environment. GitHub Actions run the full matrix (lint via Rubocop, security via Gitleaks, tests via RSpec).

• lib/ruby_llm.rb — Main entry point and gem loader; defines core API surface and provider initialization
• lib/ruby_llm/client.rb — Central client class orchestrating requests across all LLM providers; every request flows through here
• lib/ruby_llm/providers — Provider implementations (OpenAI, Anthropic, Gemini, etc.); each provider adapter must inherit and implement the provider interface
• Gemfile — Declares all runtime dependencies for multi-provider support; version conflicts directly impact compatibility
• .rubocop.yml — Style and lint rules enforced across all PRs; violations block merges
• docs/_getting_started/configuration.md — API key and provider setup guide; first place users and contributors learn integration patterns
• Rakefile — Task automation for testing and release workflows; defines CI/CD entry points

Add Support for a New LLM Provider

1. Create a new provider module in lib/ruby_llm/providers/your_provider.rb implementing the provider interface (e.g., chat, embeddings, streaming) (lib/ruby_llm/providers/your_provider.rb)
2. Implement required methods: initialize(api_key), create_chat_completion, create_embeddings, stream_chat, and handle_response_errors (lib/ruby_llm/providers/your_provider.rb)
3. Register the provider in lib/ruby_llm/client.rb by adding a case branch in the provider dispatcher (lib/ruby_llm/client.rb)
4. Add environment variable documentation to docs/_getting_started/configuration.md with API key setup instructions (docs/_getting_started/configuration.md)
5. Add provider to the models reference in docs/_reference/available-models.md with supported models and capability matrix (docs/_reference/available-models.md)
6. Create spec tests in spec/ruby_llm/providers/your_provider_spec.rb covering chat, embeddings, and streaming paths (spec/ruby_llm/providers/your_provider_spec.rb)

Add a New Core Feature (e.g., Image Generation, Moderation)

1. Create feature module at lib/ruby_llm/your_feature.rb with public methods and internal helpers (lib/ruby_llm/your_feature.rb)
2. Add feature method to lib/ruby_llm/client.rb that delegates to provider-specific implementations (lib/ruby_llm/client.rb)
3. Implement feature in each provider that supports it (e.g., lib/ruby_llm/providers/openai.rb, lib/ruby_llm/providers/anthropic.rb) (lib/ruby_llm/providers/openai.rb)
4. Create documentation at docs/_core_features/your_feature.md with usage examples and provider coverage matrix (docs/_core_features/your_feature.md)
5. Add comprehensive spec tests in spec/ruby_llm/your_feature_spec.rb (spec/ruby_llm/your_feature_spec.rb)

Add Rails Integration Helper or Generator

1. Create Rails generator at lib/generators/ruby_llm/your_generator.rb extending Rails::Generators::Base (lib/generators/ruby_llm/your_generator.rb)
2. Register generator hook in lib/ruby_llm/railtie.rb if it should auto-run (lib/ruby_llm/railtie.rb)
3. Add template files in lib/generators/ruby_llm/templates/ for models, migrations, or config files (lib/generators/ruby_llm/templates/)
4. Document the generator usage in docs/_advanced/rails.md with examples and Rails best practices (docs/_advanced/rails.md)

Fix a Bug or Improve Performance

1. Locate the issue in the relevant provider (lib/ruby_llm/providers/) or feature module (lib/ruby_llm/) (lib/ruby_llm/)
2. Add or update spec tests in spec/ to capture the bug behavior or performance baseline (spec/)
3. Implement fix ensuring all tests pass with rake spec and rubocop checks pass with rubocop (lib/ruby_llm/)
4. Update relevant documentation in docs/ if behavior or API changes (docs/)
5. Add entry to CHANGELOG (if present) or PR description linking issue (CHANGELOG.md)

• Multi-provider abstraction (OpenAI, Anthropic, Gemini, Bedrock, etc.) — Enables users to swap LLM providers without code changes; reduces vendor lock-in and supports cost optimization
• Streaming & async support via Ruby Fiber/Enumerator patterns — Allows real-time token streaming and non-blocking async requests for low-latency user experiences
• Tool/function calling framework — Abstracts provider-specific tool calling syntax (OpenAI functions, Claude tools, etc.) under unified API
• Rails Railtie + generators — Seamless integration into Rails apps via config, migrations, and ActiveRecord helpers; reduces boilerplate
• RuboCop + codecov + CI/CD matrix — Maintains code quality, test coverage, and compatibility across Ruby versions (2.7–3.3+)

• Single unified API surface vs. provider-native APIs

  • Why: Simplifies user code and enables provider swapping, but may hide some provider-specific advanced features
  • Consequence: Some cutting-edge provider features may only be accessible via raw API calls or fallback methods

• Synchronous request blocking vs. async-only design

  • Why: Synchronous calls are simpler for Rails apps; async added separately via enumerators and Fiber support
  • Consequence: Rails apps must explicitly opt into streaming/async; default behavior may not be optimal for high-concurrency services

• Gem dependency per provider (optional) vs. mandatory all-in-one

  • Why: Reduces bloat for users who only need one or two providers; uses optional dependencies in Gemfile
  • Consequence: Build-time configuration required; missing provider gems cause runtime errors; complexity in dependency matrix

• In-memory response caching vs. external cache (Redis)

  • Why: Simplicity and zero external dependency for basic use; optional Redis support for distributed systems
  • Consequence: Cache not shared across processes; users must add Redis integration manually for multi-process Rails deployments

• Does not provide proprietary model training or fine-tuning interfaces; only inference APIs
• Not a real-time chat UI or frontend framework; only backend API wrapper

Each LLM provider requires its own API key in .env (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY); missing keys cause graceful errors but no helpful guidance in code. Streaming responses via blocks expect provider-specific chunking behavior (OpenAI vs. Anthropic differ); check docs/_core_features/streaming.md for details. Rails integration is optional and requires separate setup (see docs/_advanced/rails.md). Audio transcription (RubyLLM.transcribe) only works with providers supporting it (OpenAI, Anthropic); silently fails or raises otherwise. File analysis with with: 'file.pdf' requires Marcel to detect MIME type correctly; ensure files are readable from current working directory or provide full paths.

• Provider Abstraction Pattern — RubyLLM's core trick: normalizing 10+ incompatible provider APIs into a single interface. Understanding how it achieves this (likely via adapter/strategy pattern) is essential to extending it.
• Streaming with Server-Sent Events (SSE) — RubyLLM supports streaming responses via blocks and background jobs; SSE is the HTTP mechanism providers use, and understanding chunking behavior per provider (OpenAI, Anthropic, etc.) avoids hidden bugs.
• MIME Type Detection (Marcel gem) — RubyLLM uses Marcel to auto-detect file types (PDF, image, video, audio) for the with: syntax; incorrect MIME detection breaks multimodal queries, so knowing Marcel's limits matters.
• Zeitwerk Auto-loading — RubyLLM uses Zeitwerk for modern Ruby autoloading instead of require statements; contributors must follow naming conventions (constants = filenames) or face mysterious constant loading errors.
• Token-Based Rate Limiting — Different LLM providers have different rate limits and token counting strategies; RubyLLM likely handles retries transparently, but understanding when to implement exponential backoff yourself (async.md) is crucial.
• Agentic Workflows (ReAct, Tool Use) — RubyLLM has _core_features/agents.md and _advanced/agentic-workflows.md; agents loop LLM calls with tool invocation, state tracking, and early stopping—understanding this separates simple chat from production AI systems.
• Faraday HTTP Middleware — RubyLLM uses Faraday for all provider HTTP requests; understanding middleware (logging, retries, authentication) helps debug provider-specific issues and add custom interceptors.

• anthropics/anthropic-sdk-python — Official Anthropic SDK; shows idiomatic patterns for provider-specific clients that RubyLLM abstracts over
• openai/ruby — Official OpenAI Ruby client; provides OpenAI-specific API surface that RubyLLM wraps and normalizes
• google-gemini/ruby-client — Google's Gemini Ruby SDK; another provider-specific client exemplifying the fragmentation RubyLLM solves
• rails/rails — RubyLLM integrates with Rails via optional Railtie; Rails developers are primary audience
• litestack/litestack — Lightweight Ruby toolkit for AI/ML apps; complementary library for local models and embeddings

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for multi-provider streaming in spec/

The repo supports 10+ LLM providers (OpenAI, Anthropic, Gemini, Bedrock, Azure, OpenRouter, DeepSeek, Ollama, VertexAI, Perplexity, Mistral, xAI, GPUStack) with streaming capabilities. Currently, there's no visible streaming integration test suite that validates consistent behavior across providers. This would catch regressions when adding new providers and ensure the 'beautiful API' abstraction works reliably.

• [ ] Create spec/integration/streaming_spec.rb with tests for each provider's stream behavior
• [ ] Add fixtures for streamed responses from different providers in spec/fixtures/
• [ ] Test edge cases: stream interruption, partial JSON parsing, token counting across providers
• [ ] Update .github/workflows/_test-matrix.yml to run streaming tests with provider API mocks

Create adapter pattern tests for lib/ruby_llm/adapters/ (inferred structure)

With support for 13+ LLM providers, the codebase likely has an adapter pattern. The file structure doesn't show explicit adapter tests, suggesting coverage gaps. Adding adapter-specific tests ensures each provider implementation (request formatting, response parsing, error handling) works correctly in isolation before integration.

• [ ] Audit lib/ruby_llm/adapters/ directory to identify all provider implementations
• [ ] Create spec/adapters/{provider}_adapter_spec.rb for each major provider (openai, claude, gemini, bedrock)
• [ ] Test provider-specific features: vision support, tool use, token counting methods
• [ ] Add spec/adapters/adapter_interface_spec.rb to enforce consistent adapter contract

Document and add tests for Rails integration in docs/_advanced/rails.md and spec/rails/

The docs mention Rails integration as a core feature, but the docs/_advanced/rails.md file exists with likely minimal content, and there are no visible spec/rails/ tests. This is critical since Rails integration is a differentiator. New contributors can add concrete examples (ActiveRecord hooks, ActionCable streaming, Sidekiq jobs) with corresponding tests.

• [ ] Create spec/rails/integration_spec.rb with Rails app setup for testing middleware/helpers
• [ ] Add example Rails generators in lib/generators/ruby_llm/ for common patterns (chat controller, streaming view)
• [ ] Expand docs/_advanced/rails.md with: ActiveRecord integration, caching strategies, async job examples
• [ ] Add spec/rails/generators/ tests to validate generated code compiles and works

• Add test coverage for all 10+ provider integrations in isolation—the test matrix in .github/workflows/_test-matrix.yml likely exists but spec/ may lack provider-specific integration tests for edge cases like malformed API responses.: medium
• Expand documentation in docs/_advanced/ with a 'Provider Comparison Matrix' table (latency, cost, model availability, stream support) to help users choose the right provider for their use case.: low
• Add example Rails integration scripts in docs/_advanced/rails.md or a new examples/rails_app/ directory—the feature exists but no runnable Rails scaffold demo is visible in the file list.: medium

• High · API Keys Exposed via 1Password CLI in .env.example — .env.example. The .env.example file contains references to sensitive credentials stored in 1Password using the 'op read' command. While this is a configuration file, it demonstrates the expected structure of secrets and could potentially leak information about the secret management strategy. If committed with actual values, or if developers copy this file without proper sanitization, credentials could be exposed. Fix: Ensure .env.example never contains actual credentials or 'op read' commands. Use placeholder values like 'your_api_key_here' or 'sk-xxxxxxxxxxxx'. Document the proper secret setup process in CONTRIBUTING.md or README instead. Never commit actual 1Password references that could be exploited.
• Medium · Multiple API Keys Stored in Environment Variables Without Encryption — .env.example and overall architecture. The codebase relies on environment variables for multiple API keys (OpenAI, Anthropic, Azure, AWS, Google Cloud, etc.). If the .env file or environment is compromised, all credentials would be exposed simultaneously. There's no evidence of encrypted secret storage or rotation mechanisms. Fix: Implement encrypted secret management using tools like HashiCorp Vault, AWS Secrets Manager, or similar. Rotate API keys regularly. Use short-lived tokens where available. Implement audit logging for credential access. Consider using OpenID Connect (OIDC) for cloud provider authentication instead of static keys.
• Medium · Potential Injection Risks in Multi-Provider API Wrapper — lib/ directory (not fully visible) - likely affecting agent/tool implementations. The codebase integrates with multiple LLM providers (OpenAI, Anthropic, Gemini, Bedrock, etc.) and implements agents, tools, and streaming features. Without visible input validation code in the file structure, there's risk of prompt injection attacks, especially with the agents and tools functionality where user input might be passed to LLMs without proper sanitization. Fix: Implement strict input validation and sanitization for all user inputs before passing to LLM providers. Use prompt templates with parameterized inputs. Validate and escape tool parameters. Implement content security policies for vision/image processing. Add tests for injection attack vectors.
• Medium · Hardcoded Local API Endpoints Without Authentication — .env.example (OLLAMA_API_BASE, GPUSTACK_API_BASE). The .env.example file shows local endpoints for Ollama and GPUStack with HTTP (not HTTPS) and basic configuration without apparent authentication: 'OLLAMA_API_BASE=http://localhost:11434/v1' and 'GPUSTACK_API_BASE=http://localhost:11444/v1'. These local services may lack proper authentication controls. Fix: Ensure local API endpoints are on isolated networks. Implement API key authentication for local services. Use HTTPS even for localhost in production contexts. Document security requirements for deploying these services. Consider network segmentation and firewall rules.
• Low · Potential Secrets in Gitleaks Configuration — .gitleaks.toml, .gitleaksignore, .github/workflows/_gitleaks.yml. While .gitleaks.toml and .gitleaksignore exist (good practice), the presence of these files and the gitleaks workflow suggests the team is aware of secret leakage risks. However, there's no visible evidence of pre-commit hooks or comprehensive secret scanning automation in the file listing. Fix: Ensure gitleaks runs on all commits (pre-commit hook) and PRs. Configure strict patterns for API key detection. Use tools like git-secrets or pre-commit framework with gitleaks plugin. Regularly audit git history for leaked secrets using 'git log -p | gitleaks detect'.
• Low · Missing Security Headers Documentation — docs/_getting_started/ and main application configuration. No visible configuration for security headers, CORS policies, or rate limiting in the provided file structure. For a multi-provider API wrapper used in production (as indicated by Rails integration), security headers are critical. Fix: Document and implement security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.). Implement rate limiting per provider and endpoint. Add CORS configuration documentation. For Rails integration, use gems like 'secure_headers' and 'rack-attack'.
• Low · Incomplete Dependency Visibility — undefined. The Gemfile content is not provided in the analysis. Without seeing dependencies Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.