# ShopAgent

**Repository Path**: openclaw-projects-admin/ShopAgent

## Basic Information

- **Project Name**: ShopAgent
- **Description**: 跨境电商  选品项目
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🛍️ E-commerce AI Agent

> **Intelligent multi-platform product search agent powered by AI, LangChain, and MCP (Model Context Protocol)**

An advanced AI-powered e-commerce search agent that simultaneously searches across multiple online platforms, providing intelligent product comparisons with structured results, price analysis, and smart recommendations.

![Python](https://img.shields.io/badge/python-v3.13+-blue.svg)
![Flask](https://img.shields.io/badge/flask-v3.1+-green.svg)
![LangChain](https://img.shields.io/badge/langchain-v0.3+-orange.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

## ✨ Features

### 🎯 Core Capabilities
- **Multi-Platform Search**: Simultaneously search across 11+ e-commerce platforms
- **AI-Powered Intelligence**: GPT-4o with ReAct agents for smart decision making
- **Structured Responses**: Organized results using Pydantic models with type validation
- **Smart Analysis**: Intelligent price comparison, rating analysis, and best deal detection
- **Professional Web Interface**: Modern Bootstrap-based responsive frontend
- **Multiple MCP Providers**: Support for BrightData, FireCrawl, and Tavily

### 🌍 Supported Platforms

| Platform | Region | Type | Availability |
|----------|--------|------|--------------|
| 🔸 **Amazon** | Global | General E-commerce | All versions |
| 🔸 **eBay** | Global | Marketplace | All versions |
| 🔸 **Walmart** | US | Retail Chain | All versions |
| 🔸 **Best Buy** | US | Electronics | BrightData/FireCrawl |
| 🔸 **Target** | US | Retail Chain | BrightData/FireCrawl |
| 🔸 **Costco** | US | Warehouse Club | BrightData/FireCrawl |
| 🔸 **Newegg** | Global | Technology | BrightData/FireCrawl |
| 🔸 **MercadoLibre Colombia** | LATAM | Marketplace | Tavily version |
| 🔸 **Falabella** | LATAM | Department Store | Tavily version |
| 🔸 **Alibaba** | Global | B2B | Tavily version |
| 🔸 **AliExpress** | Global | B2C Retail | Tavily version |

## 🏗️ Architecture

### Technology Stack
```
🐍 Python 3.13+          - Core language
🌐 Flask 3.1+            - Web framework  
🧠 LangChain 0.3+        - AI framework
🤖 LangGraph 0.6+        - ReAct agents
🔗 MCP 1.13+             - Model Context Protocol
📊 Pydantic              - Data validation
🎨 Bootstrap 5           - Frontend styling
⚡ OpenAI GPT-4o         - Language model
```

### Project Structure
```
Ecommerce_AI_Agent/
├── 📄 app.py                 # Version 1: BrightData MCP (Production-ready)
├── 📄 app_firecrawl.py       # Version 2: FireCrawl MCP (Content extraction)
├── 📄 app_tavily.py          # Version 3: Tavily MCP (Most advanced) ⭐
├── 📁 templates/
│   ├── base.html             # Base template with Bootstrap
│   └── index.html            # Main interface with smart dashboard
├── 📁 static/
│   └── style.css            # Custom styling
├── ⚙️ .env                   # Environment variables (create this)
├── 📋 pyproject.toml         # Python dependencies
├── 📖 CLAUDE.md              # Claude Code integration docs
├── 📚 README.md              # This file
└── 🔐 requirements.txt       # Alternative dependency format
```

## 🚀 Quick Start

### Prerequisites
- **Python 3.13+**
- **Node.js 16+** (for MCP servers)
- **API Keys** (OpenAI + chosen provider)

### 1. Clone & Setup
```bash
git clone https://github.com/yourusername/ecommerce-ai-agent.git
cd ecommerce-ai-agent

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt
```

### 2. Environment Configuration
Create a `.env` file:

```env
# Core - Required for all versions
OPENAI_API_KEY=your-openai-api-key-here

# Version 1: BrightData (app.py)
WEB_UNLOCKER_ZONE=your-zone
BROWSER_AUTH=your-browser-auth  
API_TOKEN=your-api-token

# Version 2: FireCrawl (app_firecrawl.py)
FIRECRAWL_API_KEY=your-firecrawl-api-key

# Version 3: Tavily (app_tavily.py) ⭐ Recommended
TAVILY_API_KEY=your-tavily-api-key
```

### 3. Install MCP Server
```bash
# For Tavily version (recommended)
npm install -g tavily-mcp@latest

# For BrightData version
npm install -g @brightdata/mcp

# For FireCrawl version  
npm install -g firecrawl-mcp
```

### 4. Run Application
```bash
# Recommended version (Advanced features + International platforms)
python app_tavily.py

# Alternative versions
python app.py           # BrightData (Most reliable)
python app_firecrawl.py # FireCrawl (Clean extraction)
```

Visit: **http://localhost:8000**

## 🎮 Usage Guide

### Web Interface
1. **📝 Enter Search Query**: "iPhone 15 Pro", "Samsung Galaxy S24", "wireless headphones"
2. **🎯 Select Platforms**: Choose from available e-commerce sites
3. **🚀 Execute Search**: AI agent searches and structures results  
4. **📊 View Results**: Organized by platform with smart analysis

### Example Search Results
```json
{
  "platforms": [
    {
      "platform": "Amazon",
      "results": [
        {
          "title": "Samsung Galaxy Buds2 Pro Wireless Earbuds",
          "url": "https://amazon.com/dp/B0B4RJP5J1",
          "rating": "4.3 out of 5 stars (15,240 reviews)",
          "price": "$149.99"
        }
      ]
    }
  ],
  "summary": {
    "total_products": 42,
    "platforms_count": 8,
    "price_range": "$24.99 - $299.99",
    "best_deal": {...},
    "top_rated": {...}
  }
}
```

## 🔧 Version Comparison

| Feature | BrightData<br>`app.py` | FireCrawl<br>`app_firecrawl.py` | Tavily<br>`app_tavily.py` ⭐ |
|---------|:-----:|:-------:|:-----:|
| **Platforms** | 7 | 7 | 11 |
| **Reliability** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| **International** | ❌ | ❌ | ✅ |
| **Price Analysis** | ❌ | ❌ | ✅ |
| **Smart Dashboard** | ❌ | ❌ | ✅ |
| **Error Handling** | Basic | Basic | Advanced |
| **Prompt Engineering** | Simple | Hardcoded | Advanced |
| **Best For** | Production | Clean Data | Development |

## 🧠 AI Agent Architecture

### Workflow Diagram
```mermaid
graph TD
    A[🔍 User Query] --> B[🌐 Flask App]
    B --> C[🔗 MCP Client]
    C --> D[🧰 Load LangChain Tools]
    D --> E[🤖 ReAct Agent Processing]
    E --> F[📊 Multi-Platform Search]
    F --> G[✅ Structured Response]
    G --> H[🎨 Web Template Rendering]
    
    style A fill:#e1f5fe
    style E fill:#f3e5f5
    style G fill:#e8f5e8
```

### Key Components
1. **🌐 Flask Application**: Web server with async MCP integration
2. **🔗 MCP Client**: Bridge to external scraping tools via stdio
3. **🧠 LangChain Integration**: Loads MCP tools into LangChain ecosystem  
4. **🤖 LangGraph Agent**: ReAct pattern for intelligent decision making
5. **📊 Pydantic Models**: Type-safe response structuring and validation
6. **🎨 Jinja2 Templates**: Dynamic HTML rendering with Bootstrap styling

## 🛠️ Advanced Configuration

### Custom MCP Server
```python
# Add your own MCP server
server_params = StdioServerParameters(
    command='your-custom-mcp-server',
    args=['--config', 'config.json'],
    env={'API_KEY': os.getenv('YOUR_API_KEY')}
)
```

### Extend Platform Support
```python
# Add new platforms to PLATFORMS list
PLATFORMS = ['Amazon', 'eBay', 'YourPlatform']

# Update system prompt for new platform
SYSTEM_PROMPT += "For YourPlatform: use specific extraction logic..."
```

## 🐛 Troubleshooting

### Common Issues

**❌ MCP Server Not Found**
```bash
# Verify MCP server installation
npm list -g tavily-mcp
npm install -g tavily-mcp@latest
```

**❌ API Key Errors**
```bash
# Check environment variables
echo $OPENAI_API_KEY
echo $TAVILY_API_KEY
```

**❌ Node.js Issues**
```bash
# Update Node.js to latest LTS
nvm install --lts
nvm use --lts
```

### Debug Mode
```python
# Enable debug logging
import logging
logging.basicConfig(level=logging.DEBUG)
```

## 🤝 Contributing

We welcome contributions! Here's how to get started:

### Development Setup
```bash
# Fork and clone
git clone https://github.com/yourusername/ecommerce-ai-agent.git
cd ecommerce-ai-agent

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install development dependencies
uv sync --dev
```

### Contribution Guidelines
1. 🍴 **Fork** the repository
2. 🌿 **Create** feature branch (`git checkout -b feature/amazing-feature`)
3. ✅ **Test** your changes thoroughly
4. 📝 **Commit** with clear messages (`git commit -m 'Add: amazing feature'`)
5. 📤 **Push** to branch (`git push origin feature/amazing-feature`)
6. 🔄 **Open** a Pull Request

### Code Standards
- ✅ **Type hints** for all functions
- 📚 **Docstrings** for public methods  
- 🧪 **Unit tests** for new features
- 🎨 **Black** formatting (`black .`)
- 🔍 **Linting** with ruff (`ruff check .`)

## 📋 Roadmap

### 🎯 Version 2.0 (Coming Soon)
- [ ] **🔒 User Authentication**: Save searches and preferences
- [ ] **💾 Database Integration**: Store search history
- [ ] **📱 Mobile App**: React Native companion  
- [ ] **🌍 More Platforms**: Add 20+ international platforms
- [ ] **📈 Analytics Dashboard**: Search trends and insights
- [ ] **🔔 Price Alerts**: Notify when prices drop

### 🚀 Version 3.0 (Future)
- [ ] **🤖 Advanced AI**: GPT-4 Vision for product images
- [ ] **💰 Price Prediction**: ML models for price forecasting
- [ ] **🛒 Shopping Lists**: Collaborative shopping features
- [ ] **📊 Business Intelligence**: Enterprise analytics suite

## 📊 Performance Metrics

| Metric | Target | Current |
|--------|--------|---------|
| **Response Time** | < 10s | ~8s |
| **Platforms Searched** | 15+ | 11 |
| **Success Rate** | > 95% | ~92% |
| **Concurrent Users** | 100+ | 50 |

## 🔒 Security & Privacy

- ✅ **No Data Storage**: Search queries are not logged
- ✅ **Secure API Keys**: Environment variable protection
- ✅ **HTTPS Ready**: SSL/TLS support for production
- ✅ **Rate Limiting**: Built-in request throttling
- ✅ **Input Sanitization**: XSS and injection prevention

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

```
MIT License - Feel free to use, modify, and distribute!
```

## 👨‍💻 Author

**Edwin Quintero**
- 🐙 **GitHub**: [@edwinquintero](https://github.com/edwinquintero)  
- 💼 **LinkedIn**: [Edwin Quintero](https://linkedin.com/in/edwin-quintero)
- 📧 **Email**: edwin@example.com
- 🌐 **Website**: [edwinquintero.dev](https://edwinquintero.dev)

## 🙏 Acknowledgments

Special thanks to these amazing projects and services:

- 🦜 **[LangChain](https://langchain.com/)** - AI framework foundation
- 🧠 **[OpenAI](https://openai.com/)** - GPT-4o language model
- 🔍 **[Tavily](https://tavily.com/)** - Web search API
- 🌐 **[BrightData](https://brightdata.com/)** - Enterprise web scraping
- 🔥 **[FireCrawl](https://firecrawl.dev/)** - Clean web extraction
- 🐍 **[Flask](https://flask.palletsprojects.com/)** - Web framework
- 🎨 **[Bootstrap](https://getbootstrap.com/)** - UI framework

---

<div align="center">

**⭐ If this project helps you, please give it a star on GitHub! ⭐**

[![GitHub stars](https://img.shields.io/github/stars/yourusername/ecommerce-ai-agent?style=social)](https://github.com/yourusername/ecommerce-ai-agent)
[![GitHub forks](https://img.shields.io/github/forks/yourusername/ecommerce-ai-agent?style=social)](https://github.com/yourusername/ecommerce-ai-agent)

Made with ❤️ for the open source community

</div>