Blame for README.md

---
title: Medialogia Monitor
emoji: 📬
colorFrom: gray
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
short_description: Text monitoring with Telegram alerts
---

Receives Medialogia webhooks, posts all publications to Telegram, and uses an
independent DeepSeek classifier for potential topic alerts. Text only; no image,
OCR, subtitle, or original-page fetching. The default model is deepseek-flash
with thinking disabled. A positive result is a signal for a person to assess.

Set these Space Secrets: WEBHOOK_SECRET, TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID
and DEEPSEEK_API_KEY. ALERT_MENTIONS optionally adds user mentions to alerts.
CLASSIFIER_PROMPT overrides the generic
default instructions and belongs in a Secret when it contains internal context.
Never commit credentials or confidential classifier instructions to this repo.

GET /health reports configuration. POST /medialogia/WEBHOOK_SECRET accepts a
single Medialogia post or a JSON array of posts. GET /status/WEBHOOK_SECRET
reports queue counters. Substitute the actual secret privately; do not publish
these URLs. The earlier /samples/ route now returns status, not raw payloads.

By default this is a pilot using SQLite under /tmp. Queue state and deduplication
may be lost when a Space restarts or rebuilds. For durable state set the Secret
DATABASE_URL to an external PostgreSQL connection string with TLS. No database
or paid hosting is provisioned automatically. Run only one app instance against
the database. Free Space sleeping and delivery gaps remain possible regardless
of database choice. Keep existing monitoring active during the pilot.

No exactly-once Telegram guarantee: if an API send succeeds but its response
or the subsequent database write is lost, a retry can duplicate a publication
or an alert. AI failures remain pending and are retried, never recorded as NO.
Normal posts are sent silently; alerts request a notification, which still
depends on recipients' Telegram settings. Mentions are explicit @usernames.
Post text is split across messages when necessary; its complete text is checked.

## Delivery health and independent workers

`/health` now distinguishes successful delivery, an untested Telegram connection,
delivery errors, missing configuration, and stopped workers. The public response
contains fixed error categories, never tokens, chat identifiers or post content.
It is not an end-to-end delivery guarantee. `/live` is a separate process liveness
check, so a Telegram outage does not restart the process and discard its queue.

Telegram forwarding runs whenever its token and chat ID are configured, even if
DeepSeek is not configured yet. AI processing starts independently when its key
is available. `ALERT_MENTIONS` is optional. Valid authenticated webhooks are stored
even while downstream configuration is incomplete, and workers resume delivery
after configuration is corrected and the service restarted with the same database.

## Optional free Telegram relay

The `telegram-relay/` directory contains a Cloudflare Worker for installations
where the Space cannot reach Telegram directly. It supports the Workers Free
plan within its quotas. Configure `TELEGRAM_RELAY_URL` and
`TELEGRAM_RELAY_SECRET` together to use it. Otherwise requests go directly to
Telegram as before. The Worker holds its own bot token and allows only this
monitor's five Bot API methods for one numeric chat ID. Both normal delivery and
authenticated diagnostics use the configured transport.

When the relay is configured, read-only `/diagnostics` and `/status` also accept
`Authorization: Bearer TELEGRAM_RELAY_SECRET`. The existing webhook-secret
routes continue to work. This does not authorize incoming publication webhooks.

See `telegram-relay/README.md` for deployment and secret configuration. Verify
the relay's read-only getMe, getChat and getChatMember checks before rebuilding
the Space, then verify an actual publication arrives after deployment. Neither
the bot token nor the shared secret belongs in source control.

The Worker does not fix HF sleeping or the temporary queue. Do not rebuild the
running Space until pending publications have been recovered or their loss and
replay from Medialogia have been explicitly handled. Keep only one app instance.