# danf57/agentic_ai_tesis architecture

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

- Interactive diagram: https://gitdiagram.com/danf57/agentic_ai_tesis
- Repository: https://github.com/danf57/agentic_ai_tesis

## Overview

##### Project Type and Purpose
- This is a full-stack AI-agent application built for a thesis in Computer Science.
- It consists of a client layer (agent interface + Streamlit UI), a backend server that exposes APIs and hosts a vector database, and a knowledge-population pipeline.

##### File Structure Analysis
- Top-level directories:
- client: Python scripts for the agent client (`agent_client.py`), a Streamlit UI (`ui_streamlit.py`), and an LLM factory helper.
- server: code for hosting the API (`my_server.py`), a knowledge ingestion/population script, and a prebuilt Reddit dataset JSON.
- config: YAML files for Chroma vector DB, model settings, and general settings.
- tests: unit tests covering the agent logic, LLM factory, tools, and vector DB.
- Key configuration files: `chroma.yaml` (vector DB settings), `models.yaml` (model parameters), `settings.yaml` (app-level settings).
- Build/deploy scripts aren’t present, implying manual startup (e.g., `python server/my_server.py`).

##### README Insights
- Brief description: “agent for my thesis.”

##### Main Components
a. Client Layer
- Streamlit UI (`client/ui_streamlit.py`): web interface for user input and output display.
- Agent Client (`client/agent_client.py`): orchestrates calls to the backend, sends queries, receives and processes responses.
- LLM Factory (`client/utils/llm_factory.py`): abstracts creation/configuration of LLM instances (e.g., OpenAI, local models).

b. Backend Layer
- API Server (`server/my_server.py`): REST (or HTTP) endpoints for query processing, middleware for authentication (if any), orchestrates vector DB lookups and LLM calls.
- Vector Database (Chroma): stores embeddings of knowledge base documents for similarity search. Configuration loaded from `config/chroma.yaml`.
- Knowledge Population Script (`server/knowledge/populate_vector.py`): offline/one-time job that ingests `reddit_dataset_final_1492_posts.json`, computes embeddings, and populates the vector DB.

c. Data & Configuration
- Config Service: loads `models.yaml` and `settings.yaml` at startup to parameterize LLM calls, endpoint settings, and vector DB parameters.
- Dataset Storage: raw JSON file under `server/knowledge/`.

d. External Services
- LLM Provider: external API calls (e.g., OpenAI) or local inference servers.
- (Optional) Authentication or Logging services if added in future.

##### Interactions and Data Flows
- User → Streamlit UI: inputs prompt.
- UI → Agent Client: forwards prompt.
- Agent Client → API Server: HTTP request with query payload.
- API Server → Vector DB: similarity search to retrieve top-k relevant docs.
- API Server → LLM Factory → LLM Provider: constructs prompt with retrieved docs, sends to model, obtains completion.
- API Server → Agent Client: returns LLM response.
- Agent Client → UI: displays the result.

##### Architectural Patterns and Principles
- Layered Architecture: client layer, API layer, persistence/inference layer.
- Factory Pattern: used for decoupling LLM instantiation (`llm_factory.py`).
- Configuration-Driven Design: YAML files for easy swapping of models and DB backends.
- Separation of Concerns: distinct knowledge ingestion pipeline vs. query-time processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        UI["Streamlit UI"]:::client
        AgentClient["Agent Client"]:::client
        LLMFactory["LLM Factory"]:::client
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        APIServer["API Server"]:::server
        VectorDB["Chroma Vector DB"]:::datastore
        subgraph "Knowledge Population Pipeline"
            direction TB
            Populator["Knowledge Population Script"]:::server
            RawData["Reddit Dataset JSON"]:::datastore
        end
    end

    %% Configuration
    subgraph "Configuration"
        direction TB
        ChromaCFG["chroma.yaml"]:::config
        ModelsCFG["models.yaml"]:::config
        SettingsCFG["settings.yaml"]:::config
    end

    %% External Services
    LLMProvider["LLM Provider"]:::external

    %% Interactions
    UI -->|"input prompt"| AgentClient
    AgentClient -->|"HTTP request"| APIServer
    APIServer -->|"similarity search"| VectorDB
    VectorDB -->|"top-k docs"| APIServer
    APIServer -->|"construct prompt"| LLMFactory
    LLMFactory -->|"API call"| LLMProvider
    LLMProvider -->|"completion"| LLMFactory
    LLMFactory -->|"response"| APIServer
    APIServer -->|"HTTP response"| AgentClient
    AgentClient -->|"display result"| UI

    %% Population Flow
    Populator -->|"reads data"| RawData
    Populator -->|"uses config"| ChromaCFG
    Populator -->|"populates"| VectorDB

    %% Config usage in server
    APIServer -->|"loads"| ModelsCFG
    APIServer -->|"loads"| SettingsCFG
    APIServer -->|"loads"| ChromaCFG

    %% Click Events
    click UI "https://github.com/danf57/agentic_ai_tesis/blob/main/client/ui_streamlit.py"
    click AgentClient "https://github.com/danf57/agentic_ai_tesis/blob/main/client/agent_client.py"
    click LLMFactory "https://github.com/danf57/agentic_ai_tesis/blob/main/client/utils/llm_factory.py"
    click APIServer "https://github.com/danf57/agentic_ai_tesis/blob/main/server/my_server.py"
    click ChromaCFG "https://github.com/danf57/agentic_ai_tesis/blob/main/config/chroma.yaml"
    click ModelsCFG "https://github.com/danf57/agentic_ai_tesis/blob/main/config/models.yaml"
    click SettingsCFG "https://github.com/danf57/agentic_ai_tesis/blob/main/config/settings.yaml"
    click Populator "https://github.com/danf57/agentic_ai_tesis/blob/main/server/knowledge/populate_vector.py"
    click RawData "https://github.com/danf57/agentic_ai_tesis/blob/main/server/knowledge/reddit_dataset_final_1492_posts.json"
    click TestAgent "https://github.com/danf57/agentic_ai_tesis/blob/main/tests/test_agent.py"
    click TestLLMFactory "https://github.com/danf57/agentic_ai_tesis/blob/main/tests/test_llm_factory.py"
    click TestTools "https://github.com/danf57/agentic_ai_tesis/blob/main/tests/test_tools.py"
    click TestVectorDB "https://github.com/danf57/agentic_ai_tesis/blob/main/tests/test_vector_db.py"

    %% Styles
    classDef client fill:#D6EAF8,stroke:#1B4F72;
    classDef server fill:#D5F5E3,stroke:#186A3B;
    classDef datastore fill:#FAD7A0,stroke:#B9770E,stroke-width:2px;
    classDef config fill:#EBDEF0,stroke:#6C3483,stroke-dasharray: 5 5;
    classDef external fill:#FFFFFF,stroke:#5D6D7E,stroke-dasharray: 2 2;
```
