# crmne/ruby_llm architecture

> Architecture diagram of the GitHub repository crmne/ruby_llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crmne/ruby_llm
- Repository: https://github.com/crmne/ruby_llm

## Overview

##### Main components
- Core Library (RubyLLM): This is the “heart” of the implementation, found under lib/ruby_llm. It includes the main API entry points (e.g., RubyLLM.chat, RubyLLM.embed, RubyLLM.paint) and fundamental utilities like configuration management, error handling, and streaming.
- Provider Modules: Under lib/ruby_llm/providers, separate folders exist for each AI provider (openai, anthropic, gemini, deepseek). Each provider has its own submodules for handling chat, embeddings, streaming responses, image generation, and more.
- Tool System: Modules such as RubyLLM::Tool and RubyLLM::ToolCall allow users to extend the library by letting AI perform custom Ruby operations. This is critical for the “tools” feature.
- Rails Integration: Components such as the Railtie (lib/ruby_llm/railtie.rb) and ActiveRecord extensions (under lib/ruby_llm/active_record) support integration into Rails applications to manage persistence (chats, messages, tool calls).
- External API Interaction: The library uses Faraday for HTTP requests to interact with the various external AI services, so implicit connection management to external services should be depicted.
- Streaming Module: There are dedicated portions of the code (e.g., lib/ruby_llm/streaming.rb, lib/ruby_llm/stream_accumulator.rb) to handle streaming responses, an important part of real-time interaction.

##### Relationships and interactions
- The central RubyLLM API acts as the facade that routes calls to provider-specific modules based on configuration (via RubyLLM.configure) and the API keys set.
- The chat component accepts queries and then dispatches messages to a specific provider’s chat module. Results (or errors) flow back via consistent structures.
- When a chat request is initiated, the system may additionally route through the streaming modules if real-time responses are requested.
- The tool system is layered on top of chat: when a user defines a tool (i.e., RubyLLM::Tool subclass), it is dynamically integrated so that AI queries can trigger the execution of user code.
- In the Rails context, ActiveRecord integrations (using acts_as_chat, acts_as_message, acts_as_tool_call) manage automatic persistence.

##### Architectural patterns and design principles
- Abstraction Pattern: A single API abstracts various AI providers, ensuring consistency across different underlying implementations.
- Modular and Pluggable Architecture: Each provider’s functionality is encapsulated in its own module. This separation facilitates easy extensions or additions of new providers.
- Configuration and Dependency Injection: API keys and other configurations are injected into the library using a central configuration block.
- Streamlining of API responses: Consistent formatting and error handling across providers ensure a uniform experience.
- Integration Hooks: For Rails users, the library provides hooks to integrate automatically with ActiveRecord models to reliably persist data from conversations.

##### Incorporate details specific to this project type
- For this library (an API wrapper and integration tool for AI providers), emphasize the extensibility and unified interface.
- A section that illustrates the interaction flow: starting from a client call (e.g., chat.ask), through the central dispatch of RubyLLM, into different provider adapters, and finally returning a formatted response.
- You note how the tool system allows the library to execute user-defined Ruby code (serving as a bridge between AI-triggered events and custom business logic).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("Client Request"):::external

    subgraph "Core RubyLLM Library"
        API("RubyLLM API Entry Points (chat,embed,paint)"):::core
    end

    subgraph "Provider Modules"
        OpenAI("OpenAI Chat Module"):::provider
        Anthropic("Anthropic Chat Module"):::provider
        Gemini("Gemini Chat Module"):::provider
        DeepSeek("DeepSeek Chat Module"):::provider
    end

    subgraph "Tool System"
        Tool("RubyLLM::Tool & ToolCall"):::tool
    end

    subgraph "Streaming Module"
        Streaming("Streaming Handler"):::streaming
    end

    subgraph "Rails Integration / ActiveRecord Extensions"
        Railtie("Railtie"):::rails
        AR("ActiveRecord Extensions (acts_as_chat,acts_as_message,acts_as_tool_call)"):::rails
    end

    External("External APIs (Faraday)"):::external

    Client -->|"initiates_request"| API
    API -->|"dispatch"| OpenAI
    API -->|"dispatch"| Anthropic
    API -->|"dispatch"| Gemini
    API -->|"dispatch"| DeepSeek
    API -->|"tool_integration"| Tool
    API -->|"stream_handling"| Streaming
    API -->|"rails_hook"| Railtie

    OpenAI -->|"HTTP_Request"| External
    Anthropic -->|"HTTP_Request"| External
    Gemini -->|"HTTP_Request"| External
    DeepSeek -->|"HTTP_Request"| External

    Railtie -->|"enhances"| AR

    click API "https://github.com/crmne/ruby_llm/blob/main/lib/ruby_llm.rb"
    click API "https://github.com/crmne/ruby_llm/tree/main/lib/ruby_llm/"

    click OpenAI "https://github.com/crmne/ruby_llm/tree/main/lib/ruby_llm/providers/openai"
    click Anthropic "https://github.com/crmne/ruby_llm/tree/main/lib/ruby_llm/providers/anthropic"
    click Gemini "https://github.com/crmne/ruby_llm/tree/main/lib/ruby_llm/providers/gemini"
    click DeepSeek "https://github.com/crmne/ruby_llm/tree/main/lib/ruby_llm/providers/deepseek"

    click Tool "https://github.com/crmne/ruby_llm/blob/main/lib/ruby_llm/tool.rb"
    click Tool "https://github.com/crmne/ruby_llm/blob/main/lib/ruby_llm/tool_call.rb"

    click Railtie "https://github.com/crmne/ruby_llm/blob/main/lib/ruby_llm/railtie.rb"
    click AR "https://github.com/crmne/ruby_llm/blob/main/lib/ruby_llm/active_record/acts_as.rb"

    click Streaming "https://github.com/crmne/ruby_llm/blob/main/lib/ruby_llm/streaming.rb"
    click Streaming "https://github.com/crmne/ruby_llm/blob/main/lib/ruby_llm/stream_accumulator.rb"

    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef provider fill:#bbf,stroke:#333,stroke-width:2px;
    classDef tool fill:#bfb,stroke:#333,stroke-width:2px;
    classDef rails fill:#fbf,stroke:#333,stroke-width:2px;
    classDef streaming fill:#ff9,stroke:#333,stroke-width:2px;
    classDef external fill:#ddd,stroke:#333,stroke-width:2px;
```
