🧠 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

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:

FRONTEND_URL=http://localhost:3000
LLM_PROVIDER=OLLAMA
OLLAMA_MODEL_NAME=qwen:4b
OLLAMA_API_URL=http://localhost:11434/api/generate

---

🛠️ Getting Started

✅ Prerequisites

• Docker & Docker Compose installed
• Ports 8000 (API) and 11434 (Ollama) available
• At least 8GB RAM recommended

---

📦 Installation & Setup

1. Clone the Repository

git clone https://github.com/yourusername/timecraft-backend.git
cd timecraft-backend/backend

2. Create .env File

Update environment variables:

cp .env

Or manually create .env with the following content:

FRONTEND_URL=http://localhost:3000
LLM_PROVIDER=OLLAMA
OLLAMA_MODEL_NAME=qwen:4b
OLLAMA_API_URL=http://localhost:11434/api/generate

3. Start Services with Docker

docker-compose up -d --build

This will:

• Build and run the FastAPI backend

• Launch Ollama and ensure the LLM is ready

4. Pull the Required Model (One-Time)

docker exec ollama ollama pull qwen:4b

Once the model is pulled, it will persist in the Ollama volume.

---

📅 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:

[
  {
    "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:

{
  "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

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.