Apppublic

flexistcrypto/AtlasMapBot

sourceHugging Faceupdated 4mo agoView on Hugging Face

0likes

App README

India Geography Telegram Bot Assistant

An intelligent, production-grade Telegram Bot that acts as an interactive geography encyclopedia. Powered entirely by a validated in-memory JSON database containing detailed profiles of all 28 Indian states and 5 Union Territories.

Key Features

—🏛 Interactive Profiles: Comprehensive details on Capitals, Area, Population, Demographics, Languages, Economy, Culture, Rivers, and Tourist Attractions.
—🔍 Smart Search Engine: Exact matching, partial matching, alias mapping (e.g. up, wb, tn), and fuzzy string matching (via RapidFuzz with $\ge 85$ score threshold) with spelling suggestions.
—🧠 Rule-Based NLU Parser: Automatically understands natural queries like "what is the capital of UP?" or "population of Bihar" and routes to the correct section.
—📊 Dynamic Analytics: dynamic statistics calculation (extremes for largest/smallest by area, population density, least/most populous, etc.) derived dynamically from JSON.
—🎮 Interactive Menus: Clean paginated UI keyboards and inline selection carousels optimized for Telegram Mobile.
—🏥 Admin Dashboard: Secure /health diagnostic panel displaying loaded records, uptime, and server memory metrics.

Project Architecture

The bot uses a clean, highly modular Service-Oriented Architecture to keep logic decoupled and future-proof:

text

india_geography_bot/
├── .env                  # Environment configurations
├── requirements.txt      # Dependency manifest
├── bot.py                # Bot bootstrap & catch-all unknown command router
├── config.py             # Config loader & Loguru rotation setup
├── models/
│   └── geography.py      # Pydantic schema schemas
├── services/
│   ├── geography_service.py # In-memory database loader & indexer
│   ├── search_service.py    # Fuzzy match & advanced keyword search
│   ├── nlp_service.py       # Regex-based Natural Language query parser
│   ├── analytics_service.py # Dynamic metrics calculations
│   └── ai_service.py        # Future LLM integration abstraction
├── keyboards/
│   └── menu.py           # Inline paginations & profile keyboards
├── handlers/
│   ├── command_handlers.py  # Slash commands routers
│   ├── callback_handlers.py # Inline selection callback routers
│   └── message_handlers.py  # Main text routing & NLP queries
├── utils/
│   └── formatter.py      # Safe HTML formatting & sanitization
└── tests/                # Test suite

Local Setup & Installation

1. Prerequisites

Ensure you have Python 3.11+ installed on your system.

2. Clone and Setup Environment

Navigate to your project directory and create a virtual environment:

bash

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install the production dependencies:

bash

pip install -r requirements.txt

3. Configure Environment Variables

Create a file named .env in the root of the project (a template .env is provided):

env

BOT_TOKEN=YOUR_TELEGRAM_BOT_TOKEN_FROM_BOTFATHER
ADMIN_ID=YOUR_TELEGRAM_NUMERIC_USER_ID
LOG_LEVEL=INFO
DATABASE_PATH=../india_geography_db/india_geography.json

4. Run the Bot

Start the polling loop locally:

bash

python bot.py

Testing Suite

The project includes a robust testing suite powered by pytest with $\ge 90\%$ test coverage.

To run the unit tests:

bash

pytest -v

Tests cover:

—Database Models: Validation checks and type coercions.
—Search Service: Exact, case-insensitive, alias abbreviations, and fuzzy matching.
—NLP Parser: Regex intent extractions and entities resolution.
—Analytics Engine: Extreme statistics validation.

Deployment Guide

Option 1: Docker (Recommended)

Make sure Docker and Docker Compose are installed on your host.

To start the bot container in background detached mode:

bash

docker-compose up -d --build

To view rolling logs:

bash

docker-compose logs -f

Option 2: Production VPS (Ubuntu Systemd)

For deploying directly on an Ubuntu VPS without containers:

1.Clone files to /var/www/india_geography_bot/.
2.Ensure the database JSON is placed at /var/www/india_geography_db/india_geography.json.
3.Set up the virtual environment, install requirements, and configure the .env file.
4.Create a systemd service file:

bash

   sudo nano /etc/systemd/system/geobot.service

1.Paste the following configuration:

ini

   [Unit]
   Description=India Geography Telegram Bot
   After=network.target

   [Service]
   Type=simple
   User=ubuntu
   WorkingDirectory=/var/www/india_geography_bot
   ExecStart=/var/www/india_geography_bot/venv/bin/python bot.py
   Restart=on-failure
   RestartSec=5
   Environment=PYTHONUNBUFFERED=1

   [Install]
   WantedBy=multi-user.target

1.Reload, enable, and start the daemon:

bash

   sudo systemctl daemon-reload
   sudo systemctl enable geobot.service
   sudo systemctl start geobot.service

Option 3: Railway / Render

To deploy on PaaS environments:

1.GitHub Repository: Push the project folder to GitHub. Ensure requirements.txt is in the root.
2.Environment Variables: Configure BOT_TOKEN, ADMIN_ID, LOG_LEVEL in the Render/Railway service settings.
3.Database File: If the database file is static, place india_geography.json inside a subdirectory within the repository (e.g. india_geography_db/india_geography.json) and configure DATABASE_PATH=./india_geography_db/india_geography.json in your PaaS env variables.
4.Deploy: Render/Railway will automatically detect requirements.txt, build the environment, and execute python bot.py.