# 🏫 SchoolOps Agent
### Autonomous AI Operations Manager for Schools
SchoolOps Agent is an AI-powered school operations system that helps administrators handle teacher absences and exam-supervision changes automatically.
When a teacher is absent, the agent can inspect the current exam schedule, check teacher availability, evaluate scheduling conflicts, select the best available replacement, update the exam assignment in Firestore, verify the change, and record an audit log.
The goal is to turn a manual school-operations task into a **safe, verifiable, autonomous workflow**.
---
## 🚀 What Problem Does SchoolOps Solve?
School administrators often need to react quickly when a teacher becomes unavailable.
A simple replacement process can involve:
1. Finding the teacher's exam assignment.
2. Checking which teachers are available.
3. Checking whether those teachers already have another exam.
4. Choosing the best replacement.
5. Updating the schedule.
6. Confirming that the update actually happened.
7. Keeping a record of what changed and why.
Doing this manually can be time-consuming and can introduce scheduling mistakes.
SchoolOps Agent automates this workflow while keeping the final database operation controlled and verifiable.
---
# 🤖 How SchoolOps Works
Example request:
**"Ahmed is absent tomorrow."**
The SchoolOps workflow:
Administrator Request
  │
  ▼
  SchoolOps Agent
  │
  ▼
Read Current Exam Schedule
  │
  ▼
Find Ahmed's Exam
  │
  ▼
Read Teacher Availability
  │
  ▼
Check Scheduling Conflicts
  │
  ▼
Select Best Replacement
  │
  ▼
Update Firestore
  │
  ▼
Verify Database Change
  │
  ▼
Create Audit Log
The system does not simply generate a recommendation.
It can **actually update the exam assignment and verify the resulting database state**.
---
# ✨ Key Features
## 1. Autonomous Teacher Replacement
The system identifies the exam supervised by an absent teacher and searches for suitable replacements.
Example:
Ahmed → Absent
Grade 8 English
09:00
Room 4
The system evaluates available teachers and selects the best valid candidate.
---
## 2. Availability-Based Selection
Teachers have availability information stored in Firestore.
Example:
Fatima
Status: Available
Available:
09:00
11:00
The workflow considers the teacher's availability when selecting a replacement.
When multiple teachers are suitable, the current workflow prefers the teacher with the **greatest availability**.
---
## 3. Conflict Detection
Before assigning a replacement teacher, SchoolOps checks the current exam schedule.
A teacher who already has an exam at the required time is rejected.
This prevents assignments such as:
Fatima
09:00 → Exam A
Fatima
09:00 → Exam B
---
## 4. Safe Database Updates
The replacement is not considered successful merely because an update command was executed.
The system:
1. Finds the affected exam.
2. Checks the replacement teacher.
3. Performs the update.
4. Reads the exam again.
5. Verifies that the new teacher is actually assigned.
Only then does the workflow report success.
---
## 5. Audit Logging
Every successful replacement is recorded in Firestore.
Example:
Action:
REPLACEMENT\_TEACHER\_ASSIGNED
Old Teacher:
Ahmed
New Teacher:
Fatima
Reason:
Ahmed is absent tomorrow. Selected the teacher
with the greatest availability and no scheduling conflict.
This provides a history of operational changes.
---
# 🧠 AI Agent
SchoolOps uses **Google ADK** with a Gemini model as the reasoning layer.
The agent has access to the following operational tools:
get\_exam\_schedule
get\_teacher\_availability
check\_teacher\_conflict
update\_exam\_schedule
The agent's instructions require it to:
* Inspect the real schedule.
* Identify the affected exam.
* Check teacher availability.
* Check scheduling conflicts.
* Select an appropriate replacement.
* Use the actual exam ID.
* Perform the database update.
* Verify the updated schedule.
* Never claim success unless the update succeeds.
This makes the AI agent operate as an **action-oriented operations manager**, rather than only a conversational chatbot.
---
# 🏗️ Architecture
┌───────────────────────────────┐
│ React Frontend │
│ │
│ Schedule / Teachers / Agent │
└───────────────┬───────────────┘
  │
  │ HTTP
  ▼
┌───────────────────────────────┐
│ FastAPI Backend │
│ │
│ REST API + Agent Runner │
└───────────────┬───────────────┘
  │
  ┌───────┴────────┐
  │ │
  ▼ ▼
┌───────────────┐ ┌───────────────┐
│ Google ADK / │ │ SchoolOps │
│ Gemini Agent │ │ Tools │
└───────────────┘ └───────┬───────┘
  │
  ▼
  ┌─────────────────┐
  │ Google Firestore│
  │ │
  │ Exams │
  │ Teachers │
  │ Audit Logs │
  └─────────────────┘
