# ShopAgent

  
  An autonomous multi-modal fashion shopping agent powered by **LangGraph** and **ReAct pattern**.
  
  ## Demo
  
  📄 **[demo.pdf](./demo.pdf)**
  
  ## Overview
  

  ShopAgent autonomously decides which tools to call, maintains conversation state, and determines when to respond. Built with **LangGraph**, it uses agentic patterns for intelligent product discovery.

  
  **Key Features:**
  - Autonomous tool selection and execution

  - Text search via Search API

  - Conversational context awareness

  - Real-time visual analysis (style extraction from images) 

  
  ## Tech Stack
  
  | Component | Technology |
  |-----------|-----------|
  | **Agent Framework** | LangGraph |
  | **LLM** | any LLM supported by LangChain |

  | **Search** | Search API (HTTP) |

  | **Frontend** | Streamlit |
  | **Dataset** | Kaggle Fashion Products |
  
  ## Architecture
  
  **Agent Flow:**
  
  ```mermaid
  graph LR
      START --> Agent
      Agent -->|Has tool_calls| Tools
      Agent -->|No tool_calls| END
      Tools --> Agent
      
      subgraph "Agent Node"
          A[Receive Messages] --> B[LLM Reasoning]
          B --> C{Need Tools?}
          C -->|Yes| D[Generate tool_calls]
          C -->|No| E[Generate Response]
      end
      
      subgraph "Tool Node"
          F[Execute Tools] --> G[Return ToolMessage]
      end
  ```
  
  **Available Tools:**

  - `search_products(query)` - Text-based product search via Search API

  - `analyze_image_style(image_path)` - VLM style analysis
  
  
  
  ## Examples
  
  **Text Search:**
  ```
  User: "winter coats for women"
  Agent: search_products("winter coats women") → Returns 5 products
  ```
  

  **Style Analysis + Search:**
  ```
  User: [uploads vintage jacket] "what style is this? find matching pants"
  Agent: analyze_image_style(path) → "Vintage denim bomber..."
         search_products("vintage pants casual") → Returns matching items
  ```
  
  **Multi-turn Context:**
  ```
  Turn 1: "show me red dresses"
  Agent: search_products("red dresses") → Results
  
  Turn 2: "make them formal"
  Agent: [remembers context] → search_products("red formal dresses") → Results
  ```
  
  **Complex Reasoning:**
  ```
  User: [uploads office outfit] "I like the shirt but need something more casual"
  Agent: analyze_image_style(path) → Extracts shirt details
         search_products("casual shirt [color] [style]") → Returns casual alternatives

  
  **Note:** For image uploads "find similar", use analyze_image_style first to extract attributes, then search_products with the description.

  ```
  
  ## Installation
  
  **Prerequisites:**
  - Python 3.12+ (LangChain 1.x 要求 Python 3.10+)
  - OpenAI API Key

  
  ### 1. Setup Environment
  ```bash
  # Clone and install dependencies
  git clone <repository-url>

  cd ShopAgent

  python -m venv venv
  source venv/bin/activate  # Windows: venv\Scripts\activate
  pip install -r requirements.txt
  
  # Configure environment variables
  cp .env.example .env
  # Edit .env and add your OPENAI_API_KEY
  ```
  

  ### 2. (Optional) Download Dataset
  For image style analysis, you may download the [Fashion Product Images Dataset](https://www.kaggle.com/datasets/paramaggarwal/fashion-product-images-dataset) from Kaggle:

  
  ```bash

  python scripts/download_dataset.py

  ```
  

  ### 3. Launch Application

  ```bash
  # 使用启动脚本（推荐）
  ./scripts/start.sh
  
  # 或直接运行
  streamlit run app.py
  ```

  
  Product search uses the external Search API. Configure `SEARCH_API_BASE_URL` and `SEARCH_API_TENANT_ID` in `.env` if needed.
  

  Opens at `http://localhost:8501`
  
  ### CentOS 8 部署
  详见 [docs/DEPLOY_CENTOS8.md](docs/DEPLOY_CENTOS8.md)