Add README.md

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.
+