---
# 🛠️ Technology Stack
### Frontend
* React
* Vite
* JavaScript
* CSS
### Backend
* Python
* FastAPI
* Uvicorn
### AI
* Google ADK
* Gemini
* Google GenAI SDK
### Database
* Google Cloud Firestore
### Development
* Git
* GitHub
* Python virtual environment
---
# 📁 Project Structure
schoolops-agent/
│
├── backend/
│ ├── agent/
│ ├── agent.py
│ ├── database.py
│ ├── main.py
│ ├── tools.py
│ ├── .env
│ └── schoolops.db
│
├── frontend/
│ └── src/
│ └── App.jsx
│
├── docs/
│
├── tests/
│
├── main.py
├── .gitignore
└── README.md
.env, virtual environments, Python cache files, and database files are excluded from Git using.gitignore.
---
# ☁️ Firestore Data Model
SchoolOps currently uses three main Firestore collections.
## teachers
Example document:
teachers/fatima
{
  "name": "Fatima",
  "status": "Available",
  "available\_times": \[
  "09:00",
  "11:00"
  ]
}
Example teachers currently used by the project:
Ahmed
Ali
Fatima
Sara
---
## exams
Example document:
exams/grade8\_english
{
  "grade": "Grade 8",
  "subject": "English",
  "teacher": "Ahmed",
  "room": "Room 4",
  "time": "09:00"
}
Current demonstration schedule:
| Grade | Subject | Teacher | Room | Time |
| ------- | ----------- | ------- | ------ | ----- |
| Grade 8 | English | Ahmed | Room 4 | 09:00 |
| Grade 8 | Mathematics | Sara | Room 2 | 11:00 |
| Grade 8 | Science | Ali | Room 3 | 13:00 |
---
## audit\_logs
Successful operational changes are stored in:
audit\_logs
Example:
{
  "exam\_id": 1,
  "action": "REPLACEMENT\_TEACHER\_ASSIGNED",
  "old\_teacher": "Ahmed",
  "new\_teacher": "Fatima",
  "reason": "Ahmed is absent tomorrow. Selected the teacher with the greatest availability and no scheduling conflict.",
  "created\_at": "server timestamp"
}
---
# 🔐 Environment Variables
Create:
backend/.env
Add your Gemini API key:
GOOGLE\_API\_KEY=your\_gemini\_api\_key
Never commit the real API key.
The repository's .gitignore excludes:
.env
venv/
\_\_pycache\_\_/
\*.pyc
\*.db
---
# 💻 Local Setup
## 1. Clone the repository
git clone https://github.com/Iram-Khaliq/schoolops-agent.git
cd schoolops-agent
---
## 2. Create the Python environment
From the project root:
### Windows PowerShell
python -m venv backend\\venv
Activate it:
.\\backend\\venv\\Scripts\\Activate.ps1
---
## 3. Install backend dependencies
Install the required packages used by the project.
For example:
pip install fastapi uvicorn python-dotenv google-adk google-genai google-cloud-firestore
---
# ☁️ Google Cloud / Firestore Authentication
The project uses Google Application Default Credentials for Firestore.
After installing the Google Cloud CLI, authenticate:
gcloud auth application-default login
Set the project:
gcloud config set project schoolop
Verify:
gcloud config get-value project
Expected:
schoolop
The Firestore client is configured for the schoolop Google Cloud project.
---
# ▶️ Run the Backend
From:
D:\\schoolops-agent
activate the environment:
.\\backend\\venv\\Scripts\\Activate.ps1
Then start FastAPI:
python -m uvicorn backend.main:app --reload
The API runs at:
http://127.0.0.1:8000
---
# 🌐 API Endpoints
## Health Check
GET /
Returns:
{
  "message": "SchoolOps API is running"
}
---
## Get Exam Schedule
GET /api/exams
Returns the current Firestore exam schedule.
---
## Get Teacher Availability
GET /api/teachers
Returns teachers and their availability.
---
## Get Audit Logs
GET /api/audit-logs
Returns recorded operational changes.
---
## Update Exam
POST /api/update-exam
Updates an exam supervisor after conflict validation.
---
## Run Local SchoolOps Workflow
POST /api/run-workflow
Example request:
Ahmed is absent tomorrow
The endpoint identifies the absent teacher and executes the deterministic SchoolOps workflow.
---
## Run AI Agent
POST /api/test-agent
This endpoint sends the request through the Google ADK agent.
Example:
Ahmed is absent tomorrow
The ADK agent can inspect the schedule, use its tools, perform the replacement, and report the result.
---
# 🧪 Testing the Workflow
With the backend running, test the AI agent from PowerShell:
Invoke-RestMethod `
  -Uri "http://127.0.0.1:8000/api/test-agent?request=Ahmed%20is%20absent%20tomorrow" `
  -Method POST
