A comprehensive product analysis and recommendation system that works with JSON data files. Features 12+ analysis engines, visual recommendations, Excel export, and interactive Python charts.

🎯 Comprehensive Analysis: Extract 15+ product attributes including sustainability, materials, style, pricing, brand analysis, dimensions, care instructions, target market, seasonal trends, quality assessment, and usage recommendations

🖼️ Visual Recommendations: Interactive matplotlib-based product comparisons with automatic image downloading and high-quality PNG export

📊 Professional Reports: Multi-sheet Excel exports with comprehensive data and interactive Python visualizations

🤖 No TensorFlow Required: Lightweight alternatives using scikit-learn and PIL for easy deployment

🏗️ Professional Architecture: Complete system documentation with Mermaid diagrams, component interactions, and data flow charts

⚡ Easy to Use: Simple configuration file setup - just add your JSON file paths and run!

pip install -r requirements.txt

Edit examples/product_lists.txt to add your JSON file paths:

# Product Lists Configuration
# Just add your JSON file paths - everything else is auto-detected!

C:\Users\YourName\Downloads\styles\product1.json
C:\Users\YourName\Downloads\styles\product2.json

# Analyze all products
python src/multi_product_analyzer.py --product-lists-config examples/product_lists.txt

# Create tabular charts with Python visualizations
python src/tabular_product_analyzer.py --product-lists-config examples/product_lists.txt

# Get product recommendations with visual display
python src/product_recommender_json.py --config-file examples/product_lists.txt --analyze
python src/product_recommender_json.py --config-file examples/product_lists.txt --recommend "PRODUCT_ID_HERE"

ProductClassification/
├── src/                          # Main source code
│   ├── json_data_loader.py       # JSON data loading utility
│   ├── multi_product_analyzer.py # Multi-file product analyzer
│   ├── product_analyzer_from_file.py # Single file product analyzer
│   ├── product_analyzer_json.py  # JSON-based product analyzer
│   ├── tabular_product_analyzer.py # Tabular chart generator
│   ├── product_recommender_json.py # Visual product recommendation system
│   ├── image_classifier_json.py  # Image classification
│   ├── combined_classifier_json.py # Combined text + image classifier
│   ├── simple_text_classifier.py # Text classification
│   ├── basic_text_analyzer.py    # Basic text analysis
│   ├── categorize_words_json.py  # Word categorization
│   ├── images/                   # Cached product images and recommendation visualizations
│   │   ├── product images (7 files) # Downloaded product images
│   │   └── recommendations_*.png # Visual recommendation charts
│   ├── 10045_401097928176_analysis.txt # Generated analysis report
│   └── product_analysis_charts.xlsx # Generated Excel charts
├── examples/                     # Example files and configurations
│   ├── product_lists.txt        # Your product lists configuration
│   ├── example_product_lists.txt # Example configuration template
│   ├── run_analysis.py          # Example analysis script
│   ├── run_examples.bat         # Windows batch file for examples
│   ├── analysis_results.txt     # Example analysis output
│   ├── comprehensive_analysis.xlsx # Example Excel output
│   ├── comprehensive_analysis_updated.xlsx # Updated example
│   └── comprehensive_analysis_with_python_charts.xlsx # Python charts example
├── results/                      # Legacy analysis results
│   ├── categories.txt           # Category data
│   ├── image-classification-top500-errors.html # Image classification errors
│   └── text-classification-top500-errors.html # Text classification errors
├── architecture/                 # System architecture documentation
│   ├── system_architecture.md   # Main architecture overview
│   ├── component_diagram.md     # Component interactions
│   └── data_flow.md            # Data flow documentation
├── requirements.txt             # Python dependencies
├── config.env.example          # Environment configuration template
└── README.md                   # This documentation file

• Multi-file Analysis: Analyze multiple JSON files simultaneously
• Comprehensive Metrics: Extract 15+ product attributes including sustainability, materials, style, pricing, brand analysis, dimensions, care instructions, target market, seasonal trends, quality assessment, and usage recommendations
• Inventory Analysis: Track SKU numbers, stock status, quantities, and locations

• Tabular Charts: Generate comprehensive Excel reports with multiple sheets
• Python Charts: Interactive matplotlib visualizations including:
  • Stock Status Distribution
  • Price Range Analysis
  • Brand Tier Distribution
  • Sustainability Analysis (Yes/No counts)
  • Inventory Categories
  • Market Segment Analysis
• Excel Export: Professional Excel files with formatted data

• Visual Display: Show target product and 5 recommendations with images
• Multiple Similarity Types: Text-only, image-only, or combined similarity
• Detailed Explanations: Explain why products are similar
• Image Processing: Download and analyze product images automatically

• Text Classification: Analyze product descriptions and names
• Image Classification: Extract visual features from product images
• Combined Analysis: Merge text and image features for comprehensive analysis
• No TensorFlow Required: Lightweight alternatives using scikit-learn and PIL

Copy config.env.example to config.env and configure:

SHOPSTYLE_API_KEY=your_api_key_here
DATABASE_URL=sqlite:///crawl.db

The examples/product_lists.txt file supports:

• Simple file path listing
• Automatic list name generation
• Auto-detection of categories and output files
• Comment support with #

python src/multi_product_analyzer.py --product-lists-config examples/product_lists.txt

python src/tabular_product_analyzer.py --product-lists-config examples/product_lists.txt --output-file my_analysis.xlsx

# First, analyze to see available products
python src/product_recommender_json.py --config-file examples/product_lists.txt --analyze

# Then get recommendations for a specific product
python src/product_recommender_json.py --config-file examples/product_lists.txt --recommend "productID" --top-k 5

