SMART_COLLABORATION_GUIDE.md

# Smart Collaboration Thumbnail Generator 🤖🎨

## What Is This?

Your Thumbnail Crafter Space now has **AI-powered logo fetching**! When you ask HuggingChat to create a collaboration thumbnail, it will:

1. **Search the web** for the partner company's logo
2. **Download and process** the logo automatically
3. **Load your Space** with the appropriate layout
4. **Inject the logo** into the placeholder
5. **Export the final thumbnail** and return it

## Example Use Cases

### In HuggingChat

```
You: "Create a collaboration thumbnail for Hugging Face and Nvidia
      using the Serious Collab layout with a white background"

HuggingChat calls your Space →
  📡 Searches web for "Nvidia logo PNG"
  ⬇️  Downloads the logo
  🎨 Loads Serious Collab layout
  🖼️  Replaces placeholder with Nvidia logo
  📤 Returns completed thumbnail

You receive: A professional thumbnail ready to use!
```

### More Examples

```
"Generate a Fun Collab thumbnail for Hugging Face and OpenAI"

"Create an Academia Hub collab thumbnail for Hugging Face and Stanford"

"Make a collaboration thumbnail for Hugging Face and Google
 with a light blue background"
```

## How It Works

### The Complete Workflow

```
┌─────────────────────────────────────────────────┐
│ 1. HuggingChat                                  │
│    User asks for collaboration thumbnail        │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│ 2. Your MCP Server (Python)                     │
│    • Parses request                             │
│    • Searches DuckDuckGo for company logo       │
│    • Downloads and processes logo image         │
│    • Resizes, adds transparency                 │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│ 3. Playwright Browser Automation                │
│    • Launches headless Chrome                   │
│    • Opens your React app                       │
│    • Waits for window.thumbnailAPI              │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│ 4. Your React App (window.thumbnailAPI)        │
│    • thumbnailAPI.loadLayout('seriousCollab')  │
│    • thumbnailAPI.setBgColor('#ffffff')         │
│    • thumbnailAPI.replaceLogoPlaceholder(...)  │
│    • thumbnailAPI.exportCanvas()                │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│ 5. Return to HuggingChat                        │
│    Base64-encoded PNG thumbnail                 │
└─────────────────────────────────────────────────┘
```

## Available Tools

### 1. `generate_collab_thumbnail`

Generate a collaboration thumbnail with automatic logo fetching.

**Parameters:**
- `partner_name` (required): Company name (e.g., "Nvidia", "Google", "Microsoft")
- `layout` (optional): Layout ID - "seriousCollab" (default), "funCollab", "academiaHub", "sandwich", "impactTitle"
- `partner_logo_url` (optional): Direct logo URL if you have one
- `title` (optional): Custom title text
- `bg_color` (optional): Background color hex (default: "#ffffff")
- `canvas_size` (optional): "default" (1200x675), "linkedin" (1200x627), "hf" (1160x580)

**Example Request:**
```json
{
  "name": "generate_collab_thumbnail",
  "arguments": {
    "partner_name": "Nvidia",
    "layout": "seriousCollab",
    "bg_color": "#f0f0f0"
  }
}
```

**Returns:**
```json
{
  "success": true,
  "image": "data:image/png;base64,...",
  "width": 1200,
  "height": 675,
  "partner_name": "Nvidia",
  "layout_used": "seriousCollab",
  "logo_fetched": true
}
```

### 2. `search_logo`

Just search for a logo without generating a thumbnail.

**Parameters:**
- `company_name` (required): Company to search for

**Example:**
```json
{
  "name": "search_logo",
  "arguments": {
    "company_name": "OpenAI"
  }
}
```

### 3. `get_available_layouts`

List all available collaboration layouts.

## window.thumbnailAPI Reference

Your React app now exposes a programmatic API for browser automation:

```typescript
window.thumbnailAPI = {
  // Load a layout by ID
  loadLayout(layoutId: string): boolean

  // Set background color
  setBgColor(color: string): boolean

  // Replace logo placeholder with new image
  replaceLogoPlaceholder(imageDataUri: string): boolean

  // Add image at specific position
  addImage(dataUri: string, x: number, y: number, w?: number, h?: number): boolean

  // Update text content
  updateText(identifier: string, newText: string): boolean

  // Set canvas size
  setCanvasSize(size: 'default' | 'linkedin' | 'hf'): boolean

  // Export canvas as data URL
  exportCanvas(): Promise<string>

  // Get current state
  getInfo(): object
}
```

You can also use this API manually in the browser console for testing:

```javascript
// Open your Space in browser
// Open DevTools Console (F12)

// Load a layout
window.thumbnailAPI.loadLayout('seriousCollab')

// Set background
window.thumbnailAPI.setBgColor('#e3f2fd')

// Replace logo with any data URI
window.thumbnailAPI.replaceLogoPlaceholder('data:image/png;base64,...')

// Export
const dataUrl = await window.thumbnailAPI.exportCanvas()
```