A successful response contains:
success : True
mode : adk
The agent response describes the resulting schedule change.
---
# 🔎 Verify the Database
You can verify the exam assignment directly:
python -c "from backend.database import get\_exams; import pprint; pprint.pp(get\_exams())"
Example successful result:
Grade 8 English
Teacher: Fatima
Time: 09:00
The remaining schedule stays unchanged:
Grade 8 Mathematics
Teacher: Sara
Time: 11:00
Grade 8 Science
Teacher: Ali
Time: 13:00
---
# 🧾 Verify the Audit Log
Run:
python -c "from backend.database import get\_audit\_logs; import pprint; pprint.pp(get\_audit\_logs())"
You should see a record similar to:
action:
REPLACEMENT\_TEACHER\_ASSIGNED
old\_teacher:
Ahmed
new\_teacher:
Fatima
---
# 🧠 Example Decision
Suppose Ahmed is absent for the 09:00 English exam.
Available teachers:
Ali
Available: 09:00
Sara
Available: 09:00
Fatima
Available: 09:00, 11:00
The workflow checks:
Ali
09:00 → no conflict
Sara
09:00 → no conflict
Fatima
09:00 → no conflict
All three are valid candidates.
The current selection strategy prefers the teacher with the greatest availability:
Fatima → 2 available times
Ali → 1 available time
Sara → 1 available time
Therefore:
Ahmed → Fatima
The database is then updated and verified.
---
# 🛡️ Safety and Verification
SchoolOps is designed around several important safeguards.
### No invented schedules
The agent is instructed to use the database tools instead of inventing schedule information.
### Conflict prevention
A teacher with a conflicting exam assignment is rejected.
### Database-backed updates
The replacement is actually written to Firestore.
### Post-update verification
The system reads the schedule again after the update.
### Auditability
Successful changes are recorded in the audit log.
### No false success
The system does not report a successful replacement unless the update succeeds and can be verified.
---
# 🔄 AI Failure Handling
The backend also contains a deterministic local workflow.
This provides a useful fallback architecture:
  User Request
  │
  ▼
  Google ADK Agent
  │
  ┌──────┴──────┐
  │ │
  Available API/Quota
  │ Failure
  ▼ │
  AI Workflow ▼
  Local Workflow
  │
  ▼
  Firestore Update
This allows the core scheduling operation to remain deterministic even when the Gemini service is temporarily unavailable.
---
# 🎯 Why This Is an Agent
SchoolOps is designed around an agentic workflow rather than a simple question-answering chatbot.
The agent can:
Observe
  ↓
Reason
  ↓
Choose
  ↓
Act
  ↓
Verify
  ↓
Report
For example:
Observe:
Ahmed is absent.
Reason:
Ahmed supervises the 09:00 English exam.
Observe:
Fatima, Ali and Sara are available.
Reason:
Check their scheduling conflicts.
Choose:
Fatima has the greatest availability.
Act:
Update the exam assignment.
Verify:
Read the database again.
Report:
Ahmed was replaced by Fatima.
---
# 🏆 Hackathon Value
SchoolOps demonstrates several important AI-agent capabilities:
* Autonomous multi-step reasoning
* Tool calling
* Real database interaction
* Constraint-based decision making
* Conflict detection
* Persistent state
* Action execution
* Post-action verification
* Auditability
* Graceful fallback behavior
The important distinction is that the agent is not only generating text.
It can **take an operational action and verify the resulting state**.
---
# 📊 Current Project Status
| Component | Status |
| --------------------- | ------------- |
| React frontend | ✅ Working |
| FastAPI backend | ✅ Working |
| Google ADK agent | ✅ Working |
| Gemini integration | ✅ Tested |
| Firestore | ✅ Connected |
| Teacher collection | ✅ Working |
| Exam collection | ✅ Working |
| Conflict detection | ✅ Working |
| Automatic replacement | ✅ Working |
| Database verification | ✅ Working |
| Audit logging | ✅ Working |
| Git/GitHub | ✅ Configured |
| Cloud Run deployment | ⏳ Future step |
---
# 🔮 Future Improvements
Possible next steps include:
### Multi-exam optimization
Handle multiple absent teachers and optimize the complete exam schedule.
### Better constraint solving
Consider:
* Teacher subject expertise
* Grade preferences
* Room restrictions
* Maximum supervision load
* Teacher availability windows
### Authentication
Add administrator authentication and role-based access.
### Richer audit history
Provide filtering and reporting for historical scheduling changes.
### Notifications
Notify administrators and teachers when a replacement is assigned.
### Production deployment
Deploy the backend and frontend to production infrastructure.
### Persistent agent sessions
Move beyond the current demo session handling toward persistent operational conversations.
---
# 📸 Demo
Recommended demonstration flow:
1\. Open SchoolOps frontend
  ↓
2\. Show current exam schedule
  ↓
3\. Ask:
  "Ahmed is absent tomorrow."
  ↓
4\. Agent inspects schedule
  ↓
5\. Agent checks teacher availability
  ↓
6\. Agent checks conflicts
  ↓
7\. Agent selects Fatima
  ↓
8\. Firestore is updated
  ↓
9\. Agent verifies the assignment
  ↓
10\. Audit log is created
Expected result:
Grade 8 English
09:00
Ahmed → Fatima
---
# 🔗 Repository
GitHub:
**Iram-Khaliq/schoolops-agent**
---
# 👩💻 Author
**Iram Khaliq**
Software Engineer focused on building practical AI-powered applications and autonomous workflows.
---
# 📄 License
This project is currently intended as a hackathon/demo project.
A production license can be added when the project is prepared for public distribution.
Log in or sign up for Devpost to join the conversation.