alexei.dolgolyov/haos-hacs-immich-album-watcher

Files

Validate / Hassfest (push) Has been cancelled

Details

Add Claude AI Telegram bot enhancement (Phase 6)

Integrate Claude AI into the notification system for intelligent
conversational interactions and AI-powered captions.

New modules:
- ai/service.py: Claude API client with conversation history,
  caption generation, and album activity summarization
- ai/telegram_webhook.py: Telegram webhook handler for incoming
  bot messages, routes to AI service for responses

Features:
- Conversational bot: users chat with the bot about albums
- AI captions: intelligent notification messages based on album
  context (people, locations, dates) - enabled per target via
  "ai_captions" config flag
- Album summaries: "what's new?" triggers AI-generated overview
- /start command with welcome message
- Webhook register/unregister endpoints

Architecture:
- Per-chat conversation history (in-memory, capped at 20 messages)
- Graceful degradation: AI features completely disabled without
  IMMICH_WATCHER_ANTHROPIC_API_KEY env var (zero impact)
- AI caption failure falls back to Jinja2 template rendering
- Health endpoint reports ai_enabled status

Config: IMMICH_WATCHER_ANTHROPIC_API_KEY, IMMICH_WATCHER_AI_MODEL,
IMMICH_WATCHER_AI_MAX_TOKENS

Server now has 45 API routes (was 42 after Phase 5).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-19 14:38:51 +03:00

2.1 KiB

Raw Blame History

Phase 6: Claude AI Telegram Bot Enhancement (Optional)

Status: In progress Parent: primary-plan.md

Goal

Integrate Claude AI into the Telegram notification bot to enable conversational interactions, intelligent caption generation, and natural language tracker management -- all via Telegram chat.

Features

Conversational bot: Users can chat with the bot about their albums, ask questions, get summaries
AI-powered captions: Intelligent notification messages based on album context (people, locations, dates)
Smart summaries: "What happened in my albums this week?" style queries
Natural language config: "Track my Family album and notify me when photos are added" via chat
Photo descriptions: Ask the bot to describe photos using Claude's vision capabilities

Architecture

New ai/ module in the server package
Claude API client using the Anthropic SDK
Telegram webhook handler for incoming messages (bot receives user messages)
AI context builder: assembles album data, recent events, tracker configs for Claude
Optional: can be disabled entirely if no API key is configured

Tasks

1. Add Anthropic SDK dependency `[ ]`

2. Create AI service module `[ ]`

Claude API client wrapper
System prompt with Immich Watcher context
Conversation history management (per chat, in-memory with DB fallback)

3. Create Telegram webhook handler `[ ]`

POST /api/telegram/webhook endpoint
Register webhook URL with Telegram Bot API
Route incoming messages to AI service

4. Implement AI features `[ ]`

Album summary generation
Intelligent caption formatting
Natural language tracker CRUD
Photo description (vision API)

5. Add configuration `[ ]`

ANTHROPIC_API_KEY env var
Per-target "AI enabled" toggle
AI model selection (default: claude-sonnet-4-20250514)

Acceptance Criteria

Bot responds to direct messages with contextual album info
AI captions can be enabled per notification target
Users can ask "what's new in my albums?" and get a summary
Feature is completely disabled without API key (zero impact)

2.1 KiB Raw Blame History