README.md

---
title: LifeFlow AI - Intelligent Trip Planning System
emoji: 🗺️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: mit
short_description: Don't just plan the trip. Design the flow.
thumbnail: https://cdn-uploads.huggingface.co/production/uploads/660ffb10d1eab2dd6da8a060/0AFXUPGhKtD3K7RHYT-Ek.png

tags:
  - mcp-in-action-track-enterprise
  - mcp-in-action-track-consumer
  - mcp-in-action-track-creative
---

# ✨ LifeFlow AI: Intelligent Trip Planning System

<div align="center">
    <img src="https://cdn-uploads.huggingface.co/production/uploads/660ffb10d1eab2dd6da8a060/0AFXUPGhKtD3K7RHYT-Ek.png" alt="LifeFlow AI Banner" width="55%" />
</div>

<br>

[![Gradio](https://img.shields.io/badge/UI-Gradio%205.49.1-orange?style=flat-square&logo=gradio)](https://gradio.app/)
[![Agno](https://img.shields.io/badge/Orchestration-Agno-blueviolet?style=flat-square)](https://github.com/agno-agi/agno)
[![Python](https://img.shields.io/badge/Python-3.11-blue?style=flat-square&logo=python)](https://www.python.org/)
[![Docker](https://img.shields.io/badge/Docker-Enabled-2496ED?style=flat-square&logo=docker)](https://www.docker.com/)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)

> **Your journey, in perfect rhythm.**
> An enterprise-grade, multi-agent system that orchestrates your daily schedule using real-world data, hybrid AI architecture, and mathematical optimization.

---
## 👥 Team

### Team Information:
- **Man-Ho Li** - [@Marco310](https://huggingface.co/Marco310) - Lead Developer & AI Architect
- **Chen-Yang Yu** - [@LittleFish-Coder](https://huggingface.co/LittleFish-Coder) - Technical Consultant & Marketing Director


## 📺 Demo & Submission

### 🛠️ Technical Walkthrough
> **See the "Dual-Brain" architecture in action.** Watch how LifeFlow transforms a vague prompt into a fully optimized itinerary.
<div align="center">
  <a href="https://www.youtube.com/watch?v=2P0q4jzUuvE" target="_blank">
    <img src="https://img.youtube.com/vi/2P0q4jzUuvE/maxresdefault.jpg" alt="Watch LifeFlow AI Demo" width="55%" />
  </a>
  
  <br>
  <p style="color: #888; font-size: 0.9em; margin-top: 10px; margin-bottom: 0px;">
    <i>Click the image or the button below to watch the full demo</i>
  </p>

  <a href="https://www.youtube.com/watch?v=2P0q4jzUuvE">
    <img src="https://img.shields.io/badge/▶_Watch_on_YouTube-FF0000?style=for-the-badge&logo=youtube&logoColor=white" alt="Watch on YouTube">
  </a>
</div>

### 🎬 Product Trailer
> *Experience the vision.* Watch our cinematic trailer showing the "One Man Army" journey.
<br>
👉 [**Watch Product Trailer**](https://youtu.be/VWtx70UgI5A?si=RryKCfptJGAHm_DY)

### 📅 Submission Details
* **Submission Date:** November 2025
* **Social Media Post:** [🔗 View on LinkedIn](https://www.linkedin.com/posts/chen-yang-yu_huggingface-hackathon-activity-7400902296886239232-76vQ?utm_source=social_share_send&utm_medium=member_desktop_web&rcm=ACoAAEff6RgBH-oFavqAmJ2ym_c-fD-cGJqszig)


## 📖 Overview

**LifeFlow AI** is not just a chatbot; it's a **State Machine for Real-World Operations**. It solves the complexity of daily travel planning—considering traffic, weather, opening hours, and route optimization—by coordinating a team of specialized AI agents.

Unlike traditional AI planners that hallucinate locations, LifeFlow grounds every decision in **Real-Time Data** (Google Maps & OpenWeather) and uses **Mathematical Optimization** (TSP/OR-Tools) for routing.

### 🏆 Special Access for Reviewers
To ensure a smooth testing experience during the **15-day review period**, we have **pre-configured default API keys** in the environment.
* **Zero Setup:** You do NOT need to provide your own API keys for Google Maps, OpenWeather, or LLMs (Gemini-free tier, Groq-free).
* **Ready to Run:** Simply interact with the UI; the backend is fully authenticated.
* **Note:** These promotional keys have usage quotas and will be rotated after the review phase.


## 🚀 Key Innovation: Hybrid AI Architecture

We solve the "Trilemma" of AI Agents: **Cost vs. Speed vs. Intelligence**.

### 1. Dual-Brain System 🧠 + ⚡
Instead of using one expensive model for everything, LifeFlow uses a tiered approach:
* **Primary Brain (The Leader):** Uses high-reasoning models (e.g., **GPT-5, Gemini 2.5 Pro**) for complex intent understanding, team orchestration, and final report generation.
* **Acceleration Layer (The Muscle):** Uses ultra-fast, low-cost models (e.g., **Groq/Llama-3, Qwen 2.5, Gemini Flash-lite, GPT mini**) for high-volume tool execution (searching POIs, checking weather).

### 2. Context-Offloading Protocol 📉
Traditional agents paste massive JSON search results into the chat context, burning thousands of tokens.
* **LifeFlow's Approach:** Agents treat data like "Hot Potatoes."
* **Mechanism:** Raw data (reviews, photos, coordinates) is offloaded to a structured database immediately. Agents only pass **Reference IDs** (e.g., `scout_result_123`) to the next agent.
* **Result:** Token consumption reduced by **75%** (from ~80k to ~20k per run).

---

## 🤖 The Agent Team

LifeFlow orchestrates 6 specialized agents working in a strict pipeline:

1.  **📋 Planner:** Analyzes vague user requests (e.g., "I need to buy coffee and visit the bank") and converts them into structured JSON tasks.
2.  **👨‍✈️ Team Leader:** The State Machine orchestrator. Enforces SOPs and handles error recovery.
3.  **🗺️ Scout (Fast Mode):** Interacts with Google Places API to verify locations and retrieve coordinates.
4.  **⚡ Optimizer (Fast Mode):** Uses routing algorithms to solve the *Traveling Salesperson Problem (TSP)* with time windows.
5.  **🧭 Navigator (Fast Mode):** Calculates precise traffic impacts and generates polyline routes.
6.  **🌤️ Weatherman (Fast Mode):** Checks hyper-local weather forecasts for specific arrival times.
7.  **📊 Presenter:** Compiles all data (from the DB) into a human-readable, formatted report.

---

## 🛠️ Features

* **BYOK (Bring Your Own Key):** Secure client-side key management for Google Maps, OpenWeather, and LLMs.
* **Zero-Cost Validation:** Smart API testing mechanism that checks key validity without incurring charges.
* **Interactive Map:** Visualizes routes, stops, and alternative POIs using Folium.
* **Graceful Cancellation:** Cooperative signal handling to terminate background agents instantly.
* **Reactive UI:** Modern Gradio interface with real-time streaming and responsive layouts.

---

## ⚙️ Configuration

LifeFlow AI allows deep customization via the **Settings** panel:

### Supported Providers
* **Google Gemini:** 2.5 Pro, 2.5 Flash, 2.0 Flash.
* **OpenAI:** GPT-5, GPT-5-mini, GPT-4o-mini.
* **Groq:** Llama 3.3 70B, GPT-OSS 120B, Kimi K2.

### Fast Mode (Hybrid)
Enable **Fast Mode** in settings to offload search and routing tasks to Groq. 
This significantly reduces latency and API costs while maintaining high-quality reasoning for the final output.

---

## 🛠️ Tech Stack & Components

| Component | Technology                                                    | Description |
| :--- |:--------------------------------------------------------------| :--- |
| **Frontend** | [Gradio](https://www.gradio.app/)                             | Reactive UI with custom CSS, Stepper, and Map integration. |
| **Orchestration** | [Agno](https://github.com/agno-agi/agno)                      | Manages Agent state, memory, and team coordination. |
| **Tool Protocol** | [FastMCP](https://github.com/jlowin/fastmcp)                  | Exposes Python functions as standardized AI tools. |
| **Models** | [Google Gemini](https://ai.google.dev/)                       | **Flash** for Leader/Planner (Reasoning), **Flash-Lite** for Workers (Speed). |
| **Optimization** | [Google OR-Tools](https://developers.google.com/optimization) | Solves TSPTW (Traveling Salesperson Problem with Time Windows). |
| **Data Layer** | [SQLite](https://www.sqlite.org/index.html)                   | Local file-based repository for high-speed context offloading. |

---

## 💻 Local Installation

To run LifeFlow AI locally, follow these steps:

### Prerequisites
- Python 3.11+
- Virtualenv (recommended)

### Installation Steps

1. **Clone the repository**
```bash
   git clone [https://huggingface.co/spaces/MCP-1st-Birthday/LifeFlow-AI](https://huggingface.co/spaces/MCP-1st-Birthday/LifeFlow-AI)
   cd LifeFlow-AI
```
   
2. Create and activate a virtual environment
```bash
# Linux/MacOS
python -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
venv\Scripts\activate
```

3. Install dependencies
```bash
pip install -r requirements.txt
```

4. Set up Environment Variables Create a .env file in the root directory (optional if using UI for keys):
```env
# Search API
GOOGLE_MAPS_API_KEY=your_key_here
OPENWEATHER_API_KEY=your_key_here

# MODEL API
GOOGLE_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here
GROQ_API_KEY=your_key_here
```

5. Run the application
```bash
python app.py
```

## 📚 Documentation

Explore the technical details behind LifeFlow AI:

- [**🏗️ Architecture Design**](https://huggingface.co/spaces/MCP-1st-Birthday/LifeFlow-AI/blob/main/doc/ARCHITECTURE.md)
  > Deep dive into the **"Dual-Brain" system**, **Context Offloading**, and **Exclusive MCP Channels**.
  
- [**🤖 The Agent Team**](https://huggingface.co/spaces/MCP-1st-Birthday/LifeFlow-AI/blob/main/doc/AGENTS.md)
  > Detailed roster of our 6 specialized agents, their models, tools, and prompt strategies.

- [**🔧 Troubleshooting Guide**](https://huggingface.co/spaces/MCP-1st-Birthday/LifeFlow-AI/blob/main/doc/TROUBLESHOOTING.md)
  > Solutions for common API errors (Google/OpenWeather), JSON parsing issues, and Docker setup.

## 🙌 Acknowledgements

A huge thank you to the tools and frameworks that made LifeFlow AI possible:

* **[Agno](https://github.com/agno-agi/agno)** (formerly Phidata): For providing the robust Agentic framework that powers our Scout, Weatherman, and Optimizer agents.
* **[Google Maps Platform](https://developers.google.com/maps)**: For the comprehensive Places and Routes APIs that ground our agents in real-world data.
* **[Google OR-Tools](https://developers.google.com/optimization)**: For the powerful routing optimization algorithms.
* **[Gradio](https://gradio.app/)**: For enabling the rapid development of our interactive UI.
* **[MCP-1st-Birthday](https://huggingface.co/MCP-1st-Birthday)**: For the inspiration!

## ⚠️ Disclaimer
This application uses the **Google Maps Platform API**, which is a paid service.
* **Cost:** Users are responsible for any costs incurred by their API usage.
* **Optimization:** While LifeFlow AI is designed to be efficient, running multiple agents can consume API quotas quickly.
* **Advice:** We strongly recommend setting up **Budgets & Alerts** and **Quotas** in your Google Cloud Console before running this app extensively.

## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.