# shreyas850/neel-madhav-ai architecture

> Architecture diagram of the GitHub repository shreyas850/neel-madhav-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shreyas850/neel-madhav-ai
- Repository: https://github.com/shreyas850/neel-madhav-ai

## Overview

Neel Madhav AI is a local, voice-activated desktop assistant combining conversational models with command execution and spiritual responses. In the main workflow, the desktop launcher loads speech recognition and the logic brain; recognized speech is routed to system, media, scripture, mantra, or chat handling, and the launcher speaks returned responses. A Flask chat endpoint is an alternate entry point. The README also describes dual model personalities and local GPU inference. Additional automation, Google access, and memory utilities exist, but sampled sources do not show them wired into the main workflow.

Main entry points: [`logic_brain.py`](https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py) (Command Router), [`launcher.py`](https://github.com/shreyas850/neel-madhav-ai/blob/main/launcher.py) (Desktop Launcher), [`voice_core.py`](https://github.com/shreyas850/neel-madhav-ai/blob/main/voice_core.py) (Voice Recognition), [`brain_loader.py`](https://github.com/shreyas850/neel-madhav-ai/blob/main/brain_loader.py) (Local Model Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction"]
  node_desktop["Desktop Launcher<br/>[launcher.py]"]
  node_speech["Voice Recognition<br/>[voice_core.py]"]
  node_chat_api["Chat API<br/>[server.py]"]
  node_speech_output["Speech Output<br/>[logic_brain.py]"]
end

subgraph group_intelligence["Intelligence"]
  node_command_router["Command Router<br/>[logic_brain.py]"]
  node_model_loader["Local Model Runtime<br/>[brain_loader.py]"]
  node_conversational_ai["Conversational AI<br/>[logic_brain.py]"]
  node_local_model(("Local GGUF Model"))
end

subgraph group_capabilities["Assistant Capabilities"]
  node_system_actions["System Commands<br/>[logic_brain.py]"]
  node_desktop_skills["Desktop Skills<br/>[skills.py]"]
  node_media_playback["Media Playback<br/>[logic_brain.py]"]
  node_scripture["Gita Verses<br/>[logic_brain.py]"]
  node_mantras["Mantra Recitation<br/>[logic_brain.py]"]
end

subgraph group_support["Additional Services"]
  node_speech_service(("ElevenLabs TTS"))
  node_youtube(("YouTube"))
  node_scripture_service(("Vedic Scriptures API"))
  node_autonomy["Hardware Monitoring<br/>[autonomy.py]"]
  node_google_agent["Google Calendar and Gmail<br/>[google_agent.py]"]
  node_memory["Conversation Memory<br/>[memory_core.py]"]
  node_memory_store[("JSON Memory File<br/>[memory_core.py]")]
  node_settings[("Settings Store<br/>[db.py]")]
end

node_user(("User"))

node_user -->|"speaks to"| node_desktop
node_desktop -->|"starts listening"| node_speech
node_speech -->|"transcribes and calls"| node_command_router
node_desktop -->|"routes API input"| node_command_router
node_command_router -->|"calls app opener"| node_desktop_skills
node_command_router -->|"routes playback"| node_media_playback
node_media_playback -->|"plays via"| node_youtube
node_command_router -->|"routes verse requests"| node_scripture
node_scripture -->|"requests verses"| node_scripture_service
node_command_router -->|"routes chant requests"| node_mantras
node_command_router -->|"routes other input"| node_conversational_ai
node_conversational_ai -->|"queries model"| node_model_loader
node_model_loader -->|"loads and runs"| node_local_model
node_command_router -->|"returns response"| node_desktop
node_desktop -->|"speaks response"| node_speech_output
node_speech_output -.->|"uses when configured"| node_speech_service
node_autonomy -->|"speaks alerts"| node_user
node_memory -->|"reads and writes"| node_memory_store

click node_desktop "https://github.com/shreyas850/neel-madhav-ai/blob/main/launcher.py"
click node_speech "https://github.com/shreyas850/neel-madhav-ai/blob/main/voice_core.py"
click node_chat_api "https://github.com/shreyas850/neel-madhav-ai/blob/main/server.py"
click node_command_router "https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py"
click node_model_loader "https://github.com/shreyas850/neel-madhav-ai/blob/main/brain_loader.py"
click node_conversational_ai "https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py"
click node_system_actions "https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py"
click node_desktop_skills "https://github.com/shreyas850/neel-madhav-ai/blob/main/skills.py"
click node_media_playback "https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py"
click node_scripture "https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py"
click node_mantras "https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py"
click node_speech_output "https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py"
click node_autonomy "https://github.com/shreyas850/neel-madhav-ai/blob/main/autonomy.py"
click node_google_agent "https://github.com/shreyas850/neel-madhav-ai/blob/main/google_agent.py"
click node_memory "https://github.com/shreyas850/neel-madhav-ai/blob/main/memory_core.py"
click node_memory_store "https://github.com/shreyas850/neel-madhav-ai/blob/main/memory_core.py"
click node_settings "https://github.com/shreyas850/neel-madhav-ai/blob/main/db.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_speech,node_chat_api,node_speech_output,node_user toneBlue
class node_command_router,node_model_loader,node_conversational_ai,node_local_model toneAmber
class node_system_actions,node_desktop_skills,node_media_playback,node_scripture,node_mantras toneMint
class node_speech_service,node_youtube,node_scripture_service,node_autonomy,node_google_agent,node_memory,node_memory_store,node_settings toneRose
```

## Components

### Interaction

- [Desktop Launcher](https://github.com/shreyas850/neel-madhav-ai/blob/main/launcher.py): `launcher.py`
- [Voice Recognition](https://github.com/shreyas850/neel-madhav-ai/blob/main/voice_core.py): `voice_core.py`
- [Chat API](https://github.com/shreyas850/neel-madhav-ai/blob/main/server.py): `server.py`
- [Speech Output](https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py): `logic_brain.py`

### Intelligence

- [Command Router](https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py): `logic_brain.py`
- [Local Model Runtime](https://github.com/shreyas850/neel-madhav-ai/blob/main/brain_loader.py): `brain_loader.py`
- [Conversational AI](https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py): `logic_brain.py`
- **Local GGUF Model**

### Assistant Capabilities

- [System Commands](https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py): `logic_brain.py`
- [Desktop Skills](https://github.com/shreyas850/neel-madhav-ai/blob/main/skills.py): `skills.py`
- [Media Playback](https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py): `logic_brain.py`
- [Gita Verses](https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py): `logic_brain.py`
- [Mantra Recitation](https://github.com/shreyas850/neel-madhav-ai/blob/main/logic_brain.py): `logic_brain.py`

### Additional Services

- **ElevenLabs TTS**
- **YouTube**
- **Vedic Scriptures API**
- [Hardware Monitoring](https://github.com/shreyas850/neel-madhav-ai/blob/main/autonomy.py): `autonomy.py`
- [Google Calendar and Gmail](https://github.com/shreyas850/neel-madhav-ai/blob/main/google_agent.py): `google_agent.py`
- [Conversation Memory](https://github.com/shreyas850/neel-madhav-ai/blob/main/memory_core.py): `memory_core.py`
- [JSON Memory File](https://github.com/shreyas850/neel-madhav-ai/blob/main/memory_core.py): `memory_core.py`
- [Settings Store](https://github.com/shreyas850/neel-madhav-ai/blob/main/db.py): `db.py`

### Other components

- **User**

## Connections

- User → Desktop Launcher: speaks to (evidence: `README.md`)
- Desktop Launcher → Voice Recognition: starts listening (evidence: `launcher.py`)
- Voice Recognition → Command Router: transcribes and calls (evidence: `launcher.py`)
- Desktop Launcher → Command Router: routes API input (evidence: `launcher.py`)
- Command Router → Desktop Skills: calls app opener (evidence: `logic_brain.py`)
- Command Router → Media Playback: routes playback (evidence: `logic_brain.py`)
- Media Playback → YouTube: plays via (evidence: `logic_brain.py`)
- Command Router → Gita Verses: routes verse requests (evidence: `logic_brain.py`)
- Gita Verses → Vedic Scriptures API: requests verses (evidence: `logic_brain.py`)
- Command Router → Mantra Recitation: routes chant requests (evidence: `logic_brain.py`)
- Command Router → Conversational AI: routes other input (evidence: `logic_brain.py`)
- Conversational AI → Local Model Runtime: queries model (evidence: `logic_brain.py`)
- Local Model Runtime → Local GGUF Model: loads and runs (evidence: `brain_loader.py`)
- Command Router → Desktop Launcher: returns response (evidence: `launcher.py`)
- Desktop Launcher → Speech Output: speaks response (evidence: `launcher.py`)
- Speech Output → ElevenLabs TTS: uses when configured (evidence: `logic_brain.py`)
- Hardware Monitoring → User: speaks alerts (evidence: `autonomy.py`)
- Conversation Memory → JSON Memory File: reads and writes (evidence: `memory_core.py`)
