# Phase 6: Claude AI Telegram Bot Enhancement (Optional)

**Status**: In progress
**Parent**: [primary-plan.md](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

1. **Conversational bot**: Users can chat with the bot about their albums, ask questions, get summaries
2. **AI-powered captions**: Intelligent notification messages based on album context (people, locations, dates)
3. **Smart summaries**: "What happened in my albums this week?" style queries
4. **Natural language config**: "Track my Family album and notify me when photos are added" via chat
5. **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)