# fus3n/gem-assist architecture

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

- Interactive diagram: https://gitdiagram.com/fus3n/gem-assist
- Repository: https://github.com/fus3n/gem-assist

## Overview

##### Main Components
- • Entry Point & Configuration: Highlight assistant.py as the primary runtime file and config.py for central configuration (model selection, system prompts, and assistant name).
- • Core Logic Modules: Include the gem module (which contains command definitions and utilities – see files like gem/builtin_commands.py, gem/command.py, gem/utils.py) and the func_to_schema package. These encapsulate the assistant’s command and functionality mapping.
- • Utility Tools: Mark utility.py as the collector of various built-in tools (file system, web, Reddit, system info, etc.) that the assistant leverages.
- • External Integrations: Represent the API integrations for Google Gemini (and, via litellm, additional models), DuckDuckGo, Reddit (praw), and other potential web services.
- • Testing: Separate the tests directory to indicate the presence of unit tests ensuring functionality.

##### Relationships and Interactions
- • The assistant.py script serves as the user interface (CLI) and orchestrates the flow: it reads user input, refers to the configuration in config.py, and delegates tasks to the gem module’s CommandExecutor or other components.
- • Communication exists between modules: the gem package receives user commands, uses functions from utility.py to perform tasks, and communicates with external APIs.
- • Indicate that errors or results flow back to the CLI, closing the loop.

##### Architectural Patterns & Design Principles
- • Modularity: The code is cleanly separated into modules (assistant.py, gem package, utility functions, config) which enables easy extension.
- • Tool-based Architecture: The assistant delegates specific functionalities to discrete tool functions (for file operations, web search, etc.), making the system extensible.
- • Extensibility: New commands or tools can be easily added by following examples in gem/builtin_commands.py and utility.py.
- • Testing Driven: The structure contains a tests directory, indicating unit testing practices have been followed.

##### Technologies & Frameworks
- • Python (3.11+): The language of implementation.
- • External Libraries: Mention libraries like google-genai (for Gemini), ollama, duckduckgo-search, praw, rich, and python-dotenv for environment management.
- • UV: The dependency manager and runner is part of the deployment/execution environment.

##### Elements
- • Optionally, include annotations such as “Extensible via code modifications” near gem/builtin_commands.py and note that the command ecosystem is the heart of the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Components
    A["CLI Interface (assistant.py)"]:::cli
    B["Configuration (config.py)"]:::config
    C["Command & Tool Engine (gem module)"]:::core
    D["Schema Mapping (func_to_schema)"]:::core
    E["Utility Tools (utility.py)"]:::util
    F["External APIs (Google Gemini, DuckDuckGo, Reddit, etc.)"]:::external
    G["Testing Suite (tests/)"]:::testing

    %% Relationships
    A -->|"loads_config"| B
    A -->|"interprets_commands"| C
    C -->|"maps_to_schema"| D
    C -->|"delegates_tasks"| E
    E -->|"calls_services"| F
    F -->|"returns_data"| A
    C -->|"error/feedback"| A
    G -->|"tests_component"| A
    G -->|"tests_component"| C
    G -->|"tests_component"| E

    %% Click Events
    click A "https://github.com/fus3n/gem-assist/blob/master/assistant.py"
    click B "https://github.com/fus3n/gem-assist/blob/master/config.py"
    click C "https://github.com/fus3n/gem-assist/tree/master/gem/"
    click D "https://github.com/fus3n/gem-assist/blob/master/func_to_schema/__init__.py"
    click E "https://github.com/fus3n/gem-assist/blob/master/utility.py"
    click G "https://github.com/fus3n/gem-assist/tree/master/tests/"

    %% Styles
    classDef cli fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef config fill:#d6eaf8,stroke:#2874a6,stroke-width:2px;
    classDef core fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef util fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef external fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef testing fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
```
