# Session Summary: Telegram Bot + Full Pipeline

**Date**: 2026-01-16 to 2026-01-17
**Status**: Working MVP
**Branch**: main

## What Was Built

### Telegram Bot (`scripts/telegram_bot.py`)

A complete Telegram bot for video generation:

```
User sends WB URL → Bot processes → Returns video with rating buttons
```

**Features:**
- User whitelist (ALLOWED_USERS env var)
- Activity logging per product (`/mnt/video/wb_{product_id}/activity.log`)
- Rating system (Good/Bad/Artifacts buttons)
- Comment collection after rating
- Concurrent request blocking (one video per user at a time)

**Commands:**
- `/start` - Show help
- `/status` - Check current generation status
- `/skip` - Skip comment after rating

### LaoZhang.ai Integration (`scripts/laozhang_proxy.py`)

Proxy wrapper for accessing AI APIs via LaoZhang.ai:

1. **NanoBanana Pro** (Gemini 3 Pro image-to-image)
   - Custom aspect ratios (16:9, 9:16, etc.)
   - SOCKS5 proxy routing (required for v1beta endpoint)
   - Retry logic for SSL errors (3 attempts)
   - **NEW:** Reference image support for scene consistency

2. **Veo 3.1** (Video generation)
   - First/last frame support
   - Streaming progress display
   - Audio filter error detection and retry (3 attempts)

### Full Pipeline (`scripts/full_pipeline.py`)

End-to-end automation:

```
WB URL → Fetch data → Download images (7) → Claude analysis →
NanoBanana (ACT 1 + ACT 2) → Veo3 → Video output
```

**Key improvements:**
- Downloads 7 images (was 3)
- Two-act storytelling (product → lifestyle)
- **Structured transitions**: Claude outputs separate `veo3_act1`, `veo3_transition`, `veo3_act2`
- Scene consistency decision by Claude
- Content policy rules (no babies/toddlers)
- Retry logic for AUDIO_FILTERED errors

### Systemd Services (`systemd/`)

Ready-to-use service files:
- `videobot-test.service` - For /home/videobot/dev
- `videobot-prod.service` - For /home/videobot/prod
- `env.example` - Environment template

## Architecture

```
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Telegram   │────▶│ telegram_bot │────▶│  full_pipeline  │
│    User     │     │     .py      │     │      .py        │
└─────────────┘     └──────────────┘     └────────┬────────┘
                                                  │
                    ┌─────────────────────────────┼─────────────────────────────┐
                    │                             │                             │
                    ▼                             ▼                             ▼
            ┌───────────────┐           ┌─────────────────┐           ┌─────────────────┐
            │ wb_fetcher.py │           │ laozhang_proxy  │           │   Claude CLI    │
            │  (Playwright) │           │ (NanoBanana +   │           │ (image analysis │
            └───────────────┘           │     Veo3)       │           │   + prompts)    │
                                        └────────┬────────┘           └─────────────────┘
                                                 │
                                        ┌────────┴────────┐
                                        │  SOCKS5 Proxy   │
                                        │ PROXY_HOST:1080│
                                        └─────────────────┘
```

## Environment Variables

```bash
# Required
TELEGRAM_BOT_TOKEN=...     # From @BotFather
LAOZHANG_KEY=sk-...        # LaoZhang.ai API key

# Optional
NFS_BASE=/mnt/video        # Output directory
PROXY_HOST=PROXY_HOST    # SOCKS5 proxy
PROXY_PORT=1080
ALLOWED_USERS=123,456      # Comma-separated Telegram user IDs
```

## Key Findings

### 1. SOCKS5 Proxy Required for LaoZhang v1beta
The NanoBanana API (`/v1beta/models/gemini-3-pro-image-preview`) requires routing through SOCKS5 proxy. Direct connection fails with SSL errors.

### 2. Content Moderation Issues
- **Minors detection**: Images with babies/toddlers are rejected ("图片中包含未成年人")
- **Audio filtering**: Random "PUBLIC_ERROR_AUDIO_FILTERED" errors on Veo3
- **Solution**: Added retry logic for audio errors (3 attempts), prompt rule for no babies/toddlers

### 3. Scene Consistency Challenge
When ACT 1 and ACT 2 should share the same environment (e.g., same room), NanoBanana generates inconsistent backgrounds.

