Human-in-the-Loop через middleware: README.md

README.md

@@ -1,3 +1,148 @@
-# task-69a86305-human-in-the-loop-cherez-
+# Human‑in‑the‑Loop Middleware Demo
 
-Решения домашних заданий
+This repository contains a minimal FastAPI application that demonstrates how to implement a **Human‑in‑the‑Loop (HITL)** mechanism using custom middleware.  
+The middleware allows you to pause the processing of an incoming request and resume it later, which is useful for scenarios where a human operator needs to review or approve data before the LLM generates a final response.
+
+> **TL;DR** – Send a request with `X-HITL-Interrupt: true` to pause.  
+> Then send another request with `X-HITL-Resume: <request-id>` to resume processing.
+
+---
+
+## 📦 Installation
+
+```bash
+# 1️⃣ Clone the repo
+git clone https://github.com/yourname/hitl-middleware-demo.git
+cd hitl-middleware-demo
+
+# 2️⃣ Create a virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate   # On Windows: .\.venv\Scripts\activate
+
+# 3️⃣ Install dependencies
+pip install -r requirements.txt
+```
+
+> **Dependencies**  
+> * `fastapi` – Web framework.  
+> * `uvicorn[standard]` – ASGI server.  
+> * `langchain` – LLM wrapper (OpenAI).  
+> * `qdrant-client` – Vector store client.  
+> * `rich` – Pretty console output.
+
+If you don't have a Qdrant instance running locally, install it via Docker:
+
+```bash
+docker run -p 6333:6333 qdrant/qdrant
+```
+
+---
+
+## 🚀 Running the Application
+
+```bash
+uvicorn solution:app --reload
+```
+
+The API will be available at `http://127.0.0.1:8000`.
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST /process` | Accepts a JSON body with a `text` field. The request is processed by the HITL middleware and forwarded to an OpenAI LLM via LangChain. |
+
+---
+
+## 📄 Example Usage
+
+Below are curl examples that illustrate how to interrupt and resume a request.
+
+### 1️⃣ Send a request that will be **interrupted**
+
+```bash
+curl -X POST http://127.0.0.1:8000/process \
+     -H "Content-Type: application/json" \
+     -H "X-HITL-Interrupt: true" \
+     -d '{"text":"Explain quantum entanglement."}'
+```
+
+**Response (queued)**
+
+```json
+{
+  "status": "queued",
+  "request_id": "abcd1234"
+}
+```
+
+> The middleware stores the request in memory and returns a `request_id` that can be used to resume later.
+
+### 2️⃣ Resume the queued request
+
+```bash
+curl -X POST http://127.0.0.1:8000/process \
+     -H "Content-Type: application/json" \
+     -H "X-HITL-Resume: abcd1234" \
+     -d '{"text":"Explain quantum entanglement."}'
+```
+
+**Response (processed)**
+
+```json
+{
+  "status": "completed",
+  "response": "Quantum entanglement is a physical phenomenon..."
+}
+```
+
+> The LLM processes the text and returns the answer.
+
+---
+
+## 📚 How It Works
+
+1. **Middleware (`HumanInLoopMiddleware`)**
+   * Checks for `X-HITL-Interrupt` or `X-HITL-Resume` headers.
+   * If interrupted, stores the request body in a dictionary keyed by a generated UUID.
+   * If resumed, retrieves the stored body and forwards it to the downstream route.
+
+2. **Route (`/process`)**
+   * Receives the text payload.
+   * Calls `llm.invoke()` from LangChain to generate a response.
+   * Returns the LLM output in JSON.
+
+3. **Qdrant**  
+   * The example includes an initialized Qdrant client, but it is not used in this minimal demo.  
+   * In a real-world scenario you could store embeddings or metadata there.
+
+---
+
+## 📦 Project Structure
+
+```
+.
+├── solution.py          # Main FastAPI app with HITL middleware
+├── requirements.txt     # Python dependencies
+└── README.md            # This file
+```
+
+---
+
+## 🔧 Customization
+
+- **LLM** – Replace `OpenAI(api_key="YOUR_OPENAI_API_KEY")` with another provider supported by LangChain.
+- **Storage** – Swap the in‑memory dict for Redis, PostgreSQL, or any persistence layer to survive restarts.
+- **Security** – Add authentication/authorization headers before allowing resume operations.
+
+---
+
+## 🎯 Use Cases
+
+- **Content moderation** – Pause a request until a human moderator approves it.
+- **Legal review** – Let lawyers vet LLM outputs before they are sent to clients.
+- **Data privacy** – Inspect sensitive data for compliance before processing.
+
+---
+
+Happy hacking! 🚀