Add README.md
This commit is contained in:
Hardik Sankhla
177
README.md
Normal file
177
README.md
Normal file
@@ -0,0 +1,177 @@
|
||||
# 🧠 AI-Powered Schedule and Task Planning Backend
|
||||
|
||||
This repository contains the backend service for an intelligent schedule and task planning application. It leverages a **Large Language Model (LLM)** (currently using **Qwen1.5–4B via Ollama**) to transform natural language tasks with complex recurrence rules into structured, conflict-free daily schedules.
|
||||
|
||||
---
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- **Intelligent Scheduling**: Uses a powerful LLM to understand and structure time-bound tasks.
|
||||
- **Flexible Task Input**: Supports daily, weekly, monthly recurrence with specific time rules.
|
||||
- **Advanced Recurrence Handling**: Supports “every 2nd Saturday” or “last Monday of month”.
|
||||
- **Structured JSON Output**: Returns clean machine-readable schedules.
|
||||
- **Pluggable LLM Backend**: Switch between Ollama, HuggingFace, or any generic API.
|
||||
- **FastAPI + Swagger UI**: For live API testing and documentation.
|
||||
- **Dockerized**: Easily run the entire system with Docker Compose.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Technologies Used
|
||||
|
||||
- **FastAPI** – high-performance API framework
|
||||
- **Pydantic** – data validation & schema
|
||||
- **HTTPLX** – async HTTP client for LLM
|
||||
- **Ollama** – running Qwen1.5–4B locally
|
||||
- **Docker + Compose** – containerization
|
||||
- **Python 3.10+**
|
||||
|
||||
---
|
||||
|
||||
## 📂 Project Structure
|
||||
|
||||
```bash
|
||||
backend/
|
||||
├── main.py # FastAPI entry point
|
||||
├── requirements.txt # Python dependencies
|
||||
├── Dockerfile # Docker image config
|
||||
├── docker-compose.yml # Docker orchestration
|
||||
├── .env # Runtime config
|
||||
└── app/
|
||||
├── models/
|
||||
│ └── task.py # Task schemas
|
||||
├── api/
|
||||
│ └── endpoints.py # FastAPI endpoints
|
||||
└── services/
|
||||
└── llm_service.py # LLM interaction layer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
`.env` example:
|
||||
|
||||
```env
|
||||
FRONTEND_URL=http://localhost:3000
|
||||
LLM_PROVIDER=OLLAMA
|
||||
OLLAMA_MODEL_NAME=qwen:4b
|
||||
OLLAMA_API_URL=http://localhost:11434/api/generate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📅 Weekly Task Schedule Visualization (Sample Week: July 14–20, 2025)
|
||||
|
||||
| Time | Mon (14) | Tue (15) | Wed (16) | Thu (17) | Fri (18) | Sat (19) | Sun (20) |
|
||||
|--------------|----------------------------------|----------------------------------|----------------------------------|----------------------------------|----------------------------------|----------------------------------|----------------------------------|
|
||||
| 06:00–07:00 | 🟢 🧘 Workout (Flexible) | 🟢 🧘 Workout (Flexible) | 🟢 🧘 Workout (Flexible) | 🟢 🧘 Workout (Flexible) | 🟢 🧘 Workout (Flexible) | 🟢 🧘 Workout (Flexible) | 🟢 🧘 Workout (Flexible) |
|
||||
| 07:00–08:00 | ⭐ 🧘 Workout (Preferred) | ⭐ 🧘 Workout (Preferred) | ⭐ 🧘 Workout (Preferred) | ⭐ 🧘 Workout (Preferred) | ⭐ 🧘 Workout (Preferred) | ⭐ 🧘 Workout (Preferred) | ⭐ 🧘 Workout (Preferred) |
|
||||
| 08:30–09:00 | ☕ Coffee Break | ☕ Coffee Break | ☕ Coffee Break | ☕ Coffee Break | ☕ Coffee Break | | |
|
||||
| 09:00–09:15 | 🔒 ⚠️ Stand-up + Scrum 🎯 | 🔒 ⚠️ Stand-up + Scrum 🎯 | 🔒 ⚠️ Stand-up + Scrum 🎯 | 🔒 ⚠️ Stand-up + Scrum 🎯 | 🔒 ⚠️ Stand-up + Scrum 🎯 | | |
|
||||
| 09:15–10:00 | ⚠️ Scrum Continues 🎯 | ⚠️ Scrum Continues 🎯 | ⚠️ Scrum Continues 🎯 | ⚠️ Scrum Continues 🎯 | ⚠️ Scrum Continues 🎯 | | |
|
||||
| 10:00–11:00 | 🟢 Flex / Board Review | 🔒 🧑💼 Exec Meeting | 🟢 Financial Reporting | 🔒 🧑💼 Deep Code Review | 🟢 🎯 Team Activity | | |
|
||||
| 11:00–12:00 | 🟢 Report Prep ⭐ | 🟢 Report Prep ⭐ | 🟢 Code Review / Reporting | 🔒 Code Finalization 🧑💼 | 🟢 🎯 Team Activity Cont. | 🔒 🧘 HR Audit (2nd Sat) | |
|
||||
| 12:00–13:00 | 🍽 Lunch | 🍽 Lunch | 🍽 Lunch | 🍽 Lunch | 🍽 Lunch | 🍽 Lunch | 🍽 Lunch |
|
||||
| 13:00–14:00 | ⭐ Board Meeting Prep | ⭐ Board Meeting Prep | ⭐ Board Meeting Prep | 🟢 Buffer | 🟢 Buffer | 🟢 Flex Task | 🟢 Flex Task |
|
||||
| 14:00–17:00 | 🟢 Deep Work Block | 🟢 Deep Work | 🟢 Deep Work | 🟢 Deep Work | 🟢 Deep Work | 🟢 Flex Time | 🟢 Flex Time |
|
||||
| 18:00–19:00 | 🧘 Workout (Fallback) | 🧘 Workout (Fallback) | 🧘 Workout (Fallback) | 🧘 Workout (Fallback) | 🧘 Workout (Fallback) | 🧘 Workout (Fallback) | 🧘 Workout (Fallback) |
|
||||
| 21:00–22:00 | 🧘 Wind-down | 🧘 Wind-down | 🧘 Wind-down | 🧘 Wind-down | 🧘 Wind-down | 🧘 Wind-down | 🧘 Wind-down |
|
||||
|
||||
**Legend**:
|
||||
🔒 Fixed • ⚠️ Conflict • ⭐ Preferred • 🟢 Flexible • 🧘 Personal • 🧑💼 Work • 🎯 High Impact
|
||||
|
||||
---
|
||||
|
||||
## 📬 API Endpoint: `/api/v1/schedule/tasks`
|
||||
|
||||
**POST Request** with list of tasks → returns intelligent JSON schedule.
|
||||
|
||||
Example input:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"type": "daily",
|
||||
"task_name": "Daily Stand-up",
|
||||
"task_description": "Critical morning sync.",
|
||||
"time_settings": {
|
||||
"start_time": "09:00",
|
||||
"end_time": "09:15"
|
||||
},
|
||||
"category": "work",
|
||||
"repeat_on_1": "Every weekday",
|
||||
"repeat_on_2": ["M", "T", "W", "T", "F"],
|
||||
"reminder_on": {
|
||||
"is_active": true,
|
||||
"numeric_input": 10,
|
||||
"time_unit": "Minutes"
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```json
|
||||
{
|
||||
"scheduled_tasks": [
|
||||
{
|
||||
"task_name": "Daily Stand-up",
|
||||
"date": "2025-07-14",
|
||||
"start_time": "09:00",
|
||||
"end_time": "09:15",
|
||||
"category": "work",
|
||||
"original_task_id": "task1"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Swagger UI
|
||||
Visit: `http://localhost:8000/docs` → Try `/api/v1/schedule/tasks`
|
||||
|
||||
### Curl
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/schedule/tasks \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '[{"type":"daily", "task_name":"Daily Stand-up", "task_description":"Sync","time_settings":{"start_time":"09:00","end_time":"09:15"},"category":"work","repeat_on_1":"Every weekday","repeat_on_2":["M","T","W","T","F"],"reminder_on":{"is_active":true,"numeric_input":10,"time_unit":"Minutes"}}]'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ LLM Configuration
|
||||
|
||||
**Current Provider**: `OLLAMA`
|
||||
**Model Used**: `qwen:4b`
|
||||
**API URL**: `http://localhost:11434/api/generate`
|
||||
|
||||
Switch to `HUGGINGFACE` or `GENERIC_API` by editing `.env`.
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Troubleshooting
|
||||
|
||||
- **422 Unprocessable Entity**: Add fallback logic in `llm_service.py` for null times.
|
||||
- **500 Server Error**: LLM may not be running or wrong model name.
|
||||
- **Fix Conflicts**: Use better prompts or larger models for conflict resolution.
|
||||
|
||||
---
|
||||
|
||||
## 💡 Future Enhancements
|
||||
|
||||
- Conflict resolver + dependency chains
|
||||
- User sessions & database storage
|
||||
- Calendar frontend (React)
|
||||
- Notification/reminders
|
||||
- Team role scheduling
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License – See `LICENSE` file.
|
||||
|
||||
Reference in New Issue
Block a user