**Solution implemented:**
- Claude decides if consistency is needed based on story
- If needed, ACT 1 frame is passed as reference image to ACT 2 generation
- Prompt enhanced with "maintain same environment/person/lighting"

### 4. API Error Detection
LaoZhang streaming API returns errors in Chinese within the content stream. Added detection for:
- 错误 (error)
- ❌ (emoji indicator)
- ERROR keyword

### 5. SSL Intermittent Failures
NanoBanana calls sometimes fail with `SSLEOFError`. Added 3-retry logic with 2s delay.

### 6. Structured Transitions
Initial Veo3 prompts had transitions buried inside ACT 2 text, making them unreliable.

**Solution:** Claude now outputs three separate fields:
- `veo3_act1`: Scene description for first 3 seconds
- `veo3_transition`: One of: fade, cross-dissolve, pan, hand enters, match cut
- `veo3_act2`: Scene description for last 5 seconds

Combined into: `"ACT 1 (3 sec): {act1} TRANSITION: {transition}. ACT 2 (5 sec): {act2}"`

### 7. Veo3 Physics Limitations
Complex objects like vacuum hoses, cables, and flowing fabrics often create artifacts. Veo3 struggles with:
- Hoses/cables (tangling, disappearing)
- Liquid pouring
- Rapid hand movements with small objects

## Files Modified/Created

| File | Purpose |
|------|---------|
| `scripts/telegram_bot.py` | Telegram bot implementation |
| `scripts/full_pipeline.py` | End-to-end pipeline |
| `scripts/laozhang_proxy.py` | LaoZhang API wrapper |
| `scripts/requirements.txt` | Dependencies |
| `systemd/videobot-test.service` | Test environment service |
| `systemd/videobot-prod.service` | Production service |
| `systemd/env.example` | Environment template |
| `.env` | Test environment config |

## Output Structure

```
/mnt/video/
└── wb_{product_id}/
    ├── activity.log           # All user actions
    └── {task_id}/
        ├── images/            # Downloaded WB images
        │   ├── original_1.webp
        │   ├── original_2.webp
        │   └── ...
        ├── processed/         # NanoBanana outputs
        │   ├── frame_act1.jpg
        │   └── frame_act2.jpg
        ├── videos/            # Veo3 outputs
        │   └── video.mp4
        ├── metadata.json      # Full pipeline metadata
        └── README.md          # Human-readable report
```

## Running the Bot

```bash
# Manual start (development)
cd /home/videobot/dev/scripts
source ../venv/bin/activate
python telegram_bot.py

# Or with systemd (production)
sudo cp systemd/videobot-test.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable videobot-test
sudo systemctl start videobot-test
```

## Known Issues

1. **Bot process dies silently** - Need to monitor and restart
2. **No progress updates to user** - User only sees "Starting..." then final result
3. **Single video per request** - Could generate multiple variants
4. **No cancel option** - User must wait for completion

## Future Improvements

- [ ] Progress updates to Telegram during generation
- [ ] Multiple video variants per request
- [ ] Cancel command
- [ ] Queue system for multiple users
- [ ] Error notifications to admin
- [ ] Cost tracking (LaoZhang credits)
- [ ] A/B testing different prompts

## API Costs (Approximate)

Per video generation:
- NanoBanana x2 calls: ~$0.10
- Veo 3.1 x1 call: ~$0.50
- Claude analysis: ~$0.05
- **Total: ~$0.65 per video**

## Test Results (Product: 267979934 - STIMAXON Vacuum)

| Task ID | Result | Rating | Issue |
|---------|--------|--------|-------|
| 20260116_235827 | ERROR | - | Minors detected in generated frame |
| 20260117_000916 | ERROR | - | No video URL (audio filtered?) |
| 20260117_002434 | OK | Bad | "Sofa moved in second scene" |
| 20260117_003839 | OK | Bad | "Two vacuums, ghostly people" (scene consistency test) |
| 20260117_005243 | OK | Artifacts | "Hose tangled between legs" |

**Observations:**
- Structured transitions working (cross-dissolve confirmed)
- Scene consistency with reference image needs more tuning
- Veo3 struggles with vacuum hose physics

---

**MVP is working!** User can send WB URL and receive generated video.
