# Human‑in‑the‑Loop Middleware Demo

A minimal Python project that demonstrates how to add a **Human‑in‑the‑Loop (HITL)** experience to a LangChain agent using the built‑in `HumanInTheLoopMiddleware`.  
When the agent is about to invoke an external tool, it pauses and asks for user approval (`approve` or `reject`) before continuing.

> **Why use middleware?**  
> Unlike the older `interrupt_before=['tools']` approach, the middleware automatically builds the confirmation prompt, handles the response, and resumes execution via a `Command(resume={…})`. This keeps your agent logic clean and declarative.

---

## 📦 Project Structure

```
├── agent.py      # Agent definition + HITL middleware
├── client.py     # Simple CLI that runs the agent
├── requirements.txt
└── README.md
```

- `agent.py` – creates a LangChain agent with a single tool (`get_weather`) and attaches the HITL middleware.
- `client.py` – launches the agent in an interactive loop.

---

## ⚙️ Prerequisites

| Component | Minimum Version | Notes |
|-----------|-----------------|-------|
| Python    | 3.11+           | Tested on 3.12 |
| Ollama    | latest          | Local LLM (e.g., `llama3`) |
| LangChain | 0.2.x or newer | Provides agents & middleware |
| LangGraph | 0.1.x or newer | For checkpointing (optional) |

> **Ollama** must be running locally and the model (`llama3` in this repo) should be pulled beforehand:
> ```bash
> ollama pull llama3
> ```

---

## 📦 Installation

```bash
# Clone the repository
git clone https://github.com/your-username/hitl-middleware-demo.git
cd hitl-middleware-demo

# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

`requirements.txt` contains:

```text
langchain==0.2.*
langgraph==0.1.*
langchain-ollama==0.2.*
```

---

## 🚀 Running the Project

### 1️⃣ Start the Agent (CLI)

```bash
python client.py
```

You will see a prompt like:

```
Agent: What would you like to know?
> Tell me the weather in Paris tomorrow.
...
[HITL] The agent wants to call tool `get_weather` with arguments:
{
  "city": "Paris",
  "date": "2024-06-01"
}
Approve? (approve/reject):
```

Type **`approve`** or **`reject`** and press Enter.  
If approved, the tool runs; if rejected, the agent will re‑think.

### 2️⃣ Run a Single File Directly

You can also run each file individually:

```bash
# Agent definition (no output)
python agent.py

# Client that uses the agent
python client.py
```

---

## 🔍 Example Interaction

```
Agent: Tell me the weather in Tokyo tomorrow.
[HITL] The agent wants to call tool `get_weather` with arguments:
{
  "city": "Tokyo",
  "date": "2024-06-01"
}
Approve? (approve/reject): approve
Tool output: "Tomorrow in Tokyo, expect a high of 28°C and light showers."
Agent: The weather in Tokyo tomorrow will be around 28°C with light showers.
```

If you type `reject`, the agent will ask for clarification or try a different approach.

---

## 📚 Further Reading

- [Human‑in‑the‑Loop — LangChain](https://docs.langchain.com/docs/middleware/human_in_the_loop)
- [LangGraph Checkpoints](https://langgraph.org/docs/checkpointing)

Feel free to extend the toolset or replace `ChatOllama` with an OpenAI model by swapping imports.

---

Happy hacking! 🚀