---
description:
globs:
alwaysApply: false
---
# Technical Architecture

This project implements an AI-powered database query interface using natural language processing and visualization capabilities.

## Core Components

### AI Agent & Chatbot
- [app.py](mdc:app.py): Implements the Gradio web interface and orchestrates the AI agent
  - Uses LangChain for AI agent orchestration
  - Implements chat history management
  - Handles visualization requests
  - Manages user interactions through Gradio UI

### MCP Server Implementation
- [postgre_mcp_server.py](mdc:postgre_mcp_server.py): Core MCP (Model Context Protocol) server
  - Implements FastMCP for efficient model-context communication
  - Provides database connection management
  - Implements SQL query execution tools
  - Handles data visualization requests
  - Manages database schema information

### LangChain Integration
- [langchain_mcp_client.py](mdc:langchain_mcp_client.py): LangChain-MCP integration layer
  - Connects LangChain agents with MCP tools
  - Manages conversation context
  - Handles tool execution and response formatting
  - Implements memory management for conversations

## Key Technologies

### AI & ML Stack
- LangChain: For AI agent orchestration and tool management
- OpenAI/Gemini: LLM providers for natural language understanding
- PandasAI: For data visualization and analysis

### Web & UI
- Gradio: For building the web interface
- Custom CSS: For UI styling and responsiveness

### Database & Data Processing
- PostgreSQL: Primary database
- Pandas: For data manipulation and analysis
- AsyncPG: For asynchronous database operations

## Architecture Patterns

### Model-Context Protocol (MCP)
- FastMCP implementation for efficient model-context communication
- Tool-based architecture for extensible functionality
- Context-aware request handling
- Resource management and lifecycle control

### AI Agent Architecture
- ReAct pattern implementation
- Tool-based reasoning
- Context-aware memory management
- Natural language to SQL conversion
- Visualization request handling

## Development Guidelines

### Code Organization
- Modular tool implementation
- Clear separation of concerns
- Async-first approach
- Error handling and logging
- Type hints and documentation

### Best Practices
- Read-only database operations
- Secure API key management
- Efficient resource utilization
- Proper error handling
- Comprehensive logging