From 53f976c0b8a2cae0a1bddebb3e646b07db2c5832 Mon Sep 17 00:00:00 2001 From: Hardik Sankhla Date: Fri, 27 Jun 2025 05:58:14 +0530 Subject: [PATCH] Add README.md --- README.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2ca1b28 --- /dev/null +++ b/README.md @@ -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. +