# alchaplinsky/regent architecture

> Architecture diagram of the GitHub repository alchaplinsky/regent, 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/alchaplinsky/regent
- Repository: https://github.com/alchaplinsky/regent

## Overview

##### Project Type and Purpose
- Regent is a framework (Ruby gem) for constructing AI agents that can reason (via ReAct) and execute actions using external tools.
- The primary goal is to integrate language models (like OpenAI’s GPT, Anthropic’s Claude, the Gemini family, and local Ollama models) with a flexible tool system so that the agents’ decision-making and execution are both traceable and debuggable.
- The README outlines key features including multi-LLM support, extensible tool systems, engine customization, and session tracing.

##### File Structure
- The top-level directories/files include:
- lib/regent.rb: A central file that likely ties together core components.
- lib/regent/agent.rb: The Agent class representing the central AI entity.
- lib/regent/llm/: Modules for LLM integrations (OpenAI, Anthropic, Gemini, Ollama).
- lib/regent/engine/: Contains the base engine and specific implementations (such as the React engine).
- lib/regent/tool.rb and lib/regent/toolchain.rb: Define the tools available to the agents.
- lib/regent/concerns/: Mixins that provide reusable functionality (like identifiable or toolable behaviors).
- lib/regent/session.rb and lib/regent/span.rb: Represent execution sessions and traces.
- Other supporting files including logger, version, and Rakefile/specs show testing and development support.
- The spec directory shows extensive usage of fixtures (mostly for simulating responses from different LLMs) indicating emphasis on ensuring that each LLM and tool interaction is covered within tests.

##### Components
a. Main Components:
- Agent: The central component that receives prompts/questions and orchestrates responses.
- LLM Modules: Represent integrations with various language model providers (OpenAI, Anthropic, Gemini, Ollama). These modules are encapsulated under lib/regent/llm.
- Tools: Represent the different capabilities that the Agent might call (for example search, weather, or any custom tool) as defined in lib/regent/tool and extended via the toolchain.
- Engine: Represents the reasoning process (with default ReAct but adaptable to custom engines). Shown under lib/regent/engine.
- Session/Tracing: Illustrates the debugging and tracing mechanism built into the framework. This captures spans, logs, and session details.
- Concerns and Logger: Support modules that cross-cut application logic (for logging, identification, duration measurements, etc.).

b. Relationships and Interactions:
- The Agent serves as the orchestrator: It receives a user prompt, then initiates a session.
- The Agent calls the Engine (e.g., ReAct engine) to perform reasoning. The engine may invoke:
- LLM calls (through modules under Regent::LLM) where parameters (like temperature or API keys) come into play.
- Tool invocations when specific actions, such as fetching weather data or performing calculations, are required.
- Session or tracing components capture each step, allowing you to track from the initial input to the final result.
- Logger and Concerns are used throughout these interactions to ensure that internal operations (like identity marking, timing, and tool handling) are recorded and consistent.

c. Architectural Patterns & Important Design Principles:
- Modularity: Different concerns are separated (LLM handling, tool execution, engine processing, session logging) allowing straightforward extension.
- Extensibility: Custom tools, engines, and even model integrations can be plugged in—reflected by the inheritance from base classes.

##### Recap and Additional Notes
- Interplay between the AI reasoning components (the engine and LLM calls) and the action components (tool invocations and session logging).
- Extension points where custom engines or tools can be integrated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Layer"
        U["User Input"]:::user
    end

    subgraph "Agent Layer"
        A["Agent"]:::agent
    end

    subgraph "Processing Layer"
        subgraph "Engine (ReAct)"
            EB["Engine Base"]:::engine
            RE["React Engine"]:::engine
            PT["Prompt Template"]:::engine
            EB --> RE
            RE --> PT
        end
        subgraph "LLM Integrations"
            O["OpenAI"]:::llm
            ANT["Anthropic"]:::llm
            G["Gemini"]:::llm
            OL["Ollama"]:::llm
        end
        subgraph "Tools"
            T1["Tool Definition"]:::tool
            T2["Toolchain"]:::tool
        end
    end

    subgraph "Session & Tracing"
        S["Session Handling"]:::session
        SP["Span/Tracing"]:::session
    end

    subgraph "Support"
        C["Concerns"]:::support
        L["Logger"]:::support
    end

    U -->|"initiates"| A
    A -->|"invokes"| EB
    PT -->|"callsLLM"| O
    PT -->|"callsLLM"| ANT
    PT -->|"callsLLM"| G
    PT -->|"callsLLM"| OL
    O -->|"returns"| PT
    ANT -->|"returns"| PT
    G -->|"returns"| PT
    OL -->|"returns"| PT
    PT -->|"callsTools"| T1
    PT -->|"callsTools"| T2
    T1 -->|"returns"| PT
    T2 -->|"returns"| PT
    PT -->|"responds"| A
    A -->|"logsTo"| S
    A -->|"logsTo"| SP
    A -->|"uses"| C
    A -->|"logsWith"| L

    click A "https://github.com/alchaplinsky/regent/blob/main/lib/regent/agent.rb"
    click O "https://github.com/alchaplinsky/regent/blob/main/lib/regent/llm/open_ai.rb"
    click ANT "https://github.com/alchaplinsky/regent/blob/main/lib/regent/llm/anthropic.rb"
    click G "https://github.com/alchaplinsky/regent/blob/main/lib/regent/llm/gemini.rb"
    click OL "https://github.com/alchaplinsky/regent/blob/main/lib/regent/llm/ollama.rb"
    click T1 "https://github.com/alchaplinsky/regent/blob/main/lib/regent/tool.rb"
    click T2 "https://github.com/alchaplinsky/regent/blob/main/lib/regent/toolchain.rb"
    click EB "https://github.com/alchaplinsky/regent/blob/main/lib/regent/engine/base.rb"
    click RE "https://github.com/alchaplinsky/regent/blob/main/lib/regent/engine/react.rb"
    click PT "https://github.com/alchaplinsky/regent/blob/main/lib/regent/engine/react/prompt_template.rb"
    click S "https://github.com/alchaplinsky/regent/blob/main/lib/regent/session.rb"
    click SP "https://github.com/alchaplinsky/regent/blob/main/lib/regent/span.rb"
    click C "https://github.com/alchaplinsky/regent/tree/main/lib/regent/concerns/"
    click L "https://github.com/alchaplinsky/regent/blob/main/lib/regent/logger.rb"

    classDef user fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef agent fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef engine fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef llm fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef tool fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
    classDef session fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef support fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
```
