# superagent-ai/reag architecture

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

- Interactive diagram: https://gitdiagram.com/superagent-ai/reag
- Repository: https://github.com/superagent-ai/reag

## Overview

##### Main Components
- Document Ingestion: Represent the raw document ingestion process where full documents (e.g., markdown with metadata) are accepted.
- Language Model Interface: Although the project is language model agnostic, include an “LLM Service” component that symbolizes the external language model that the system interacts with.
- Query Handling and Dynamic Synthesis: Showcase the processing pipeline where the prompt (which includes the document context) is sent to the language model and the client receives the synthesized answer.
- Testing and Validation: Optionally include a “Tests” component for quality assurance (as seen in the tests folders).

##### Relationships and Interactions
- From Document Ingestion to the Processing Pipeline: Show that raw documents enter the system via an ingestion module.
- Flow from Ingestion to Prompt Formation: Indicate how the “prompt” module constructs queries from ingested documents.
- Integration and Synthesis: Illustrate that once responses are returned, the system combines and synthesizes answers (“Dynamic Synthesis”) that complete the querying process.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Emphasize that different modules (client, prompt, schema) handle distinct parts of the process. This separation may also be reflected by having separate directories for the Python and Typescript implementations.

##### Relevant Technologies and Frameworks
- That there are specific configurations and project setup files (e.g., pyproject.toml for Python, package.json and tsconfig.json for Typescript) which manage dependencies and build processes.
- If needed, mention environment configurations (e.g., .env.example files) that are critical for deployment or integration with external LLM services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Entry Point
    DI["Document Ingestion"]:::core

    %% Python Pipeline
    PP["Python Prompt"]:::core
    PC["Python Client"]:::core
    PS["Python Schema"]:::core
    PConfig1["Python pyproject.toml"]:::config
    PConfig2["Python .env.example"]:::config
    PTests["Python Tests"]:::test

    %% Typescript Pipeline
    TP["Typescript Prompt"]:::core
    TC["Typescript Client"]:::core
    TS["Typescript Schema"]:::core
    TConfig1["Typescript package.json"]:::config
    TConfig2["Typescript tsconfig.json"]:::config
    TConfig3["Typescript env.example"]:::config
    TTests["Typescript Tests"]:::test

    %% Shared External and Synthesis
    LLM["LLM Service"]:::external
    DS["Dynamic Synthesis"]:::core
    OUT["Synthesized Output"]:::core

    %% Document Ingestion feeds both pipelines
    DI -->|"feeds"| PP
    DI -->|"feeds"| TP

    %% Python Pipeline Flow
    PP -->|"generates"| PC
    PC -.->|"uses"| PS
    PC -->|"calls"| LLM

    %% Python Configurations and Tests attached to Client
    PC -->|"configured_by"| PConfig1
    PConfig1 -->|"and"| PConfig2
    PC -->|"tested_by"| PTests

    %% Typescript Pipeline Flow
    TP -->|"generates"| TC
    TC -.->|"uses"| TS
    TC -->|"calls"| LLM

    %% Typescript Configurations and Tests attached to Client
    TC -->|"configured_by"| TConfig1
    TConfig1 -->|"and"| TConfig2
    TConfig2 -->|"and"| TConfig3
    TC -->|"tested_by"| TTests

    %% Convergence and Synthesis
    LLM -->|"returns"| DS
    DS -->|"produces"| OUT

    %% Styling
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef test fill:#f8d7da,stroke:#721c24,stroke-width:2px;

    %% Click Events
    click PC "https://github.com/superagent-ai/reag/blob/main/python/src/reag/client.py"
    click PP "https://github.com/superagent-ai/reag/blob/main/python/src/reag/prompt.py"
    click PS "https://github.com/superagent-ai/reag/blob/main/python/src/reag/schema.py"
    click TC "https://github.com/superagent-ai/reag/blob/main/typescript/src/client.ts"
    click TP "https://github.com/superagent-ai/reag/blob/main/typescript/src/prompt.ts"
    click TS "https://github.com/superagent-ai/reag/blob/main/typescript/src/schema.ts"
    click PTests "https://github.com/superagent-ai/reag/tree/main/python/tests/"
    click TTests "https://github.com/superagent-ai/reag/tree/main/typescript/tests/"
    click PConfig1 "https://github.com/superagent-ai/reag/blob/main/python/pyproject.toml"
    click PConfig2 "https://github.com/superagent-ai/reag/blob/main/python/.env.example"
    click TConfig1 "https://github.com/superagent-ai/reag/blob/main/typescript/package.json"
    click TConfig2 "https://github.com/superagent-ai/reag/blob/main/typescript/tsconfig.json"
    click TConfig3 "https://github.com/superagent-ai/reag/blob/main/typescript/env.example"
```
