Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
158 lines (115 loc) · 3.89 KB

SETUP_GUIDE.md

File metadata and controls

158 lines (115 loc) · 3.89 KB

QueryGPT - Quick Setup Guide

Follow these steps to get QueryGPT running in minutes!

🚀 Quick Start

Step 1: Get Your Gemini API Key

  1. Go to Google AI Studio
  2. Sign in with your Google account
  3. Click "Create API Key"
  4. Copy your API key

Step 2: Configure the API Key

Option A: Using .env file (Recommended)

# Create .env file from template
cp env_template.txt .env

# Edit .env and replace with your actual API key
nano .env  # or use any text editor

Option B: Export as environment variable

export GEMINI_API_KEY="your_actual_api_key_here"

Step 3: Install Dependencies

pip3 install -r requirements.txt

Step 4: Start the Server

Option A: Using the startup script (Easiest)

chmod +x start_server.sh
./start_server.sh

Option B: Manual start

python3 backend/app.py

Step 5: Open the Frontend

Open index.html in your browser:

  • macOS: open index.html
  • Linux: xdg-open index.html
  • Windows: Double-click index.html

✅ Verify Installation

  1. Check that the connection status shows "✓ Connected to Database"
  2. Try an example query by clicking on one of the example cards
  3. Click "Generate & Execute Query"

📝 Example Queries to Try

  1. Documentation Status

    Show me all farmers with their documentation status by partner

  2. Recent Plantations

    List all kyaris created in the last 30 days with verification status

  3. Missing Documents

    Get all farms with missing land records grouped by district

  4. Species Analytics

    Show plantation model usage with species distribution

🔧 Troubleshooting

"Gemini API key not configured"

  • Make sure your API key is set in .env or as an environment variable
  • Restart the server after setting the API key

"Connection Failed"

  • Check your internet connection
  • Verify the database credentials in backend/app.py
  • Ensure the database server is accessible

Dependencies Install Failed

# Try upgrading pip first
pip3 install --upgrade pip

# Then install requirements again
pip3 install -r requirements.txt

Port 5000 Already in Use

# Find and kill the process using port 5000
lsof -ti:5000 | xargs kill -9

# Or change the port in backend/app.py (last line)
app.run(debug=True, host='0.0.0.0', port=5001)

🎯 What You Can Do

  • ✅ Query any table in the database using natural language
  • ✅ Export results as CSV or JSON
  • ✅ Copy generated SQL for reuse
  • ✅ Filter data by date ranges, partners, locations, etc.
  • ✅ Aggregate and analyze data with complex queries

🔒 Security

  • All queries are read-only (SELECT statements only)
  • Dangerous operations (INSERT, UPDATE, DELETE) are blocked
  • Uses dedicated read-only database user
  • SQL injection protection built-in

📊 Database Coverage

The system understands your complete schema including:

  • Farmer and farm management
  • Plantation and species tracking
  • Documentation and media
  • Location hierarchy
  • Biochar production
  • Carbon quantification
  • AWD (Alternate Wetting & Drying) projects

💡 Tips for Better Results

  1. Be specific: "Show farmers in Punjab created last month" works better than "show farmers"
  2. Use examples: Click example cards to see query patterns
  3. Check the SQL: Review generated SQL to understand what data you're getting
  4. Iterate: If results aren't quite right, refine your query and try again

🆘 Need Help?

  1. Check the console (browser DevTools) for frontend errors
  2. Check terminal for backend errors
  3. Review the generated SQL to see what query was created
  4. Try simpler queries first, then build up complexity

🎉 You're Ready!

Start querying your database with natural language! The AI will help you write complex SQL queries without knowing SQL.

Happy Querying! 🚀