telegram-retriever
telegram-retriever is a functional, human-in-the-loop extension for LangChain. It allows an LLM agent to pause execution, send a query to a specific Telegram user, and synchronously wait for a text-based reply.
🧠 The Functional Pipeline
The retriever follows a strict data-flow architecture:
- Dispatch: Sends the AI's question to the target chat via the Telegram Bot API.
- Poll: Enters a stateless polling loop to fetch updates.
- Filter: Validates incoming data to ensure it is a text-based "Reply-To" message from the correct user.
- Transform: Converts the validated Telegram message into a LangChain
Document.
🚀 Installation
pip install telegram-retriever
🛠 Usage
Synchronous (Blocking)
Perfect for scripts where the process should wait for human intervention.
import os
from telegram_retriever import TelegramRetriever
retriever = TelegramRetriever(
bot_token=os.getenv("TELEGRAM_BOT_TOKEN"),
chat_id=os.getenv("TELEGRAM_CHAT_ID")
)
# Execution pauses here until the human replies on Telegram
docs = retriever.invoke("Do you approve the budget for Q3?")
print(f"Human response: {docs[0].page_content}")
Asynchronous (Non-blocking)
Recommended for FastAPI or LangServe applications to keep the event loop free.
docs = await retriever.ainvoke("Should I trigger the deployment?")
⚙️ Configuration
| Parameter | Type | Default | Description |
|---|---|---|---|
bot_token |
SecretStr |
Required | Your Telegram Bot API Token. |
chat_id |
str |
Required | The target User ID or Group ID. |
polling_timeout |
float |
600.0 |
Seconds to wait before timing out. |
polling_interval |
float |
2.0 |
Seconds between update checks. |
🧪 Development
The project is built on pure functions, making testing simple and reliable.
# Install test dependencies
pip install .[test]
# Run the functional test suite
pytest
🎮 Demo: Human-in-the-Loop Workflow
This demo uses the script located at examples/chatbot.py to showcase how the AI agent (via DSPy) intelligently decides when human intervention is necessary.
How it Works:
- Direct AI Response (Autonomous): When the user asks a straightforward math question ("What's 127 x 23?"), the AI handles it locally using its internal knowledge. It does not trigger a Telegram notification because the task is simple and clear.
- Human-in-the-Loop (Triggered): When the user asks a subjective or context-heavy question ("What's so special about 67?"), the AI recognizes its own limitations.
- Telegram Integration: The AI pauses, sends the query to the human expert via Telegram, and waits for a reply.
- Synthesis: Once the human replies ("It's an internet meme"), the AI synthesizes this "expert context" into a comprehensive final answer for the user.
(Note: Sensitive Telegram identifiers have been safely redacted in this image.)
Metadata
Release files for telegram-retriever 0.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| telegram_retriever-0.1.4.tar.gz | 169.5 kB | Without provenance | Details for telegram_retriever-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| telegram_retriever-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for telegram_retriever-0.1.4-py3-none-any.whl |
Total release size: 175.8 kB
Release files / telegram_retriever-0.1.4.tar.gz
| Download URL | telegram_retriever-0.1.4.tar.gz |
|---|---|
| Size | 169.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ab43ae98bc9d52c6b9ea09da7633c455b5c4cacf310cf4c5aded41594e410108
|
|
BLAKE2b-256 checksum How to use checksums |
74841d19428f96dceb1015e0f553b0d26135bfb434c25be19549db2481111553
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / telegram_retriever-0.1.4-py3-none-any.whl
| Download URL | telegram_retriever-0.1.4-py3-none-any.whl |
|---|---|
| Size | 6.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8a7b3457c1589ea96d0b7fbef4a631460aef3e215a7691c56555c30954895800
|
|
BLAKE2b-256 checksum How to use checksums |
2734d40ed72a97022e27c9e26b75de713f126a4d31f687666b8e1c8899b66fd0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for telegram-retriever 0.1.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.