# honestsoul/generative_ai_project architecture

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

- Interactive diagram: https://gitdiagram.com/honestsoul/generative_ai_project
- Repository: https://github.com/honestsoul/generative_ai_project

## Overview

##### Project type and purpose
- This is an open-source “Generative AI Project Template” that provides a modular foundation for building LLM-powered applications. It is neither a web front-end nor a traditional back-end service, but rather a library/toolkit that coordinates prompt engineering, LLM clients, caching, rate-limiting, logging, and error handling to streamline AI integrations.

##### File structure
- Top-level directories:
- config/ – YAML files for model settings, prompts, and logging.
- src/ – Core modules organized into llm clients, prompt_engineering, utils, and handlers.
- data/ – Persistent storage for caches, prompt definitions, embeddings, and outputs.
- examples/ & notebooks/ – Entry points showing how to drive the library (scripts and Jupyter labs).

##### README for additional insights
- The README confirms support for multiple providers (Anthropic Claude & OpenAI GPT), details pre-configured utilities (rate limiter, token counter, caching, logging), and outlines best practices (YAML configs, modularity, error handling).

##### Main components & interactions
a. Components
- Entry Layer: Examples & Notebooks
- Configuration Loader (config/*.yaml)
- Prompt Engineering Module (src/prompt_engineering)
- LLM Client Layer (src/llm/base.py, claude_client.py, openai_client.py, utils.py)
- Utility Services (src/utils: rate_limiter, token_counter, cache, logger)
- Error Handler (src/handlers/error_handler.py)
- Data Storage (data/cache, data/prompts, data/outputs, data/embeddings)
- External LLM APIs (Anthropic Claude, OpenAI GPT)

b. Relationships & Data Flows
1. User (scripts/notebooks) → loads YAML configs
2. User → selects or builds prompt via Prompt Engineering module
3. Prompt Engine → invokes LLM Client (base client + provider plugin)
4. LLM Client → applies utils: rate_limit → token_counter → cache_lookup
- On cache miss, Client → External API → receives response → cache_store
5. Response → passes back up through error_handler wrapping
6. Final output → written to data/outputs and returned to the entry layer
7. Logger records each stage (loading, request/response, errors)

c. Architectural patterns & design principles
- Plugin pattern for LLM providers (base class + concrete subclasses)
- Separation of concerns: prompt templates, client logic, utilities, error handling
- Layered architecture: Entry → Config → Prompt Engine → Client → External
- Caching and rate-limiting as cross-cutting concerns injected via utils

d. Key technologies & libraries
- YAML for configuration (PyYAML or ruamel.yaml)
- HTTP client (requests or httpx) within LLM clients
- JSON for data serialization in data/
- Jupyter for notebooks
- Python logging module configured via logging_config.yaml

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Layer
    subgraph "Entry Layer" 
        direction TB
        EB1["examples/basic_completion.py"]:::entry
        EB2["examples/chain_prompts.py"]:::entry
        EB3["examples/chat_session.py"]:::entry
        NB1["notebooks/model_experimentation.ipynb"]:::entry
        NB2["notebooks/prompt_testing.ipynb"]:::entry
        NB3["notebooks/response_analysis.ipynb"]:::entry
    end

    %% Configuration Loader
    subgraph "Configuration Loader" 
        direction TB
        CFG1["config/logging_config.yaml"]:::config
        CFG2["config/model_config.yaml"]:::config
        CFG3["config/prompt_templates.yaml"]:::config
    end

    %% Core Modules
    subgraph src
        direction TB
        subgraph "Prompt Engineering Module"
            direction TB
            PE1["src/prompt_engineering/chain.py"]:::core
            PE2["src/prompt_engineering/few_shot.py"]:::core
            PE3["src/prompt_engineering/templates.py"]:::core
        end
        subgraph "LLM Client Layer"
            direction TB
            LC1["src/llm/base.py"]:::core
            LC2["src/llm/claude_client.py"]:::core
            LC3["src/llm/openai_client.py"]:::core
            LCU["src/llm/utils.py"]:::core
        end
        subgraph "Utility Services"
            direction TB
            U1["src/utils/cache.py"]:::util
            U2["src/utils/logger.py"]:::util
            U3["src/utils/rate_limiter.py"]:::util
            U4["src/utils/token_counter.py"]:::util
        end
        subgraph "Error Handler"
            direction TB
            EH["src/handlers/error_handler.py"]:::handler
        end
    end

    %% Data Storage
    subgraph "Data Storage"
        direction TB
        DS1["data/cache/"]:::storage
        DS2["data/prompts/"]:::storage
        DS3["data/outputs/"]:::storage
        DS4["data/outputs/embeddings/"]:::storage
    end

    %% External APIs
    subgraph "External LLM APIs"
        direction TB
        EX1["Anthropic Claude"]:::external
        EX2["OpenAI GPT"]:::external
    end

    %% Flows
    EB1 -->|"loads config"| CFG1
    EB2 --> CFG2
    EB3 --> CFG3
    NB1 --> CFG2
    NB2 --> CFG3
    NB3 --> CFG1

    CFG1 --> PE1
    CFG2 --> PE2
    CFG3 --> PE3

    PE1 --> LC1
    PE2 --> LC1
    PE3 --> LC1

    LC1 --> U3
    U3 --> U4
    U4 --> U1
    U1 -->|cache miss| EX1
    U1 -->|cache miss| EX2

    EX1 -->|response| U1
    EX2 -->|response| U1

    U1 --> EH
    EH --> DS3
    EH --> DS4

    %% Logging across stages
    EB1 --> U2
    EB2 --> U2
    EB3 --> U2
    U2 --> DS1
    U2 --> DS2

    %% Click Events
    click EB1 "https://github.com/honestsoul/generative_ai_project/blob/main/examples/basic_completion.py"
    click EB2 "https://github.com/honestsoul/generative_ai_project/blob/main/examples/chain_prompts.py"
    click EB3 "https://github.com/honestsoul/generative_ai_project/blob/main/examples/chat_session.py"
    click NB1 "https://github.com/honestsoul/generative_ai_project/blob/main/notebooks/model_experimentation.ipynb"
    click NB2 "https://github.com/honestsoul/generative_ai_project/blob/main/notebooks/prompt_testing.ipynb"
    click NB3 "https://github.com/honestsoul/generative_ai_project/blob/main/notebooks/response_analysis.ipynb"
    click CFG1 "https://github.com/honestsoul/generative_ai_project/blob/main/config/logging_config.yaml"
    click CFG2 "https://github.com/honestsoul/generative_ai_project/blob/main/config/model_config.yaml"
    click CFG3 "https://github.com/honestsoul/generative_ai_project/blob/main/config/prompt_templates.yaml"
    click PE1 "https://github.com/honestsoul/generative_ai_project/blob/main/src/prompt_engineering/chain.py"
    click PE2 "https://github.com/honestsoul/generative_ai_project/blob/main/src/prompt_engineering/few_shot.py"
    click PE3 "https://github.com/honestsoul/generative_ai_project/blob/main/src/prompt_engineering/templates.py"
    click LC1 "https://github.com/honestsoul/generative_ai_project/blob/main/src/llm/base.py"
    click LC2 "https://github.com/honestsoul/generative_ai_project/blob/main/src/llm/claude_client.py"
    click LC3 "https://github.com/honestsoul/generative_ai_project/blob/main/src/llm/openai_client.py"
    click LCU "https://github.com/honestsoul/generative_ai_project/blob/main/src/llm/utils.py"
    click U1 "https://github.com/honestsoul/generative_ai_project/blob/main/src/utils/cache.py"
    click U2 "https://github.com/honestsoul/generative_ai_project/blob/main/src/utils/logger.py"
    click U3 "https://github.com/honestsoul/generative_ai_project/blob/main/src/utils/rate_limiter.py"
    click U4 "https://github.com/honestsoul/generative_ai_project/blob/main/src/utils/token_counter.py"
    click EH "https://github.com/honestsoul/generative_ai_project/blob/main/src/handlers/error_handler.py"

    classDef core fill:#D0E8FF,stroke:#0066CC,color:#003366,stroke-width:1px;
    classDef util fill:#E6FFDE,stroke:#339900,color:#336600,stroke-width:1px;
    classDef storage fill:#FFE8C4,stroke:#CC6600,color:#663300,stroke-width:1px;
    classDef external fill:#EEEEEE,stroke:#888888,color:#555555,stroke-width:1px,stroke-dasharray: 5 5;
    classDef entry fill:#F0E6FF,stroke:#9933CC,color:#660066,stroke-width:1px;
    classDef config fill:#FFF4B2,stroke:#CCCC00,color:#666600,stroke-width:1px;
    classDef handler fill:#FFD6D6,stroke:#CC0000,color:#660000,stroke-width:1px;
```
