Database Agent

A sophisticated conversational AI agent for database interactions featuring a modern web GUI, comprehensive logging, configurable system prompts, and AWS Bedrock integration with Claude 3.5 Sonnet.

Overview

Database Agent is an intelligent database assistant that provides safe, monitored interactions through both CLI and web interfaces. Built with enterprise-grade architecture, robust error handling, and powered by AWS Bedrock's Claude 3.5 Sonnet model.

Key Features

• Modern Web GUI: Apple Messages-inspired Streamlit interface with multi-session support
• Database Integration: Seamless connection to databases via Model Context Protocol (MCP)
• AI-Powered: AWS Bedrock Claude 3.5 Sonnet for intelligent responses
• Enterprise Logging: Structured JSONL logging with performance monitoring
• Smart Memory Management: Context window optimization with intelligent trimming
• Configurable Prompts: Multiple system prompt modes (default, debug, read_only)
• Robust Error Handling: Automated recovery strategies and user guidance
• MCP Prompts: Execute predefined templates from MCP servers
• Mock Mode: Full functionality without external dependencies for testing

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Streamlit GUI  │────│  Database Agent  │────│  AWS Bedrock    │
│   (Web UI)      │    │   Application    │    │ Claude 3.5 Sonnet│
└─────────────────┘    └────────┬─────────┘    └─────────────────┘
                                │
┌─────────────────┐    ┌────────▼─────────┐    ┌─────────────────┐
│   CLI Interface │────│  Core Components │────│   MCP Server    │
│                 │    │                  │    │  (Database)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Core Components:

• Application Manager: Orchestrates all components and manages lifecycle
• Agent Manager: Handles AWS Bedrock integration and prompt management
• Memory Manager: Intelligent context window management
• Error Handler: Centralized error handling with recovery strategies
• MCP Manager: Model Context Protocol client with mock support

Getting Started

Prerequisites

• Python 3.13+: Latest Python for optimal performance
• uv package manager: Fast, reliable Python package management
• AWS credentials: For Bedrock access (or use mock mode for testing)
• MCP server: Optional, mock mode available for development

Installation

1. Clone and setup environment:

   git clone <repository-url>
   cd Agent
   uv sync

2. Configure environment variables: Create a .env file in the project root:

   # AWS Bedrock Configuration (required for full functionality)
   aws_access_key_id=your_aws_access_key
   aws_secret_access_key=your_aws_secret_key
   aws_region=us-west-2
   
   # MCP Server Configuration (optional)
   MCP_HOST=localhost
   MCP_PORT=8001
   MCP_PATH=/mcp
   
   # Application Configuration (optional)
   AGENT_PROMPT_MODE=default  # Options: default, debug, read_only
   MCP_MOCK=false  # Set to "true" for testing mode

3. Launch the application:

   # Modern web GUI (recommended)
   python run_gui.py
   
   # CLI interface
   python main.py
   
   # Mock mode for testing (no AWS/MCP required)
   MCP_MOCK=true python main.py

Quick Start Examples

Web GUI Experience:

1. Run python run_gui.py
2. Open http://localhost:8501
3. Start chatting with the database agent
4. Use sidebar for quick actions (Tools, Prompts, Memory)

CLI Examples:

# Start the CLI agent
python main.py

# Basic database interaction
You: what databases do I have
Assistant: [Lists available databases using MCP tools]

# System management
You: /memory
Assistant: [Shows memory usage and statistics]

You: /sysmodes
Assistant: [Lists available prompt modes]

# MCP prompt execution
You: /prompts
Assistant: [Shows available MCP prompts]

You: /prompt analyze_data {"table": "users"}
Assistant: [Executes analysis and returns insights]

You: /quit

Project Structure

Agent/
├── main.py                    # CLI entry point
├── streamlit_app.py          # Modern web GUI application
├── run_gui.py               # GUI launcher with optimized settings
├── src/                       # Source code directory
│   ├── main.py               # Application orchestration
│   ├── command_handlers.py   # CLI command processing
│   ├── core/                 # Core business logic
│   │   ├── application.py    # Main application coordinator
│   │   ├── agent_manager.py  # Agent initialization & management
│   │   ├── mcp_manager.py    # MCP client setup
│   │   ├── mock_mcp.py       # Mock MCP for testing
│   │   ├── memory_manager.py # Memory & context management
│   │   ├── error_handler.py  # Error handling & recovery
│   │   └── chat_manager.py   # Chat loop & user interaction
│   ├── integrations/         # External service integrations
│   │   └── aws_bedrock.py    # AWS Bedrock integration
│   └── config/               # Configuration modules
│       ├── logging_config.py # JSONL logging configuration
│       ├── prompts.yaml      # System prompt configurations
│       └── prompt_manager.py # Prompt management
├── logs/                     # Auto-generated log files
├── pyproject.toml           # Project configuration
└── README.md               # This file

Modern Web Interface

Interface Features

Apple Messages-Inspired Design:

• Blue user messages, gray assistant responses
• Smooth animations and professional gradients
• Mobile-responsive with optimized typography
• Intuitive navigation and accessibility features

Multi-Session Management:

• Create unlimited chat sessions
• Automatic title generation from first message
• Persistent conversation history
• Easy session switching

Advanced Functionality:

• Real-time Processing: Live feedback and status indicators
• Command Integration: Execute any CLI command through the GUI
• Smart Caching: Reduced server requests for better performance
• Form-based Prompts: JSON parameter input for complex MCP prompts

Web Interface Access

# Recommended: Optimized settings
python run_gui.py

