ATLAS (Attendance Tracking & Leave Analytics System)

ATLAS is a robust Python engine designed to seamlessly manage academic attendance, project semester timelines, and safely simulate leave (bunking) without corrupting your baseline data.

Built with native Excel Windows COM integration and an automated Almanac JSON parser, ATLAS transforms static attendance tracking into a highly predictive analytics tool. It now features a sleek, dark-mode desktop GUI alongside a lightning-fast CLI.

🚀 Key Features

• Sleek Desktop GUI: Powered by customtkinter, the interactive dashboard features a live calendar to visualize holidays, bunks, and projections.
• Customizable Daily Schedule: Easily configure how many classes you have on each day of the week (Monday-Sunday). ATLAS dynamically applies these to your Excel formulas.
• AI-Powered Almanac Integration: Feed ATLAS your academic calendar JSON, and it will mathematically map out your entire semester, automatically filtering out weekends, holidays, and examination blocks.
• Bunk Simulation Engine: Safely test the mathematical impact of skipping a class. ATLAS projects your target attendance (e.g., 75%) and warns you of any timeline delays before you officially record the absence.
• Native Excel Automation: Uses Windows COM to silently auto-refresh and recalculate live Excel formulas in the background—no manual saving or opening required.
• Dynamic Holiday Management: Instantly add or remove public holidays directly from the calendar UI or CLI, dynamically rewriting your live tracker on the fly.

🛠️ Setup & Installation

⚡ Option 1 — Download the EXE (Recommended, No Python Required)

1. Go to the Releases page.
2. Download the latest ATLAS.zip.
3. Unzip it anywhere and run ATLAS.exe. That's it!

No Python, no pip, no setup. Just download and run.

🐍 Option 2 — Run from Source (Python)

1. Clone the repository:

   git clone https://github.com/bdwarker/ATLAS.git
   cd ATLAS

2. Install dependencies:

   pip install openpyxl customtkinter tkcalendar

3. Run the Application:
   • To launch the GUI:

     python gui.py

   • To launch the CLI:

     python main.py

🧠 Extracting Your Almanac (The Magic Prompt)

To fully automate your semester timeline, you need an almanac.json file. You can easily generate this by providing your college's Academic Calendar (PDF/Images) to any LLM (ChatGPT, Gemini, Claude) along with the following prompt:

System Prompt for AI: I am uploading my college Academic Calendar (Almanac) and my list of holidays. Please analyze these documents and extract the timeline for the current/upcoming semester.

I need you to output the data strictly in the following JSON format, with absolutely no markdown formatting, no backticks, and no extra text. Only provide the raw JSON. Dates must be in YYYY-MM-DD format.

{ "semester_start_date": "YYYY-MM-DD", "semester_end_date": "YYYY-MM-DD", "holidays": [ {"date": "YYYY-MM-DD", "name": "Holiday Name"} ], "exams": [ {"start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD", "name": "Exam Name"} ] }

Instructions:

1. Find the official start date of class work and the final working date (or end of semester date).
2. List all single-day holidays in the holidays array.
3. For exams (Mid-terms, finals, practicals), list them in the exams array with their start and end dates.
4. Ensure year accuracy based on the academic year.

Save the AI's response as almanac.json in the root directory of the project.

🖥️ Usage Guide

GUI Overview

• Dashboard: View a real-time snapshot of your attendance (Attended / Total), your current percentage, and the projected date to hit your target percentage.
• Calendar & Bunk Simulator: A fully interactive calendar. Bunks are highlighted in orange, holidays in red. Click any date to view attendance details, mark it as a holiday, or simulate skipping classes for that day.
• Tracker Setup: Automatically generate your Excel tracker using the AI almanac.json, manually build one, or completely customize your daily class schedule.

CLI Overview

When you run python main.py, you'll be greeted with the interactive terminal:

1. Auto-Build from Almanac JSON: Generates a fresh tracker starting from today until the end of the semester.
2. Generate Base Tracker Manually: Allows you to specify the duration and manually build the tracker.
3. Simulate / Record a Bunk: Tests the mathematical impact of a bunk against the baseline spreadsheet.
4. Manage College Holidays: Manually append or remove holidays.
5. Manage Class Schedule: Define exactly how many classes occur on Monday-Sunday.
6. View Current Status: Quick terminal printout of your current standing and recorded bunks.