## Deployment Steps

### 1. Build Your React App

```bash
npm run build
```

This creates the `dist/` folder with your production frontend.

### 2. Choose Which MCP Server to Use

**Option A: Smart Server (Recommended)**
```bash
# Rename to use the smart server
mv mcp_server_smart.py main.py
```

**Option B: Keep Both**
Keep both files and update Dockerfile to use `mcp_server_smart.py`

### 3. Update Dockerfile

```dockerfile
# Copy the smart MCP server
COPY mcp_server_smart.py main.py
# OR
COPY mcp_server_smart.py .

# Update CMD
CMD ["uvicorn", "mcp_server_smart:app", "--host", "0.0.0.0", "--port", "7860"]
```

### 4. Install Playwright Browsers in Dockerfile

Add to your Dockerfile:

```dockerfile
# After installing Python packages
RUN playwright install chromium
RUN playwright install-deps chromium
```

### 5. Deploy to Hugging Face

```bash
git add -A
git commit -m "feat: Add smart collaboration thumbnail generation with logo fetching"
git push
```

### 6. Wait for Build

Hugging Face will build your Docker container (~10-15 minutes).

### 7. Test the Endpoint

```bash
curl -X POST https://huggingface.co/spaces/YOUR-USERNAME/Thumbnail-Crafter.mini/tools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "generate_collab_thumbnail",
    "arguments": {
      "partner_name": "Nvidia",
      "layout": "seriousCollab"
    }
  }'
```

### 8. Register in HuggingChat

1. Go to HuggingChat → Settings → MCP Servers
2. Add your Space URL
3. Enable it

### 9. Use It!

```
User in HuggingChat:
"Create a collab thumbnail for Hugging Face and Nvidia"

HuggingChat:
*generates thumbnail automatically*
Here's your collaboration thumbnail! [shows image]
```

## Local Testing

### Test the Smart Server Locally

```bash
# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium

# Start your React app (in one terminal)
npm run dev

# Start the MCP server (in another terminal)
python mcp_server_smart.py
```

### Test Logo Fetching

```bash
curl -X POST http://localhost:7860/tools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search_logo",
    "arguments": {"company_name": "Google"}
  }'
```

### Test Full Workflow

```bash
curl -X POST http://localhost:7860/tools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "generate_collab_thumbnail",
    "arguments": {
      "partner_name": "Microsoft",
      "layout": "seriousCollab",
      "bg_color": "#ffffff"
    }
  }'
```

## Troubleshooting

### Logo Not Found

**Problem:** Can't find logo for company X

**Solutions:**
1. Try a more specific name: "Microsoft Corporation" instead of "MS"
2. Provide direct logo URL: `partner_logo_url: "https://..."`
3. Use a well-known variant: "Meta" instead of "Facebook"

### Logo Not Replacing Placeholder

**Problem:** Logo fetched but not showing in thumbnail

**Solutions:**
1. Check layout has a logo placeholder: `seriousCollab`, `funCollab`, `academiaHub` do
2. Check browser console logs for errors
3. Verify window.thumbnailAPI is loaded

### Browser Automation Fails

**Problem:** Playwright can't open the app

**Solutions:**
1. Ensure React app is running at APP_URL
2. Check Playwright is installed: `playwright install chromium`
3. Check firewall/network issues
4. Try increasing timeouts in Python code

### Image Quality Issues

**Problem:** Logo looks pixelated or wrong size

**Solutions:**
1. Adjust `target_size` in `process_logo_image()`
2. Search for higher resolution: add "high resolution" to search query
3. Provide direct URL to vector/high-res logo

## Performance Considerations

- **Logo Fetching:** 2-5 seconds
- **Browser Launch:** 1-3 seconds
- **Layout Rendering:** 1-2 seconds
- **Export:** 0.5-1 second

**Total Time:** ~5-10 seconds per thumbnail

To improve:
- Keep browser instance warm (already implemented)
- Cache fetched logos (TODO)
- Pre-download common logos (TODO)

## Security & Privacy

- Logos are fetched from public web sources (DuckDuckGo Images)
- No API keys required for image search
- All processing happens server-side
- No user data is stored
- Respects robots.txt and rate limits

## Future Enhancements

- [ ] Cache frequently used logos
- [ ] Support for multiple logos (three-way collabs)
- [ ] Custom logo positioning
- [ ] Batch generation
- [ ] Video thumbnail generation
- [ ] Real-time preview in HuggingChat

---

**Built with Claude Code** 🤖

Questions? Check the main [MCP_DEPLOYMENT_GUIDE.md](./MCP_DEPLOYMENT_GUIDE.md)