README.md

---
title: Chatbot
emoji: 💻
colorFrom: yellow
colorTo: green
sdk: gradio
sdk_version: 6.6.0
app_file: app.py
pinned: false
short_description: Chatbot
---

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

# 🤖 Memory Chatbot

A multi-user, multi-thread AI chatbot with **short-term and long-term memory**, powered by LangGraph, LangChain, Groq (Qwen3-32B), and a Gradio UI. The chatbot can call a variety of tools and displays which tools were used directly in the chat interface.

---

## ✨ Features

| Feature | Description |
|---|---|
| 🧠 Short-term memory | Remembers conversation context within a thread using `InMemorySaver` |
| 💾 Long-term memory | Stores user preferences, profile, interests, and project info using `InMemoryStore` |
| 👥 Multi-user support | Each user has isolated memory and conversation threads |
| 🧵 Multi-thread support | Each user can have multiple independent chat sessions |
| 🔧 Tool use | 12 built-in tools (web search, weather, calculator, Python exec, and more) |
| 🏷️ Tool call badges | The UI shows which tools were called for each AI response |
| ⚡ Fast inference | Powered by Groq's ultra-fast LLM API |

---

## 🗂️ Project Structure

```
.
├── memory_chatbot.py   # LangGraph graph: memory nodes + agent chat node
├── app.py              # Gradio UI with multi-user / multi-thread support
├── tool.py             # All tool definitions (12 tools)
├── .env                # API keys (not committed)
└── README.md
```

---

## 🧩 Architecture

```
User Message
     │
     ▼
┌─────────────────┐
│ memory_analyzer │  ← Detects if message contains info worth storing long-term
└────────┬────────┘
         │
         ▼
┌──────────────────┐
│ memory_retrieval │  ← Searches long-term store and injects relevant memories
└────────┬─────────┘
         │
         ▼
┌───────────────┐
│   chat_node   │  ← LangChain agent with 12 tools; returns answer + tool log
└───────────────┘
         │
         ▼
    AI Response
  + Tool Call Badges
```

### Memory Types

- **Short-term (checkpointer):** Full conversation history per `thread_id`, managed automatically by LangGraph's `InMemorySaver`.
- **Long-term (store):** Key-value memories namespaced by `(user_id, category)`. Categories: `preferences`, `profile`, `interests`, `project`.

---

## 🔧 Tools

| Tool | Description |
|---|---|
| `tool_tavily` | Web search via Tavily API |
| `time_date` | Returns today's date |
| `calculator` | Evaluates math expressions |
| `python_exec` | Executes arbitrary Python code |
| `get_weather` | Current weather for any city |
| `wikipedia_search` | Wikipedia summary search |
| `scrape_website` | Extracts text from a URL |
| `read_file` | Reads a local file |
| `format_json` | Pretty-prints JSON |
| `generate_sql` | Converts natural language to SQL |
| `system_info` | Returns OS/platform info |
| `save_user_preference` | Saves a user preference to memory |

---

## 🚀 Setup

### 1. Clone & install dependencies

```bash
git clone <your-repo-url>
cd memory-chatbot
pip install -r requirements.txt
```

**Key dependencies:**

```
langgraph
langchain
langchain-groq
langchain-tavily
gradio
wikipedia
beautifulsoup4
requests
python-dotenv
```

### 2. Configure API keys

Create a `.env` file in the project root:

```env
GROQ_API_KEY=your_groq_api_key
TAVILY_API_KEY=your_tavily_api_key
```

Get your keys:
- Groq: https://console.groq.com
- Tavily: https://app.tavily.com

### 3. Run

```bash
python app.py
```

Then open http://localhost:7860 in your browser.

---

## 🖥️ UI Guide

```
┌─────────────────┬──────────────────────────────────────┐
│  👤 Users       │                                      │
│  ┌──────────┐   │   [Chat history appears here]        │
│  │ user_abc │   │                                      │
│  └──────────┘   │   User: What's the weather in Paris? │
│  [➕ New User]  │                                      │
│                 │   AI: It's 18°C and sunny in Paris.  │
│  🧵 Threads     │   🔧 get_weather                     │
│  ○ thread_123   │                                      │
│  ● thread_456   │                                      │
│  [➕ New Chat]  │   ┌─────────────────────────────┐    │
│                 │   │ Type message and press Enter │    │
└─────────────────┴───┴─────────────────────────────┴────┘
```

- **New User** — creates an isolated user with fresh memory and a new thread
- **New Chat** — starts a new thread for the current user (long-term memory is preserved)
- **Tool badges** — appear below each AI reply showing which tools were called

---

## 🔍 How Tool Display Works

When the agent calls tools, `chat_node` inspects the returned messages for `tool_calls` and `ToolMessage` entries and builds a `tool_log` list. The Gradio UI renders these as colored HTML badges inline in the chat (Gradio's `Chatbot` renders HTML by default).

Example badge output:
```
🔧 get_weather   🔧 wikipedia_search
```

---

## 📝 Configuration

| Parameter | Location | Default | Description |
|---|---|---|---|
| `model` | `memory_chatbot.py` | `qwen/qwen3-32b` | Groq model to use |
| `temperature` | `memory_chatbot.py` | `0` | LLM temperature |
| `max_results` | `tool.py` (Tavily) | `5` | Web search result count |
| `memory categories` | `memory_chatbot.py` | preferences, profile, interests, project | Long-term memory namespaces |

---

## ⚠️ Limitations

- Memory is **in-process only** — all memory resets when the server restarts. For persistence, replace `InMemorySaver` and `InMemoryStore` with database-backed alternatives (e.g., `PostgresSaver`, `RedisStore`).
- `python_exec` tool executes arbitrary code with no sandboxing — use with caution in production.
- `scrape_website` does not handle JavaScript-rendered pages.

---

## 🛠️ Extending

**Add a new tool:** Define it with `@tool` in `tool.py`, then add it to the `tools` list in `memory_chatbot.py`.

**Persist memory to a database:** Replace `InMemorySaver()` with a LangGraph-compatible checkpointer and `InMemoryStore()` with a persistent store.

**Change the LLM:** Swap `ChatGroq` for any LangChain-compatible chat model (OpenAI, Anthropic, etc.).

---