# benjichat/langgraph-home-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/benjichat/langgraph-home-assistant
- Repository: https://github.com/benjichat/langgraph-home-assistant

## Overview

##### Project Type and Purpose
- Project Type: This is a multi-agent home assistant application.
- Purpose: It automates household planning tasks through a natural language interface and integrates with various external services such as Notion, Google Calendar, Google Sheets, and Gmail. The core idea is that a “supervisor” agent receives user queries and routes them to dedicated sub-agents (e.g., calendar, notion, email, meal planner, contact).

##### File Structure
- Top-Level Files: You have configuration files (.env.example, app_config.yaml, config.py), a main entry point (main.py), and a README.md.
- Directories:
- agents: Contains the definition of at least the supervisor agent.
- tools: Holds code for various agent-specific functionalities (e.g., calendar, email, meal planning tools).
- utils: Provides shared utilities like Google authentication and a React agent factory.
- helper_scripts: Contains scripts to check or get tokens and manage Google credentials.
- google_credentials: Contains example credential files.
- Observations: The structure clearly divides responsibilities across agents, tools, and utilities. This modularity is essential for a multi-agent architecture using LangGraph.

##### README for Architectural Details
- The README outlines external services integration (Notion and Google APIs) and explains that the supervisor agent manages routing.
- It also explains how to add new tools and agents, emphasizing extensibility.

a. Main Components:
- User Interface: Although not tightly coupled in the repository (the interface might be Telegram, web, or voice assistants), include a placeholder for “User Input” (e.g., Telegram).
- Supervisor Agent: Central component that receives queries and dispatches tasks.
- Sub-Agents:
- Calendar Agent – interacts with Google Calendar.
- Notion Agent – interacts with Notion.
- Email Agent – handles Gmail.
- Meal Planner Agent – creates meal plans and processes user iterative feedback.
- Contact Agent – interacts with Google Sheets for contact management.
- External Services: Notion API, Google Calendar, Gmail, and Google Sheets.
- Tools & Utilities: Modules in tools/ and utils/ that support agent functionalities (e.g., react_agent_factory, google_auth, etc.).
- Configurations: Represent config files (.env, app_config.yaml) and helper scripts managing credentials.

b. Relationships and Interactions:
- Data Flow: Start with "User Query" entering the system (potentially via a chatbot interface). The Supervisor Agent (shown as a central node) receives the query and, based on logic, routes it to the appropriate sub-agent.
- Each sub-agent interacts with its designated external service (e.g., the Calendar Agent issues commands to Google Calendar) and, in some cases, uses a tool from the tools registry.
- All API interactions are authenticated using tokens and configurations provided via the credentials in google_credentials and configurations in .env.

c. Architectural Patterns:
- Modular Multi-Agent Design: Separation of concerns through individual agents handling specific domains.
- Extensibility: The design allows new agents and tools to be added easily, as indicated in the README.
- Integration with LangGraph: Agents are possibly built using a React Agent pattern defined in utils/react_agent_factory.py, signifying a design based on reactive components and a directed graph of operations.
- Dependency Injection: Through configuration files (app_config.yaml, agents_config.yaml) that manage the agents’ prompts and behavior.

d. Relevant Technologies and Frameworks:
- LangGraph/LangChain: for orchestrating the agents and handling their interactions.
- Python 3.11+: the runtime environment.
- External APIs: Google APIs (Calendar, Sheets, Gmail) and Notion API.
- Additional tools: Scripts for token management and authentication utilities.

##### Elements
- From the user to the supervisor.
- From the supervisor to each sub-agent.
- From sub-agents to external services (e.g., Google, Notion).
- Use consistent labels for each component.
- Optionally, you might add annotations or notes that specify the use of LangGraph and how tools from the tools registry are integrated.

