---
title: Stateful Reminder Agent
emoji: 📊
colorFrom: yellow
colorTo: yellow
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
short_description: Agent that manages user reminders with in-session memory
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

# ⏰ Stateful Reminder Agent (Timezone-Aware)

A simple agentic AI app to help you add, view, check, and delete reminders — now with **timezone support**! Built using Python and Gradio, this project showcases stateful behavior and time-based task handling in real-time.

---

## 🚀 Live Demo

👉 [Launch on Hugging Face Spaces](https://huggingface.co/spaces/ujwal55/Stateful_Reminder_Agent) *(Replace with your actual link)*

---

## 🧠 Features

- ✅ **Add Reminders** — set reminders using a chosen timezone.
- 🌍 **Timezone Support** — select from common timezones (e.g., Asia/Kolkata, UTC).
- 📋 **List Reminders** — shows upcoming reminders with time left.
- 🔔 **Check “What’s Next?”** — tells you if something is due right now.
- 🗑️ **Delete Reminders** — remove a reminder by exact time + timezone.
- 💾 **In-Session State** — reminders are stored in memory (not persisted).

---

## 📦 Tech Stack

- **Python 3.6+**
- **Gradio** — interactive UI
- **pytz** — for timezone-aware datetime handling

---

## 📁 File Structure

```

Stateful\_Reminder\_Agent/
├── app.py            # Main app logic
├── README.md         # This file
└── requirements.txt  # Dependencies

````

---

## 🧠 Agentic AI Concepts

This agent simulates key agentic AI principles:

- Maintains **session memory** of tasks (reminders)
- Responds to user input with **goal-oriented behavior**
- Operates with **real-time logic** and conditional decisions
- Supports **multi-function interaction** via tabs

---

## 🛠️ Setup & Run Locally

### 1. Clone the repo
```bash
git clone https://huggingface.co/spaces/ujwal55/Stateful_Reminder_Agent
cd Stateful_Reminder_Agent
````

### 2. Install dependencies

```bash
pip install -r requirements.txt
```

### 3. Run the app

```bash
python app.py
```

---

## 🧪 Example Usage

* **Add Reminder**
  ➤ Time: `2025-06-07 09:00`
  ➤ Message: `Join Turing Test Interview`
  ➤ Timezone: `Asia/Kolkata`

* **List All**
  → Shows upcoming reminders in your selected timezone.

* **Check "What's Next?"**
  → Tells if anything is due within the next 60 seconds.

* **Delete Reminder**
  → Input same time + timezone to remove.

---

## ⚠️ Known Limitations

* Data is not persisted — reminders are lost when session ends.
* No background scheduler (must manually press "What's Next?")
* Limited timezone dropdown (can be expanded easily)

---

## 💡 Possible Extensions

* Persist reminders with SQLite or JSON
* Use natural language input like: *"Remind me to drink water in 2 hours"*
* Add background trigger or sound alert
* Detect user’s timezone automatically (via browser)

---

👨‍💻 Built by [@ujwal55](https://huggingface.co/ujwal55) — aspiring Agentic AI Developer