gudb 0.1.0__tar.gz

gudb-0.1.0/.env.example

@@ -0,0 +1,23 @@
+# AI-DB-Sentinel Configuration
+
+# Database Connection
+DB_URL=postgresql://user:password@localhost/db
+
+# Gemini API
+GEMINI_API_KEY=your_gemini_api_key_here
+GEMINI_MODEL=gemini-2.0-flash-exp
+
+# Discord Webhook (Optional - for Discord notifications)
+# Get your webhook URL from Discord Server Settings > Integrations > Webhooks
+DISCORD_WEBHOOK_URL=
+
+# Query Monitoring Thresholds (milliseconds)
+SLOW_QUERY_THRESHOLD_MS=500
+CRITICAL_THRESHOLD_MS=2000
+
+# Feature Flags
+ENABLE_AUTO_ANALYSIS=true
+ENABLE_NOTIFICATIONS=true
+
+# Notification Settings
+MAX_STORED_ALERTS=100

gudb-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+.env
+__pycache__/
+*.pyc
+venv/
+env/
+*.sqlite3
+*.log
+.DS_Store
+.idea/
+.vscode/    
+migrations/
+instance/
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.tox/
+.pytest_cache/
+celerybeat-schedule
+*.sqlite3-journal

gudb-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: gudb
+Version: 0.1.0
+Summary: gudb: The Database Seatbelt 🛡️ - A professional database guardian SDK with AI-backed query interception and safety guardrails.
+Project-URL: Homepage, https://gudb.ai
+Project-URL: Documentation, https://docs.gudb.ai
+Project-URL: Repository, https://github.com/gudb-ai/gudb.git
+Project-URL: Issues, https://github.com/gudb-ai/gudb/issues
+Author-email: Gudb Team <hello@gudb.ai>
+License-Expression: MIT
+Keywords: ai,database,gudb,monitoring,safety,sentinel,sql,sre
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: sqlparse>=0.4.4
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: httpx>=0.24.0; extra == 'dev'
+Requires-Dist: isort; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# gudb: The Database Seatbelt 🛡️
+
+**"You never notice a seatbelt until it saves your life. We do the same for your production database."**
+
+gudb is a high-performance safety layer that prevents "Career-Ending" database disasters. It intercepts unconstrained `DELETE`, `DROP`, and `TRUNCATE` operations in real-time with zero latency, while using Gemini AI as an asynchronous "Senior DRE Advisor" to suggest performance optimizations.
+
+## 🎬 Killer Demo (Hackathon Special)
+Check out our high-impact terminal demo that showcases the seatbelt in action:
+```bash
+python3 examples/hackathon_demo.py
+```
+
+## Features
+- ⚡ **Zero-Latency Seatbelt**: Hardcoded safety rules block disasters in <1ms.
+- 🤖 **AI Advisor**: Asynchronous query analysis suggests indexes and refactors.
+- 🔔 **Command Center**: A beautiful dashboard for real-time observability.
+- 🔧 **One-Line Integration**: `conn = monitor(raw_psycopg2_conn)`
+
+## Architecture
+
+```
+User Request → Middleware (Detects Slow Query) → Creates Alert → Triggers AI Analysis
+                                                        ↓
+                                                 Notification Badge
+                                                        ↓
+                                            User Clicks → Shows Details
+                                                        ↓
+                                            AI Recommendations + Fix
+```
+
+## Installation
+
+1. Clone the repository:
+```bash
+git clone <your-repo-url>
+cd gudb
+```
+
+2. Create virtual environment:
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+4. Configure environment variables:
+```bash
+cp .env.example .env
+# Edit .env with your database URL and Gemini API key
+```
+
+## Configuration
+
+Edit `.env` file:
+
+```env
+# Database Connection
+DB_URL=postgresql://user:password@localhost:5432/your_database
+
+# Gemini API
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# Thresholds (milliseconds)
+SLOW_QUERY_THRESHOLD_MS=500
+CRITICAL_THRESHOLD_MS=2000
+```
+
+## Usage
+
+### Start the Server
+
+```bash
+uvicorn main:app --reload
+```
+
+### Access the Dashboard
+
+Open your browser and navigate to:
+- **Production Dashboard**: [https://gudb.ai/dashboard](https://gudb.ai/dashboard)
+- **Local Dashboard**: http://localhost:8000/dashboard
+- **Local API Docs**: http://localhost:8000/docs
+
+### Test Slow Query Detection
+
+Trigger a test slow query:
+```bash
+curl http://localhost:8000/test/slow
+```
+
+Watch the notification badge update and click to see AI analysis!
+
+## API Endpoints
+
+### Notifications
+- `GET /api/notifications/` - Get all alerts
+- `GET /api/notifications/?severity=critical` - Filter by severity
+- `GET /api/notifications/count` - Get notification count
+- `GET /api/notifications/{alert_id}` - Get specific alert
+
+### Analysis
+- `GET /api/analysis/{alert_id}` - Get detailed AI analysis for an alert
+
+### Health
+- `GET /health` - Health check
+- `GET /` - Service info
+
+## How It Works
+
+1. **Detection**: Middleware measures query execution time
+2. **Alert Creation**: If time exceeds threshold, creates an alert with severity level
+3. **Background Analysis**: Triggers AI analysis using LangGraph workflow:
+   - **Detective Node**: Runs EXPLAIN ANALYZE and gathers schema info
+   - **Architect Node**: Uses Gemini to identify bottlenecks and suggest fixes
+   - **Validator Node**: Stores analysis results
+4. **User Interaction**: User sees notification badge, clicks to view detailed analysis
+5. **Action**: User can copy the suggested SQL fix and apply it
+
+## LangGraph Workflow
+
+```
+Detective → Architect → Validator
+   ↓           ↓           ↓
+EXPLAIN    Gemini AI    Store
+ANALYZE    Analysis     Results
+```
+
+## Project Structure
+
+```
+gudb/
+├── main.py                 # FastAPI app with middleware
+├── services/
+├── src/
+│   └── gudb/               # The SDK Package
+│       ├── core/
+│       ├── providers/
+│       └── middlewares/
+├── static/                 # Dashboard UI
+└── requirements.txt
+```
+
+## Use as SDK/Middleware
+
+To integrate into your own FastAPI app:
+
+```python
+from fastapi import FastAPI
+from gudb.middlewares.fastapi import SafeDBMiddleware
+
+app = FastAPI()
+app.add_middleware(SafeDBMiddleware)
+
+# Your routes here...
+```
+
+## Customization
+
+### Adjust Thresholds
+Edit `.env`:
+```env
+SLOW_QUERY_THRESHOLD_MS=300  # More sensitive
+CRITICAL_THRESHOLD_MS=1000   # Lower critical threshold
+```
+
+### Disable Auto-Analysis
+```env
+ENABLE_AUTO_ANALYSIS=false
+```
+
+## 🌐 Vercel Deployment
+
+To deploy the gudb Command Center on Vercel as a static site:
+
+1.  **Project Root**: Ensure you are in the repository root.
+2.  **Configuration**: The included `vercel.json` automatically handles routing to the `static/` directory.
+3.  **Deployment**:
+    ```bash
+    vercel --prod
+    ```
+
+> [!TIP]
+> This deployment mode is for the **frontend only**. To protect your production database, ensure the gudb SDK is deployed within your application cluster.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+---
+
+Built with ❤️ using FastAPI, LangGraph, and Google Gemini

gudb-0.1.0/README.md

@@ -0,0 +1,198 @@
+# gudb: The Database Seatbelt 🛡️
+
+**"You never notice a seatbelt until it saves your life. We do the same for your production database."**
+
+gudb is a high-performance safety layer that prevents "Career-Ending" database disasters. It intercepts unconstrained `DELETE`, `DROP`, and `TRUNCATE` operations in real-time with zero latency, while using Gemini AI as an asynchronous "Senior DRE Advisor" to suggest performance optimizations.
+
+## 🎬 Killer Demo (Hackathon Special)
+Check out our high-impact terminal demo that showcases the seatbelt in action:
+```bash
+python3 examples/hackathon_demo.py
+```
+
+## Features
+- ⚡ **Zero-Latency Seatbelt**: Hardcoded safety rules block disasters in <1ms.
+- 🤖 **AI Advisor**: Asynchronous query analysis suggests indexes and refactors.
+- 🔔 **Command Center**: A beautiful dashboard for real-time observability.
+- 🔧 **One-Line Integration**: `conn = monitor(raw_psycopg2_conn)`
+
+## Architecture
+
+```
+User Request → Middleware (Detects Slow Query) → Creates Alert → Triggers AI Analysis
+                                                        ↓
+                                                 Notification Badge
+                                                        ↓
+                                            User Clicks → Shows Details
+                                                        ↓
+                                            AI Recommendations + Fix
+```
+
+## Installation
+
+1. Clone the repository:
+```bash
+git clone <your-repo-url>
+cd gudb
+```
+
+2. Create virtual environment:
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+4. Configure environment variables:
+```bash
+cp .env.example .env
+# Edit .env with your database URL and Gemini API key
+```
+
+## Configuration
+
+Edit `.env` file:
+
+```env
+# Database Connection
+DB_URL=postgresql://user:password@localhost:5432/your_database
+
+# Gemini API
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# Thresholds (milliseconds)
+SLOW_QUERY_THRESHOLD_MS=500
+CRITICAL_THRESHOLD_MS=2000
+```
+
+## Usage
+
+### Start the Server
+
+```bash
+uvicorn main:app --reload
+```
+
+### Access the Dashboard
+
+Open your browser and navigate to:
+- **Production Dashboard**: [https://gudb.ai/dashboard](https://gudb.ai/dashboard)
+- **Local Dashboard**: http://localhost:8000/dashboard
+- **Local API Docs**: http://localhost:8000/docs
+
+### Test Slow Query Detection
+
+Trigger a test slow query:
+```bash
+curl http://localhost:8000/test/slow
+```
+
+Watch the notification badge update and click to see AI analysis!
+
+## API Endpoints
+
+### Notifications
+- `GET /api/notifications/` - Get all alerts
+- `GET /api/notifications/?severity=critical` - Filter by severity
+- `GET /api/notifications/count` - Get notification count
+- `GET /api/notifications/{alert_id}` - Get specific alert
+
+### Analysis
+- `GET /api/analysis/{alert_id}` - Get detailed AI analysis for an alert
+
+### Health
+- `GET /health` - Health check
+- `GET /` - Service info
+
+## How It Works
+
+1. **Detection**: Middleware measures query execution time
+2. **Alert Creation**: If time exceeds threshold, creates an alert with severity level
+3. **Background Analysis**: Triggers AI analysis using LangGraph workflow:
+   - **Detective Node**: Runs EXPLAIN ANALYZE and gathers schema info
+   - **Architect Node**: Uses Gemini to identify bottlenecks and suggest fixes
+   - **Validator Node**: Stores analysis results
+4. **User Interaction**: User sees notification badge, clicks to view detailed analysis
+5. **Action**: User can copy the suggested SQL fix and apply it
+
+## LangGraph Workflow
+
+```
+Detective → Architect → Validator
+   ↓           ↓           ↓
+EXPLAIN    Gemini AI    Store
+ANALYZE    Analysis     Results
+```
+
+## Project Structure
+
+```
+gudb/
+├── main.py                 # FastAPI app with middleware
+├── services/
+├── src/
+│   └── gudb/               # The SDK Package
+│       ├── core/
+│       ├── providers/
+│       └── middlewares/
+├── static/                 # Dashboard UI
+└── requirements.txt
+```
+
+## Use as SDK/Middleware
+
+To integrate into your own FastAPI app:
+
+```python
+from fastapi import FastAPI
+from gudb.middlewares.fastapi import SafeDBMiddleware
+
+app = FastAPI()
+app.add_middleware(SafeDBMiddleware)
+
+# Your routes here...
+```
+
+## Customization
+
+### Adjust Thresholds
+Edit `.env`:
+```env
+SLOW_QUERY_THRESHOLD_MS=300  # More sensitive
+CRITICAL_THRESHOLD_MS=1000   # Lower critical threshold
+```
+
+### Disable Auto-Analysis
+```env
+ENABLE_AUTO_ANALYSIS=false
+```
+
+## 🌐 Vercel Deployment
+
+To deploy the gudb Command Center on Vercel as a static site:
+
+1.  **Project Root**: Ensure you are in the repository root.
+2.  **Configuration**: The included `vercel.json` automatically handles routing to the `static/` directory.
+3.  **Deployment**:
+    ```bash
+    vercel --prod
+    ```
+
+> [!TIP]
+> This deployment mode is for the **frontend only**. To protect your production database, ensure the gudb SDK is deployed within your application cluster.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+---
+
+Built with ❤️ using FastAPI, LangGraph, and Google Gemini

gudb-0.1.0/SDK_README.md

@@ -0,0 +1,93 @@
+# gudb: The Database Seatbelt 🛡️
+
+**gudb** is a high-performance database safety layer designed to prevent production disasters *before* they happen. It acts as a "seatbelt" for your data, intercepting dangerous queries at the driver level with zero-latency heuristics and Senior DRE-level AI advice.
+
+## ✨ Why a Seatbelt?
+- **Zero-Latency Protection**: Local heuristics block `DELETE` or `DROP` without `WHERE` in <1ms.
+- **Fail-Safe by Design**: If the AI or network is down, the seatbelt stays on.
+- **AI Advisor**: Deep query analysis and optimization tips provided by Gemini AI.
+- **Driver-Level Hook**: Drops into your `psycopg2` connection in one line of code.
+- **Privacy First**: SQL redaction ensures sensitive PII never leaves your network.
+
+## 📦 Installation
+
+```bash
+pip install gudb
+```
+
+To install with framework-specific extras:
+```bash
+pip install "gudb[fastapi]"
+```
+
+## 🚀 Quick Start
+
+### 1. The One-Liner (DB Driver Level)
+Wrap your database connection to start guarding immediately.
+
+```python
+import psycopg2
+from gudb import monitor
+
+# Create your connection
+raw_conn = psycopg2.connect("postgres://...")
+
+# --- GUARD IT ---
+conn = monitor(raw_conn)
+# -----------------
+
+cur = conn.cursor()
+cur.execute("DELETE FROM orders;") # 🛑 Raises DisasterBlockedError
+```
+
+### 2. FastAPI Integration
+```python
+from fastapi import FastAPI
+from gudb.middlewares.fastapi import SafeDBMiddleware
+
+app = FastAPI()
+app.add_middleware(SafeDBMiddleware)
+```
+
+## ⚙️ Configuration
+The SDK can be configured via environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GUDB_API_ENDPOINT` | The evaluation backend URL | `https://ai-db-sentinel.onrender.com/api/sdk/evaluate` |
+| `GUDB_ENVIRONMENT`  | `prod`, `stage`, or `dev` | `production` |
+| `GUDB_FAIL_OPEN`    | Allow queries if AI is down | `True` |
+| `GUDB_REDACT_PII`   | Scrub SQL literals | `True` |
+
+## 🛠️ Advanced Usage (Extensibility)
+You can implement your own AI provider if you want to use a local model or a different API.
+
+```python
+from gudb.providers.base import BaseProvider
+from gudb import Gudb
+
+class MyCustomProvider(BaseProvider):
+    def evaluate(self, query, context):
+        if "DROP" in query.upper():
+            return {"verdict": "STOP", "issue": "No drops allowed"}
+        return {"verdict": "GO"}
+
+# Initialize with custom provider
+gudb = Gudb(provider=MyCustomProvider())
+```
+
+## 🏗️ Development & Publishing
+To test locally:
+```bash
+pip install -e .[dev]
+pytest tests/
+```
+
+To publish to PyPI:
+```bash
+python -m build
+twine upload dist/*
+```
+
+---
+Built with ❤️ by the gudb Team. Ensuring your database sleeps soundly.

gudb-0.1.0/api/analysis.py

@@ -0,0 +1,25 @@
+from fastapi import APIRouter, HTTPException
+from services.models import QueryAnalysis
+from utils.notifier import notification_manager
+
+router = APIRouter(prefix="/api/analysis", tags=["analysis"])
+
+
+@router.get("/{alert_id}", response_model=QueryAnalysis)
+async def get_analysis(alert_id: str):
+    """Get detailed AI analysis for a specific alert"""
+    # First check if alert exists
+    alert = notification_manager.get_alert(alert_id)
+    if not alert:
+        raise HTTPException(status_code=404, detail="Alert not found")
+    
+    # Get analysis results
+    analysis = notification_manager.get_analysis(alert_id)
+    if not analysis:
+        # Alert exists but analysis not ready yet
+        raise HTTPException(
+            status_code=202, 
+            detail=f"Analysis in progress (status: {alert.status})"
+        )
+    
+    return analysis

gudb-0.1.0/api/notifications.py

@@ -0,0 +1,39 @@
+from fastapi import APIRouter, HTTPException, Query
+from typing import List, Optional
+from services.models import QueryAlert
+from utils.notifier import notification_manager
+
+router = APIRouter(prefix="/api/notifications", tags=["notifications"])
+
+
+@router.get("/", response_model=List[QueryAlert])
+async def get_notifications(
+    limit: int = Query(50, ge=1, le=100),
+    severity: Optional[str] = Query(None, regex="^(info|warning|critical)$")
+):
+    """Get recent query alerts, optionally filtered by severity"""
+    alerts = notification_manager.get_alerts(limit=limit, severity=severity)
+    return alerts
+
+
+@router.get("/count")
+async def get_notification_count():
+    """Get count of unread notifications"""
+    count = notification_manager.get_unread_count()
+    return {"count": count}
+
+
+@router.get("/{alert_id}", response_model=QueryAlert)
+async def get_notification(alert_id: str):
+    """Get a specific alert by ID"""
+    alert = notification_manager.get_alert(alert_id)
+    if not alert:
+        raise HTTPException(status_code=404, detail="Alert not found")
+    return alert
+
+
+@router.delete("/clear")
+async def clear_notifications():
+    """Clear all notifications (for testing)"""
+    notification_manager.clear_all()
+    return {"message": "All notifications cleared"}

gudb-0.1.0/examples/enterprise_demo.py

@@ -0,0 +1,41 @@
+import sys
+import os
+from pprint import pprint
+
+# Add src to path for demo
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'src')))
+
+from ai_db_sentinel import monitor, sentinel, settings
+from ai_db_sentinel.exceptions import DisasterBlockedError
+
+def demo_driver_interception():
+    print("--- 🛡️ Driver Interception Demo ---")
+    
+    # Mocking a PEP 249 connection
+    class MockCursor:
+        def execute(self, q, v=None): print(f"Executing SQL: {q}")
+    class MockConn:
+        def cursor(self): return MockCursor()
+        
+    conn = monitor(MockConn())
+    cur = conn.cursor()
+    
+    print("\n1. Testing Safe Query...")
+    cur.execute("SELECT * FROM users WHERE id = 1")
+    
+    print("\n2. Testing Disaster Query (Heuristic Block)...")
+    try:
+        cur.execute("DELETE FROM orders;")
+    except DisasterBlockedError as e:
+        print(f"✅ Intercepted Disaster: {e.issue}")
+        print(f"💥 Impact: {e.impact}")
+
+def demo_configuration():
+    print("\n--- ⚙️ Configuration Demo ---")
+    print(f"Default Endpoint: {settings.api_endpoint}")
+    print(f"Environment: {settings.environment}")
+    print(f"Fail Open: {settings.fail_open}")
+
+if __name__ == "__main__":
+    demo_configuration()
+    demo_driver_interception()