TimeCraft_Backend/backend/README.md

# 🧠 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.