# PhotoShoot AI Design

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-green.svg)](https://modelcontextprotocol.io)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin%20Market-purple.svg)](https://claude.ai/code)
[![Pi Agent](https://img.shields.io/badge/Pi%20Agent-Plugin%20Market-orange.svg)](https://pi.agent)
[![OpenLLM](https://img.shields.io/badge/OpenLLM-Plugin%20Compatible-blue.svg)](https://github.com/vllm-project/openllm)

> AI-powered photoshoot design tools with MCP servers, reusable skills, and intelligent agents. Supports WaveSpeed AI, Nano Banana, OpenAI, Stability AI, and PhotoShoot App integration.

[**Quick Setup →**](SETUP.md) | [Documentation →](docs/) | [Examples →](examples/)

## Overview

PhotoShoot AI Design extends the [photoshoot.app](https://photoshoot.app/) platform with advanced AI agent capabilities through the Model Context Protocol (MCP). This project provides a unified interface to multiple AI image generation services, enabling seamless photoshoot automation for:

- **E-commerce** - Product photography for Amazon, Shopify, and online stores
- **Fashion** - OOTD (Outfit of the Day) content for social media
- **Marketing** - Campaign visuals and brand content
- **Portraits** - Professional headshots and personal branding

## Features

### AI Provider Integration

Seamlessly switch between multiple AI providers:

| Provider | Models | Best For | Pricing |
|----------|--------|----------|---------|
| [WaveSpeed AI](https://wavespeed.ai) | 700+ models including FLUX, Stable Diffusion, Kling, Veo, Sora | Product photography, video content | Competitive rates |
| [Nano Banana](https://ai.google.dev/gemini-api/docs/image-generation) | Google Gemini's native image generation | Fashion, OOTD, lifestyle | ~$0.02/image |
| [OpenAI](https://platform.openai.com) | DALL-E 3, GPT-4 | Professional portraits, creative concepts | Standard OpenAI pricing |
| [Stability AI](https://platform.stability.ai) | Stable Diffusion XL | Custom styles, artistic content | $0.004-$0.02/image |
| [PhotoShoot App](https://photoshoot.app) | Proprietary photoshoot models | E-commerce, brand consistency | Platform pricing |
| [fal.ai](https://fal.ai) | Fast inference | Rapid prototyping, batch processing | Pay-per-use |

### MCP Tools

Complete set of Model Context Protocol tools:

- **`photoshoot_generate`** - Generate AI photos from text or reference images
- **`photoshoot_edit`** - Edit and enhance existing images
- **`photoshoot_template`** - Get available templates and styles
- **`photoshoot_batch`** - Process multiple images in batch
- **`photoshoot_variations`** - Generate image variations
- **`photoshoot_upscale`** - Upscale images to higher resolution

### Skills System

Modular, reusable skills for common design workflows:

| Skill | Description | Use Cases |
|-------|-------------|-----------|
| [`product-photography`](packages/skills/product-photography.md) | Professional product photo generation | E-commerce, product listings, catalogs |
| [`ootd-fashion`](packages/skills/ootd-fashion.md) | Fashion and lifestyle content creation | Instagram, TikTok, Pinterest fashion |
| [`image-enhancement`](packages/skills/image-enhancement.md) | AI-powered photo editing and retouching | Post-processing, optimization |
| [`brand-style`](packages/skills/brand-style.md) | Brand-consistent visual generation | Campaigns, marketing materials |
| [`batch-production`](packages/skills/batch-production.md) | High-volume batch processing | Catalog production, bulk operations |

### AI Agents

Autonomous agents for complex workflows:

**DesignerAgent**
- Analyze reference images and extract style parameters
- Generate photos based on brand guidelines
- Create platform-specific content (Amazon, Instagram, TikTok)
- Manage template libraries

**OptimizerAgent**
- Batch image enhancement
- Platform optimization (Amazon, Shopify, social media)
- Background removal and replacement
- Watermarking and formatting

## Installation

### Quick Start (3 minutes)

```bash
# Clone the repository
git clone git@github.com:photoshootapp/photoshoot-ai-design.git
cd photoshoot-ai-design

# Install dependencies
npm install

# Configure API keys
cp .env.example .env
# Edit .env and add your API keys

# Start MCP server
npm run mcp:start
```

See [SETUP.md](SETUP.md) for detailed setup instructions and API key acquisition.

### Claude Code Plugin

```bash
# Install from plugin marketplace
claude plugin install photoshoot-ai-design

# Or manually configure in .claude/settings.json
{
  "mcpServers": {
    "photoshoot": {
      "command": "node",
      "args": ["packages/mcp-server/dist/index.js"],
      "cwd": "/path/to/photoshoot-ai-design"
    }
  }
}
```

### Pi Agent Plugin

```bash
pi-agent plugin add photoshoot-ai-design
```

### OpenLLM Plugin

```python
import openllm

plugin = openllm.load_plugin("photoshoot-ai-design")
model = openllm.start("vllm/nano-banana", plugins=[plugin])
```

## Usage

### MCP Tool Examples

```typescript
// Generate product photography
await mcpClient.callTool({
  name: "photoshoot_generate",
  arguments: {
    type: "product",
    provider: "wavespeed",
    prompt: "Professional product photo of wireless headphones",
    style: "studio",
    quantity: 4
  }
});

// Generate OOTD fashion content
await mcpClient.callTool({
  name: "photoshoot_generate",
  arguments: {
    type: "ootd",
    provider: "nano-banana",
    prompt: "Streetwear fashion photoshoot, urban setting",
    style: "vibrant",
    quantity: 6
  }
});

// Edit and enhance images
await mcpClient.callTool({
  name: "photoshoot_edit",
  arguments: {
    image: "https://example.com/product.jpg",
    provider: "auto",
    edits: {
      lighting: "studio",
      background: "white",
      retouch: true
    }
  }
});
```

### Skill Examples

```bash
# Product photography
/photoshoot-design product --reference="product.jpg" --style=studio --platform=amazon

# OOTD fashion
/photoshoot-design ootd --reference="outfit.jpg" --style=streetwear --location=urban

# Image enhancement
/photoshoot-design enhance --image="photo.jpg" --intensity=medium
```

### Agent Examples

```typescript
import { DesignerAgent, createPhotoShootClient } from '@photoshoot/agents';

const client = await createPhotoShootClient();
const agent = new DesignerAgent(client, {
  defaultStyle: 'studio',
  defaultQuantity: 4
});

// Generate product photography
await agent.generateProductPhotography({
  productImage: 'shoe.jpg',
  style: 'minimalist',
  platform: 'amazon',
  quantity: 8
});

// Create OOTD content
await agent.createOOTDContent({
  outfitImage: 'outfit.jpg',
  style: 'luxury',
  location: 'rooftop',
  vibe: 'chic'
});

// Optimize for platforms
await agent.optimizeForPlatform({
  images: ['img1.jpg', 'img2.jpg'],
  platform: 'instagram'
});
```

## Architecture

```
photoshoot-ai-design/
├── packages/
│   ├── mcp-server/          # MCP server with all AI providers
│   │   ├── src/
│   │   │   ├── api/clients/ # Individual API clients
│   │   │   │   ├── wavespeed.ts
│   │   │   │   ├── nanobanana.ts
│   │   │   │   ├── openai.ts
│   │   │   │   ├── stability.ts
│   │   │   │   ├── photoshoot.ts
│   │   │   │   └── fal.ts
│   │   │   ├── config.ts
│   │   │   └── index.ts
│   │   └── .env.example
│   │
│   ├── mcp-client/          # MCP client SDK
│   ├── skills/              # Skill definitions (Markdown)
│   ├── agents/              # AI agent implementations
│   │
│   └── plugins/
│       ├── claude-code/     # Claude Code plugin
│       ├── pi-agent/        # Pi Agent plugin
│       └── openllm/         # OpenLLM plugin
│
├── docs/                    # Documentation
├── examples/                # Usage examples
├── .env.example             # Environment configuration template
├── SETUP.md                 # Quick setup guide
└── README.md                # This file
```

## API Reference

### MCP Tools

#### `photoshoot_generate`

Generate photoshoot images using AI.

```typescript
{
  type: 'product' | 'ootd' | 'portrait',
  provider?: 'wavespeed' | 'nano-banana' | 'openai' | 'stability' | 'auto',
  prompt: string,
  reference?: string,
  style?: string,
  quantity?: number,
  width?: number,
  height?: number
}
```

#### `photoshoot_edit`

Edit and enhance images.

```typescript
{
  image: string,
  provider?: 'wavespeed' | 'nano-banana' | 'openai' | 'stability' | 'auto',
  prompt?: string,
  edits?: {
    lighting?: string,
    background?: string,
    retouch?: boolean,
    enhance?: boolean
  }
}
```

#### `photoshoot_batch`

Batch process multiple images.

```typescript
{
  images: string[],
  operation: 'enhance' | 'resize' | 'format' | 'watermark' | 'remove-background',
  options?: Record<string, unknown>
}
```

## Configuration

### Environment Variables

```bash
# WaveSpeed AI (recommended for product photography)
WAVESPEED_API_KEY=your_key_here
WAVESPEED_API_URL=https://api.wavespeed.ai/v1

# Nano Banana (Google Gemini - recommended for fashion)
NANO_BANANA_API_KEY=your_key_here
NANO_BANANA_API_URL=https://generativelanguage.googleapis.com/v1beta

# OpenAI (DALL-E)
OPENAI_API_KEY=your_key_here
OPENAI_API_URL=https://api.openai.com/v1

# Stability AI (Stable Diffusion)
STABILITY_API_KEY=your_key_here
STABILITY_API_URL=https://api.stability.ai/v1

# PhotoShoot App
PHOTOSHOOT_API_KEY=your_key_here
PHOTOSHOOT_API_URL=https://api.photoshoot.app

# fal.ai
FAL_API_KEY=your_key_here
FAL_API_URL=https://fal.ai
```

### Provider Selection

The system automatically selects the best provider based on:

1. **Available API keys** - Only configured providers are used
2. **Content type** - Different providers excel at different types
3. **User preference** - Manual override available

**Automatic selection logic:**
- Product photography → WaveSpeed AI
- Fashion/OOTD → Nano Banana
- Portraits → OpenAI DALL-E
- Custom styles → Stability AI
- Fallback → PhotoShoot App (demo mode without API key)

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Areas for Contribution

- New AI provider integrations
- Additional skill definitions
- Agent capability enhancements
- Plugin support for other platforms
- Documentation and examples

## Development

```bash
# Install dependencies
npm install

# Build all packages
npm run build

# Run MCP server
npm run mcp:start

# Run tests
npm test

# Development mode with hot reload
npm run dev
```

## Performance

- **Batch Processing**: Process up to 100 images simultaneously
- **Auto Caching**: Reduce redundant API calls with intelligent caching
- **Concurrent Requests**: Configurable concurrent request limits
- **Timeout Protection**: Built-in timeout for all API calls

## Roadmap

- [ ] Video generation support (Kling, Veo, Sora via WaveSpeed)
- [ ] 3D model generation
- [ ] Advanced editing features (inpainting, outpainting)
- [ ] Real-time style transfer
- [ ] Mobile app integration
- [ ] Cloud storage integration
- [ ] Team collaboration features

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [PhotoShoot App](https://photoshoot.app/) - Main platform
- [WaveSpeed AI](https://wavespeed.ai/docs) - WaveSpeed documentation
- [Nano Banana](https://ai.google.dev/gemini-api/docs/image-generation) - Google Gemini docs
- [MCP Specification](https://modelcontextprotocol.io) - Protocol details
- [Claude Code](https://claude.ai/code) - Claude Code IDE
- [Pi Agent](https://pi.agent) - Pi Agent platform
- [OpenLLM](https://github.com/vllm-project/openllm) - OpenLLM ecosystem

## Support

- **GitHub Issues**: [github.com/photoshootapp/photoshoot-ai-design/issues](https://github.com/photoshootapp/photoshoot-ai-design/issues)
- **Email**: support@photoshoot.app
- **Discord**: Coming soon

## Acknowledgments

Built with:
- [Model Context Protocol](https://modelcontextprotocol.io) - Standard for AI tool integration
- [WaveSpeed AI](https://wavespeed.ai) - Unified AI API platform
- [Google Gemini](https://ai.google.dev/gemini-api) - Nano Banana image generation
- [Claude](https://claude.ai) - Anthropic's AI assistant

---

**Built with ❤️ for the AI photography community**