# Direct access
streamlit run streamlit_app.py

# Then open: http://localhost:8501

System Prompt Management

Available Modes

• default: Standard database assistant with comprehensive safety guidelines
• debug: Enhanced debugging with detailed explanations and performance insights
• read_only: Strictly read-only operations, prevents any data modifications

Prompt Commands

/sysinfo          # Show current prompt configuration and preview
/sysmodes         # List all available prompt modes  
/sysmode debug    # Switch to debug mode dynamically

Custom Prompt Development

Edit src/config/prompts.yaml to customize behavior:

system_prompt:
  custom_mode: |
    You are a specialized assistant for {specific_domain}...
    
templates:
  data_analyst: |
    Focus on data analysis for {domain} with insights...
  troubleshooter: |
    Specialized database troubleshooting assistant...

Enterprise-Grade Logging

Logging Features

• Structured JSONL: All events captured in analyzable format
• Daily Rotation: 10MB files with 5 backup copies
• Performance Monitoring: Request timing and memory usage
• Security Logging: User input tracking and error classification

Log Analysis Examples

# Real-time monitoring
tail -f logs/agent_$(date +%Y%m%d).jsonl

# User interaction analysis
grep '"user_input"' logs/agent_*.jsonl | head -10

# Error tracking
grep '"level":"ERROR"' logs/agent_*.jsonl

# Tool usage statistics
grep '"tool_name"' logs/agent_*.jsonl | jq .tool_name | sort | uniq -c

Log Structure

{
  "timestamp": "2024-01-15T10:30:45.123456",
  "level": "INFO",
  "logger": "src.core.agent_manager", 
  "message": "Agent initialized successfully",
  "module": "agent_manager",
  "function": "initialize_agent",
  "line": 61,
  "user_input": "what databases do I have",
  "tool_name": "database_list"
}

Testing & Development

Mock Mode

Perfect for development without external dependencies:

# Enable mock mode
export MCP_MOCK=true
python main.py

# Or with GUI
MCP_MOCK=true python run_gui.py

Mock Features:

• Simulated MCP server with sample prompts
• No AWS or external server requirements
• Full application functionality for testing

Memory Management

Automatic Features:

• Context window overflow prevention
• Smart message trimming (keeps recent context)
• Real-time memory usage monitoring
• Automatic cleanup on overflow detection

Manual Control:

/memory    # View detailed memory status
/clear     # Clear conversation memory

MCP Integration

Prompt Execution

# List available prompts
/prompts

# Execute with JSON parameters
/prompt analyze_table {"table": "users", "sample_size": 100}

# Execute with simple text
/prompt generate_report Q4 sales analysis

# List available tools
/tools

MCP Benefits

• Reusable Templates: Curated, tested prompts for common tasks
• Parameter Support: Flexible argument passing (JSON or text)
• Server-side Logic: Leverage domain-specific processing
• Consistent Results: Standardized output formats

Error Handling & Recovery

Automated Recovery

• Context Overflow: Automatic memory clearing with user notification
• AWS Authentication: Clear credential troubleshooting guidance
• MCP Connection: Network connectivity diagnostics
• Graceful Degradation: Continue operation with reduced functionality

Error Classification

• Critical Errors: Application-level issues with restart recommendations
• User Errors: Input validation with helpful suggestions
• System Errors: Infrastructure issues with resolution steps
• Recovery Actions: Automated fixes where possible

Configuration

Environment Variables

# AWS Bedrock (required for full functionality)
aws_access_key_id=your_key
aws_secret_access_key=your_secret  
aws_region=us-west-2

# MCP Server (optional, has defaults)
MCP_HOST=localhost
MCP_PORT=8001
MCP_PATH=/mcp

# Application Behavior (optional)
AGENT_PROMPT_MODE=default  # default, debug, read_only
MCP_MOCK=false              # true for testing mode

GUI Customization

Edit src/config/prompts.yaml:

gui:
  agent:
    name: "Your Agent Name"
    subtitle: "Your Custom Subtitle"
  theme:
    default_mode: "light"  # light, dark
  chat:
    max_display_messages: 100
    show_timestamps: false
  memory:
    show_usage_warning: true
    auto_clear_threshold: 0.9

Advanced Features

• Multi-session Support: Unlimited concurrent conversations
• Smart Caching: Optimized performance for repeated commands
• Mobile Responsive: Works seamlessly on all device sizes
• Accessibility: WCAG-compliant interface design
• Real-time Updates: Live memory and status monitoring
• Export Functionality: Save conversations and logs
• Custom Themes: Light/dark mode with smooth transitions

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone and setup
git clone <repo-url>
cd Agent
uv sync

# Run in mock mode for development
MCP_MOCK=true python main.py

# Run GUI in development mode
MCP_MOCK=true python run_gui.py

License

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

Support & Troubleshooting

Common Issues

1. AWS Authentication Errors: Check credentials in .env file
2. MCP Connection Issues: Verify server is running or use mock mode
3. Memory Overflow: Use /clear or enable auto-management
4. GUI Not Loading: Ensure Streamlit is installed (uv sync)

Getting Help

1. Check Logs: Review logs/agent_*.jsonl for detailed information
2. Console Output: Monitor console for warnings and errors
3. Mock Mode: Test functionality without external dependencies
4. Documentation: Review CLAUDE.md for detailed configuration

Debug Commands

/sysinfo    # System configuration and prompt preview
/memory     # Detailed memory usage statistics
/tools      # Available MCP tools and capabilities
/help       # Complete command reference

---

Built with Python, AWS Bedrock, Streamlit, and the Model Context Protocol