umat-kit 0.1.3

🎓 Complete UMAT Student Portal Toolkit - API client, automated course assessment bot, CLI interface, and utilities for UMAT students

🎓 UMAT Kit - Complete Student Portal Toolkit

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)

pip install umat-kit

Install from Source

git https://github.com/Odeneho-Calculus/UMaT-Kit.git
cd UMaT-Kit
pip install -e .

🎯 Quick Start

CLI Interface

# Launch the interactive CLI
umat-kli ui

# Direct login
umat-kli login --username your_student_id

# View help
umat-kli --help

Python API

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:

# 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

# 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:

# 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

# 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

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

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

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

# 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

# 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 for details.

Development Setup

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

pytest tests/

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub 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

---

Made with ❤️ for UMAT students by students

Simplifying student life, one API call at a time. 🚀