python src/simple_text_classifier.py --json-file path/to/your/products.json

python src/image_classifier_json.py --json-file path/to/your/products.json

The recommendation system displays:

• Target Product: Large, centered display with image and description
• 5 Recommendations: Side-by-side layout with similarity scores
• Image Support: Automatic image downloading and display
• Fallback Handling: Placeholder images for missing or broken images
• Professional Layout: Clean, organized visual presentation

• Excel Reports: Multi-sheet workbooks with comprehensive data (src/product_analysis_charts.xlsx)
• Python Charts: Interactive visualizations displayed in separate windows
• Text Reports: Detailed analysis summaries (src/{list_name}_analysis.txt)
• Image Cache: Automatically cached product images (src/images/)

• Visual Display: Matplotlib-based product comparison
• Similarity Scores: Numerical similarity ratings
• Explanations: Detailed reasoning for recommendations
• Product Details: Names, descriptions, categories, and images
• Saved Visualizations: PNG files automatically saved to src/images/ (e.g., recommendations_prod261180192.png)

Here's an actual analysis output from the system analyzing 6 products:

The product recommendation system generates visual comparisons and saves them as high-quality PNG files:

🎬 See it in action! The system creates professional visualizations like this:

Try it yourself: Run python src/product_recommender_json.py --config-file examples/product_lists.txt --recommend "productID" to generate your own visual recommendations!

• Top Row: Target product (large, centered display)
• Bottom Row: 5 recommended products with similarity scores
• High Resolution: 300 DPI PNG files for crisp display
• Professional Layout: Clean, organized presentation with product details

• Format: recommendations_{PRODUCT_ID}.png
• Example: recommendations_prod261180192.png
• Location: src/images/ directory
• Automatic: Generated every time you run recommendations

🎯 PRODUCT: DRESSING FLORAL ITALIAN BRIEF

• ID: prod285360089
• Category: Women
• Materials: cotton, polyester, nylon
• Style: floral design
• Price: mid-range ($120)
• Brand: Lise Charmel
• Sustainability: ❌ No (Score: 1/10)
• Market: mass market, budget conscious
• Quality: standard craftsmanship

🎯 PRODUCT: SK 3/4S BTNK LNG

• ID: prod205250129
• Category: Women
• Materials: silk
• Style: Daytime occasions
• Price: luxury ($1038)
• Brand: Eskandar
• Sustainability: ✅ Yes (Score: 3/10, sustainable materials: silk)
• Market: premium market
• Quality: high craftsmanship

• Total Products: 6
• Sustainable Products: 1/6 (16.7%)
• Average Sustainability Score: 2.0/10
• Price Distribution: 4 premium, 1 mid-range, 1 luxury
• Quality Distribution: 4 high quality, 2 unknown
• Market Distribution: 4 premium market, 1 mass market, 1 luxury market
• Care Requirements: 4 high maintenance, 2 unknown

✅ Sustainability Analysis: Identifies eco-friendly materials and practices ✅ Material Extraction: Detects primary materials (cotton, silk, polyester, nylon) ✅ Price Analysis: Categorizes products by price range and luxury level ✅ Brand Analysis: Identifies brand names and reputation scores ✅ Market Segmentation: Determines target demographics and market positioning ✅ Quality Assessment: Evaluates craftsmanship and construction quality ✅ Care Instructions: Provides maintenance recommendations ✅ Style Analysis: Identifies design elements and occasions ✅ Dimensional Analysis: Extracts size and weight information

• Core: numpy, pandas, matplotlib, seaborn
• Image Processing: Pillow
• Excel Export: openpyxl
• HTTP Requests: requests
• Database: sqlalchemy
• Machine Learning: scikit-learn (optional)

• No TensorFlow Required: System uses lightweight alternatives
• JSON-Based: Works directly with JSON product data files
• Cross-Platform: Works on Windows, macOS, and Linux
• Extensible: Easy to add new analysis features
• Professional: Clean, organized codebase with proper documentation

1. Clone/Download this repository
2. Install dependencies: pip install -r requirements.txt
3. Configure product lists: Edit examples/product_lists.txt with your JSON file paths
4. Run analysis: python src/multi_product_analyzer.py --product-lists-config examples/product_lists.txt
5. View results:
   • Check src/{list_name}_analysis.txt for detailed text reports
   • Check src/product_analysis_charts.xlsx for comprehensive Excel data
   • View Python charts displayed in separate windows
   • Browse src/images/ for cached product images
   • Check src/images/recommendations_*.png for visual recommendation charts

Run the example script: python examples/run_analysis.py or double-click examples/run_examples.bat

For detailed understanding of the system architecture:

• System Architecture: Complete system overview with component diagrams
• Component Interactions: Detailed component relationships and data flow
• Data Flow: How data moves through the system from input to output

The architecture documentation includes:

• Component Diagrams: Visual representation of all system components
• Data Flow Charts: How data flows through the processing pipeline
• Sequence Diagrams: Step-by-step interaction flows
• Technical Details: Design patterns, scalability, and performance considerations

If you found this project helpful, please give it a ⭐ star! It helps others discover this tool and motivates continued development.

We welcome contributions! See our Contributing Guidelines for details.

• 🐛 Found a bug? Open an issue
• 💡 Have an idea? Suggest a feature
• 🔧 Want to contribute? Submit a PR

• 📖 Documentation: Check the Architecture Documentation for detailed system overview
• 💬 Discussions: Use GitHub Discussions for questions and ideas
• 🐛 Issues: Report bugs and request features via Issues

Made with ❤️ for the data science community

Enjoy analyzing your products! 🎉