##### Final Details
- Be very detailed but ensure clarity. The goal is to capture all essential architectural elements:
- User Input → Supervisor Agent → (Calendar, Notion, Email, Meal Planner, Contact Agents) → External Services.
- Tools and Utilities aiding the agents’ operations.
- Configuration and authentication mechanisms that secure API interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U["User Input"]:::external

    %% Core Agents and Query Processing
    SUP["Supervisor Agent"]:::internal

    %% Sub-Agents (Agent Tools)
    CAL["Calendar Agent Tools"]:::internal
    NOT["Notion Agent Tools"]:::internal
    EMA["Email Agent Tools"]:::internal
    MPA["Meal Planner Agent Tools"]:::internal
    CON["Contact Agent Tools"]:::internal

    %% External Services
    subgraph "External Services"
        GCAL["Google Calendar"]:::external
        NOTAPI["Notion API"]:::external
        GMAIL["Gmail"]:::external
        GSHEETS["Google Sheets"]:::external
    end

    %% Utilities and Tools Registry
    subgraph "Utilities & Tools"
        TR["Tools Registry"]:::utility
        GAUTH["Google Authentication Utilities"]:::utility
        RAF["React Agent Factory"]:::utility
    end

    %% Configuration and Credential Management
    subgraph "Configurations"
        ENV[".env.example"]:::config
        ACFG["app_config.yaml"]:::config
        CFG["config.py"]:::config
        ACFG["agents_config.py"]:::config
        GCRED1["Google Credentials (Credentials)"]:::config
        GCRED2["Google Credentials (Token)"]:::config
        HGS["Check Gmail Labels"]:::config
        GTOK["Get Token"]:::config
    end

    %% Flow of Query
    U -->|"sends query"| SUP
    SUP -->|"routes to"| CAL
    SUP -->|"routes to"| NOT
    SUP -->|"routes to"| EMA
    SUP -->|"routes to"| MPA
    SUP -->|"routes to"| CON

    %% Sub-Agents invoking External Services
    CAL -->|"calls"| GCAL
    NOT -->|"calls"| NOTAPI
    EMA -->|"calls"| GMAIL
    CON -->|"calls"| GSHEETS

    %% All Sub-Agents use Utilities
    CAL ---|"uses"| TR
    CAL ---|"auth"| GAUTH
    CAL ---|"react"| RAF

    NOT ---|"uses"| TR
    NOT ---|"auth"| GAUTH
    NOT ---|"react"| RAF

    EMA ---|"uses"| TR
    EMA ---|"auth"| GAUTH
    EMA ---|"react"| RAF

    MPA ---|"uses"| TR
    MPA ---|"auth"| GAUTH
    MPA ---|"react"| RAF

    CON ---|"uses"| TR
    CON ---|"auth"| GAUTH
    CON ---|"react"| RAF

    %% Configurations influencing the system
    ENV ---|"config"| SUP
    ACFG ---|"config"| SUP
    CFG ---|"config"| SUP
    ACFG ---|"config"| SUP

    GCRED1 ---|"provides"| GAUTH
    GCRED2 ---|"provides"| GAUTH
    HGS ---|"helper"| GAUTH
    GTOK ---|"helper"| GAUTH

    %% Styles
    classDef internal fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#ffc107,stroke-width:2px,stroke-dasharray: 5 5;
    classDef utility fill:#d4edda,stroke:#28a745,stroke-width:2px;

    %% Click Events for Components
    click SUP "https://github.com/benjichat/langgraph-home-assistant/blob/main/agents/supervisor.py"
    click CAL "https://github.com/benjichat/langgraph-home-assistant/blob/main/tools/calendar_agent_tools.py"
    click NOT "https://github.com/benjichat/langgraph-home-assistant/blob/main/tools/notion_agent_tools.py"
    click EMA "https://github.com/benjichat/langgraph-home-assistant/blob/main/tools/email_agent_tools.py"
    click MPA "https://github.com/benjichat/langgraph-home-assistant/blob/main/tools/meal_planner_agent_tools.py"
    click CON "https://github.com/benjichat/langgraph-home-assistant/blob/main/tools/contact_agent_tools.py"
    click TR "https://github.com/benjichat/langgraph-home-assistant/blob/main/tools/tools_registry.py"
    click GAUTH "https://github.com/benjichat/langgraph-home-assistant/blob/main/utils/google_auth.py"
    click RAF "https://github.com/benjichat/langgraph-home-assistant/blob/main/utils/react_agent_factory.py"
    click ENV "https://github.com/benjichat/langgraph-home-assistant/blob/main/.env.example"
    click ACFG "https://github.com/benjichat/langgraph-home-assistant/blob/main/app_config.yaml"
    click CFG "https://github.com/benjichat/langgraph-home-assistant/blob/main/config.py"
    click ACFG "https://github.com/benjichat/langgraph-home-assistant/blob/main/agents_config.py"
    click GCRED1 "https://github.com/benjichat/langgraph-home-assistant/blob/main/google_credentials/credentials.example.json"
    click GCRED2 "https://github.com/benjichat/langgraph-home-assistant/blob/main/google_credentials/token.example.json"
    click HGS "https://github.com/benjichat/langgraph-home-assistant/blob/main/helper_scripts/check_gmail_labels.py"
    click GTOK "https://github.com/benjichat/langgraph-home-assistant/blob/main/helper_scripts/get_token.py"
```
