---
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
[](https://gradio.app/)
[](https://github.com/agno-agi/agno)
[](https://www.python.org/)
[](https://www.docker.com/)
[](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.
Click the image or the button below to watch the full demo
### ๐ฌ Product Trailer
> *Experience the vision.* Watch our cinematic trailer showing the "One Man Army" journey.
๐ [**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.
