# 🎓 UMAT Kit - Complete Student Portal Toolkit
[](https://badge.fury.io/py/umat-kit)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
**UMAT Kit** is a comprehensive Python toolkit designed for UMAT (University of Mines and Technology) students to interact with the student portal programmatically. It provides a rich CLI interface, automated course assessment bot, API client, and utilities for seamless student portal management.
## ✨ Features
### 🤖 **Automated Course Assessment Bot**
- **Smart Rating System**: Automatically rates courses with realistic scores (3-5 range)
- **Bulk Submission**: Submit all course assessments at once (matches web interface)
- **Manual Mode**: Course-by-course assessment with full control
- **Progress Tracking**: Real-time progress indicators and success statistics
### 📊 **Academic Management**
- **Results Viewer**: View current and historical academic results
- **GPA Calculator**: Automatic GPA and CGPA calculations
- **Transcript Export**: Download and export academic transcripts
### 💰 **Financial Management**
- **Bills Overview**: View outstanding fees and payment history
- **Payment Tracking**: Monitor payment status and due dates
- **Fee Breakdown**: Detailed breakdown of all charges
### 📚 **Course Management**
- **Registration Status**: View registered courses and schedules
- **Course Details**: Access detailed course information
- **Assessment Progress**: Track course assessment completion
### 👤 **Profile Management**
- **Profile Updates**: Update contact information and email
- **Session Management**: Secure authentication and session handling
- **Data Export**: Export personal and academic data
### 🖥️ **Rich CLI Interface**
- **Interactive Menus**: Beautiful, intuitive command-line interface
- **Progress Bars**: Visual feedback for long-running operations
- **Colored Output**: Rich formatting with emojis and colors
- **Error Handling**: Graceful error handling with helpful messages
## 🚀 Installation
### Install from PyPI (Recommended)
```bash
pip install umat-kit
```
### Install from Source
```bash
git https://github.com/Odeneho-Calculus/UMaT-Kit.git
cd UMaT-Kit
pip install -e .
```
## 🎯 Quick Start
### CLI Interface
```bash
# Launch the interactive CLI
umat-kli ui
# Direct login
umat-kli login --username your_student_id
# View help
umat-kli --help
```
### Python API
```python
from umat_kit.student_portal import StudentPortal
# Initialize portal
portal = StudentPortal()
# Login
portal.login("your_student_id", "your_password")
# Get academic results
results = portal.get_academic_results()
print(f"Current GPA: {results['current_gpa']}")
# Automated course assessment
portal.automated_course_assessment()
# View bills
bills = portal.get_student_bills()
```
## 🤖 Automated Course Assessment
The standout feature of UMAT Kit is the **Automated Course Assessment Bot**:
```python
# Quick automated assessment
portal.automated_course_assessment()
```
**What it does:**
- 🎯 Finds all pending course assessments
- 🎲 Generates realistic random ratings (3-5: Average to Very Good)
- 📝 Applies optional general comments to all courses
- 📦 Submits all assessments in one bulk request (matches web interface)
- 📊 Provides detailed success statistics
**Assessment Flow:**
```
🤖 Automated Course Assessment
📚 Found 8 pending courses
🎲 Generating random ratings...
📊 Assessment Summary:
┌─────────┬──────────────────────┬───────────┬─────────────┐
│ Course │ Course Name │ Questions │ Avg Rating │
├─────────┼──────────────────────┼───────────┼─────────────┤
│ CS 101 │ Programming Basics │ 21 │ 4.2/5.0 │
│ MA 201 │ Advanced Mathematics │ 21 │ 3.8/5.0 │
└─────────┴──────────────────────┴───────────┴─────────────┘
✅ All assessments submitted successfully!
📈 Success Rate: 100% (8/8 courses)
```
## 📋 Available Commands
### CLI Commands
```bash
# Authentication
umat-kli login # Interactive login
umat-kli logout # Logout current session
# Academic
umat-kli results # View academic results
umat-kli courses # View registered courses
# Assessment
umat-kli assess # Launch course assessment
umat-kli assess --auto # Automated assessment
umat-kli assess --manual # Manual assessment
# Financial
umat-kli bills # View bills and payments
# Profile
umat-kli profile # View/update profile
umat-kli profile --update-email # Update email address
# Utilities
umat-kli export --results # Export academic results
umat-kli export --bills # Export financial data
```
## 🔧 Configuration
### Environment Variables
Create a `.env` file in your project directory:
```env
# Optional: Auto-login credentials
UMAT_USERNAME=your_student_id
UMAT_PASSWORD=your_password
# Optional: API Configuration
UMAT_API_TIMEOUT=30
UMAT_MAX_RETRIES=3
```
### Configuration File
```python
# config.py
UMAT_CONFIG = {
'api_base_url': 'https://student.umat.edu.gh/api',
'timeout': 30,
'max_retries': 3,
'auto_assessment_range': (3, 5), # Rating range for auto assessment
}
```
## 🛡️ Security Features
- **🔐 Secure Authentication**: Encrypted credential storage
- **🔒 Session Management**: Automatic session timeout and renewal
- **🛡️ Data Protection**: Secure handling of sensitive student data
- **🚫 Rate Limiting**: Built-in API rate limiting to prevent abuse
## 📊 API Reference
### StudentPortal Class
```python
class StudentPortal:
def login(username: str, password: str) -> bool
def get_academic_results() -> Dict[str, Any]
def get_student_bills() -> Dict[str, Any]
def get_registered_courses() -> Dict[str, Any]
def automated_course_assessment(comment: str = "") -> Dict[str, Any]
def manual_course_assessment() -> None
def update_profile(data: Dict[str, Any]) -> bool
def export_data(data_type: str, format: str = "json") -> str
```
### API Manager
```python
class APIManager:
def submit_all_course_assessments(assessments: List[Dict], remarks: str) -> Dict
def get_course_assessments() -> Dict[str, Any]
def get_academic_results() -> Dict[str, Any]
def get_student_bills() -> Dict[str, Any]
```
## 🎨 Examples
### Automated Assessment with Custom Comments
```python
from umat_kit.student_portal import StudentPortal
portal = StudentPortal()
portal.login("your_id", "your_password")
# Automated assessment with custom comment
result = portal.automated_course_assessment(
comment="Great semester! Learned a lot from all courses."
)
print(f"✅ Assessed {result['courses_submitted']} courses")
print(f"📊 Success Rate: {result['success_rate']}%")
```
### Export Academic Data
```python
# Export results to JSON
results_file = portal.export_data("results", format="json")
print(f"Results exported to: {results_file}")
# Export bills to CSV
bills_file = portal.export_data("bills", format="csv")
print(f"Bills exported to: {bills_file}")
```
### Batch Operations
```python
# Check multiple students (if you have admin access)
students = ["student1", "student2", "student3"]
for student_id in students:
portal.login(student_id, get_password(student_id))
portal.automated_course_assessment()
portal.logout()
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
git clone https://github.com/Odeneho-Calculus/UMaT-Kit.git
cd UMaT-Kit
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest tests/
```
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🆘 Support
- **Issues**: [GitHub Issues](https://github.com/Odeneho-Calculus/UMaT-Kit/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Odeneho-Calculus/UMaT-Kit/discussions)
## 🎯 Roadmap
- [ ] **Mobile App Integration**: React Native/Flutter companion app
- [ ] **Telegram Bot**: Interactive Telegram bot interface
- [ ] **Web Dashboard**: Web-based dashboard for portal management
- [ ] **Notification System**: Email/SMS notifications for important updates
- [ ] **Analytics**: Advanced analytics and reporting features
- [ ] **Multi-University Support**: Extend support to other universities
## ⭐ Star History
[](https://star-history.com/#Odeneho-Calculus/umat-kit&Date)
---
**Made with ❤️ for UMAT students by students**
*Simplifying student life, one API call at a time.* 🚀
Raw data
{
"_id": null,
"home_page": null,
"name": "umat-kit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "umat, student-portal, api-client, course-assessment, automation, cli, education",
"author": null,
"author_email": "kalculusGuy <umatkit@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ea/82/7edb11b87e1f59ff2128b7241e730070cc7c4d63a929e84ebbea6ad4ee5d/umat_kit-0.1.3.tar.gz",
"platform": null,
"description": "# \ud83c\udf93 UMAT Kit - Complete Student Portal Toolkit\r\n\r\n[](https://badge.fury.io/py/umat-kit)\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\n**UMAT Kit** is a comprehensive Python toolkit designed for UMAT (University of Mines and Technology) students to interact with the student portal programmatically. It provides a rich CLI interface, automated course assessment bot, API client, and utilities for seamless student portal management.\r\n\r\n## \u2728 Features\r\n\r\n### \ud83e\udd16 **Automated Course Assessment Bot**\r\n- **Smart Rating System**: Automatically rates courses with realistic scores (3-5 range)\r\n- **Bulk Submission**: Submit all course assessments at once (matches web interface)\r\n- **Manual Mode**: Course-by-course assessment with full control\r\n- **Progress Tracking**: Real-time progress indicators and success statistics\r\n\r\n### \ud83d\udcca **Academic Management**\r\n- **Results Viewer**: View current and historical academic results\r\n- **GPA Calculator**: Automatic GPA and CGPA calculations\r\n- **Transcript Export**: Download and export academic transcripts\r\n\r\n### \ud83d\udcb0 **Financial Management**\r\n- **Bills Overview**: View outstanding fees and payment history\r\n- **Payment Tracking**: Monitor payment status and due dates\r\n- **Fee Breakdown**: Detailed breakdown of all charges\r\n\r\n### \ud83d\udcda **Course Management**\r\n- **Registration Status**: View registered courses and schedules\r\n- **Course Details**: Access detailed course information\r\n- **Assessment Progress**: Track course assessment completion\r\n\r\n### \ud83d\udc64 **Profile Management**\r\n- **Profile Updates**: Update contact information and email\r\n- **Session Management**: Secure authentication and session handling\r\n- **Data Export**: Export personal and academic data\r\n\r\n### \ud83d\udda5\ufe0f **Rich CLI Interface**\r\n- **Interactive Menus**: Beautiful, intuitive command-line interface\r\n- **Progress Bars**: Visual feedback for long-running operations\r\n- **Colored Output**: Rich formatting with emojis and colors\r\n- **Error Handling**: Graceful error handling with helpful messages\r\n\r\n## \ud83d\ude80 Installation\r\n\r\n### Install from PyPI (Recommended)\r\n```bash\r\npip install umat-kit\r\n```\r\n\r\n### Install from Source\r\n```bash\r\ngit https://github.com/Odeneho-Calculus/UMaT-Kit.git\r\ncd UMaT-Kit\r\npip install -e .\r\n```\r\n\r\n## \ud83c\udfaf Quick Start\r\n\r\n### CLI Interface\r\n```bash\r\n# Launch the interactive CLI\r\numat-kli ui\r\n\r\n# Direct login\r\numat-kli login --username your_student_id\r\n\r\n# View help\r\numat-kli --help\r\n```\r\n\r\n### Python API\r\n```python\r\nfrom umat_kit.student_portal import StudentPortal\r\n\r\n# Initialize portal\r\nportal = StudentPortal()\r\n\r\n# Login\r\nportal.login(\"your_student_id\", \"your_password\")\r\n\r\n# Get academic results\r\nresults = portal.get_academic_results()\r\nprint(f\"Current GPA: {results['current_gpa']}\")\r\n\r\n# Automated course assessment\r\nportal.automated_course_assessment()\r\n\r\n# View bills\r\nbills = portal.get_student_bills()\r\n```\r\n\r\n## \ud83e\udd16 Automated Course Assessment\r\n\r\nThe standout feature of UMAT Kit is the **Automated Course Assessment Bot**:\r\n\r\n```python\r\n# Quick automated assessment\r\nportal.automated_course_assessment()\r\n```\r\n\r\n**What it does:**\r\n- \ud83c\udfaf Finds all pending course assessments\r\n- \ud83c\udfb2 Generates realistic random ratings (3-5: Average to Very Good)\r\n- \ud83d\udcdd Applies optional general comments to all courses\r\n- \ud83d\udce6 Submits all assessments in one bulk request (matches web interface)\r\n- \ud83d\udcca Provides detailed success statistics\r\n\r\n**Assessment Flow:**\r\n```\r\n\ud83e\udd16 Automated Course Assessment\r\n\ud83d\udcda Found 8 pending courses\r\n\ud83c\udfb2 Generating random ratings...\r\n\ud83d\udcca Assessment Summary:\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502 Course \u2502 Course Name \u2502 Questions \u2502 Avg Rating \u2502\r\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\r\n\u2502 CS 101 \u2502 Programming Basics \u2502 21 \u2502 4.2/5.0 \u2502\r\n\u2502 MA 201 \u2502 Advanced Mathematics \u2502 21 \u2502 3.8/5.0 \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n\r\n\u2705 All assessments submitted successfully!\r\n\ud83d\udcc8 Success Rate: 100% (8/8 courses)\r\n```\r\n\r\n## \ud83d\udccb Available Commands\r\n\r\n### CLI Commands\r\n```bash\r\n# Authentication\r\numat-kli login # Interactive login\r\numat-kli logout # Logout current session\r\n\r\n# Academic\r\numat-kli results # View academic results\r\numat-kli courses # View registered courses\r\n\r\n# Assessment\r\numat-kli assess # Launch course assessment\r\numat-kli assess --auto # Automated assessment\r\numat-kli assess --manual # Manual assessment\r\n\r\n# Financial\r\numat-kli bills # View bills and payments\r\n\r\n# Profile\r\numat-kli profile # View/update profile\r\numat-kli profile --update-email # Update email address\r\n\r\n# Utilities\r\numat-kli export --results # Export academic results\r\numat-kli export --bills # Export financial data\r\n```\r\n\r\n## \ud83d\udd27 Configuration\r\n\r\n### Environment Variables\r\nCreate a `.env` file in your project directory:\r\n\r\n```env\r\n# Optional: Auto-login credentials\r\nUMAT_USERNAME=your_student_id\r\nUMAT_PASSWORD=your_password\r\n\r\n# Optional: API Configuration\r\nUMAT_API_TIMEOUT=30\r\nUMAT_MAX_RETRIES=3\r\n```\r\n\r\n### Configuration File\r\n```python\r\n# config.py\r\nUMAT_CONFIG = {\r\n 'api_base_url': 'https://student.umat.edu.gh/api',\r\n 'timeout': 30,\r\n 'max_retries': 3,\r\n 'auto_assessment_range': (3, 5), # Rating range for auto assessment\r\n}\r\n```\r\n\r\n## \ud83d\udee1\ufe0f Security Features\r\n\r\n- **\ud83d\udd10 Secure Authentication**: Encrypted credential storage\r\n- **\ud83d\udd12 Session Management**: Automatic session timeout and renewal\r\n- **\ud83d\udee1\ufe0f Data Protection**: Secure handling of sensitive student data\r\n- **\ud83d\udeab Rate Limiting**: Built-in API rate limiting to prevent abuse\r\n\r\n## \ud83d\udcca API Reference\r\n\r\n### StudentPortal Class\r\n```python\r\nclass StudentPortal:\r\n def login(username: str, password: str) -> bool\r\n def get_academic_results() -> Dict[str, Any]\r\n def get_student_bills() -> Dict[str, Any]\r\n def get_registered_courses() -> Dict[str, Any]\r\n def automated_course_assessment(comment: str = \"\") -> Dict[str, Any]\r\n def manual_course_assessment() -> None\r\n def update_profile(data: Dict[str, Any]) -> bool\r\n def export_data(data_type: str, format: str = \"json\") -> str\r\n```\r\n\r\n### API Manager\r\n```python\r\nclass APIManager:\r\n def submit_all_course_assessments(assessments: List[Dict], remarks: str) -> Dict\r\n def get_course_assessments() -> Dict[str, Any]\r\n def get_academic_results() -> Dict[str, Any]\r\n def get_student_bills() -> Dict[str, Any]\r\n```\r\n\r\n## \ud83c\udfa8 Examples\r\n\r\n### Automated Assessment with Custom Comments\r\n```python\r\nfrom umat_kit.student_portal import StudentPortal\r\n\r\nportal = StudentPortal()\r\nportal.login(\"your_id\", \"your_password\")\r\n\r\n# Automated assessment with custom comment\r\nresult = portal.automated_course_assessment(\r\n comment=\"Great semester! Learned a lot from all courses.\"\r\n)\r\n\r\nprint(f\"\u2705 Assessed {result['courses_submitted']} courses\")\r\nprint(f\"\ud83d\udcca Success Rate: {result['success_rate']}%\")\r\n```\r\n\r\n### Export Academic Data\r\n```python\r\n# Export results to JSON\r\nresults_file = portal.export_data(\"results\", format=\"json\")\r\nprint(f\"Results exported to: {results_file}\")\r\n\r\n# Export bills to CSV\r\nbills_file = portal.export_data(\"bills\", format=\"csv\")\r\nprint(f\"Bills exported to: {bills_file}\")\r\n```\r\n\r\n### Batch Operations\r\n```python\r\n# Check multiple students (if you have admin access)\r\nstudents = [\"student1\", \"student2\", \"student3\"]\r\nfor student_id in students:\r\n portal.login(student_id, get_password(student_id))\r\n portal.automated_course_assessment()\r\n portal.logout()\r\n```\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\r\n\r\n### Development Setup\r\n```bash\r\ngit clone https://github.com/Odeneho-Calculus/UMaT-Kit.git\r\ncd UMaT-Kit\r\npython -m venv venv\r\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Running Tests\r\n```bash\r\npytest tests/\r\n```\r\n\r\n## \ud83d\udcdd License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83c\udd98 Support\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/Odeneho-Calculus/UMaT-Kit/issues)\r\n- **Discussions**: [GitHub Discussions](https://github.com/Odeneho-Calculus/UMaT-Kit/discussions)\r\n\r\n## \ud83c\udfaf Roadmap\r\n\r\n- [ ] **Mobile App Integration**: React Native/Flutter companion app\r\n- [ ] **Telegram Bot**: Interactive Telegram bot interface\r\n- [ ] **Web Dashboard**: Web-based dashboard for portal management\r\n- [ ] **Notification System**: Email/SMS notifications for important updates\r\n- [ ] **Analytics**: Advanced analytics and reporting features\r\n- [ ] **Multi-University Support**: Extend support to other universities\r\n\r\n## \u2b50 Star History\r\n\r\n[](https://star-history.com/#Odeneho-Calculus/umat-kit&Date)\r\n\r\n---\r\n\r\n**Made with \u2764\ufe0f for UMAT students by students**\r\n\r\n*Simplifying student life, one API call at a time.* \ud83d\ude80\r\n",
"bugtrack_url": null,
"license": null,
"summary": "\ud83c\udf93 Complete UMAT Student Portal Toolkit - API client, automated course assessment bot, CLI interface, and utilities for UMAT students",
"version": "0.1.3",
"project_urls": {
"Source": "https://github.com/Odeneho-Calculus/UMaT-Kit",
"Tracker": "https://github.com/Odeneho-Calculus/UMaT-Kit/issues"
},
"split_keywords": [
"umat",
" student-portal",
" api-client",
" course-assessment",
" automation",
" cli",
" education"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5d6f09725bae22f9c2e010e55d588cd37d58c9b8c8214364dd0394a575df1d4c",
"md5": "5648d8f1eeb0160b228350927539343e",
"sha256": "635e330920872d7ac90cc2a0609e3a3496e2591d09807bcfe15178f401004cda"
},
"downloads": -1,
"filename": "umat_kit-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5648d8f1eeb0160b228350927539343e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 108993,
"upload_time": "2025-08-18T00:49:06",
"upload_time_iso_8601": "2025-08-18T00:49:06.640144Z",
"url": "https://files.pythonhosted.org/packages/5d/6f/09725bae22f9c2e010e55d588cd37d58c9b8c8214364dd0394a575df1d4c/umat_kit-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ea827edb11b87e1f59ff2128b7241e730070cc7c4d63a929e84ebbea6ad4ee5d",
"md5": "681e55f9e42507c3111dc5c22c6f98c1",
"sha256": "15a13fc182092b88b63c0b8ecb272fdfd513370e7f78703478c5dea0e415933a"
},
"downloads": -1,
"filename": "umat_kit-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "681e55f9e42507c3111dc5c22c6f98c1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 98920,
"upload_time": "2025-08-18T00:49:08",
"upload_time_iso_8601": "2025-08-18T00:49:08.239696Z",
"url": "https://files.pythonhosted.org/packages/ea/82/7edb11b87e1f59ff2128b7241e730070cc7c4d63a929e84ebbea6ad4ee5d/umat_kit-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 00:49:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Odeneho-Calculus",
"github_project": "UMaT-Kit",
"github_not_found": true,
"lcname": "umat-kit"
}
JSON
