Skip to content

Telegram Companion — owner E2E (lab side)

Companion (MacBook archive app) is a thin consumer of LiteLLM, Phoenix, and telemetry. Full owner checklist with Mac steps lives in the Companion repo:

docs/homelab-owner-e2e.md (local: /Users/renjamin/Documents/Projects/TelegramAudioTranscriber/docs/homelab-owner-e2e.md)

This page is the lab-only slice so it sits next to llm-observability.md and monitoring client onboarding.

Security model

Companion uses the trusted Personal VLAN model and does not add application authentication to its Mac-local services. The UDM limits lab access to one source and two backend ports: 192.168.6.17 may reach Mac 192.168.3.37 on TCP 11434 (Ollama) and 8091 (speech shim) only. The Companion UI/dev server on 5173 remains Personal-VLAN-local; there is no inter-VLAN allow for it. Legacy backend port 1234 is not required and must also remain excluded.

Lab checklist

# Task Pointer
1 UDM: keep Servers→Personal allow scoped to 192.168.6.17 → 192.168.3.37 TCP 11434,8091; never add 1234 or 5173 firewall-policy.md
2 LiteLLM aliases companion-archive-default (+ optional deep / vision / embedding) Edit services/litellm/config.yaml; redeploy per LiteLLM README. Vision needs huihui_ai/qwen2.5-vl-abliterated:7b; embedding needs the exact nomic-embed-text:v1.5 tag on the Mac.
3 Virtual key alias telegram-companion Preview/apply services/litellm/virtual-keys/telegram-companion.json with scripts/configure-litellm-virtual-key.py; the allowlist includes text, vision, speech, and companion-archive-embedding without storing either key
4 TELEMETRY_CLIENTS.telegram_companion + render Same as GHA clients in github-actions-observability.md; sudo scripts/render-monitoring-secrets.sh
5 Optional Prometheus scrape Mac:8000/metrics Static job precedent reddit-explorer in monitoring README
6 Smoke LiteLLM → Phoenix llm-observability.md § E2E Tests using model companion-archive-default; use the LiteLLM README embedding smoke for companion-archive-embedding and confirm 768 dimensions

Before enabling semantic retrieval, run the synthetic private-safe embedding benchmark documented in the LiteLLM README. Record latency, dimensionality, recall@1/3/5, and MRR. The benchmark must target direct Mac Ollama on a private address and must never contain production Companion archive content.

Do not

  • Invent Tempo exporters (Tempo is not deployed).
  • Point Companion at raw loki:3100 — use https://telemetry.infra.realemail.app.
  • Reuse Alertmanager’s Discord webhook in Companion .env.
  • Collide Loki job=enhanced-tdler (Enhanced TDLer) with job=telegram-companion.