How crmne/ruby_llm works
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).