Spaces:

neural-arun
/

ArunCore

Runtime error

App Files Files Community

ArunCore / data /github /neet-bot /README.md

GitHub Actions Bot

deploy: automated sync from github main

985f3ee 12 days ago

preview code

Raw

History Blame Contribute Delete

7.17 kB

metadata

project_name: neet-bot
github_url: https://github.com/neural-arun/neet-bot
language: HTML
stars: 0
topics:
  - None
updated_at: 2026-07-26T01:35:53.000Z

neet-bot

GitHub Repository: https://github.com/neural-arun/neet-bot
Primary Language: HTML | Stars: 0 | Forks: 0
Description: No description provided.

🎓 NEET Preparation Platform & Telegram AI Multi-Bot System

An end-to-end, AI-powered preparation ecosystem for NEET & JEE Mains aspirants featuring 3 specialized Telegram bots (Biology, Chemistry, Physics), an interactive Web App, an AI Performance Diagnostic Engine, and a curated dataset of 20,195 PYQs & NCERT questions aligned with the latest official NTA NEET Syllabus.

🏗️ Architecture & How the Entire System Functions

The platform operates as a unified Python micro-service system designed for high availability, zero latency, and seamless multi-channel learning (Telegram + Web Browser).

                            ┌─────────────────────────────────────────┐
                            │            USER INTERFACES              │
                            └────────────────────┬────────────────────┘
                                                 │
                     ┌───────────────────────────┼───────────────────────────┐
                     ▼                           ▼                           ▼
          🤖 GPT Biology Bot            🧪 GPT Chemistry Bot         ⚡ GPT Physics Bot
          (Telegram Polling)            (Telegram Polling)           (Telegram Polling)
                     │                           │                           │
                     └───────────────────────────┼───────────────────────────┘
                                                 │
                                                 ▼
                                     🌐 Embedded Web App & API
                                     (Python HTTPServer on 8080)
                                                 │
          ┌──────────────────────────────────────┼──────────────────────────────────────┐
          ▼                                      ▼                                      ▼
  📁 Question Engine                    🤖 AI Diagnostic Mentor                📄 ReportLab PDF Generator
  (questions.py)                        (ai_analyzer.py - GPT-4o-mini)          (pdf_report.py)
  Loads 20,195 Questions                Analyzes Missed Concepts                Renders Full Solution Reports
          │                                      │                                      │
          └──────────────────────────────────────┼──────────────────────────────────────┘
                                                 │
                                                 ▼
                                     💾 SQLite Database (db.py)
                                     Tracks Scores, Analytics & Users

🚀 How the System Works Step-by-Step

1. Multi-Bot Engine (`neet_bot/main.py`)

The core entry point launches background threads for 3 Telegram bots concurrently:
- GPT Biology Bot: Serves 11,279 Biology questions across 32 active NTA chapters.
- GPT Chemistry Bot: Serves 4,392 Chemistry questions across 18 active NTA chapters.
- GPT Physics Bot: Serves 4,524 Physics questions across 20 active NTA chapters.
Runs a multi-port health and HTTP server (0.0.0.0:8080) providing live web app interfaces and diagnostic APIs for Railway / Cloud deployment.

2. Interactive Chapter Test Flow

Chapter Selection: Students choose any NCERT chapter or custom multi-chapter mock test.
Inline Practice & Timer: Questions are served with interactive Telegram inline keyboards or Web UI buttons.
Instant Verification & Scoring: Tracks correct/wrong answers, time spent, and detailed option choices.

3. AI Performance Diagnostics (`ai_analyzer.py`)

When a test is finished, the AI Diagnostic Engine evaluates the student's missed questions using OpenAI's gpt-4o-mini model.
Generates a personalized diagnostic report highlighting Core Weak Topics, Key Misconceptions, and an Actionable NCERT Revision Plan.

4. Automated Detailed PDF Report Cards (`pdf_report.py`)

Generates a downloadable PDF report card featuring:
- Overall score, percentage, and time taken.
- Question-by-question breakdown showing student choice vs correct answer.
- 💡 Detailed Step-by-Step Solutions with mathematical derivations and key NCERT memory tips.

📂 Repository Directory Guide

Directory / File	Description & Functionality
`neet_bot/`	Master NEET Multi-Bot Engine. Contains the combined bot runner, web app server, AI analyzer, SQLite database driver, and report card generator.
`chemistry_bot/`	Dedicated Chemistry Bot module configured for 4,392 NEET & JEE Mains Chemistry questions.
`physics_bot/`	Dedicated Physics Bot module configured for 4,524 NEET & JEE Mains Physics questions.
`dataset/`	Master dataset folder containing 20,195 JSON and JSONL question banks organized by subject and NTA chapter.
`Dockerfile`	Docker container build recipe configured for Railway and cloud deployments.
`requirements.txt`	Python dependencies (`python-telegram-bot`, `openai`, `reportlab`, `apscheduler`).
`nixpacks.toml`	Railway fallback build specification.

🛠️ Local Development & Quickstart

# 1. Clone the repository
git clone https://github.com/neural-arun/neet-bot.git
cd neet-bot

# 2. Set up virtual environment and install requirements
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3. Configure environment variables in .env
# BIOLOGY_BOT_TOKEN=your_token
# CHEMISTRY_BOT_TOKEN=your_token
# PHYSICS_BOT_TOKEN=your_token
# OPENAI_API_KEY=your_openai_key

# 4. Start the Master Multi-Bot Engine
python3 neet_bot/main.py