🤖 LangGraph ChatAgent

An advanced, state-of-the-art conversational agent built using LangGraph and LangChain. This project implements a robust LLM-driven graph orchestrator with multi-provider support, custom tool execution, stateful task planning, automated per-turn tool usage limits, human-in-the-loop safety gating, SQLite-backed conversation state persistence, desktop media/screenshot automation, and a Slack bridge adapter.

---

📐 Architecture Overview

The agent is designed as an iterative state machine orchestrated by LangGraph. It runs in a loop between an LLM agent ("judge") and an execution module ("tools") until the LLM decides to respond directly to the user or a terminal state is reached. After tools execute, an intermediate node updates the active task plan checklist before looping back to the judge.

graph TD
    START([Start]) --> JudgeNode[Judge Node<br/>generate_response_or_tool]
    JudgeNode --> ConditionalRoute{Has Tool Calls?}
    
    ConditionalRoute -- Yes --> ToolsNode[Tools Node<br/>ToolNode with wrap_tool_call]
    ConditionalRoute -- No --> END([End])
    
    ToolsNode --> LimitInterceptor{Retry / Usage Limit Exceeded?}
    LimitInterceptor -- Yes --> HumanApproval{Human-in-the-loop Interrupt}
    LimitInterceptor -- No --> ExecTool[Execute Tool]
    
    HumanApproval -- Approved --> ExecTool
    HumanApproval -- Denied --> ErrorMsg[Return Blocked Error Message]
    
    ExecTool --> PlanNode[Plan State Node<br/>update_plan_state]
    ErrorMsg --> PlanNode
    PlanNode --> JudgeNode

Loading

---

✨ Features

• 🔌 Dual LLM Engine: Supports both Google Gemini (via langchain-google-genai) and OpenRouter (via REST API and models like DeepSeek, Nemotron, etc.) with automated fallback options.
• 💾 Persistent State Checkpointing: Uses SQLite to store chat history and conversation graphs across session restarts.
• 📋 Stateful Task Planning: Features built-in task planning tools (create_task_plan, update_task_plan) that maintain an active checklist in the graph state for complex, multi-step execution.
• 🛡️ Safe Tool Execution Gating: Intercepts tool execution to limit the number of times expensive or sensitive tools can run in a single turn.
• 👤 Human-in-the-loop (HITL): Uses LangGraph interrupts to pause execution and prompt the user for confirmation when a tool's retry limit is exceeded.
• 🖥️ Desktop & Media Automation: Includes tools for taking full-screen screenshots and controlling computer media playback (play/pause, volume, track selection).
• 💬 Slack Bridge Adapter: An integrated adapter that converts Markdown to Slack mrkdwn formatting and runs the LangGraph agent over Socket Mode for real-time Slack chat.
• ⚡ Prompt Injection Mitigation & Context Trimming: Automatically sanitizes user inputs, limits character length, and smartly trims message history at human/system boundaries to keep LLM payloads bounded.

---

🛠️ Available Tools

The agent is equipped with several custom tools for interacting with the system, managing tasks, and querying external APIs:

Tool Category	Tool Name	Description
Search & API	internet_search	Search the web using Tavily Search API.
	get_weather	Retrieve current weather conditions for a specified location.
Task Planning	create_task_plan	Create an initial TODO checklist for complex, multi-step tasks.
	update_task_plan	Update the active task checklist by marking steps completed or adding new ones.
System & Media	calculator	Evaluate complex mathematical expressions safely.
	get_battery_status	Retrieve system battery level and charging status.
	execute_shell_command	Execute shell commands safely with a per-turn execution limit.
	take_screenshot	Capture a full-screen screenshot and share it directly in chat.
	control_media	Control system media playback (playpause, nexttrack, prevtrack, volume*).
File System	fs_list_directory	List contents of local directories.
	fs_search_files	Search for files matching specific glob patterns.
	fs_get_file_info	Read metadata (size, permissions) of files.
	fs_read_file	Read the content of text files safely.

---

🚀 Getting Started

📋 Prerequisites

• Python 3.10 or higher
• Git

🔧 Installation & Setup

1. Clone the Repository:

   git clone <repository-url>
   cd ChatAgent

2. Initialize Environment Variables & User Profile: Copy .env.example to .env and fill in your API credentials:

   cp .env.example .env

   Copy the user profile template and customize your preferences:

   cp prompt/USER.md.example prompt/USER.md

3. Install Dependencies: Create a virtual environment and install the required libraries:

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # macOS/Linux:
   source .venv/bin/activate
   
   pip install -r requirements.txt

   (Note: Ensure you have langchain, langgraph, slack_bolt, Pillow, pyautogui, and related provider packages installed)

🎮 Running the Agent

💻 Interactive CLI Chat

To run the interactive console chat application directly, execute:

python main.py

⚡ Running the Slack Bridge Bot

To spin up the Slack bot adapter running in socket mode:

python slack_bridge_script.py

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.