{"id":32879295,"url":"https://github.com/okefemi12/student-success-chatbot","last_synced_at":"2026-04-13T14:33:10.243Z","repository":{"id":323223758,"uuid":"1074524595","full_name":"okefemi12/student-success-chatbot","owner":"okefemi12","description":"Student Success Chatbot (ACE Bot) is an AI-powered academic assistant that helps students analyze study materials, generate summaries, and create personalized study plans. It uses machine learning, OCR, and natural language processing to understand PDFs, images, and text  offering smart study support, progress tracking, and performance prediction ","archived":false,"fork":false,"pushed_at":"2026-02-28T13:58:49.000Z","size":1112,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-28T17:18:14.401Z","etag":null,"topics":["cloudinary","cohere","docker","education","firestore","flask","gemini","google-cloud","machine-learning","nlp","ocr","python","student-success"],"latest_commit_sha":null,"homepage":"https://student-success-backend.onrender.com/test","language":"Jupyter Notebook","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/okefemi12.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-12T00:45:40.000Z","updated_at":"2026-02-28T13:58:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/okefemi12/student-success-chatbot","commit_stats":null,"previous_names":["okefemi12/student-success-chatbot"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/okefemi12/student-success-chatbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okefemi12%2Fstudent-success-chatbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okefemi12%2Fstudent-success-chatbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okefemi12%2Fstudent-success-chatbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okefemi12%2Fstudent-success-chatbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/okefemi12","download_url":"https://codeload.github.com/okefemi12/student-success-chatbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/okefemi12%2Fstudent-success-chatbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31757477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T13:27:56.013Z","status":"ssl_error","status_checked_at":"2026-04-13T13:21:23.512Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cloudinary","cohere","docker","education","firestore","flask","gemini","google-cloud","machine-learning","nlp","ocr","python","student-success"],"created_at":"2025-11-09T18:00:41.246Z","updated_at":"2026-04-13T14:33:10.230Z","avatar_url":"https://github.com/okefemi12.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧠 Student Success Chatbot (ACE Bot)\n\nA comprehensive **AI-powered academic assistant** designed to help students plan, track, and improve their academic performance.\n\nThe system combines a **modular Flask backend** with a robust **XGBoost Machine Learning model** to predict student success probabilities (94.4% accuracy). It features real-time chat, automated study planning, document analysis (OCR), and gamification, all deployed securely on the cloud.\n\n---\n\n## 🚀 Key Features\n\n### 🤖 AI \u0026 Machine Learning\n* **Performance Prediction:** Integrated XGBoost model predicts pass/fail probability based on live user data (study habits, attendance, sleep).\n* **Smart Tutoring:** Generates personalized study plans and flashcards using **Google Gemini** and **OpenAI**.\n* **Adaptive Quizzes:** Automatically generates quizzes from uploaded notes (PDF/DOCX/Images) or chat topics.\n* **Content Recommendations:** Suggests relevant YouTube videos based on the user's course and weak subjects.\n\n### 🛠️ Core Functionality\n* **Multi-Modal Chat:** Supports text and voice interactions (Speech-to-Text \u0026 Text-to-Speech).\n* **Document Analysis:** Extracts text from PDFs, Word docs, PowerPoints, and Images using **PyMuPDF** \u0026 **Tesseract OCR**.\n* **Cloud Storage:**\n    * **Firestore:** Securely stores user profiles, chat history, and study logs.\n    * **Cloudinary:** Hosts uploaded documents and handles file format management for the frontend.\n* **Gamification:** Tracks streaks, awards badges, and levels up users based on study consistency.\n* **Modular Architecture:** Clean, scalable \"Modular Monolith\" code structure using Flask Blueprints.\n\n---\n\n## 🧩 Project Structure\n\nThe project is organized into a modular structure for maintainability and scalability:\n\n```text\nflask/ACE_bot/\n├── app.py                   # Application entry point\n├── config.py                # Environment configuration\n├── extensions.py            # Database \u0026 external service initialization\n├── key_manager.py           # API key rotation logic for reliability\n│\n├── routes/                  # API Endpoints (Blueprints)\n│   ├── auth.py              # User authentication, profile, \u0026 activity logging\n│   ├── chat.py              # Chatbot logic, history, \u0026 audio processing\n│   ├── study_tools.py       # Summaries, Library, Reminders, \u0026 Recommendations\n│   └── quizzes.py           # Quiz generation, flashcards, \u0026 scoring\n│\n├── services/                # Core Logic\n│   ├── ai_engine.py         # LLM integration (Gemini/Groq) \u0026 ML pipeline\n│   ├── audio_service.py     # TTS \u0026 STT services\n│   └── doc_processor.py     # OCR \u0026 file extraction (PDF, DOCX, IMG)\n│\n├── utils/                   # Helpers\n│   └── helpers.py           # Token verification \u0026 data sanitization\n│\n├── model/                   # Machine Learning Artifacts\n│   └── student_prediction_model.pkl  # XGBoost model\n│\n├── Notebook/                # Data Science Work\n│   └── prediction-model.ipynb        # Model training \u0026 analysis notebook\n│\n├── templates/               # HTML templates\n├── requirements.txt         # Python dependencies\n├── Dockerfile               # Container configuration\n└── .dockerignore\n---\n\n## ⚙️ Installation (Local Development)\n\n1. **Clone the repo**\n   ```bash\n   git clone https://github.com/okefemi12/student-success-chatbot.git\n   cd student-success-chatbot/flask/ACE_bot\n````\n\n2. **Create and activate a virtual environment**\n\n   ```bash\n   python -m venv venv\n   source venv/bin/activate      # Mac/Linux\n   venv\\Scripts\\activate         # Windows\n   ```\n\n3. **Install dependencies**\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. **Run the Flask app**\n\n   ```bash\n   python app.py\n   ```\n\n   The app will start at `http://127.0.0.1:5000`.\n\n---\n\n## 🐳 Running with Docker\n\n1. **Build the image**\n\n   ```bash\n   docker build -t student-chatbot .\n   ```\n\n2. **Run the container**\n\n   ```bash\n   docker run -p 5000:5000 student-chatbot\n   ```\n\n3. Open in your browser:\n\n   ```\n   http://localhost:5000\n   ```\n\n---\n\n## ☁️ Deployment (Render)\n\nThis app is pre-configured for Render:\n\n* `Dockerfile` and `.dockerignore` are already set up at the repo root.\n* Render automatically builds and exposes port `5000`.\n\nIf deploying manually:\n\n1. Connect your GitHub repo to Render.\n2. Choose **“Web Service” → “Docker”**.\n3. Deploy.\n4. Watch logs for:\n\n   ```\n   Detected open port 5000 — service is live!\n   ```\n\n---\n\n## 🔒 Environment Variables\n\n| Variable               | Description                                     |\n| ---------------------- | ----------------------------------------------- |\n| `FIREBASE_CREDENTIALS` | Path or JSON credentials for Firestore          |\n| `CLOUDINARY_URL`       | Cloudinary API connection URL                   |\n| `JWT_SECRET`           | Secret key for JWT authentication               |\n| `OPENAI_API_KEY`       | (Optional) For OpenAI or LangChain integrations |\n| `PORT`                 | Port (Render sets this automatically)           |\n\n---\n\n## 🧠 Model Info\n\nThe included model:\n\n```\nflask/ACE_bot/model/student_prediction_model.pkl\n```\n\nis an ML model used to predict student success probability or study recommendations.\nMake sure this file is available when deploying (it’s included via `.dockerignore` exception).\n\n---\n\n## 🧪 API Endpoints (Example)\n\n| Route                  | Method | Description             |\n| ---------------------- | ------ | ----------------------- |\n| `/register`            | POST   | Register a new user     |\n| `/test-login`          | POST   | User login              |\n| `/profile`             | GET    | Fetch profile info      |\n| `/create_chat_session` | POST   | Start chat              |\n| `/chat_summary_pdf`    | POST   | Upload and analyze PDF  |\n| `/log_activity`        | POST   | Log user study activity |\n\n---\n\n## 🧰 Tech Stack\n\n* **Backend:** Flask (Python)\n* **Database:** Firestore (Firebase)\n* **Storage:** Cloudinary\n* **ML / AI:** Scikit-learn, LangChain, OpenAI, Gemini, XGBOOST Classifier\n* **OCR:** PyMuPDF, Pytesseract\n* **Deployment:** Render + Docker , Cloud(soon)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fokefemi12%2Fstudent-success-chatbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fokefemi12%2Fstudent-success-chatbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fokefemi12%2Fstudent-success-chatbot/lists"}