balaji958685/attendance-compliance-agent

Attendance Compliance Agent

A fully functional FastAPI-based attendance tracking system compliant with VFSTR R22 regulations. It handles session scheduling, attendance percentage calculations, On-Duty (OD) leave workflows, condonation processing, holiday calendar integration, and report generation in JSON/CSV/XLSX formats.

Quick Start

pip install -r requirements.txt
uvicorn app.main:app --reload

Open http://localhost:8000/docs for interactive API documentation.

Project Structure

attendance_agent/
├── app/
│   ├── main.py                    # FastAPI entry point
│   ├── models.py                  # SQLAlchemy ORM models + SQLite
│   ├── attendance_calculator.py   # Attendance % logic with R22 rules
│   ├── timetable.py               # Slot & session management
│   ├── holidays.py                # Holiday calendar integration
│   ├── od_workflow.py             # Faculty→HOD OD approval chain
│   ├── condonation.py             # Condonation rules (65%/55% thresholds)
│   ├── report.py                  # JSON, CSV, XLSX report exports
│   └── routers/
│       ├── students.py            # Student CRUD
│       ├── subjects.py            # Subject CRUD
│       ├── timetable_routes.py    # Timetable & session endpoints
│       ├── attendance.py          # Mark attendance & calculate %
│       ├── od_routes.py           # OD request/approval APIs
│       ├── condonation_routes.py  # Condonation APIs
│       ├── holidays_routes.py     # Holiday APIs
│       └── reports_routes.py      # Report generation APIs
├── tests/
│   ├── test_full.py               # 27 comprehensive unit tests
│   └── integration_test.py        # End-to-end integration test
└── requirements.txt

Core Features

Attendance Calculation

• Formula: Attended Sessions / Total Sessions × 100
• Excludes holidays automatically
• OD counts as present after approval
• Handles Lecture (L), Tutorial (T), Practical (P) session types

VFSTR R22 Rules

Percentage	Status
≥ 75%	Eligible
65–74%	First condonation (with fee)
55–64%	Second condonation (if first approved)
< 55%	Not eligible / repeat course

Session Management

• Timetable slots define weekly recurring schedules
• Sessions auto-generated for dates matching slots
• No duplicates generated
• Holiday dates skip session creation

OD Workflow

Student Request → Faculty Review → HOD Approval → Attendance Updated

Report Types

• Daily Attendance — per-session records
• Subject-wise Summary — % per student per subject
• Monthly Report — attendance trends
• Defaulter Report — students below 75%
• OD/Condonation Report — pending and processed requests

Export Formats

• JSON (default)
• CSV
• XLSX (Excel)

Testing

# Unit tests (27 tests)
pytest tests/test_full.py -v

# Integration test (requires server running)
python tests/integration_test.py

API Endpoints

Feature	Endpoint
Health	GET /health
Students	POST /students/, GET /students/
Subjects	POST /subjects/, GET /subjects/
Timetable Slots	POST /timetable/slots, GET /timetable/slots
Generate Sessions	POST /timetable/generate-sessions/{date}
Mark Attendance	POST /attendance/mark
Calculate %	POST /attendance/calculate
Defaulters	GET /attendance/defaulters/{section}
OD Request	POST /od/
OD Faculty Approval	POST /od/{id}/approve-faculty
OD HOD Approval	POST /od/{id}/approve-hod
Condonation	POST /condonation/, POST /condonation/{id}/approve
Holidays	POST /holidays/, GET /holidays/
Reports	POST /reports/ (json/csv/xlsx)

Dependencies

• FastAPI ≥ 0.110.0
• SQLAlchemy ≥ 2.0.0
• Pydantic ≥ 2.6.0
• openpyxl ≥ 3.1.0
• pytest ≥ 8.0.0

Generated by ML Intern

This model repository was generated by ML Intern, an agent for machine learning research and development on the Hugging Face Hub.

• Try ML Intern: https://smolagents-ml-intern.hf.space
• Source code: https://github.com/huggingface/ml-intern

Usage

from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "balaji958685/attendance-compliance-agent"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id)

For non-causal architectures, replace AutoModelForCausalLM with the appropriate AutoModel class.