Spaces:
Running
Running
File size: 6,433 Bytes
1afcb94 6d5e70c 1afcb94 f899746 1afcb94 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 |
# 🏗️ System Architecture
LifeFlow AI implements a novel **"Dual-Brain"** architecture combined with a **Context-Offloading Protocol** to solve the scalability issues of traditional Agentic workflows. This document details the system design, data flow, and infrastructure.
## 📐 High-Level Design
The system is built on a modular microservices-like architecture using **Agno (Phidata)** for orchestration and **FastMCP** for tool isolation.
```mermaid
graph TD
User[User Interface] -->|Gradio Websocket| App[Application Core]
App -->|Input Analysis| Planner[📋 Planner Agent]
subgraph "Core Team (State Machine)"
Leader[👨✈️ Team Leader]
Leader -->|Delegates| Scout[🗺️ Scout]
Leader -->|Delegates| Optimizer[⚡ Optimizer]
Leader -->|Delegates| Navigator[🧭 Navigator]
Leader -->|Delegates| Weatherman[🌤️ Weatherman]
Leader -->|Delegates| Presenter[📊 Presenter]
end
Planner -->|Task List JSON| Leader
subgraph "The 'Hot Potato' Data Pipeline"
direction LR
DB[(POI Repository / SQLite)]
Scout -.->|Write Raw POIs| DB
DB -.->|Read Ref ID| Optimizer
Optimizer -.->|Write Ordered List| DB
DB -.->|Read Opt ID| Navigator
Navigator -.->|Write Routes| DB
DB -.->|Read Nav ID| Weatherman
Weatherman -.->|Write Final Timeline| DB
end
```
## 🚀 Key Architectural Patterns
1. Context Offloading Protocol ("Hot Potato")
Traditional agents pass massive JSON blobs (search results, reviews, coordinates) back and forth in the chat context, quickly hitting token limits and causing hallucinations.
### LifeFlow's Solution:
- Data Isolation: Agents NEVER see the full data payload.
- Reference Passing: Agents only exchange Reference IDs (e.g., scout_result_123).
- Mechanism:
1. Scout finds 50+ locations, saves them to poi_repo, and returns {"scout_ref": "uuid"} to the Leader.
2. Leader passes this UUID to the Optimizer.
3. Optimizer loads data from the repo, solves the TSPTW problem, and saves the result.
* Result: Reduces token consumption by ~75% for complex trips.
2. Exclusive MCP Channels (Tool Isolation)
In standard multi-agent setups, all tools are often dumped into a shared context, confusing the LLM (e.g., the "Optimizer" trying to use "Weather" tools).
### LifeFlow's Solution (in app.py):
We implement a custom Lifecycle Manager that spins up isolated FastMCP connections for each agent.
- Scout Agent $\leftrightarrow$ Channel A (Only search_and_offload)
- Optimizer Agent $\leftrightarrow$ Channel B (Only optimize_from_ref)
- Navigator Agent $\leftrightarrow$ Channel C (Only calculate_traffic_and_timing)
This guarantees 100% Tool Usage Accuracy and prevents agents from hallucinating tool calls.
### 🔗 The Unifying Link: Shared State via Reference IDs
While the **Execution Channels** (A, B, C) are strictly isolated to prevent tool hallucinations, they share a **Unified State Layer**.
The "Glue" connecting these isolated environments is the **Database Reference ID** (e.g., `scout_ref_uuid`).
* **Mechanism:**
* **Channel A (Scout)** executes a search, writes the heavy JSON payload to the shared **POI Repository (DB)**, and returns *only* the ID `ref_123`.
* The **Leader Agent** passes `ref_123` to **Channel B (Optimizer)**.
* **Channel B** uses its tool (`optimize_from_ref`) to "hydrate" the data by reading `ref_123` from the same shared DB, processes it, and saves a new `ref_456`.
This architecture ensures that while **Tools are Private** (security & accuracy), **Data is Global** (accessibility).
```text
+-----------------------------+ +-------------------------+
| ⚡ EXECUTION CHANNELS | | 💾 UNIFIED STORAGE |
+-----------------------------+ +-------------------------+
(Write Data) +-------------------------+
1. [ Channel A: SCOUT ] ------------------------>| |
| | |
| (Pass Ref ID: "ref_123") | |
v | |
| POI REPOSITORY |
2. [ Channel B: OPTIMIZER ] <----(Read/Write)--->| (SQLite) |
| | |
| (Pass Ref ID: "ref_456") | |
v | |
| |
3. [ Channel C: NAVIGATOR ] <----(Read/Write)--->| |
+------------------------ +
```
## 🛠️ Tech Stack & Compon**ents**
| Component | Technology | Description |
| :--- |:------------------| :--- |
| **Frontend** | Gradio 5.49.1 | Reactive UI with custom CSS, Stepper, and Map integration. |
| **Orchestration** | Agno (Phidata) | Manages Agent state, memory, and team coordination. |
| **Tool Protocol** | FastMCP | Exposes Python functions as standardized AI tools. |
| **Models** | Google Gemini 2.5 | **Flash** for Leader/Planner (Reasoning), **Flash-Lite** for Workers (Speed). |
| **Optimization** | Google OR-Tools | Solves TSPTW (Traveling Salesperson Problem with Time Windows). |
| **Data Layer** | SQLite / JSON | Local file-based repository for high-speed context offloading. |
## 🔄 Data Flow Example
1. User Input: "Plan a day in SF, visit Pier 39 and get crab."
2. Planner: Converts to structured JSON Tasks.
3. Leader: Receives Tasks → Delegates to Scout.
> Scout: Calls Google Places API → Saves 20 candidates → Returns ref_scout.
4. Leader: Delegates to Optimizer.
> Optimizer: Loads ref_scout → Runs OR-Tools → Returns ref_opt (Sorted).
5. Leader: Delegates to Navigator.
> Navigator: Loads ref_opt → Calls Google Routes (Traffic) → Returns ref_nav.
6. Leader: Delegates to Weatherman.
> Weatherman: Loads ref_nav → Checks OpenWeather → Returns ref_final.
7. Leader: Delegates to Presenter.
> Presenter: Reads ref_final → Generates UI Report.
8. User sees a complete, optimized itinerary with maps and weather. |