1 line
9.9 KiB
JSON
1 line
9.9 KiB
JSON
{"repo": "bichitrabehera/location-agent", "files": {"README.md": {"a1f2efac59a0c056dc93493ac37b4926d609bc39": {"t": 1785846894.6533449, "n": 9371, "h": "1f9a8f3bbf8f09d6", "c": "# AI Location Agent with Gemini\n\nA Node.js application that fetches location data from multiple APIs (Google Places, BigQuery, Distance Matrix) and uses the Gemini LLM model to provide intelligent location recommendations.\n\n## Architecture\n\n- **Data Sources**: Google Places API, BigQuery, Google Distance Matrix\n- **LLM**: Google Gemini API\n- **Runtime**: Node.js with async/await\n\n---\n\n## Prerequisites\n\n- Node.js (v16 or higher)\n- npm or yarn\n- Google Cloud Account with billing enabled\n- Internet connection\n\n---\n\n## Complete Setup Instructions\n\n### PART 1: Create Google Cloud Project\n\n#### Step 1.1: Create a New Project\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Click the **project dropdown** at the top (shows \"Select a Project\")\n3. Click **NEW PROJECT**\n4. Enter:\n - **Project name**: `location-agent` (or any name)\n - **Organization**: Leave blank (or select your org)\n5. Click **CREATE**\n6. Wait 1-2 minutes for the project to initialize\n7. You should now see your project in the dropdown\n\n#### Step 1.2: Enable Billing\n\n1. In Google Cloud Console, go to **Billing**\n2. Click **Link a Billing Account**\n3. Select or create a billing account\n4. Click **LINK BILLING ACCOUNT**\n\n**Note**: Google Cloud provides free credits. You won't be charged unless you exceed free tier limits.\n\n---\n\n### PART 2: Enable Required APIs\n\nGo to **APIs & Services > Library** in Google Cloud Console. For each API below, search, click it, and press **ENABLE**.\n\n#### Enable Google Places API\n1. Search for: **Places API**\n2. Click result → **ENABLE**\n3. Wait for confirmation\n\n#### Enable Google Distance Matrix API\n1. Search for: **Distance Matrix API**\n2. Click result → **ENABLE**\n3. Wait for confirmation\n\n#### Enable BigQuery API\n1. Search for: **BigQuery API**\n2. Click result → **ENABLE**\n3. Wait for confirmation\n\n---\n\n### PART 3: Create and Configure API Key\n\n#### Step 3.1: Generate API Key\n\n1. Go to **APIs & Services > Credentials** in Google Cloud Console\n2. Click **+ CREATE CREDENTIALS** → **API Key**\n3. A popup shows your API key — **COPY IT** (looks like `AIza...`)\n4. Click **RESTRICT KEY** on the popup\n\n#### Step 3.2: Restrict API Key\n\n1. Under **API restrictions**, select **Restrict key**\n2. In the dropdown, select these APIs:\n - Google Places API\n - Distance Matrix API\n3. Click **SAVE**\n\nThis is your `GOOGLE_MAPS_API_KEY`.\n\n---\n\n### PART 4: Set Up BigQuery\n\n#### Step 4.1: Create a BigQuery Dataset\n\n1. Go to **BigQuery** in Google Cloud Console (left sidebar)\n2. Click on your **Project ID** in the left panel\n3. Click **+ CREATE DATASET**\n4. Fill in:\n - **Dataset ID**: `workshop_data`\n - **Data location**: `asia-south1` (for Bangalore)\n - Leave other settings as default\n5. Click **CREATE DATASET**\n\n#### Step 4.2: Create a Table\n\n1. Click on the **workshop_data** dataset\n2. Click **+ CREATE TABLE**\n3. Fill in:\n - **Table name**: `bangalore_places`\n - Under **Schema**, click **EDIT AS TEXT**\n4. Paste this JSON schema:\n\n```json\n[\n {\"name\": \"name\", \"type\": \"STRING\", \"mode\": \"NULLABLE\"},\n {\"name\": \"category\", \"type\": \"STRING\", \"mode\": \"NULLABLE\"},\n {\"name\": \"latitude\", \"type\": \"FLOAT64\", \"mode\": \"NULLABLE\"},\n {\"name\": \"longitude\", \"type\": \"FLOAT64\", \"mode\": \"NULLABLE\"},\n {\"name\": \"area\", \"type\": \"STRING\", \"mode\": \"NULLABLE\"}\n]\n```\n\n5. Click **CREATE TABLE**\n\n#### Step 4.3: Insert Sample Data\n\n1. Go to your **bangalore_places** table\n2. Click the **INSERT ROWS** button at the top\n3. Paste this data (or click **View data** → **Add row** manually):\n\n**Sample Cafes:**\n```\nThird Wave Coffee, cafe, 13.0369, 77.6249, Indiranagar\nMatteo Coffea, cafe, 13.1853, 77.5957, Church Street\nThe Hole in the Wall Cafe, cafe, 13.0282, 77.6245, Koramangala\n```\n\n**Sample Gyms:**\n```\nCult Fitness, gym, 13.0369, 77.6249, Indiranagar\nGold's Gym, gym, 13.0282, 77.6245, Koramangala\nSnap Fitness, gym, 13.1720, 77.5939, Jayanagar\n```\n\n**Sample Parks:**\n```\nCubbon Park, park, 13.1939, 77.5941, Central Bangalore\nLalbagh Botanical Garden, park, 13.2352, 77.5845, Basavanagudi\nJP Park, park, 13.0760, 77.5631, Mathikere\n```\n\nTo insert via UI:\n1. In BigQuery console, click **INSERT ROWS**\n2. Fill in columns manually for each row\n\n---\n\n### PART 5: Set Up Gemini API\n\n#### Step 5.1: Enable Generative Language API\n\n1. Go to **APIs & Services > Library**\n2. Search for: **Generative Language API**\n3. Click result → **ENABLE**\n\n#### Step 5.2: Get Gemini API Key\n\n1. Go to [Google AI Studio](https://makersuite.google.com/app/apikey)\n2. Click **CREATE API KEY** → **Create new secret key in Google Cloud**\n3. **COPY the API key** displayed (starts with `AIza...`)\n\nThis is your `GEMINI_API_KEY`.\n\n---\n\n### PART 6: Create `.env` File\n\nCreate a file named `.env` in the project root directory:\n\n```env\n# Google Cloud Project Configuration\nPROJECT_ID=your-project-id-here\n\n# BigQuery\nDATASET=workshop_data\nTABLE=bangalore_places\n\n# Google Maps APIs\nGOOGLE_MAPS_API_KEY=your-google-maps-api-key-here\n\n# Gemini LLM\nGEMINI_API_KEY=your-gemini-api-key-here\nGEMINI_API_URL=https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent\n```\n\n**Where to get each value:**\n- `PROJECT_ID`: Top-left of Google Cloud Console (after \"Google Cloud\")\n- `GOOGLE_MAPS_API_KEY`: From Step 3.1\n- `GEMINI_API_KEY`: From Step 5.2\n\n**Replace `your-...` with your actual values!**\n\n---\n\n### PART 7: Install Dependencies\n\nOpen terminal in the project directory and run:\n\n```bash\nnpm install\n```\n\nThis installs:\n- `axios` — HTTP requests\n- `dotenv` — Load `.env` variables\n- `@google-cloud/bigquery` — BigQuery client\n- `readline-sync` — Interactive CLI\n\n---\n\n### PART 8: Run the Agent\n\n```bash\nnode index.js\n```\n\nYou should see:\n```\nAI Location Agent - Bangalore Workshop Edition\nTry: cafes in Indiranagar, gyms in Bangalore, parks in Bangalore, museums, malls\nType \"exit\" to quit.\n\nQuery: \n```\n\n---\n\n## Example Queries\n\nType any of these at the `Query:` prompt:\n\n```\ncafes in Indiranagar\ngyms in Bangalore\nparks in Whitefield\nrestaurants in Koramangala\nmuseums\nmalls in HSR\n```\n\n**Expected Output:**\n```\nTop cafes in Indiranagar:\n\n1. Third Wave Coffee – 0.5 km (3 mins)\n2. [Another cafe] – 1.2 km (5 mins)\n3. [Another cafe] – 1.8 km (7 mins)\n\nWhy:\nThese cafes are in accessible, high-demand areas...\n[Gemini's intelligent analysis]\n\nNote: Indiranagar has several options. Competition is balanced.\n```\n\n---\n\n## File Structure\n\n```\n.\n├── index.js # Entry point / CLI\n├── src/\n│ ├── geminiAgent.js # Main agent (fetches APIs, calls Gemini)\n│ ├── places.js # Category mappings & utilities\n│ ├── agent.js # Original agent (backup)\n│ └── tools.js # Original tools (backup)\n├── .env # Environment variables (create this)\n├── package.json # Dependencies\n└── README.md # This file\n```\n\n---\n\n## How It Works\n\n```\nUser Query\n ↓\nParse Category & Area (places.js)\n ↓\nFetch from Google Places API\n ↓ (if empty, fallback to)\nQuery BigQuery Dataset\n ↓\nCall Google Distance Matrix API (for each place)\n ↓\nFormat Data & Create Prompt\n ↓\nCall Gemini API (generate analysis)\n ↓\nDisplay Results to User\n```\n\n---\n\n## Troubleshooting\n\n### Error: \"GOOGLE_MAPS_API_KEY is required\"\n- ✅ Check `.env` file exists\n- ✅ Verify `GOOGLE_MAPS_API_KEY=...` is filled in\n- ✅ Confirm Places API & Distance Matrix API are **ENABLED**\n- ✅ Check billing is enabled on your project\n\n### Error: \"GEMINI_API_URL and GEMINI_API_KEY are required\"\n- ✅ Add both to `.env`\n- ✅ Verify Generative Language API is **ENABLED**\n- ✅ Confirm keys are copied correctly (no extra spaces)\n\n### Error: \"ProjectNotFound\" from BigQuery\n- ✅ Verify `PROJECT_ID` in `.env` matches your project\n- ✅ Confirm `DATASET=workshop_data` and `TABLE=bangalore_places` exist\n- ✅ Check BigQuery API is **ENABLED**\n\n### Error: \"UNAUTHENTICATED\" from Gemini\n- ✅ Verify `GEMINI_API_KEY` is correct\n- ✅ Regenerate key at [Google AI Studio](https://makersuite.google.com/app/apikey)\n- ✅ Confirm Generative Language API is **ENABLED**\n\n### No results returned\n- ✅ Verify Google Places API is **ENABLED**\n- ✅ Try query: `\"cafes in Bangalore\"` (be specific)\n- ✅ Check BigQuery has sample data inserted\n- ✅ Check internet connection\n\n---\n\n## API Quota & Costs\n\n| API | Free Tier | Cost |\n|-----|-----------|------|\n| Google Places | 100 free requests/month | ~$7-17 per 1K requests |\n| Distance Matrix | 100 free requests/month | ~$5 per 1K requests |\n| BigQuery | 1 TB/month free | ~$6.25 per TB scanned |\n| Gemini API | Various free limits | Variable token pricing |\n\nMonitor usage in Google Cloud Console → **Billing**.\n\n---\n\n## Quick Reference\n\n### Common Queries\n```bash\nnode index.js\n# At the Query: prompt, try:\ncafes in Indiranagar\ngyms in Bangalore\nparks\nrestaurants in Whitefield\nmuseums\nmalls\n```\n\n### Stop the Agent\n```\nType: exit\n```\n\n### Modify Queries\nEdit [places.js](src/places.js) to add more categories or aliases.\n\n---\n\n## Environment Variables Reference\n\n| Variable | Example | Required |\n|----------|---------|----------|\n| `PROJECT_ID` | `location-agent-adk` | ✓ |\n| `DATASET` | `workshop_data` | ✓ |\n| `TABLE` | `bangalore_places` | ✓ |\n| `GOOGLE_MAPS_API_KEY` | `AIza...` | ✓ |\n| `GEMINI_API_KEY` | `AIza...` | ✓ |\n| `GEMINI_API_URL` | `https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent` | ✓ |\n\n---\n\n## License\n\nMIT\n"}}}} |