# ggeop/python-ai-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/ggeop/python-ai-assistant
- Repository: https://github.com/ggeop/python-ai-assistant

## Overview

##### Project Type and Purpose
- Jarvis is an intelligent voice-commanding assistant built in Python 3.8. Its purpose is to interpret voice (or text) commands, process them using natural language techniques, and execute a wide range of skills (from opening applications to fetching weather data) including integration with external APIs (e.g., OpenWeatherMap, WolframAlpha, IPStack).

##### File Structure for Key Architectural Components
- Top-level files like README.md, run_jarvis.sh, setup.sh, and requirements.txt indicate a standalone application with deployment and testing scripts.
- The “bin” directory contains deployment and test scripts, suggesting a CI/CD integration (as confirmed by the Travis CI configuration and badges in the README).
- The “src” directory houses the main implementation:
- The core of the assistant is within src/jarvis/jarvis/, with subfolders:
- “core”: Contains modules like console.py, nlp.py, and processor.py. This is where command input processing and decision making happen.
- “engines”: Contains stt.py (speech-to-text), tts.py (text-to-speech), and ttt.py. These are responsible for transforming voice inputs and outputs.
- “skills” and “skills/collection”: These modules hold the implementations for the various tasks the assistant can perform (e.g., opening browsers, checking weather, math calculations, etc.). The registry and skill.py modules are used to register and manage these skills.
- “utils”: Contains helper modules (such as console, input handling, mapping, MongoDB interactions, and app startup routines).
- The tests (src/tests) ensure each module behaves as expected.

##### Understanding Architectural Decisions from the README
- The README outlines a decision model for mapping user commands to skills. It shows that the system employs a TF-IDF matrix for extracting the most similar skill, leveraging similarity metrics (e.g., cosine similarity).
- The assistant supports asynchronous command execution, dual user input modes (voice and text), and runtime settings changes.
- There are also external API integrations and UI feedback (either text via console or audio responses).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1("Console (Text Input/Feedback)"):::ui
        UI2("Speech-to-Text (Voice Input)"):::ui
        UI3("Text-to-Speech (Audio Feedback)"):::ui
    end

    %% Core Processing Unit
    subgraph "Core Processing Unit"
        NP("NLP Processor"):::core
        CP("Command Processor"):::core
        DM("Decision Model (TF-IDF&Cosine)"):::core
    end

    %% Skill Management
    subgraph "Skill Management"
        SR("Skills Registry"):::skills
        SEC("Skill Execution Core"):::skills
        SC("Skills Collection"):::skills
    end

    %% External API Integration
    subgraph "External API Integration"
        WS("External API: Weather Skill"):::external
        WA("External API: WolframAlpha Skill"):::external
    end

    %% Utility and Persistence Layer
    subgraph "Utility and Persistence"
        M("MongoDB Interface"):::utility
        U("Utility Modules"):::utility
    end

    %% Data Flow
    UI1 -->|"input"| NP
    UI2 -->|"input"| NP
    NP -->|"process"| CP
    CP -->|"decision"| DM
    DM -->|"match_skill"| SR
    SR -->|"execute_skill"| SEC
    SEC -->|"invoke_tasks"| SC

    %% Output Flow
    SEC -->|"audio_response"| UI3
    SEC -->|"console_response"| UI1

    %% External API Calls
    SEC -->|"call"| WS
    SEC -->|"call"| WA
    WS -->|"response"| SEC
    WA -->|"response"| SEC

    %% Utility Connections
    U ---|"support"| CP
    M ---|"log"| CP

    %% Click Events
    click UI1 "https://github.com/ggeop/python-ai-assistant/blob/develop/src/jarvis/jarvis/core/console.py"
    click UI2 "https://github.com/ggeop/python-ai-assistant/blob/develop/src/jarvis/jarvis/engines/stt.py"
    click UI3 "https://github.com/ggeop/python-ai-assistant/blob/develop/src/jarvis/jarvis/engines/tts.py"
    click NP "https://github.com/ggeop/python-ai-assistant/blob/develop/src/jarvis/jarvis/core/nlp.py"
    click CP "https://github.com/ggeop/python-ai-assistant/blob/develop/src/jarvis/jarvis/core/processor.py"
    click SR "https://github.com/ggeop/python-ai-assistant/blob/develop/src/jarvis/jarvis/skills/registry.py"
    click SEC "https://github.com/ggeop/python-ai-assistant/blob/develop/src/jarvis/jarvis/skills/skill.py"
    click SC "https://github.com/ggeop/python-ai-assistant/tree/develop/src/jarvis/jarvis/skills/collection/"
    click WS "https://github.com/ggeop/python-ai-assistant/blob/develop/src/jarvis/jarvis/skills/collection/weather.py"
    click WA "https://github.com/ggeop/python-ai-assistant/blob/develop/src/jarvis/jarvis/skills/collection/wolframalpha.py"
    click M "https://github.com/ggeop/python-ai-assistant/blob/develop/src/jarvis/jarvis/utils/mongoDB.py"
    click U "https://github.com/ggeop/python-ai-assistant/tree/develop/src/jarvis/jarvis/utils/"

    %% Styles
    classDef ui fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef skills fill:#bfb,stroke:#333,stroke-width:2px;
    classDef external fill:#ffb,stroke:#333,stroke-width:2px;
    classDef utility fill:#fdd,stroke:#333,stroke-width:2px;
```
