{"id":29422527,"url":"https://github.com/tejas242/scope","last_synced_at":"2026-04-08T16:03:50.546Z","repository":{"id":296425048,"uuid":"974216771","full_name":"Tejas242/SCOPE","owner":"Tejas242","description":"AI-powered system to classify, prioritize, and manage student complaints within educational institutions.","archived":false,"fork":false,"pushed_at":"2025-05-30T16:23:59.000Z","size":4601,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-12T05:22:56.599Z","etag":null,"topics":["bert","fastapi","huggingface-transformers","langchain","llm","nextjs15","python","pytorch","typescript"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tejas242.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}},"created_at":"2025-04-28T12:39:34.000Z","updated_at":"2025-05-30T16:24:02.000Z","dependencies_parsed_at":"2025-05-30T23:14:55.730Z","dependency_job_id":"f4da6e05-269f-4c5f-90f9-0b090a77e22b","html_url":"https://github.com/Tejas242/SCOPE","commit_stats":null,"previous_names":["tejas242/scope"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Tejas242/SCOPE","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tejas242%2FSCOPE","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tejas242%2FSCOPE/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tejas242%2FSCOPE/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tejas242%2FSCOPE/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tejas242","download_url":"https://codeload.github.com/Tejas242/SCOPE/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tejas242%2FSCOPE/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31562697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"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":["bert","fastapi","huggingface-transformers","langchain","llm","nextjs15","python","pytorch","typescript"],"created_at":"2025-07-12T05:14:47.566Z","updated_at":"2026-04-08T16:03:50.539Z","avatar_url":"https://github.com/Tejas242.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🎓 SCOPE\n\n### Student Complaint Optimisation and Prioritisation Engine\n\n[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=for-the-badge\u0026logo=fastapi)](https://fastapi.tiangolo.com/)\n[![Next.js](https://img.shields.io/badge/next.js-000000?style=for-the-badge\u0026logo=nextdotjs\u0026logoColor=white)](https://nextjs.org/)\n[![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://www.python.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge\u0026logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![HuggingFace](https://img.shields.io/badge/🤗_Hugging_Face-FFD21E?style=for-the-badge)](https://huggingface.co/)\n[![LangChain](https://img.shields.io/badge/🦜️🔗_LangChain-46BC99?style=for-the-badge)](https://langchain.com/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)\n\n\u003c/div\u003e\n\n![SCOPE - Student Complaint Optimisation \u0026 Prioritisation Engine](./scope-frontend/public/banner.png)\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eSCOPE\u003c/b\u003e is an intelligent system designed to streamline the handling of student complaints within educational institutions. It automatically classifies incoming complaints by \u003cb\u003ecategory\u003c/b\u003e and \u003cb\u003eurgency\u003c/b\u003e, enabling staff to prioritize and address critical issues efficiently.\n\u003c/p\u003e\n\n\u003chr\u003e\n\n## ✨ Key Features\n\n*   **🧠 Automated Complaint Classification \u0026 Prioritization:** Utilizes a fine-tuned DistilBERT multi-task model to accurately categorize complaints and assess their urgency.\n*   **📊 Interactive Dashboards:** Role-specific dashboards (Admin, Staff, Student) providing insights into complaint trends, response times, and common topics using charts and visualizations.\n*   **🤖 AI Chatbot Assistant:** A RAG-based chatbot powered by Google Gemini and LangChain, equipped with tools to query complaint data, provide summaries, and assist users.\n*   **🔐 Secure Authentication:** JWT-based authentication ensures secure access for different user roles.\n*   **⚙️ Full-Stack Architecture:** Robust FastAPI backend and a modern Next.js frontend with TypeScript.\n*   **📈 Data Analytics:** Endpoints for analyzing trends, identifying high-priority issues, and exploring common complaint topics.\n\n## Screenshots \n\n\u003cdiv align=\"center\"\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e📸 \u003cstrong\u003eView Screenshots\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n**🏠 Landing Page**\n![Landing Page](./scope-frontend/public/screenshots/landing.png)\n*Welcome to SCOPE - Your intelligent complaint management system*\n\n\u003cbr\u003e\n\n**🎯 Features Overview**\n![Features Overview](./scope-frontend/public/screenshots/features.png)\n*Comprehensive feature set for efficient complaint handling*\n\n\u003cbr\u003e\n\n**📊 Analytics Dashboard**\n![Analytics Dashboard](./scope-frontend/public/screenshots/analytics-dash.png)\n*Real-time insights and data visualization for informed decision-making*\n\n\u003cbr\u003e\n\n**🧠 AI-Powered Classification \u0026 Prioritization**\n![Complaint Classification \u0026 Prioritization](./scope-frontend/public/screenshots/complaint-classification-prioritization.png)\n*Automated complaint categorization and urgency assessment*\n\n\u003cbr\u003e\n\n**👥 User Management System**\n![User Management](./scope-frontend/public/screenshots/user-management.png)\n*Role-based access control and user administration*\n\n\u003cbr\u003e\n\n**🤖 AI Chatbot Assistant**\n![Chatbot Features](./scope-frontend/public/screenshots/chatbot-features.png)\n*Advanced RAG-based features for complaint data analysis*\n![Chatbot Demo](./scope-frontend/public/screenshots/chatbot-demo.png)\n*Interactive AI assistant powered by Google Gemini and LangChain*\n\u003cbr\u003e\n\n\n\u003c/details\u003e\n\n\u003c/div\u003e\n\n\n## 🛠️ Tech Stack\n\n*   **Backend:**\n    *   Python 3.10+\n    *   FastAPI\n    *   SQLAlchemy (with SQLite)\n    *   Pydantic\n    *   Transformers (Hugging Face)\n    *   PyTorch\n    *   LangChain, LangChain Google Genai\n    *   Uvicorn\n*   **Frontend:**\n    *   Node.js 18+\n    *   Next.js (App Router)\n    *   TypeScript\n    *   React\n    *   Tailwind CSS\n    *   Shadcn/ui (Radix UI \u0026 Tailwind)\n    *   Recharts\n    *   Axios\n*   **Database:**\n    *   SQLite (default for local development)\n*   **ML Model:**\n    *   Fine-tuned DistilBERT/RoBERTa (Multi-task classification)\n\n## 🖼️ Interface Preview\n\n\u003e Will be added later\n\n## 🚀 Getting Started (Local Setup)\n\nFollow these steps to set up and run the SCOPE project locally.\n\n**Prerequisites:**\n\n*   Git\n*   Python 3.10 or later\n*   Node.js 18 or later (includes npm/yarn/pnpm)\n*   Access to a terminal or command prompt\n\n**1. Clone the Repository:**\n```bash\ngit clone https://github.com/tejas242/SCOPE.git\n```\n\n#### 1.1 Get the model.pt\nUse the jupyter-notebook at `notebooks/Model_SCOPE.ipynb` and the dataset in `data/complaints.csv` to train the model and download and store it in the `model/model.pt` file.\n\nThe model is too large to upload to github repo.\n\n**2. Backend Setup (FastAPI):**\n\n\u003e I have used [uv](https://docs.astral.sh/uv/) in development, but following the instructions below will work too.\n\n```bash\n# Navigate to the backend directory\ncd scope-backend\n\n# Create a Python virtual environment\npython -m venv venv\n\n# Activate the virtual environment\n# On macOS/Linux:\nsource venv/bin/activate\n# On Windows:\n.\\venv\\Scripts\\activate\n\n# Install backend dependencies\npip install -r requirements.txt\n\n# Set up environment variables\ncp .env.example .env\n\n# !! IMPORTANT !!\n# Edit the .env file:\n# - Replace SECRET_KEY with a strong, unique secret.\n# - Add your GOOGLE_API_KEY if you want to use the chatbot features.\n# - Adjust DATABASE_URL or other settings if needed.\n\n# Seed the database with initial data (optional but recommended)\n# This creates default users and sample complaints\npython ../scripts/seed_data.py ../data/complaints-small.csv # Use complaints.csv for more data\n\n# Start the backend server\nuvicorn main:app --reload --host 0.0.0.0 --port 8000\n```\n\nThe backend API will be running at `http://localhost:8000`. You can access the interactive API documentation (Swagger UI) at `http://localhost:8000/docs`.\n\n**3. Frontend Setup (Next.js):**\n\n```bash\n# Open a NEW terminal window/tab\n# Navigate to the frontend directory from the project root\ncd scope-frontend\n\n# Install frontend dependencies\nnpm install\n# or yarn install or pnpm install\n\n# Set up environment variables\ncp .env.local.example .env.local\n\n# !! IMPORTANT !!\n# Edit the .env.local file if your backend is running on a different URL\n# NEXT_PUBLIC_API_URL=http://localhost:8000 # Default\n\n# Start the frontend development server\nnpm run dev\n# or yarn dev or pnpm dev\n```\n\nThe frontend application will be running at `http://localhost:3000`.\n\n**4. Access the Application:**\n\nOpen your web browser and navigate to `http://localhost:3000`. You can log in using the default credentials.\n\n## 🔑 Default Users\n\n*   **Admin:** `admin@example.com` / `adminpassword`\n*   **Staff:** `staff@example.com` / `staffpassword`\n*   **Student:** `student@example.com` / `studentpassword`\n\n*(Remember to change these default passwords in a production environment!)*\n\n## ⚙️ Environment Variables\n\nConfiguration is managed via environment variables. Example files are provided:\n\n*   `scope-backend/.env.example`: Contains settings for the FastAPI backend (database URL, JWT secret, Google API key, etc.). Copy this to `.env` and fill in your values.\n*   `scope-frontend/.env.local.example`: Contains settings for the Next.js frontend (primarily the backend API URL). Copy this to `.env.local` and adjust if necessary.\n\n**Crucially, the actual `.env` and `.env.local` files should NOT be committed to version control.** They are included in the `.gitignore` file.\n\n## 📚 API Documentation\n\nThe backend API includes automatically generated documentation using Swagger UI. Once the backend server is running, access it at:\n\n[http://localhost:8000/docs](http://localhost:8000/docs)\n\n## 🔮 Future Enhancements\n\n*   Integration with a dedicated front-end dashboard (In Progress)\n*   Email notifications for high-priority complaints or status updates.\n*   More sophisticated analytics and reporting features.\n*   Enhanced chatbot capabilities with more tools and context awareness.\n*   Deployment scripts and configurations (Docker, etc.).\n*   User profile management.\n\n## 🤝 Contributing\n\nContributions are welcome! Please follow standard Gitflow practices. (Add more detailed contribution guidelines if needed).\n\n1.  Fork the repository.\n2.  Create a new branch (`git checkout -b feature/your-feature-name`).\n3.  Make your changes.\n4.  Commit your changes (`git commit -m 'Add some feature'`).\n5.  Push to the branch (`git push origin feature/your-feature-name`).\n6.  Open a Pull Request.\n\n## 📜 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftejas242%2Fscope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftejas242%2Fscope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftejas242%2Fscope/lists"}