{"id":31698865,"url":"https://github.com/yeakiniqra/govai-application-backend","last_synced_at":"2026-04-17T08:02:27.455Z","repository":{"id":317967608,"uuid":"1068693397","full_name":"yeakiniqra/GOVAI-Application-backend","owner":"yeakiniqra","description":"GovAI Bangladesh - Your AI-Powered Guide to Government Services","archived":false,"fork":false,"pushed_at":"2025-10-04T06:33:49.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T08:24:36.784Z","etag":null,"topics":["ai","fastapi","gpt","langchain","rag-chatbot","serpapi"],"latest_commit_sha":null,"homepage":"https://mygov-ai.vercel.app/","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/yeakiniqra.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-02T19:07:06.000Z","updated_at":"2025-10-04T06:33:53.000Z","dependencies_parsed_at":"2025-10-04T08:24:48.259Z","dependency_job_id":null,"html_url":"https://github.com/yeakiniqra/GOVAI-Application-backend","commit_stats":null,"previous_names":["yeakiniqra/govai-application-backend"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/yeakiniqra/GOVAI-Application-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeakiniqra%2FGOVAI-Application-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeakiniqra%2FGOVAI-Application-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeakiniqra%2FGOVAI-Application-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeakiniqra%2FGOVAI-Application-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yeakiniqra","download_url":"https://codeload.github.com/yeakiniqra/GOVAI-Application-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeakiniqra%2FGOVAI-Application-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31920518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"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":["ai","fastapi","gpt","langchain","rag-chatbot","serpapi"],"created_at":"2025-10-08T19:11:21.969Z","updated_at":"2026-04-17T08:02:27.433Z","avatar_url":"https://github.com/yeakiniqra.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GovAI Bangladesh - FastAPI Backend\n\nAI-powered government information assistant for Bangladesh that provides step-by-step guidance in Bangla for all government-related queries.\n\n## Features\n\n- 🤖 **AI-Powered Responses**: Uses Hugging Face LLMs for intelligent, context-aware answers\n- 🔍 **Smart Search**: Integrates Tavily and SerpAPI for finding relevant government information\n- 🌐 **Multilingual Support**: Accepts queries in English, Bangla, or Banglish\n- 🇧🇩 **Bangla Output**: All responses are provided in Bangla for better accessibility\n- 📚 **Source Citations**: Includes references to official government sources\n- 🏗️ **Modular Architecture**: Clean separation of concerns with LangGraph workflow\n- ⚡ **Fast \u0026 Reliable**: Built with FastAPI for high performance\n\n## Project Structure\n\n```\ngovai_backend/\n├── main.py                          # Updated with admin routes\n├── requirements.txt                 # Updated with new dependencies\n├── .env                            # Environment variables\n├── .env.example                    # Environment template\n├── logs/                           # Auto-created for query logs\n│   └── queries.jsonl              # Query logs (auto-created)\n├── static/                         # Static files directory\n├── templates/                      # Jinja2 templates\n│   └── admin/\n│       ├── login.html             # Login page\n│       ├── dashboard.html         # Main dashboard\n│       ├── logs.html              # Logs viewer\n│       └── stats.html             # Statistics page\n├── config/\n│   └── settings.py                # Updated with admin settings\n├── models/\n│   ├── schemas.py                 # Existing schemas\n│   └── admin_schemas.py           # NEW: Admin data models\n├── utils/\n│   ├── helpers.py                 # Existing helpers\n│   ├── admin_auth.py              # NEW: Authentication utilities\n│   └── query_logger.py            # NEW: Query logging system\n├── admin/\n│   ├── __init__.py               # NEW: Admin package init\n│   └── routes.py                 # NEW: Admin routes\n└── routers/\n    └── query_router.py           # Updated with logging\n```\n\n## Prerequisites\n\n- Python 3.9 or higher\n- Hugging Face API token\n- At least one search API key (Tavily or SerpAPI)\n\n## Setup Instructions\n\n### 1. Installation\n\n```bash\n# Clone the repository\ngit clone \u003cyour-repo-url\u003e\ncd govai-backend\n\n# Create virtual environment\npython -m venv venv\n\n# Activate virtual environment\n# On Windows:\nvenv\\Scripts\\activate\n# On Linux/Mac:\nsource venv/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n### 2. Environment Configuration\n\nCreate a `.env` file in the root directory:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and add your credentials:\n\n```env\n# Required: Hugging Face Token\nHF_TOKEN=hf_your_token_here\n\n# Required: At least ONE search API key\nTAVILY_API_KEY=tvly_your_key_here\nSERPAPI_API_KEY=your_serpapi_key_here\n\n# AI Model Configuration\nAI_MODEL=google/gemma-2-2b-it OR openai/gpt-oss-120b\nMAX_TOKENS=512\nTEMPERATURE=0.7\n\n# Search Configuration\nSEARCH_MAX_RESULTS=5\n\n# Server Configuration\nHOST=0.0.0.0\nPORT=8000\nDEBUG=True\n```\n\n**⚠️ IMPORTANT**: Generate a secure secret key:\n```bash\npython -c \"import secrets; print(secrets.token_urlsafe(32))\"\n```\n\n### 3. Get API Keys\n\n#### Hugging Face Token (Required)\n1. Go to https://huggingface.co/settings/tokens\n2. Click \"New token\"\n3. Give it a name and select \"Read\" access\n4. Copy the token (starts with `hf_`)\n\n#### Tavily API (Recommended)\n1. Go to https://tavily.com/\n2. Sign up for a free account\n3. Get your API key from the dashboard\n4. Free tier includes 1,000 searches/month\n\n#### SerpAPI (Alternative)\n1. Go to https://serpapi.com/\n2. Sign up for a free account\n3. Get your API key from dashboard\n4. Free tier includes 100 searches/month\n\n**Note:** You only need ONE search API key (either Tavily or SerpAPI), though having both provides redundancy.\n\n### 4. Verify Configuration\n\nRun the configuration verification script:\n\n```bash\npython verify_config.py\n```\n\nThis will check if all required API keys are properly configured.\n\n### 5. Start the Application\n\n```bash\n# Development mode (with auto-reload)\nuvicorn main:app --reload\n\n# Or specify host and port\nuvicorn main:app --host 0.0.0.0 --port 8000 --reload\n\n# Production mode\nuvicorn main:app --host 0.0.0.0 --port 8000 --workers 4\n```\n\nThe API will be available at:\n- API: http://localhost:8000\n- Interactive Docs: http://localhost:8000/docs\n- Alternative Docs: http://localhost:8000/redoc\n\n## API Endpoints\n\n### Health Check\n```http\nGET /health\n```\n\nResponse:\n```json\n{\n  \"status\": \"healthy\",\n  \"message\": \"GovAI Bangladesh API is running\",\n  \"timestamp\": \"2025-10-03T10:30:00\"\n}\n```\n\n### Process Query\n```http\nPOST /query\n```\n\nRequest Body:\n```json\n{\n  \"query\": \"How do I apply for a passport?\",\n  \"user_id\": \"optional_user_id\",\n  \"include_sources\": true\n}\n```\n\nResponse:\n```json\n{\n  \"query\": \"How do I apply for a passport?\",\n  \"answer\": \"পাসপোর্টের জন্য আবেদন করতে নিম্নলিখিত ধাপগুলি অনুসরণ করুন:\\n\\n১. অনলাইন আবেদন...\",\n  \"sources\": [\n    {\n      \"title\": \"পাসপোর্ট আবেদন - বাংলাদেশ সরকার\",\n      \"url\": \"https://www.dip.portal.gov.bd/\",\n      \"snippet\": \"পাসপোর্ট আবেদনের জন্য প্রয়োজনীয় কাগজপত্র...\",\n      \"score\": 0.95\n    }\n  ],\n  \"timestamp\": \"2025-10-03T10:30:00\",\n  \"processing_time\": 2.5\n}\n```\n\n## Example Usage\n\n### Using cURL\n\n```bash\ncurl -X POST \"http://localhost:8000/query\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"পাসপোর্ট করতে কি কি লাগে?\",\n    \"include_sources\": true\n  }'\n```\n\n### Using Python Requests\n\n```python\nimport requests\n\nurl = \"http://localhost:8000/query\"\npayload = {\n    \"query\": \"How to get NID card?\",\n    \"include_sources\": True\n}\n\nresponse = requests.post(url, json=payload)\ndata = response.json()\nprint(data[\"answer\"])\n```\n\n### Using JavaScript Fetch\n\n```javascript\nconst response = await fetch('http://localhost:8000/query', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    query: 'birth certificate er jonno ki korte hobe?',\n    include_sources: true\n  })\n});\n\nconst data = await response.json();\nconsole.log(data.answer);\n```\n\n## Supported Query Types\n\nThe API can handle various government-related queries in English, Bangla, or Banglish:\n\n- **English**: \"How do I apply for a passport?\"\n- **Bangla**: \"আমি কিভাবে পাসপোর্টের জন্য আবেদন করব?\"\n- **Banglish**: \"passport korte ki ki lagbe?\"\n\n## Common Use Cases\n\n1. **Passport Applications**: \"পাসপোর্ট করতে কি কি ডকুমেন্ট লাগে?\"\n2. **NID Card**: \"জাতীয় পরিচয়পত্র করতে কত সময় লাগে?\"\n3. **Birth Certificate**: \"birth certificate online e kivabe korbo?\"\n4. **Tax Information**: \"আয়কর রিটার্ন দাখিল করার নিয়ম কি?\"\n5. **Driving License**: \"ড্রাইভিং লাইসেন্স রিনিউ করতে কত টাকা লাগে?\"\n6. **Business Registration**: \"trade license kivabe nibo?\"\n7. **Land Records**: \"জমির দলিল যাচাই করব কিভাবে?\"\n8. **Education**: \"SSC certificate হারিয়ে গেলে কি করব?\"\n\n## Configuration Options\n\nEdit `config/settings.py` to customize:\n\n```python\n# AI Model settings\nAI_MODEL = \"google/gemma-2-2b-it\"  # Recommended for Bangla\nMAX_TOKENS = 512\nTEMPERATURE = 0.7\n\n# Alternative models:\n# AI_MODEL = \"mistralai/Mistral-7B-Instruct-v0.2\"\n# AI_MODEL = \"meta-llama/Llama-2-7b-chat-hf\"\n\n# Search settings\nSEARCH_MAX_RESULTS = 5\n```\n\n## Recommended AI Models\n\nFor best Bangla language support, use these models:\n\n1. **google/gemma-2-2b-it** (Recommended) - Best Bangla support, fast OR openai/gpt-oss-120b\n2. **mistralai/Mistral-7B-Instruct-v0.2** - Good multilingual support\n3. **meta-llama/Llama-2-7b-chat-hf** - Requires model access approval\n\n## Architecture\n\nThe application uses LangGraph for intelligent query processing:\n\n```\nUser Query → Language Detection → Search Service → AI Generation → Response\n                                     ↓\n                                  Tavily/SerpAPI\n                                     ↓\n                              Government Websites\n```\n\n### LangGraph Workflow\n\n1. **Analyze Query** - Understands user intent\n2. **Search Information** - Finds relevant sources\n3. **Generate Response** - Creates detailed Bangla answer\n\n## Logging\n\nLogs are saved in the `logs/` directory:\n- `govai.log` - All logs\n- `govai_errors.log` - Error logs only\n\n## Error Handling\n\nThe API includes comprehensive error handling:\n\n- **400 Bad Request**: Empty or invalid queries\n- **500 Internal Server Error**: AI service or search failures\n- Automatic fallback to cached government service information\n- Graceful degradation when search APIs are unavailable\n\n## Production Deployment\n\nFor production deployment:\n\n### Using Gunicorn\n\n```bash\npip install gunicorn\ngunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000\n```\n\n### Using Docker\n\n```dockerfile\nFROM python:3.11-slim\n\nWORKDIR /app\nCOPY requirements.txt .\nRUN pip install --no-cache-dir -r requirements.txt\n\nCOPY . .\n\nCMD [\"uvicorn\", \"main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]\n```\n\n## 🔐 Accessing the Admin Dashboard\n\n### Login\n\n1. Navigate to: `http://localhost:8000/admin/login`\n2. Enter credentials:\n   - Username: `admin` (or your custom username)\n   - Password: Your password from `.env`\n\n### Dashboard Features\n\n**Main Dashboard** (`/admin/dashboard`):\n- Real-time statistics cards\n- Query trend charts (last 24 hours)\n- Language distribution pie chart\n- Top 10 most frequent queries\n- Recent queries list\n\n**Logs Page** (`/admin/logs`):\n- Complete query logs table\n- Search functionality\n- Filter by status (success/error)\n- Filter by language (Bengali/English/Banglish)\n- Export to CSV\n\n**Statistics Page** (`/admin/stats`):\n- Detailed performance metrics\n- Enhanced visualizations\n- Top 20 queries with percentages\n- Language breakdown\n\n## 🔒 Security Features\n\n1. **JWT Authentication**: Session-based authentication using JWT tokens\n2. **HTTP-Only Cookies**: Tokens stored in secure cookies\n3. **Password Hashing**: Using bcrypt (ready for production)\n4. **Session Expiration**: Auto-logout after configured time\n5. **Protected Routes**: All admin routes require authentication\n\n## 📊 Query Logging\n\nThe system automatically logs:\n- Query text\n- Detected language\n- Processing time\n- Client IP address\n- Success/failure status\n- Timestamp\n\n### Production Checklist\n\n- [ ] Set proper CORS origins\n- [ ] Use environment-specific configurations\n- [ ] Set up SSL/TLS certificates\n- [ ] Implement rate limiting\n- [ ] Add authentication if needed\n- [ ] Set up monitoring and logging\n- [ ] Configure backup search API\n- [ ] Set DEBUG=False in production\n\n## Troubleshooting\n\n### Search API Connection Error\n**Problem**: \"No search tool available\"  \n**Solution**: \n- Verify your API keys in `.env`\n- Check if you have either TAVILY_API_KEY or SERPAPI_API_KEY\n- Run `python verify_config.py` to diagnose\n\n### Hugging Face API Error\n**Problem**: \"Task 'text-generation' not supported\"  \n**Solution**: \n- Make sure you're using a compatible model like openai/gpt-oss-120b\n- Change AI_MODEL to `google/gemma-2-2b-it` in `.env`\n- Verify your HF_TOKEN is valid\n\n### Unicode/Encoding Errors (Windows)\n**Problem**: UnicodeEncodeError in console logs  \n**Solution**:\n- Use the logging configuration in `config/logging_config.py`\n- Run: `chcp 65001` in your terminal before starting\n- Or redirect logs to file instead of console\n\n### Import Errors\n**Problem**: ModuleNotFoundError  \n**Solution**: \n```bash\npip install -r requirements.txt\npython -m pip install --upgrade pip\n```\n\n## API Rate Limits\n\n### Tavily (Free Tier)\n- 1,000 searches per month\n- 5 requests per second\n\n### SerpAPI (Free Tier)\n- 100 searches per month\n- No rate limit\n\n### Hugging Face Inference API (Free)\n- Rate limits vary by model\n- Consider using HF Pro for production\n\n## Contributing\n\nContributions are welcome! Please ensure:\n- Code follows PEP 8 style guidelines\n- All functions have docstrings\n- New features include appropriate logging\n- Test changes before submitting\n- Update README if adding new features\n\n## Testing\n\n```bash\n# Run tests (if implemented)\npytest\n\n# Test specific endpoint\ncurl -X POST http://localhost:8000/query \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"test query\", \"include_sources\": true}'\n```\n\n## Performance\n\nTypical response times:\n- Simple queries: 2-5 seconds\n- Complex queries: 5-15 seconds\n- With search: 15-25 seconds\n\nFactors affecting performance:\n- AI model size\n- Search API response time\n- Query complexity\n- Network latency\n\n## Security\n\n- Never commit `.env` file to version control\n- Rotate API keys regularly\n- Use HTTPS in production\n- Implement rate limiting\n- Add authentication for public deployment\n\n## 📞 Contact\n\n- GitHub: [yeakiniqra](https://github.com/yeakiniqra)  \n- Website: [www.yeakiniqra.com](https://www.yeakiniqra.com)\n\n## Support\n\nFor issues or questions:\n- Create an issue in the repository\n- Check troubleshooting section\n- Review logs in `logs/` directory\n\n## Acknowledgments\n\n- Hugging Face for LLM infrastructure\n- Tavily for search capabilities\n- LangChain for workflow orchestration\n- FastAPI for the excellent framework\n\n---\n\n**Made with ❤️ for the citizens of Bangladesh**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeakiniqra%2Fgovai-application-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyeakiniqra%2Fgovai-application-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeakiniqra%2Fgovai-application-backend/lists"}