# dipamsoni/intellinexus architecture

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

- Interactive diagram: https://gitdiagram.com/dipamsoni/intellinexus
- Repository: https://github.com/dipamsoni/intellinexus

## Overview

##### Project type and purpose
- This is a Python-based, full-stack LLM-driven autonomous agent application.
- It provides both an interactive Streamlit UI (`app.py`) and an optional FastAPI backend (`main_api.py`) to drive a ReAct (Reasoning & Acting) agent that uses locally hosted LLMs (via Ollama) plus custom tools for document Q&A, file reading, and calculations.

##### File structure
- Top-level Python modules correspond to logical layers, not separate folders:
- `app.py` – Streamlit UI layer
- `main_api.py` – FastAPI service layer
- `core_initializer.py` – bootstrapping shared components
- `agent.py` – ReAct agent engine (prompt template, reasoning loop)
- `tools.py` – implementations of `PolicyDocumentQA`, `FileReaderTool`, `CalculatorTool`
- `llm_interface.py` – wrapper for Ollama API calls
- Data artifacts & config:
- `policy.docx` and `report.csv` – domain data sources
- `faiss_policy_index/` (runtime) – persisted vector index storage
- `persistent_chat_history.json` – conversational memory persistence
- Environment & dependency files:
- `requirements.txt`, `.vscode/`, `__pycache__`

##### README for additional insights
- Confirms two execution modes (UI vs API), local model requirements (Ollama, Mistral, nomic-embed-text), and multi-tool ReAct architecture.
- Highlights core design patterns: modular tool abstraction, ReAct prompting, FAISS-based RAG retrieval, centralized initialization.

1. User Interfaces
– Streamlit UI (`app.py`)
– FastAPI Service (`main_api.py`)
2. Core Service Layer
– `core_initializer.py` (initializes Agent + Tools + QA index)
3. Agent Engine
– `agent.py` (ReAct loop)
4. Tool Suite
– `PolicyDocumentQA` (RAG pipeline + FAISS + embeddings)
– `FileReaderTool` (CSV/text reader)
– `CalculatorTool`
5. LLM Interface
– `llm_interface.py` (Ollama HTTP client)
6. External LLM Service
– Ollama Server (models: mistral, nomic-embed-text)
7. Data Stores
– `policy.docx` / `report.csv` (raw files)
– FAISS vector index folder (`faiss_policy_index/`)
– Conversation history JSON (`persistent_chat_history.json`)

– User → Streamlit UI / FastAPI (HTTP/web UI)
– UI/API → Core Initializer → Agent Engine (in-process calls)
– Agent → Tools (method invocations)
– Tools (PolicyDocumentQA) → FAISS index + embeddings LLM → LLM Service
– Tools (CalculatorTool, FileReaderTool) → local code & file system
– Agent → LLM Interface → Ollama Server (LLM calls for thought generation)
– Agent results → UI/API → User
– Agent / UI → Conversation history store (read/write)

c. Architectural patterns & design principles
- ReAct pattern (Thought → Action → Observation loop)
- Modular tool abstraction (each tool encapsulates its own logic)
- RAG pipeline using FAISS + embeddings
- Separation of concerns: UI layer vs core agent logic vs external service
- Single codebase, dual interfaces (UI and REST API) sharing the same core

d. Key technologies & frameworks
- Streamlit (front-end)
- FastAPI + Uvicorn (back-end)
- Python 3.9+
- Ollama (local LLM hosting)
- LangChain, FAISS (RAG retrieval)
- pandas (CSV reading)
- JSON file store for chat memory

##### Final recommendations
- Every essential element, even if thinly described in the code: UI, API, agent loop, tools, LLM calls, data layers.
- Iterate: start broad, then add sub-components (e.g., break “LLM Interface” into HTTP client and model names) as needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User"
        U["User"]:::external
    end

    subgraph "Frontend (UI)"
        UI["Streamlit UI"]:::ui
    end

    subgraph "Backend API"
        API["FastAPI Service"]:::ui
    end

    subgraph "Core Layer"
        CI["Core Initializer"]:::core
        AG["ReAct Agent Engine"]:::core
    end

    subgraph "Agent & Tools"
        AG
        subgraph "Tools Suite"
            TDQA["PolicyDocumentQA Tool"]:::core
            FRT["FileReaderTool"]:::core
            CT["CalculatorTool"]:::core
        end
    end

    subgraph "LLM Integration"
        LI["LLM Interface"]:::core
        OS["Ollama Server"]:::external
    end

    subgraph "Data Stores"
        PD[(policy.docx)]:::datastore
        RC[(report.csv)]:::datastore
        FI[(faiss_policy_index/)]:::datastore
        CH[(persistent_chat_history.json)]:::datastore
    end

    subgraph "Project Artifacts"
        REQ[(requirements.txt)]:::datastore
        MD[(README.md)]:::datastore
    end

    U --> UI
    U --> API
    UI --> CI
    API --> CI
    CI --> AG

    AG --> TDQA
    AG --> FRT
    AG --> CT

    AG --> LI
    LI --> OS

    TDQA --> FI
    TDQA --> LI
    FRT --> RC
    CT --> CT
    
    PD --> TDQA
    RC --> FRT
    FI --> TDQA
    AG --> CH

    click UI "https://github.com/dipamsoni/intellinexus/blob/main/app.py"
    click API "https://github.com/dipamsoni/intellinexus/blob/main/main_api.py"
    click CI "https://github.com/dipamsoni/intellinexus/blob/main/core_initializer.py"
    click AG "https://github.com/dipamsoni/intellinexus/blob/main/agent.py"
    click TDQA "https://github.com/dipamsoni/intellinexus/blob/main/tools.py"
    click FRT "https://github.com/dipamsoni/intellinexus/blob/main/tools.py"
    click CT "https://github.com/dipamsoni/intellinexus/blob/main/tools.py"
    click LI "https://github.com/dipamsoni/intellinexus/blob/main/llm_interface.py"
    click PD "https://github.com/dipamsoni/intellinexus/blob/main/policy.docx"
    click RC "https://github.com/dipamsoni/intellinexus/blob/main/report.csv"
    click REQ "https://github.com/dipamsoni/intellinexus/blob/main/requirements.txt"
    click MD "https://github.com/dipamsoni/intellinexus/blob/main/README.md"

    classDef ui fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef core fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef datastore fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef externalUser fill:#fafafa,stroke:#999,stroke-width:1px
    class U externalUser
```
