AI Planner

A full-stack AI application that generates personalised plans from a single goal.

Built with Microsoft AutoGen (ag2) and React. Three specialised agents — Planner, Retriever, and Executor — each own a fixed tool set and cover a distinct pipeline stage, limiting LLM usage to exactly 3 calls per run.

---

Live Demo

Service	URL
Backend API	https://ai-unlocked-backend--0000001.delightfulplant-f1a77e99.southeastasia.azurecontainerapps.io
Frontend URL	https://ai-unlocked-frontend.delightfulplant-f1a77e99.southeastasia.azurecontainerapps.io/
Docker Hub (backend)	jayansh805/ai-unlocked-backend:latest
Docker Hub (frontend)	jayansh805/ai-unlocked-frontend:latest

---

Architecture

Browser (React 7-step Wizard)
    │  POST /api/plan
    ▼
FastAPI (api.py)
    │  run_workflow(brief)
    ▼
Stage 1 — Planner Agent      (LLM call #1)
  Tools: parse_uploaded_document, check_plan_feasibility
  Output: GOAL_TYPE · TOPICS · WEEKS · WARNINGS

Stage 2 — Retriever Agent    (LLM call #2)
  Tools: build_schedule, build_milestones, build_resources, build_reminders
  Output: 4 data blocks → shared-state dict

Stage 3 — Executor Agent     (LLM call #3)
  Tools: save_plan
  Output: formatted plan file (txt / pdf / ical / xlsx)

Each agent has its own dedicated UserProxyAgent; tools are never shared across agents. Results flow through shared-state dicts — no chat-history parsing required.

---

Project Structure

AI_UNLOCKED-/
├── backend/
│   ├── api.py                  # FastAPI — POST /api/plan, GET /api/health
│   ├── cli.py                  # Interactive CLI entry point
│   ├── requirements.txt
│   ├── Dockerfile
│   ├── agents/
│   │   ├── planner.py          # Stage 1: goal decomposition + feasibility
│   │   ├── retriever.py        # Stage 2: schedule, milestones, resources, reminders
│   │   └── executor.py         # Stage 3: final assembly + file save
│   ├── tools/
│   │   ├── document_parser.py  # PDF / Excel / CSV / txt extraction
│   │   ├── conflict_detector.py# Feasibility heuristics (risk: low/medium/high)
│   │   ├── schedule_tool.py    # Week-by-week / day-by-day schedule generator
│   │   ├── resource_tool.py    # Curated resource DB (20+ CS/tech topics)
│   │   ├── reminder_tool.py    # Goal-type-aware reminder routines
│   │   └── output_builder.py   # Multi-format output: txt, pdf, ical, xlsx
│   ├── orchestrator/
│   │   └── workflow.py         # run_workflow(brief) — 3-stage pipeline
│   └── config/
│       └── llm_config.py       # Groq + Llama 3.3 70B, temperature=0.3
├── frontend/
│   ├── Dockerfile              # Multi-stage: Node 20 build → nginx:alpine
│   ├── nginx.conf
│   ├── vite.config.js          # Dev proxy /api → 127.0.0.1:8000
│   └── src/
│       ├── App.jsx
│       ├── pages/Index.jsx     # 7-step wizard shell + API call
│       └── components/         # Sidebar, steps, plan display
├── docker-compose.yml
└── README.md

---

API Reference

POST /api/plan

Field	Type	Default	Description
goal	string	required	Learning / project goal (≥ 5 chars)
doc_path	string	""	Path to PDF / Excel / CSV / txt file
planning_value	int	0	Duration value (0 = AI decides)
planning_unit	string	"weeks"	"weeks" or "days"
preferred_weeks	int	0	Override duration in weeks
hours_per_day	float	2.0	Available focused hours per day (0.5–16)
user_level	string	"intermediate"	beginner | intermediate | advanced
output_format	string	"text"	text | pdf | ical | excel
constraints	string	""	Free-form constraints (e.g. "no weekends")
start_date	string	today	YYYY-MM-DD

Response:

{
  "final_plan": "...",
  "output_file": "/tmp/plan_learn_react_20260310_120000.txt",
  "conflicts": { "risk_level": "low", "warnings": [], "suggestions": [] },
  "goal_type": "learning"
}

GET /api/health

{ "status": "ok", "date": "2026-03-10" }

---

Environment Variables

Variable	Required	Description
GROQ_API_KEY	Yes	Groq API key — console.groq.com
VITE_BACKEND_URL	No	Backend base URL (no trailing slash). Defaults to same-origin via Vite proxy in dev.

---

Running Locally

Prerequisites

• Python 3.11+
• Node.js 20+
• A Groq API key

Backend

cd backend
echo "GROQ_API_KEY=gsk_your_key_here" > .env
pip install -r requirements.txt
uvicorn api:app --reload --port 8000
# or interactively:
python cli.py

Frontend

cd frontend
npm install
npm run dev   # http://localhost:5173 (proxied to backend)

Docker Compose

# Ensure backend/.env contains GROQ_API_KEY
docker-compose up --build

Service	URL
Frontend	http://localhost:3000
Backend API	http://localhost:8000

---

Deployment

Build & Push

docker build -t jayansh805/ai-unlocked-backend:latest ./backend
docker build -t jayansh805/ai-unlocked-frontend:latest ./frontend
docker push jayansh805/ai-unlocked-backend:latest
docker push jayansh805/ai-unlocked-frontend:latest

Backend

Set GROQ_API_KEY as a secret in your container environment, then run:

docker run -p 8000:8000 \
  -e GROQ_API_KEY=your_key_here \
  jayansh805/ai-unlocked-backend:latest

Frontend

Set VITE_BACKEND_URL to the backend's public URL:

docker run -p 3000:80 \
  -e VITE_BACKEND_URL=https://your-backend-url.azurecontainerapps.io \
  jayansh805/ai-unlocked-frontend:latest

The frontend is served by nginx on port 80 (mapped to 3000) with SPA routing and gzip enabled.

---

Key Design Decisions

• 3 LLM calls, not N — each agent owns a fixed tool set; results travel via shared-state dicts, not re-parsed chat history.
• Isolated agent pairs — AssistantAgent + UserProxyAgent per stage keeps tool registration and reasoning fully scoped.
• Pure-Python tools — zero LLM calls inside any tool; all tools are deterministic and unit-testable.
• Format-agnostic output — output_builder.py produces txt, pdf (fpdf2), iCal (icalendar), or Excel (openpyxl) from the same data structure.
• Stateless pipeline — all 3 agents are factory functions; each build_*() call creates a fresh, independent (agent, proxy) pair.

---

Tool Ownership

Tool	Agent	Description
parse_uploaded_document	Planner	Parses PDF/Excel/CSV/txt → ~2000-char structured summary
check_plan_feasibility	Planner	Returns risk level + warnings; Planner self-corrects on HIGH risk
build_schedule	Retriever	Real-date week/day schedule with goal-type-adapted execution phases
build_milestones	Retriever	Quarterly checkpoints at 25/50/75/100% with review criteria
build_resources	Retriever	Books, courses, docs, platforms per topic (parallel lookups)
build_reminders	Retriever	Weekly reminders adapted to goal type
save_plan	Executor	Captures save params; workflow writes txt/pdf/ical/xlsx

---

Tech Stack

Component	Technology
Agent Framework	Microsoft AutoGen / ag2 v0.11.2
LLM	Llama 3.3 70B via Groq
API	FastAPI + Pydantic
Frontend	React + Vite + TanStack Query
PDF output	fpdf2
iCal output	icalendar
Excel output	openpyxl
Document parsing	pdfplumber, openpyxl
Container	Docker + Azure Container Apps
Language	Python 3.11+