# semphares/rag_spec_bot architecture

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

- Interactive diagram: https://gitdiagram.com/semphares/rag_spec_bot
- Repository: https://github.com/semphares/rag_spec_bot

## Overview

##### Project type and purpose
- This is a Python-based Retrieval-Augmented Generation (RAG) “spec bot” utility library and CLI application.
- Its goal is to load and split documentation, index it in a vector store, retrieve relevant passages at query time, build prompts via templates, and invoke various LLM back-ends to generate or summarize specifications.

##### File structure
- Top-level files:
- Makefile / requirements.txt – install and run conveniences;
- README.md – minimal usage instructions;
- __init__.py – makes the root a Python package.
- app/specbot/ – core package directory:
- config.py & config.json & .env – hold environment variables and configuration;
- doc_loader/ – loads raw documents, splits them into chunks, utilities for parsing;
- retriever/ – transforms doc chunks (e.g. embeddings via sentence_transformer), custom search logic, vectorstore persistence;
- model_api/ – adapters for different LLM back-ends (Gemini, LlamaCpp, Ollama), common LLM typing;
- prompter/ – prompt construction and templating (contexts, summarization);
- utils/ – logging, helper functions;
- spec_app.py – CLI entrypoint or orchestrator script.

##### README for additional insights
- Basic usage: “make install” and “make run”—no explicit web server or UI, implying a CLI/daemon mode.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI / Orchestrator\n(spec_app.py)"]:::internal
    subgraph "Configuration Layer"
        ENV["Environment Variables\n(.env)"]:::internal
        JSON["JSON Config\n(config.json)"]:::internal
        CFG["Config Loader\n(config.py)"]:::internal
    end
    subgraph "Document Loader"
        LOADER["Loader Entrypoint\n(loader.py)"]:::internal
        SPLIT["Splitting Logic\n(spliter.py)"]:::internal
        LDR_UTIL["Loader Utilities\n(loader_utils.py)"]:::internal
    end
    subgraph "Retriever Layer"
        subgraph "Doc Transformers"
            LLM_TR["LLM Transformer\n(llm_transformer.py)"]:::internal
            SENT_TR["Sentence Transformer\n(sentence_transformer.py)"]:::internal
            OTH_TR["Other Transformers\n(others_transformer.py)"]:::internal
        end
        RETR_LOG["Custom Retriever Logic\n(custom_retriever.py)"]:::internal
        VS[(Vector Store)]:::database
    end
    subgraph "Prompter Layer"
        PROMPT["Prompt Construction\n(prompt.py)"]:::internal
        CONT_TMP["Context Template\n(context.py)"]:::internal
        SUM_TMP["Summarization Template\n(summarize.py)"]:::internal
    end
    subgraph "Model API Layer"
        GEM["Gemini Adapter\n(gemini_model.py)"]:::internal
        LLCPP["LlamaCpp Adapter\n(llamacpp_model.py)"]:::internal
        OLL["Ollama Adapter\n(ollama_model.py)"]:::internal
        LLMTYP["Common LLM Typing\n(llm_typing.py)"]:::internal
    end
    subgraph "Utilities"
        LOG["Logging\n(log.py)"]:::internal
        HELP["Helper Functions\n(usefull.py)"]:::internal
    end
    subgraph "External Services"
        LLM_EXT["LLM Providers\n(Gemini, Ollama, llama.cpp)"]:::external
    end

    CLI -->|reads| CFG
    CLI -->|loads docs| LOADER
    LOADER -->|uses| LDR_UTIL
    LOADER -->|splits| SPLIT
    SPLIT -->|produces chunks| LLM_TR
    SPLIT -->|produces chunks| SENT_TR
    SPLIT -->|produces chunks| OTH_TR
    LLM_TR -->|embeddings| VS
    SENT_TR -->|embeddings| VS
    OTH_TR -->|embeddings| VS
    CLI -->|queries| RETR_LOG
    RETR_LOG -->|searches| VS
    VS -->|returns chunks| RETR_LOG
    RETR_LOG -->|provides chunks| PROMPT
    PROMPT -->|builds prompt| PROMPT
    PROMPT -->|"invoke adapter"| GEM
    PROMPT -->|"invoke adapter"| LLCPP
    PROMPT -->|"invoke adapter"| OLL
    GEM -->|implements| LLMTYP
    LLCPP -->|implements| LLMTYP
    OLL -->|implements| LLMTYP
    GEM -->|requests| LLM_EXT
    LLCPP -->|requests| LLM_EXT
    OLL -->|requests| LLM_EXT
    LLM_EXT -->|response| GEM
    LLM_EXT -->|response| LLCPP
    LLM_EXT -->|response| OLL
    GEM -->|returns output| CLI
    LLCPP -->|returns output| CLI
    OLL -->|returns output| CLI

    CFG -.->|configures| LOADER
    CFG -.->|configures| RETR_LOG
    CFG -.->|configures| PROMPT
    CFG -.->|configures| GEM
    CFG -.->|configures| LLCPP
    CFG -.->|configures| OLL

    LOG -.->|logs| CLI
    LOG -.->|logs| LOADER
    LOG -.->|logs| RETR_LOG
    LOG -.->|logs| PROMPT
    LOG -.->|logs| GEM

    classDef internal fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#c2f0c2,stroke:#333,stroke-width:1px
    classDef database fill:#ffe5b4,stroke:#333,stroke-width:1px

    click CLI "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/spec_app.py"
    click ENV "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/.env"
    click JSON "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/config.json"
    click CFG "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/config.py"
    click LOADER "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/doc_loader/loader.py"
    click SPLIT "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/doc_loader/spliter.py"
    click LDR_UTIL "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/doc_loader/loader_utils.py"
    click RETR_LOG "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/retriever/custom_retriever.py"
    click LLM_TR "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/retriever/doc_transformer/llm_transformer.py"
    click SENT_TR "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/retriever/doc_transformer/sentence_transfomer.py"
    click OTH_TR "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/retriever/doc_transformer/others_transformer.py"
    click VS "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/retriever/vectorstore.py"
    click PROMPT "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/prompter/prompt.py"
    click CONT_TMP "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/prompter/prompt_template/context.py"
    click SUM_TMP "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/prompter/prompt_template/summarize.py"
    click GEM "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/model_api/gemini_model.py"
    click LLCPP "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/model_api/llamacpp_model.py"
    click OLL "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/model_api/ollama_model.py"
    click LLMTYP "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/model_api/llm_typing.py"
    click LOG "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/utils/log.py"
    click HELP "https://github.com/semphares/rag_spec_bot/blob/master/app/specbot/utils/usefull.py"
```
