LLM AGENT V2

LLM Agent V2

A modular, CLI-based AI agent built in LangGraph.


Report Bug · Request Feature

Caution

This project is in active development. Expect frequent updates and possible instability.

Always review the commands generated by the AI before executing them, especially file system operations.

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Customization Guide
5. License
6. Acknowledgments

About The Project

This project is a sophisticated, persona-driven AI agent that runs in your terminal. Powered by a robust backend using LangGraph for state management and Gemini for intelligence, it maintains a persistent conversation history via MongoDB. Its modular architecture allows for easy extension of new tools and capabilities, from web searching and scraping to multimodal analysis of images, audio, and video files.

Built With

Getting Started

To get the agent running on your local machine, follow these simple steps.

Prerequisites

You will need the following software and API keys to run this project.

• Python 3.10+
• uv (or any other Python virtual environment and package manager like pip or poetry)

  pip install uv

• API Keys for:
  • Google Gemini
  • MongoDB Atlas (for persistent memory)
  • Tavily AI (for the web search tool)
  • Cloudinary (for multimodal file handling)

Installation

1. Clone the repository:

   git clone https://github.com/aditsuru-git/llm-agent-v2.git
   cd llm-agent-v2

2. Create and activate a virtual environment:

   uv venv
   source .venv/bin/activate

3. Install the required dependencies:

   uv pip install -requirements pyproject.toml

4. Create a .env file in the root of the project by copying the example file:

   cp .env.example .env

5. Edit the .env file and add your API keys and secrets:

   # Google Gemini API
   GOOGLE_API_KEY="your_gemini_api_key"
   
   # MongoDB for persistent memory
   MONGO_URI="your_mongodb_connection_string"
   MONGO_DB_NAME="langgraph_chat_db"
   MONGO_COLLECTION="conversations"
   SESSION_ID="my_personal_chatbot_session"
   
   # Tavily for Web Search Tool
   TAVILY_API_KEY="your_tavily_api_key"
   
   # Cloudinary for multimodal file uploads
   CLOUDINARY_CLOUD_NAME="your_cloudinary_cloud_name"
   CLOUDINARY_API_KEY="your_cloudinary_api_key"
   CLOUDINARY_API_SECRET="your_cloudinary_api_secret"

Usage

Start the chat application from the root directory:

uv run -m src.cli

Features

• 🧠 Persistent Memory: Stores conversations in MongoDB, enabling the agent to recall past interactions and maintain long-term context across sessions.
• 🌐 Web Search & Scraping: Leverages Tavily for autonomous web exploration, combining real-time search with structured webpage scraping to deliver precise, up-to-date answers.
• 🎨 Multimodal Understanding: Processes images, audio, and video via local file paths, unlocking cross-media analysis (with optional manual cleanup through the Cloudinary dashboard).
• ⚡ System Command Execution: Executes safe, non-interactive shell commands with built-in guardrails—always prompting for confirmation before running critical operations.
• 💻 Rich CLI Interface: A sleek, intuitive command-line experience powered by Rich, featuring color-coded outputs, tables, and progress spinners for maximum usability.

Chat Commands

Command	Description
/help	Show the help message with all available commands.
/clear	Clear the entire conversation history from MongoDB.
/exit, /quit	Gracefully exit the assistant.

Customization Guide

Overview

The agent is designed to be highly customizable. You can easily change its appearance, personality, and capabilities by editing a few key files.

UI Customization

Modify src/config.py to change the colors and styles of the entire chat interface. The file is well-commented, allowing you to change theme colors, actor colors (AI/User), and more.

# src/config.py

# --- Core Theme ---
THEME_COLOR_PRIMARY = "cyan"
THEME_COLOR_SECONDARY = "magenta"

# --- Actor Colors ---
AI_COLOR = "#FF5733"
USER_COLOR = "green"

Personality Customization

Edit src/persona.py to completely change the AI's persona. The persona_text string contains detailed instructions on the character's identity, behavior, and core principles. Modify this to create any character you can imagine.

Important: Please adjust only the persona-related context. Altering other settings could disrupt the AI’s functionality.

# src/persona.py

persona_name = "Chizuru"

persona_text = """
[IMMEDIATE DIRECTIVE]
You are Chizuru Ichinose. From this moment on, you will act...

[CORE OPERATING PRINCIPLES]
1.  **Tool Mastery & Confidence**: You have a suite of internal capabilities...
"""

Tool Customization

Adding or removing capabilities is simple and centralized. All tools are managed in the src/tool_registry.py file.

To add a new tool:

1. Create your tool function in a relevant file (e.g., src/tools/misc.py).
2. Import it into src/tool_registry.py.
3. Add the tool function to the all_tools list.

The agent will automatically recognize the new tool and its description, and the LLM will learn to use it when appropriate.

# src/tool_registry.py

# ... other tool imports
from src.tools.misc import my_new_tool

all_tools = [
    web_search,
    scrape_webpage,
    # ... other tools
    my_new_tool, # Add your new tool here
]

License

Distributed under the MIT License. See LICENSE for more information.

Acknowledgments

This project wouldn't be possible without these incredible open-source projects and services.

• Google Gemini
• LangChain & LangGraph
• Rich
• Tavily AI

(back to top)