# suraj-yadav-aiml/adaptive-rag architecture

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

- Interactive diagram: https://gitdiagram.com/suraj-yadav-aiml/adaptive-rag
- Repository: https://github.com/suraj-yadav-aiml/adaptive-rag

## Overview

##### Main Components
- Application Entry Point (app.py): Represents the launching service that initializes the Streamlit UI.
- UI Module (src/AdaptiveRag/ui): Contains the Streamlit interface components and configuration files (uiconfigfile.ini). This is the primary interaction layer where users configure the system and ask questions.
- Graph Module (src/AdaptiveRag/graph): Implements the LangGraph state machine workflow that orchestrates the processing nodes.
- Nodes Module (src/AdaptiveRag/nodes): Contains the processing logic such as query rewriting, answer generation, retrieving documents, grading, and web search.
- Edge Module (src/AdaptiveRag/edge): Implements “edge” functions that likely manage routing and control logic (e.g., query router, answer grading) to handle dynamic decision-making.
- LLM Module (src/AdaptiveRag/llm): Integrates with external language models (OpenAI, Anthropic, Groq) for generating responses.
- Retriever Module (src/AdaptiveRag/retriever): Handles document retrieval from local vector databases or other data sources.
- State Module (src/AdaptiveRag/state): Manages internal state to keep track of query processes and context flow.
- Tools Module (src/AdaptiveRag/tools): Provides auxiliary functionality, such as handling web search and tool management.

##### Relationships and Interactions
- The UI receives a user query and sends it to the main workflow orchestrated by the Graph module.
- Within the graph, the query is first analyzed by routing logic in the Edge module (specifically query_router_edge).
- Query analysis may decide to use a local vectorstore (via the Retriever module) or invoke a web search (via the Tools module).
- On retrieving the data, processing nodes (like document_grader_node, answer_generator_node, question_rewriter_node) process the results.
- The LLM module is then involved to generate the answer using one of the supported providers.
- The State module tracks the current execution state to manage transitions and retries (e.g., if quality control via hallucination grading fails, trigger additional retrieval/reformulation).
- Finally, processed data and final answers are sent back via the UI layer for display.

##### Architectural Patterns and Design Principles
- Modular design: Each package represents a distinct layer/responsibility (edge functions, nodes, state, LLM integrations).
- Directed graph workflow (using LangGraph) for state management and query processing: Emphasize the flow from query reception through multiple decision points.
- Dynamic query routing: Highlight how queries are rerouted based on complexity and context.
- Quality control (including relevance grading and answer verification): This ensures robustness in output generation.
- Separation of concerns: Each component is responsible for a well-defined part of the pipeline.

##### Technologies and Frameworks
- Python as the primary language.
- Streamlit for the interactive UI.
- Integration with external LLM services (via OpenAI, Anthropic, Groq).
- The LangGraph library for managing the state machine workflow.
- Configuration through INI files (uiconfigfile.ini) and dependency management via requirements.txt.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Application Entry Point (app.py)"]:::entry
    B["Streamlit UI (UI Module)"]:::ui
    C["Graph Module (LangGraph)"]:::orchestration
    D["Edge Module (Query Routing & Grading)"]:::processing
    E["Nodes Module (Processing Nodes)"]:::processing
    F["LLM Module (External LLMs)"]:::external
    G["Retriever Module (Document Retrieval)"]:::external
    H["Tools Module (Web Search & Tools)"]:::external
    I["State Module (Workflow State)"]:::orchestration

    A -->|"start"| B
    B -->|"userQuery"| C
    C -->|"initiateWorkflow"| D
    C -->|"initiateWorkflow"| E
    D -->|"queryRouting"| E
    E -->|"invokeLLM"| F
    E -->|"retrieveDocs"| G
    E -->|"webSearch"| H
    F -->|"generateAnswer"| I
    G -->|"provideDocs"| I
    H -->|"provideSearchResults"| I
    I -->|"finalResult"| B

    click A "https://github.com/suraj-yadav-aiml/adaptive-rag/blob/main/app.py"
    click B "https://github.com/suraj-yadav-aiml/adaptive-rag/tree/main/src/AdaptiveRag/ui"
    click C "https://github.com/suraj-yadav-aiml/adaptive-rag/tree/main/src/AdaptiveRag/graph"
    click D "https://github.com/suraj-yadav-aiml/adaptive-rag/tree/main/src/AdaptiveRag/edge"
    click E "https://github.com/suraj-yadav-aiml/adaptive-rag/tree/main/src/AdaptiveRag/nodes"
    click F "https://github.com/suraj-yadav-aiml/adaptive-rag/tree/main/src/AdaptiveRag/llm"
    click G "https://github.com/suraj-yadav-aiml/adaptive-rag/tree/main/src/AdaptiveRag/retriever"
    click H "https://github.com/suraj-yadav-aiml/adaptive-rag/tree/main/src/AdaptiveRag/tools"
    click I "https://github.com/suraj-yadav-aiml/adaptive-rag/tree/main/src/AdaptiveRag/state"

    classDef entry fill:#f9c74f,stroke:#333,stroke-width:2px
    classDef ui fill:#90be6d,stroke:#333,stroke-width:2px
    classDef orchestration fill:#577590,stroke:#333,stroke-width:2px
    classDef processing fill:#f3722c,stroke:#333,stroke-width:2px
    classDef external fill:#277da1,stroke:#333,stroke-width:2px
```
