{"id":30618317,"url":"https://github.com/baha2rm98/db-ai-agent","last_synced_at":"2026-05-03T21:31:24.233Z","repository":{"id":309287097,"uuid":"1030339394","full_name":"Baha2rM98/DB-AI-Agent","owner":"Baha2rM98","description":"An AI-powered natural language interface for database operations","archived":false,"fork":false,"pushed_at":"2025-08-19T13:14:09.000Z","size":93,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-19T13:40:49.405Z","etag":null,"topics":["fastapi","langchain","langraph","llmops","postresql","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Baha2rM98.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-01T13:23:18.000Z","updated_at":"2025-08-19T12:23:26.000Z","dependencies_parsed_at":"2025-08-19T13:40:52.026Z","dependency_job_id":"ec79f312-dcc2-4dd4-8d7f-e83656482a55","html_url":"https://github.com/Baha2rM98/DB-AI-Agent","commit_stats":null,"previous_names":["baha2rm98/ai_engineering_assignment","baha2rm98/db-ai-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Baha2rM98/DB-AI-Agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baha2rM98%2FDB-AI-Agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baha2rM98%2FDB-AI-Agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baha2rM98%2FDB-AI-Agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baha2rM98%2FDB-AI-Agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Baha2rM98","download_url":"https://codeload.github.com/Baha2rM98/DB-AI-Agent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Baha2rM98%2FDB-AI-Agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272845838,"owners_count":25002915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","langchain","langraph","llmops","postresql","python"],"created_at":"2025-08-30T11:35:54.654Z","updated_at":"2026-04-13T18:01:45.411Z","avatar_url":"https://github.com/Baha2rM98.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LangGraph Database Agent\n*An AI-powered natural language interface for database operations*\n\n[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/Baha2rM98/AI_Engineering_Assignment/actions)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)](https://fastapi.tiangolo.com/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-15+-blue.svg)](https://www.postgresql.org/)\n[![LangGraph](https://img.shields.io/badge/LangGraph-Latest-orange.svg)](https://langchain-ai.github.io/langgraph/)\n\n## 📋 Table of Contents\n- [Overview](#overview)\n- [Key Features](#key-features)\n- [Architecture](#architecture)\n- [Technology Stack](#technology-stack)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [API Documentation](#api-documentation)\n- [Database Schema](#database-schema)\n- [Development](#development)\n- [Deployment](#deployment)\n- [Contributing](#contributing)\n\n## 🎯 Overview\n\nThe LangGraph Database Agent is a sophisticated AI-powered system that enables natural language interactions with PostgreSQL databases. Built using the LangGraph framework and Google's Gemini model, it transforms conversational queries into precise SQL operations while maintaining context across sessions.\n\n**What makes this special:**\n- 🧠 **Conversational Memory**: Remembers context within sessions\n- 🔄 **Multi-step Reasoning**: Uses LangGraph's state-driven workflow\n- 🎯 **Context Resolution**: Understands references like \"that table\" or \"show me more\"\n- 🛡️ **Error Recovery**: Intelligent fallback mechanisms\n- 📊 **Real-time Processing**: Immediate query execution and results\n\n## ✨ Key Features\n\n### 🤖 AI Agent Capabilities\n- **Natural Language Processing**: Convert human language to SQL\n- **Context Awareness**: Maintains conversation history and references\n- **Multi-table Operations**: Handles complex joins and relationships\n- **Error Handling**: Graceful handling of ambiguous or impossible requests\n\n### 🔧 Technical Features\n- **Session Management**: Isolated conversation contexts per user\n- **Schema Introspection**: Automatic database structure discovery\n- **Query Optimization**: Intelligent SQL generation with proper indexing\n- **Memory Management**: Configurable conversation history limits\n- **API Security**: Request validation and error handling\n\n### 🏗️ Infrastructure\n- **Containerized Deployment**: Docker-ready with CI/CD pipeline\n- **Scalable Architecture**: Modular design for easy extension\n- **Health Monitoring**: Built-in health checks and logging\n- **Environment Management**: Flexible configuration system\n\n## 🏛️ Architecture\n\n[//]: # ()\n[//]: # (The system follows a multi-stage LangGraph workflow:)\n\n[//]: # ()\n[//]: # (```mermaid)\n\n[//]: # (graph TD)\n\n[//]: # (    A[Natural Language Query] --\u003e B[Query Understanding])\n\n[//]: # (    B --\u003e C[Execution Planning])\n\n[//]: # (    C --\u003e D[SQL Generation])\n\n[//]: # (    D --\u003e E[Database Execution])\n\n[//]: # (    E --\u003e F[Response Formulation])\n\n[//]: # (    F --\u003e G[Natural Language Response])\n\n[//]: # (    )\n[//]: # (    H[Session Memory] --\u003e B)\n\n[//]: # (    H --\u003e C)\n\n[//]: # (    H --\u003e F)\n\n[//]: # (    )\n[//]: # (    I[Error Handler] --\u003e B)\n\n[//]: # (    I --\u003e C)\n\n[//]: # (    I --\u003e D)\n\n[//]: # (    I --\u003e E)\n\n[//]: # (```)\n\n### Core Components\n\n1. **LangGraph Agent** (`app/agent/langraph_agent.py`)\n   - Multi-node workflow processing\n   - State management between nodes\n   - Error handling and recovery\n\n2. **DB Agent Connector** (`app/agent/db_agent_connector.py`)\n   - Session management and memory\n   - Context resolution and reference handling\n   - SQL generation and execution coordination\n\n3. **Database Connector** (`app/database/db_connector.py`)\n   - Low-level database operations\n   - Schema introspection and caching\n   - Connection pooling and error handling\n\n4. **API Layer** (`app/api/routes.py`)\n   - RESTful endpoints\n   - Request/response validation\n   - Session routing and management\n\n## 🛠️ Technology Stack\n\n### AI \u0026 Language Models\n- **LangGraph**: State-driven AI agent framework\n- **Google Gemini 1.5 Pro**: Advanced language model for query understanding\n- **LangChain**: LLM integration and prompt management\n\n### Backend \u0026 Database\n- **FastAPI**: Modern, high-performance Python web framework\n- **PostgreSQL**: Primary database (tested with Sakila sample database)\n- **SQLAlchemy**: Database ORM and query building\n- **Pydantic**: Data validation and serialization\n\n### DevOps \u0026 Deployment\n- **Docker**: Containerization and deployment\n- **GitHub Actions**: CI/CD pipeline automation\n- **pytest**: Testing framework\n- **uvicorn**: ASGI server for production\n\n## 🚀 Installation\n\n### Prerequisites\n- Python 3.11+\n- PostgreSQL 15+\n- Google API Key (for Gemini access)\n- Docker (optional, for containerized deployment)\n\n### Local Development Setup\n\n1. **Clone the repository**\n```bash\ngit clone https://github.com/Baha2rM98/AI_Engineering_Assignment.git\ncd AI_Engineering_Assignment\n```\n\n2. **Create virtual environment**\n```bash\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n```\n\n3. **Install dependencies**\n```bash\npip install -r requirements.txt\n```\n\n4. **Set up environment variables**\n```bash\ncp .env.example .env\n# Edit .env with your configuration\n```\n\n5. **Initialize database**\n```bash\n# Set up PostgreSQL with Sakila sample database\n```\n\n6. **Run the application**\n```bash\npython app/main.py\n```\n\n### Docker Deployment\n\n```bash\n# Build and run with Docker Compose\ndocker-compose up --build\n\n# Or use the provided Dockerfile\ndocker build -f docker/Dockerfile -t langraph-db-agent .\ndocker run -p 8000:8000 --env-file .env langraph-db-agent\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n```bash\n# Database Configuration\nDB_HOST=localhost\nDB_PORT=5432\nDB_USER=your_db_user\nDB_PASSWORD=your_db_password\nDB_NAME=sakila\n\n# AI Model Configuration\nGOOGLE_API_KEY=your_gemini_api_key\n\n# Application Settings\nPORT=8000\nLOG_LEVEL=INFO\n\n# Session Management\nMAX_SESSIONS=100\nSESSION_TIMEOUT=60\nMAX_HISTORY_PER_SESSION=10\n```\n\n### Application Settings\n\nThe system supports various configuration options:\n- Session timeout and cleanup intervals\n- Maximum conversation history per session\n- Database connection pooling settings\n- Logging levels and output formats\n\n## 📖 Usage\n\n### Basic Natural Language Queries\n\n```python\n# Example queries the system can handle:\n\n# Data retrieval\n\"Show me all actors\"\n\"Find films with rating PG-13\"\n\"How many customers are there?\"\n\n# Contextual follow-ups\n\"Show me the first 5\"\n\"How many are there?\"\n\"What about that table?\"\n\n# Complex operations\n\"Find all films by actors named John\"\n\"Show customer payment history\"\n\"List top-grossing film categories\"\n```\n\n### API Usage\n\n```python\nimport requests\n\n# Basic query\nresponse = requests.post(\"http://localhost:8000/query\", json={\n    \"query\": \"Show me all actors named John\",\n    \"session_id\": \"user123\"\n})\n\n# Follow-up query in same session\nresponse = requests.post(\"http://localhost:8000/query\", json={\n    \"query\": \"How many are there?\",\n    \"session_id\": \"user123\"  # Same session maintains context\n})\n```\n\n### Session Management\n\n```python\n# Get session information\nresponse = requests.get(\"http://localhost:8000/sessions/user123\")\n\n# Clear session history\nresponse = requests.delete(\"http://localhost:8000/sessions/user123\")\n\n# List active sessions\nresponse = requests.get(\"http://localhost:8000/sessions\")\n```\n\n## 📚 API Documentation\n\n### Core Endpoints\n\n#### `POST /query`\nExecute a natural language database query.\n\n**Request:**\n```json\n{\n    \"query\": \"Show me all films with rating R\",\n    \"session_id\": \"optional-session-id\"\n}\n```\n\n**Response:**\n```json\n{\n    \"success\": true,\n    \"message\": \"I found 195 records in film that match your query.\",\n    \"data\": [\n        {\n            \"film_id\": 1,\n            \"title\": \"Academy Dinosaur\",\n            \"rating\": \"PG\"\n        },\n       {\n          etc...\n       },\n    ],\n    \"affected_rows\": 195,\n    \"session_id\": \"user123\"\n}\n```\n\n#### `GET /health`\nCheck system health and database connectivity.\n\n**Response:**\n```json\n{\n    \"status\": \"connected\",\n    \"database_connection\": \"ok\",\n    \"active_sessions\": 5\n}\n```\n\n#### `GET /sessions/{session_id}`\nGet detailed session information.\n\n**Response:**\n```json\n{\n    \"session_id\": \"user123\",\n    \"created_at\": \"2024-01-15T10:30:00\",\n    \"last_activity\": \"2024-01-15T11:45:00\",\n    \"query_count\": 12,\n    \"last_table\": \"film\",\n    \"last_operation\": \"select\",\n    \"context_summary\": \"Recently working with table: film | Last operation: select\"\n}\n```\n\n\n## 🗄️ Database Schema\n\nThe system is tested with the **Sakila DVD Rental Database**, which includes:\n\n### Main Tables\n- **film**: Movie catalog with ratings, descriptions, rental rates\n- **actor**: Actor information and filmography\n- **customer**: Customer data and rental history\n- **rental**: Rental transactions and dates\n- **payment**: Payment records and amounts\n- **inventory**: Store inventory and availability\n\n### Relationship Tables\n- **film_actor**: Links films to their cast\n- **film_category**: Categorizes films by genre\n\n### Reference Tables\n- **category**: Film genres and classifications\n- **language**: Available languages\n- **address/city/country**: Geographic data\n\nThe agent automatically discovers and understands these relationships, enabling complex queries across multiple tables.\n\n## 🔧 Development\n\n### Project Structure\n\n```\nAI_Engineering_Assignment/\n├── app/\n│   ├── agent/\n│   │   ├── langraph_agent.py      # Core LangGraph workflow\n│   │   └── db_agent_connector.py  # Session management \u0026 context\n│   ├── api/\n│   │   └── routes.py              # FastAPI endpoints\n│   ├── database/\n│   │   └── db_connector.py        # Database operations\n│   └── main.py                    # Application entry point\n├── tests/\n│   ├── conftest.py                 # Sets up comprehensive test fixtures\n│   ├── test_agent.py               # Agent functionality tests\n│   ├── test_api.py                 # API endpoint tests\n│   ├── test_database.py            # Database operation tests\n    └── test_db_agent_connector.py  # Database agent connector tests\n├── docker/\n│   └── Dockerfile                # Container configuration\n├── .github/workflows/\n│   └── ci-cd.yml                 # CI/CD pipeline\n└── requirements.txt              # Python dependencies\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n```\n\n### Code Quality\n\nThe project follows these standards:\n- **PEP 8**: Python code style guidelines\n- **Type Hints**: Full type annotation coverage\n- **Error Handling**: Comprehensive exception management\n- **Logging**: Structured logging for debugging and monitoring\n- **Documentation**: Docstrings for all public methods\n\n### Adding New Features\n\n1. **Database Operations**: Extend `DatabaseConnector` for new operation types\n2. **Agent Capabilities**: Add nodes to the LangGraph workflow\n3. **API Endpoints**: Create new routes in `routes.py`\n4. **Session Features**: Enhance `ConversationSession` class\n\n## 🚢 Deployment\n\n### Production Deployment\n\n1. **Environment Setup**\n```bash\n# Production environment variables\nexport ENV=production\nexport LOG_LEVEL=WARNING\nexport DB_POOL_SIZE=20\n```\n\n2. **Docker Deployment**\n```bash\n# Build production image\ndocker build -f docker/Dockerfile -t langraph-agent:prod .\n\n# Run with production settings\ndocker run -d \\\n  --name langraph-agent \\\n  -p 8000:8000 \\\n  --env-file .env.prod \\\n  langraph-agent:prod\n```\n\n3. **Kubernetes Deployment**\n```yaml\n# Example k8s deployment configuration\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: langraph-agent\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: langraph-agent\n  template:\n    metadata:\n      labels:\n        app: langraph-agent\n    spec:\n      containers:\n      - name: langraph-agent\n        image: langraph-agent:prod\n        ports:\n        - containerPort: 8000\n```\n\n### CI/CD Pipeline\n\nThe project includes automated GitHub Actions workflows:\n\n- **Testing**: Runs on every push and PR\n- **Security Scanning**: Dependency vulnerability checks\n- **Docker Build**: Automated image building and pushing\n- **Deployment**: Automatic deployment to staging/production\n\n## 🤝 Contributing\n\nWe welcome contributions! Please follow these guidelines:\n\n### Development Process\n\n1. **Fork the repository**\n2. **Create a feature branch**\n   ```bash\n   git checkout -b feature/amazing-feature\n   ```\n3. **Make your changes**\n   - Follow existing code style\n   - Add tests for new functionality\n   - Update documentation as needed\n\n4. **Run tests and checks**\n   ```bash\n   pytest\n   black app/ tests/  # Code formatting\n   mypy app/         # Type checking\n   ```\n\n5. **Submit a pull request**\n   - Provide clear description of changes\n   - Reference any related issues\n   - Ensure all CI checks pass\n\n### Code Guidelines\n\n- **Write Tests**: All new features must include tests\n- **Document Changes**: Update README and docstrings\n- **Handle Errors**: Implement proper error handling\n- **Type Safety**: Use type hints throughout\n- **Performance**: Consider the impact on session memory and database operations\n\n### Areas for Contribution\n\n- **New Database Support**: Add connectors for MySQL, MongoDB, etc.\n- **Enhanced NLP**: Improve query understanding and context resolution\n- **UI Interface**: Build a web frontend for the API\n- **Performance Optimization**: Database query optimization and caching\n- **Security Features**: Authentication, authorization, and audit logging\n\n---\n\n## 🙏 Acknowledgments\n\n- **LangGraph Team**: For the powerful agent framework\n- **Google**: For the Gemini language model\n- **FastAPI**: For the excellent web framework\n- **PostgreSQL**: For reliable database foundations\n- **Sakila Database**: For comprehensive testing data\n\n## 📞 Contact\n\n**Baha2r** - [GitHub](https://github.com/Baha2rM98)\n\nProject Link: [https://github.com/Baha2rM98/AI_Engineering_Assignment](https://github.com/Baha2rM98/AI_Engineering_Assignment)\n\n---\n\n*Built with ❤️ for the AI Engineering Assignment - showcasing the power of LangGraph, natural language processing, and intelligent database interactions.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaha2rm98%2Fdb-ai-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbaha2rm98%2Fdb-ai-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaha2rm98%2Fdb-ai-agent/lists"}