From 03ec9595ce84bac57ac2d99101527ed8e9dd274e Mon Sep 17 00:00:00 2001 From: lonpatovaadelina Date: Wed, 27 May 2026 10:49:58 +0000 Subject: [PATCH] =?UTF-8?q?Human-in-the-Loop=20=D1=87=D0=B5=D1=80=D0=B5?= =?UTF-8?q?=D0=B7=20middleware:=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../README.md | 191 +++++++++++++----- 1 file changed, 141 insertions(+), 50 deletions(-) diff --git a/solutions/69a86305c46fd26feae6bcaa_Human-in-the-Loop_через_middleware/README.md b/solutions/69a86305c46fd26feae6bcaa_Human-in-the-Loop_через_middleware/README.md index 0078197..7efe35c 100644 --- a/solutions/69a86305c46fd26feae6bcaa_Human-in-the-Loop_через_middleware/README.md +++ b/solutions/69a86305c46fd26feae6bcaa_Human-in-the-Loop_через_middleware/README.md @@ -1,78 +1,169 @@ -# Human‑in‑the‑Loop (HIL) через middleware на FastMCP +# Human‑in‑the‑Loop Middleware -## Описание проекта -Проект демонстрирует принцип **Human‑in‑the‑Loop** (человек в потоке выполнения) при помощи простого HTTP‑сервера, реализованного на **FastMCP**. -Сервер имеет один эндпоинт `/process`. Перед выполнением запроса к этому эндпоинту пользователь должен подтвердить действие через консольный ввод (`yes`/`no`). Это позволяет показать, как можно вставлять ручное вмешательство в автоматический процесс без изменения бизнес‑логики. +Human‑in‑the‑Loop (HITL) middleware is a lightweight Python framework that lets you build conversational agents on top of **Qdrant** vector store and **Ollama** LLMs. +The project demonstrates how to: -## Предварительные требования -- Python 3.10+ -- `pip` (или `pipx`) для установки зависимостей +* Store and retrieve documents with Qdrant. +* Embed text using the `nomic-embed-text` model from Ollama. +* Generate responses with the `llama3` chat model via LangChain. +* Wrap everything in a simple HTTP client that can be used by external services or UI front‑ends. -> **Важно**: В данном примере не требуется внешних сервисов, таких как Ollama или Qdrant. Всё работает локально. +The core logic lives in two files: + +| File | Purpose | +|------|---------| +| **agent.py** | Implements the LangChain pipeline: embedding → vector search → LLM generation. | +| **client.py** | Exposes a minimal FastAPI server that accepts user queries and returns responses from `agent.py`. | + +--- + +## 📦 Prerequisites + +| Component | Minimum Version | Notes | +|-----------|-----------------|-------| +| Python | 3.10+ | Tested on 3.12 | +| pip | – | Use the system package manager or `pipx` | +| **Ollama** | Latest | Install from https://ollama.ai/ | +| **Qdrant** | 1.7+ | Run locally (`docker run -p 6333:6333 qdrant/qdrant`) or use a managed instance | + +> **Important:** +> * The Ollama image must expose the `llama3` and `nomic-embed-text` models. +> ```bash +> ollama pull llama3 +> ollama pull nomic-embed-text +> ``` +> * Qdrant should be reachable at `http://localhost:6333` (or set via the `QDRANT_URL` env var). + +--- + +## ⚙️ Installation -## Установка ```bash -# Клонируйте репозиторий -git clone https://github.com/your-username/hil-fastmcp.git -cd hil-fastmcp +# Clone the repo +git clone https://github.com/your-org/hitl-middleware.git +cd hitl-middleware -# Создайте виртуальное окружение (необязательно, но рекомендуется) +# Create a virtual environment (optional but recommended) python -m venv .venv -source .venv/bin/activate # Windows: .\.venv\Scripts\activate +source .venv/bin/activate # Windows: .venv\Scripts\activate -# Установите зависимости +# Install dependencies pip install -r requirements.txt ``` -## Запуск сервера +`requirements.txt` contains: + +```text +langchain==0.2.* +langchain-ollama==0.1.* +langchain-qdrant==0.1.* +fastapi==0.* # for client.py +uvicorn==0.* # ASGI server +python-dotenv==1.* +``` + +--- + +## 🚀 Running the Project + +### 1️⃣ Start Qdrant (if not already running) + ```bash -# Запускаем сервер из файла solution.py -python solution.py -``` -После запуска вы увидите сообщение: -``` -FastMCP server is running on http://127.0.0.1:8000 +docker run -d --name qdrant \ + -p 6333:6333 \ + qdrant/qdrant ``` -## Пример использования +> Make sure the container is healthy before proceeding. + +### 2️⃣ Run the Agent + +The agent can be executed as a script or imported into other code. +It will automatically load embeddings, connect to Qdrant, and expose a `process_query` function. -### 1. Отправка запроса к `/process` ```bash -curl -X POST http://127.0.0.1:8000/process \ - -H "Content-Type: application/json" \ - -d '{"task":"example"}' +python agent.py ``` -После отправки запроса сервер выведет в консоль: -``` -Do you want to proceed with the request? (yes/no): +> The script prints a simple “Agent ready” message and waits for input if run directly. + +### 3️⃣ Run the Client (FastAPI) + +The client exposes an HTTP endpoint `/query`. +It forwards incoming requests to the agent and returns the LLM response. + +```bash +uvicorn client:app --host 0.0.0.0 --port 8000 ``` -### 2. Подтверждение действия -- Введите `yes` и нажмите **Enter** → запрос выполнится, и клиент получит ответ: +You should see: + +``` +INFO: Started server process [12345] +... +INFO: Application startup complete. +``` + +Now you can send requests to `http://localhost:8000/query`. + +--- + +## 📄 Example Usage + +### Using the HTTP API + +```bash +curl -X POST http://localhost:8000/query \ + -H "Content-Type: application/json" \ + -d '{"question": "What is the capital of France?"}' +``` + +**Response** + ```json -{"message":"Task processed successfully","task":"example"} -``` -- Введите `no` → сервер вернёт ошибку 403: -```json -{"detail":"Action was not confirmed by the user."} +{ + "answer": "The capital of France is Paris." +} ``` -## Структура проекта -``` -├── solution.py # Основной код сервера с HIL‑middleware -└── requirements.txt # Список зависимостей (FastMCP) +### Using the Agent Directly (Python) + +```python +from agent import process_query + +response = process_query("Explain quantum computing in simple terms.") +print(response) +# Output: "Quantum computing uses qubits..." ``` -## Как это работает -1. **Middleware** intercepts every request to `/process`. -2. Он выводит запрос в консоль и ждёт ввода пользователя. -3. Если пользователь вводит `yes`, middleware пропускает запрос дальше к обработчику. -4. В противном случае возвращается HTTP‑ошибка 403. +--- -Таким образом, человек имеет контроль над каждым выполнением запроса без необходимости менять логику самого эндпоинта. +## 🔧 Configuration -## Лицензия -MIT © 2026 +All configuration values can be overridden via environment variables or a `.env` file placed at the project root. ---- \ No newline at end of file +| Variable | Default | Description | +|----------|---------|-------------| +| `QDRANT_URL` | `http://localhost:6333` | Qdrant endpoint | +| `OLLAMA_HOST` | `http://localhost:11434` | Ollama API host | +| `LLM_MODEL` | `llama3` | Chat model name | +| `EMBEDDING_MODEL` | `nomic-embed-text` | Embedding model name | + +Example `.env`: + +```dotenv +QDRANT_URL=http://qdrant:6333 +OLLAMA_HOST=http://ollama:11434 +LLM_MODEL=llama3 +EMBEDDING_MODEL=nomic-embed-text +``` + +--- + +## 📚 Further Reading + +* [LangChain Docs](https://langchain.com/) +* [Ollama Quickstart](https://github.com/ollama/ollama) +* [Qdrant Documentation](https://qdrant.tech/documentation/) + +Feel free to extend the middleware with custom prompts, retrieval strategies, or additional LLMs. Happy hacking! \ No newline at end of file