🧰 LifeHelper

Full-stack AI Agent Workbench — Intent parsing, task decomposition, tool calling with retry & trace,
session replay, evaluation dashboard. A runnable product-style prototype, not a one-off prompt demo.

---

✨ Why LifeHelper?

Most AI "agent" demos are just a single prompt → response loop. Real agent applications need more: intent understanding, task decomposition, ordered tool execution, retry handling, trace observability, and evaluation — all tied together with a working frontend.

LifeHelper is a full-stack reference implementation of an AI Agent application that covers the entire lifecycle:

🤖 Intent → Plan → Tool Calls → Retry → Trace → Session Replay → Evaluation

It's built for portfolio walkthroughs and interview demonstrations — every component has mock fallback so it runs without paid API keys.

---

🚀 Quick Start

# 1. Clone & setup backend
cd backend
copy .env.example .env
pip install -r requirements.txt
uvicorn app.main:app --reload

# 2. Setup frontend (separate terminal)
cd frontend
npm install
npm run dev

# 3. Open http://localhost:5173 → start chatting with the agent

🔌 No API keys needed — mock providers are enabled by default for all tools.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                   React Frontend                     │
│  Chat Panel │ Task DAG │ Trace │ Replay │ Eval       │
└──────────────────────┬──────────────────────────────┘
                       │ REST + SSE
┌──────────────────────▼──────────────────────────────┐
│                 FastAPI Backend                       │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ Intents  │  │  Tasks   │  │  Tools (8 total)  │  │
│  │ Parser   │  │ Scheduler│  │  Search/Weather/   │  │
│  │          │  │          │  │  Route/Notes/Etc   │  │
│  └──────────┘  └──────────┘  └───────────────────┘  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ Provider │  │ Session  │  │  Evaluation Store │  │
│  │ (mock/   │  │ (memory/ │  │  (JSONL/PG)       │  │
│  │  real)   │  │  PG)     │  │                   │  │
│  └──────────┘  └──────────┘  └───────────────────┘  │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│        Storage: Redis / PostgreSQL / Celery           │
│              (optional, mock fallback)                │
└─────────────────────────────────────────────────────┘

---

📊 Features

Feature	Description
🧠 Intent Analysis	Parses user queries to identify task type and decompose into sub-steps
🔧 Tool Calling	8 tools: search, notes, calendar, weather, route, food, deals, image inspection
🔄 Retry & Fallback	Automatic retry with error categorization; mock providers when real APIs unavailable
📈 Trace & DAG	Per-request timing traces and task dependency graph visualization
🎬 Session Replay	Replay any past session step-by-step — intent, task graph, tool calls, final answer
📋 Evaluation Dashboard	Completion rate, retry rate, latency metrics, manual ratings, aggregation
🔐 Multi-Provider	Search (Tavily/SerpAPI/mock), Weather (Open-Meteo/mock), Map (AMap/Baidu/mock)
🌐 Full-Stack	FastAPI backend + React/TypeScript frontend + optional Redis/PostgreSQL/Celery
📄 Debug Reports	One-click Markdown debug report download for any session
🏗️ Docker Compose	One-command local stack: docker compose up --build
🔒 Auth (Optional)	Bearer token authentication gated by ENABLE_AUTH flag

---

🧪 Verification

# Backend tests
cd backend
py -m pytest
# → 112 passed (14 test files, covering API, auth, queue, service, session, provider, tools, intents, evaluation, debug report)

# Frontend build
cd frontend
npm install
npm run build
# → build passed, 0 vulnerabilities

---

📁 Repository Layout

LifeHelper/
├── backend/          # FastAPI backend, agent orchestration, tools, auth, persistence, tests
├── frontend/         # React + TypeScript demo UI (Ant Design, Vite)
├── docs/             # Architecture notes, showcase guide
├── scripts/          # Windows local / Docker helper scripts
└── docker-compose.yml

---

🔧 Tech Stack

Layer	Technology
Backend	Python, FastAPI, Pydantic v2, Celery, pytest
Frontend	React 18, TypeScript, Ant Design, Vite
Agent	Intent analysis, task decomposition, ordered tool execution
Storage	Redis, PostgreSQL, JSONL (auto-fallback)
Providers	Mock (default), Tavily, SerpAPI, Open-Meteo, AMap, Baidu Map
DevOps	Docker Compose, smoke-check.ps1

---

🌍 Public-Release Notes

This repo is safe for public demos with mock providers. Before publishing or sharing:

• Real .env / .env.local are gitignored — no keys committed
• backend/data/ local JSONL stores are gitignored
• Screenshots/debug reports do not include private prompts or keys
• Provider credentials configured only through environment variables

---

🗺️ Roadmap

• Add demo screenshots / walkthrough GIF
• Frontend code splitting (reduce Ant Design chunk size)
• Provider-backed prompts across more tools
• Auth hardening (OAuth2 / API key rotation)

---

🤝 Contributing

Pull requests welcome! For major changes, please open an issue first.

1. Fork the repo
2. Create a branch (git checkout -b feature/your-feature)
3. Run tests (cd backend && py -m pytest)
4. Submit a PR with description

---

📄 License

MIT © Hengwei Zhang

---

_{Built with ❤️ as a portfolio piece. Mock-first, always runnable.}