# rtjshreyd/excelus_agents architecture

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

- Interactive diagram: https://gitdiagram.com/rtjshreyd/excelus_agents
- Repository: https://github.com/rtjshreyd/excelus_agents

## Overview

##### Project Type and Purpose
- This project serves as a production micro-service architecture for hosting AI agents (with a current demonstration being the “medical_reception” agent) designed for the ExcelusAI team.
- The project uses a REST API built with FastAPI, integrates a langchain-based agent that leverages the GPT-4 OpenAI model, and employs components like a Redis cache for agent memory, a text embedding tool, and custom tools using OpenAI functions.
- The intention is that each agent is a self-contained micro-service.

##### Analyzing the File Structure
- Top-Level Overview:
- The root includes project metadata files (.gitignore, LICENSE, main README.md) and a main “medical_reception” directory.
- Inside the “medical_reception” Directory:
- Configuration: Contains environment files (.env and Docker configs), a Dockerfile, and the docker-compose.yml for container orchestration.
- The “configs” folder includes JSON and text-based configuration files (agent_config.json, base_prompt.txt) and configuration python files which set various parameters.
- The “core” folder provides foundational functionalities such as dependency management and validation routines.
- The “lib” directory houses key modules that implement the agent logic: agent functionality, custom tools, information handling, and domain-specific object definitions.
- External resources are stored in the “external_media” folder (doctors.txt, packages.txt) which likely provide lookup data for the medical context.
- The medical_reception client script and main application file (main.py) tie these components together.
- Additional supporting files such as test.py and requirements.txt indicate testing and dependency management.

a. MAIN COMPONENTS:
- REST API Service: Represent the FastAPI-based REST interface.
- AI Agent Microservice: Highlight the langchain-based integration using GPT-4.
- Caching & Memory: Identify the Redis cache component for storing the agent’s conversational/memory state.
- Configuration & Environment Management: Represent configuration files, environment variables (.env) that tailor the agent’s behavior.
- External Data & Media: Show the external media (doctors, packages) feeding into the agent’s domain data.
- Custom Tools & Libraries: Represent the custom tool implementations and additional libraries that extend core functionality.

b. RELATIONSHIPS AND INTERACTIONS:
- The REST API (FastAPI) receives incoming user requests and forwards them to the AI agent service.
- The agent service, using its core and lib modules, processes inquiries. It leverages configurations (from the configs folder) and accesses external data (from the external_media folder) as needed.
- The AI component interacts with the GPT-4 model for generating responses.
- How Docker (Dockerfile and docker-compose.yml) containerizes and orchestrates these services.

c. ARCHITECTURAL PATTERNS / DESIGN PRINCIPLES:
- Micro-service architecture: Each agent (like medical_reception) is designed to be independent.
- Separation of concerns: There is a clear separation between configuration, core business logic, and helper tools.
- Containerization: Emphasize containerization (Docker/Docker Compose) supporting scalable deployment.

d. TECHNOLOGIES, FRAMEWORKS, LIBRARIES:
- FastAPI for the REST API.
- Python-based modules (langchain, custom python modules under lib) using GPT-4 from OpenAI.
- Redis for caching agent memory.
- Docker for containerization.
- Ancillary tools for text embedding and additional custom OpenAI functions.

- Clearly labeled components (e.g., “FastAPI REST API”, “GPT-4 AI Agent”, “Redis Cache”, “External Data Sources”).
- Annotations for key technologies (e.g., “FastAPI”, “langchain”, “Redis”) next to the respective component blocks.
- Distinct sections or grouping (for example, a container representing a Docker environment which includes the agent service and its dependencies).

## Diagram (Mermaid)

```mermaid
flowchart TD
    U("User"):::user
    U --> A1("FastAPI REST API"):::service

    subgraph "Medical Reception Service"
        direction TB
        A1("FastAPI REST API"):::service
        A2("AI Agent Microservice"):::service
        A3("Core Business Logic"):::core
        A4("Configuration & Environment"):::config
        A5("Lib Modules"):::library
    end

    A1 --> A2
    A2 --> A3
    A2 --> A4
    A2 --> A5

    subgraph "Configuration & Environment Files"
        direction TB
        C1(".env.docker-example"):::config
        C2(".env.example"):::config
        C3("agent_config.json"):::config
        C4("base_prompt.txt"):::config
        C5("config.py"):::config
    end

    A4 --> C1
    A4 --> C2
    A4 --> C3
    A4 --> C4
    A4 --> C5

    subgraph "Lib Modules Files"
        direction TB
        L1("custom_tools.py"):::library
        L2("tools.py"):::library
        L3("info_handler.py"):::library
        L4("objects.py"):::library
    end

    A5 --> L1
    A5 --> L2
    A5 --> L3
    A5 --> L4

    A2 --> R1("Redis Cache"):::external
    A2 --> G1("GPT-4 Model"):::external
    A2 --> E1("External Media"):::config

    subgraph "Containerization & Orchestration"
        direction TB
        D1("Dockerfile"):::container
        D2("docker-compose.yml"):::container
    end

    D1 --> A1

    %% Click Events
    click A1 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/main.py"
    click A2 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/lib/agent.py"
    click C1 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/.env.docker-example"
    click C2 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/.env.example"
    click C3 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/configs/agent_config.json"
    click C4 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/configs/base_prompt.txt"
    click C5 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/configs/config.py"
    click A3 "https://github.com/rtjshreyd/excelus_agents/tree/main/medical_reception/core"
    click L1 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/lib/custom_tools.py"
    click L2 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/lib/tools.py"
    click L3 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/lib/info_handler.py"
    click L4 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/lib/objects.py"
    click E1 "https://github.com/rtjshreyd/excelus_agents/tree/main/medical_reception/external_media"
    click D1 "https://github.com/rtjshreyd/excelus_agents/tree/main/medical_reception/Dockerfile"
    click D2 "https://github.com/rtjshreyd/excelus_agents/blob/main/medical_reception/docker-compose.yml"

    %% Styles
    classDef user fill:#ffe6f9,stroke:#cc0099,stroke-width:2px;
    classDef service fill:#cce6ff,stroke:#004d99,stroke-width:2px;
    classDef core fill:#ffd9cc,stroke:#e65c00,stroke-width:2px;
    classDef config fill:#fff2cc,stroke:#e6ac00,stroke-width:2px;
    classDef library fill:#d9f2d9,stroke:#267326,stroke-width:2px;
    classDef external fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef container fill:#e6ccff,stroke:#6600cc,stroke-width:2px;
```
