PHPackages                             navindbhudiya/module-product-recommendation - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. navindbhudiya/module-product-recommendation

ActiveMagento2-module[Utility & Helpers](/categories/utility)

navindbhudiya/module-product-recommendation
===========================================

AI-Powered Product Recommendations using ChromaDB Vector Database for Magento 2

1.0.0(5mo ago)172MITPHPPHP ^8.1 || ^8.2 || ^8.3

Since Dec 12Pushed 5mo agoCompare

[ Source](https://github.com/navindbhudiya-aws/magento2-ai-product-recommendations)[ Packagist](https://packagist.org/packages/navindbhudiya/module-product-recommendation)[ Docs](https://github.com/navindbhudiya-aws/magento2-ai-product-recommendations)[ GitHub Sponsors](https://github.com/sponsors/navindbhudiya)[ RSS](/packages/navindbhudiya-module-product-recommendation/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (14)Versions (2)Used By (0)

Magento 2 AI-Powered Product Recommendation Module
==================================================

[](#magento-2-ai-powered-product-recommendation-module)

[![Magento 2](https://camo.githubusercontent.com/7df245be8baa1e4f0c2b29d6ac9528a556eea0b8b70cef4db07a25c8205e45cf/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d6167656e746f2d322e342e362b2d6f72616e67652e737667)](https://magento.com/)[![PHP](https://camo.githubusercontent.com/45d36955804bf3f4f17097b05a7f41a28e578dc24e0d3ad0d21ae9d9762f44c6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312b2d626c75652e737667)](https://php.net/)[![License](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

An advanced AI-powered product recommendation system for Magento 2 that uses ChromaDB vector database and Large Language Models (LLMs) to provide intelligent, personalized product suggestions.

🎥 Video Demo
------------

[](#-video-demo)

Watch the full module tour and configuration guide:

[![Magento 2 AI Product Recommendation Module Demo](https://camo.githubusercontent.com/8fb0306b2bbc3ac24cc085617d3ce530a6cf4f9dfdaa7f69f139ca35bbc48fab/68747470733a2f2f696d672e796f75747562652e636f6d2f76692f74497531623330343779732f302e6a7067)](https://youtu.be/tIu1b3047ys)
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

[](#)

📋 Table of Contents
-------------------

[](#-table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Module Architecture](#module-architecture)
- [Usage](#usage)
- [CLI Commands](#cli-commands)
- [API Endpoints](#api-endpoints)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

---

✨ Features
----------

[](#-features)

### Core Capabilities

[](#core-capabilities)

- **AI-Powered Recommendations**: Uses vector embeddings and semantic similarity for intelligent product matching
- **Multi-LLM Support**: Integrates with Claude (Anthropic) and OpenAI for advanced ranking
- **ChromaDB Integration**: Leverages vector database for fast, scalable similarity searches
- **Personalization**: Tracks customer behavior (views, purchases, wishlist) for tailored recommendations
- **Real-time Updates**: Automatic indexing on product save/delete with event-driven architecture
- **Multiple Recommendation Types**:
    - Related Products (semantic similarity)
    - Cross-sell (complementary products)
    - Up-sell (premium alternatives)
    - Personalized recommendations (behavior-based)
    - Trending products (popularity-based)

### Technical Features

[](#technical-features)

- **Caching Layer**: Intelligent caching with configurable TTL
- **Circuit Breaker**: Fault-tolerant external API calls
- **Diversity Filtering**: Prevents redundant recommendations
- **GraphQL Support**: Complete GraphQL API for headless commerce
- **REST API**: Full REST API with WebAPI support
- **CLI Management**: Comprehensive command-line tools
- **Widget Support**: Easy CMS page integration
- **Hyva Theme Compatible**: Ready for Hyva-based stores
- **Admin Interface**: Full configuration UI in Magento Admin
- **Indexer Integration**: Magento indexer support for embeddings
- **Cron Jobs**: Automated data sync and refresh

---

📦 Requirements
--------------

[](#-requirements)

### System Requirements

[](#system-requirements)

- **Magento**: 2.4.6+ (2.4.7 or 2.4.8 recommended)
- **PHP**: 8.1+ (8.2 or 8.3 recommended)
- **MySQL/MariaDB**: 8.0+ / 10.4+
- **Elasticsearch/OpenSearch**: 7.x+ / 1.x+
- **ChromaDB Server**: Latest version
- **Memory**: Minimum 2GB PHP memory\_limit

### PHP Extensions

[](#php-extensions)

- `json`
- `curl`
- `openssl`
- `gd` or `imagick`

### External Services

[](#external-services)

- **ChromaDB**: Vector database (can be self-hosted or cloud)
- **LLM Provider** (optional): Claude AI or OpenAI API access

---

🚀 Installation
--------------

[](#-installation)

### Method 1: Composer (Recommended)

[](#method-1-composer-recommended)

```
# Navigate to Magento root
cd /path/to/magento2

# Require the module
composer require navindbhudiya/module-product-recommendation

# Enable the module
php bin/magento module:enable NavinDBhudiya_ProductRecommendation

# Run setup upgrade
php bin/magento setup:upgrade

# Compile DI
php bin/magento setup:di:compile

# Deploy static content (production mode)
php bin/magento setup:static-content:deploy -f

# Reindex
php bin/magento indexer:reindex

# Clear cache
php bin/magento cache:flush
```

### Method 2: Manual Installation

[](#method-2-manual-installation)

```
# Create module directory
mkdir -p app/code/NavinDBhudiya/ProductRecommendation

# Extract/copy module files to:
# app/code/NavinDBhudiya/ProductRecommendation/

# Enable and setup (same as above)
php bin/magento module:enable NavinDBhudiya_ProductRecommendation
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
```

### Method 3: Docker Setup (Development)

[](#method-3-docker-setup-development)

```
# Clone the repository
git clone https://github.com/navindbhudiya-aws/magento2-ai-product-recommendations.git

# Navigate to docker directory
cd magento2-product-recommendation/docker

# Start ChromaDB
docker-compose -f docker-compose.chromadb.yml up -d

# Optional: Start embedding service
docker-compose up -d
```

---

⚙️ Configuration
----------------

[](#️-configuration)

### 1. ChromaDB Setup

[](#1-chromadb-setup)

```
# Install ChromaDB (if self-hosting)
pip install chromadb

# Start ChromaDB server
chroma run --host 0.0.0.0 --port 8000

# Or use Docker
docker run -d -p 8000:8000 chromadb/chroma
```

### 2. Admin Configuration

[](#2-admin-configuration)

Navigate to: **Stores → Configuration → NavinDBhudiya → Product Recommendation**

#### ChromaDB Settings

[](#chromadb-settings)

- **Enable Module**: Yes
- **ChromaDB Host**:
- **Collection Name**: magento\_products
- **Batch Size**: 100 (for indexing)

#### Embedding Provider

[](#embedding-provider)

- **Provider**: ChromaDB (built-in) or Custom Service
- **Embedding Service URL**:  (if using custom)
- **Embedding Model**: all-MiniLM-L6-v2 (default)

#### LLM Provider (Optional)

[](#llm-provider-optional)

- **Enable LLM Ranking**: Yes
- **Provider**: Claude or OpenAI
- **API Key**: your-api-key-here
- **Model**: claude-3-sonnet-20240229 or gpt-4

#### Product Attributes

[](#product-attributes)

- **Attributes for Embeddings**:
    - name
    - description
    - short\_description
    - category\_names
    - brand (if available)

#### Recommendation Settings

[](#recommendation-settings)

- **Max Recommendations**: 10
- **Similarity Threshold**: 0.7
- **Enable Personalization**: Yes
- **Tracking Cookie Name**: pr\_tracking
- **Cache TTL**: 3600 seconds

#### Behavior Tracking

[](#behavior-tracking)

- **Track Product Views**: Yes
- **Track Purchases**: Yes
- **Track Wishlist Adds**: Yes
- **Behavior Weight**:
    - View: 1.0
    - Cart Add: 2.0
    - Purchase: 3.0
    - Wishlist: 2.5

---

🏗️ Module Architecture
----------------------

[](#️-module-architecture)

### Data Flow

[](#data-flow)

```
┌─────────────────────────────────────────────────────────────┐
│                     MAGENTO 2 FRONTEND                       │
│  (Product Pages, CMS Widgets, API Calls)                    │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   RECOMMENDATION LAYER                       │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Plugins    │  │   Blocks     │  │     API      │     │
│  │ (Related/    │  │ (Widgets/    │  │ (REST/       │     │
│  │  Cross/Up)   │  │  Templates)  │  │  GraphQL)    │     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘     │
│         └──────────────────┼──────────────────┘             │
│                            ▼                                 │
│           ┌────────────────────────────┐                    │
│           │  RecommendationService     │                    │
│           │  - Get Similar Products    │                    │
│           │  - Get Personalized        │                    │
│           │  - Apply Filters           │                    │
│           └──────────┬─────────────────┘                    │
└──────────────────────┼──────────────────────────────────────┘
                       │
         ┌─────────────┼─────────────┐
         ▼             ▼             ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│  ChromaDB  │ │    LLM     │ │   Cache    │
│   Client   │ │  Re-Ranker │ │   Layer    │
│ (Vector DB)│ │ (Optional) │ │            │
└─────┬──────┘ └────────────┘ └────────────┘
      │
      ▼
┌────────────────────────────────────────┐
│         ChromaDB Server                │
│  - Product Embeddings                  │
│  - Similarity Search                   │
│  - Vector Collections                  │
└────────────────────────────────────────┘

```

### Component Flow

[](#component-flow)

#### 1. Product Indexing

[](#1-product-indexing)

```
Product Save → Observer → Indexer → Embedding Generation → ChromaDB Storage

```

#### 2. Recommendation Request

[](#2-recommendation-request)

```
User Request → Plugin/Block → Service → Cache Check → ChromaDB Query →
LLM Ranking (optional) → Diversity Filter → Response

```

#### 3. Personalization

[](#3-personalization)

```
User Action → Behavior Collector → Customer Profile → Weight Calculation →
Personalized Recommendations

```

### Key Components

[](#key-components)

#### Service Layer

[](#service-layer)

- **RecommendationService**: Core recommendation engine
- **ChromaClient**: ChromaDB integration
- **EmbeddingProvider**: Generates product embeddings
- **LlmReRanker**: Re-ranks with LLM intelligence
- **DiversityFilter**: Removes redundant suggestions
- **ContextBuilder**: Builds user context
- **BehaviorCollector**: Tracks user behavior

#### Model Layer

[](#model-layer)

- **CustomerProfile**: Stores user preferences
- **LlmRanking**: Caches LLM results
- **ProductEmbedding**: Vector representations

#### API Layer

[](#api-layer)

- **REST API**: `/rest/V1/recommendation/`
- **GraphQL**: `personalizedRecommendations` query
- **WebAPI**: Service contracts

---

📖 Usage
-------

[](#-usage)

### Frontend Implementation

[](#frontend-implementation)

#### 1. Using Plugins (Automatic)

[](#1-using-plugins-automatic)

The module automatically enhances:

- Related Products block
- Cross-sell Products (cart page)
- Up-sell Products (product page)

No additional code needed!

#### 2. Using Widgets

[](#2-using-widgets)

Add to any CMS page:

```
{{widget type="NavinDBhudiya\ProductRecommendation\Block\Widget\PersonalizedProducts"
  title="Recommended For You"
  max_products="8"
  template="NavinDBhudiya_ProductRecommendation::personalized/recommendations.phtml"}}

```

#### 3. Using Layout XML

[](#3-using-layout-xml)

```

        10
        Recommended For You

```

#### 4. Using AJAX (Dynamic Loading)

[](#4-using-ajax-dynamic-loading)

```
require(['jquery'], function($) {
    $.ajax({
        url: '/productrecommendation/ajax/personalized',
        type: 'GET',
        data: {
            product_id: 123, // optional
            max_results: 10
        },
        success: function(response) {
            console.log('Recommendations:', response);
            // Render products
        }
    });
});
```

### GraphQL Query

[](#graphql-query)

```
query {
  personalizedRecommendations(
    customerId: 123
    currentProductId: 456
    maxResults: 10
  ) {
    product_id
    sku
    name
    price
    score
    reason
  }
}
```

### REST API Call

[](#rest-api-call)

```
# Get personalized recommendations
curl -X GET "https://your-store.com/rest/V1/recommendation/personalized?customerId=123&maxResults=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get similar products
curl -X GET "https://your-store.com/rest/V1/recommendation/similar/123?maxResults=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

💻 CLI Commands
--------------

[](#-cli-commands)

### Indexing Commands

[](#indexing-commands)

```
# Index all products to ChromaDB
php bin/magento productrecommendation:index:products

# Index specific products by IDs
php bin/magento productrecommendation:index:products --product-ids=1,2,3

# Re-index specific store
php bin/magento productrecommendation:index:products --store-id=2

# Clear collection and re-index
php bin/magento productrecommendation:index:products --clear-collection
```

### Recommendation Commands

[](#recommendation-commands)

```
# Get similar products for a product
php bin/magento productrecommendation:similar:get 123

# Get personalized recommendations for customer
php bin/magento productrecommendation:personalized:get 456

# Test with specific store view
php bin/magento productrecommendation:personalized:get 456 --store-id=2
```

### Maintenance Commands

[](#maintenance-commands)

```
# Refresh customer profiles
php bin/magento productrecommendation:profile:refresh

# Refresh all profiles
php bin/magento productrecommendation:profile:refresh --all

# Refresh trending products data
php bin/magento productrecommendation:trending:refresh

# Clear ChromaDB collection
php bin/magento productrecommendation:collection:clear

# Test ChromaDB connection
php bin/magento productrecommendation:connection:test
```

### Magento Indexer

[](#magento-indexer)

```
# Reindex product embeddings
php bin/magento indexer:reindex navindbhudiya_product_embedding

# Check indexer status
php bin/magento indexer:status navindbhudiya_product_embedding
```

---

🔧 Cron Jobs
-----------

[](#-cron-jobs)

The module includes several cron jobs:

JobScheduleDescription`productrecommendation_sync_embeddings`Every 6 hoursSyncs product changes to ChromaDB`productrecommendation_refresh_profiles`Daily at 2 AMRefreshes customer profiles`productrecommendation_refresh_trending`Every hourUpdates trending products data`productrecommendation_clean_cache`Daily at 3 AMCleans expired cache entries---

📊 Database Tables
-----------------

[](#-database-tables)

The module creates the following tables:

### `navindbhudiya_customer_profile`

[](#navindbhudiya_customer_profile)

Stores customer behavior and preferences:

- `profile_id` (primary)
- `customer_id`
- `viewed_products` (JSON)
- `purchased_products` (JSON)
- `wishlist_products` (JSON)
- `category_preferences` (JSON)
- `updated_at`

### `navindbhudiya_llm_ranking`

[](#navindbhudiya_llm_ranking)

Caches LLM ranking results:

- `ranking_id` (primary)
- `product_id`
- `context_hash`
- `ranking_data` (JSON)
- `model_name`
- `created_at`

---

🐛 Troubleshooting
-----------------

[](#-troubleshooting)

### ChromaDB Connection Issues

[](#chromadb-connection-issues)

```
# Test connection
php bin/magento productrecommendation:connection:test

# Check ChromaDB is running
curl http://localhost:8000/api/v1/heartbeat

# Check ChromaDB logs
docker logs chromadb  # if using Docker
```

### Indexing Problems

[](#indexing-problems)

```
# Clear and re-index
php bin/magento productrecommendation:collection:clear
php bin/magento productrecommendation:index:products

# Check indexer status
php bin/magento indexer:status

# Reset indexer
php bin/magento indexer:reset navindbhudiya_product_embedding
php bin/magento indexer:reindex navindbhudiya_product_embedding
```

### No Recommendations Showing

[](#no-recommendations-showing)

1. **Check module is enabled**:

    ```
    php bin/magento module:status NavinDBhudiya_ProductRecommendation
    ```
2. **Clear cache**:

    ```
    php bin/magento cache:clean
    ```
3. **Check configuration**:

    - Stores → Configuration → NavinDBhudiya → Product Recommendation
    - Ensure "Enable Module" is set to Yes
4. **Check product indexing**:

    ```
    php bin/magento productrecommendation:index:products
    ```
5. **Check logs**:

    ```
    tail -f var/log/system.log | grep -i recommendation
    tail -f var/log/exception.log
    ```

### Performance Issues

[](#performance-issues)

1. **Enable caching**:

    - Increase Cache TTL in admin config
    - Enable Magento Full Page Cache
2. **Optimize batch size**:

    - Reduce batch size in admin config if memory issues
    - Default: 100, try 50 for large catalogs
3. **Use circuit breaker**:

    - Configured automatically for LLM calls
    - Prevents cascading failures

---

🔒 Security
----------

[](#-security)

### API Authentication

[](#api-authentication)

REST API endpoints require:

- OAuth 1.0a or 2.0 authentication
- Customer token for personalized recommendations
- Admin token for management operations

### Data Privacy

[](#data-privacy)

- Customer behavior data is pseudonymized
- Tracking uses secure cookies
- Complies with GDPR requirements
- Data retention configurable via admin

---

🧪 Testing
---------

[](#-testing)

### Unit Tests

[](#unit-tests)

```
# Run unit tests
php vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist app/code/NavinDBhudiya/ProductRecommendation/Test/Unit

# Run specific test
php vendor/bin/phpunit app/code/NavinDBhudiya/ProductRecommendation/Test/Unit/Helper/ConfigTest.php
```

### Integration Testing

[](#integration-testing)

```
# Test recommendation flow
php bin/magento productrecommendation:similar:get 123

# Test with different parameters
php bin/magento productrecommendation:personalized:get 456 --max-results=20
```

---

📈 Performance Tips
------------------

[](#-performance-tips)

1. **Index regularly**: Schedule cron jobs for automated indexing
2. **Use caching**: Enable recommendation caching with appropriate TTL
3. **Optimize embeddings**: Select only relevant product attributes
4. **Monitor ChromaDB**: Ensure adequate resources for vector searches
5. **Batch operations**: Use CLI commands for bulk operations
6. **Circuit breaker**: Enabled by default for external API stability

---

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -m 'Add amazing feature'`
4. Push to branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

### Coding Standards

[](#coding-standards)

- Follow Magento 2 Coding Standards
- Use PHP\_CodeSniffer with Magento rules
- Add unit tests for new features
- Update documentation

---

📝 Changelog
-----------

[](#-changelog)

### Version 1.0.0 (Current)

[](#version-100-current)

- ChromaDB integration for vector database
- Vector similarity search for intelligent product matching
- LLM re-ranking support (Claude AI & OpenAI)
- Advanced personalization engine with behavior tracking
- GraphQL API support for headless commerce
- REST API with WebAPI integration
- Hyva theme compatibility
- Enhanced caching layer with configurable TTL
- Circuit breaker pattern for fault tolerance
- Diversity filtering to prevent redundant recommendations
- Custom embedding providers support
- Admin configuration UI
- Multiple recommendation types (Related, Cross-sell, Up-sell, Personalized, Trending)
- CLI commands for indexing and management
- Magento indexer integration
- Real-time product updates via observers
- Cron jobs for automated data sync
- Widget support for CMS pages
- Customer behavior tracking (views, purchases, wishlist)
- Initial release of complete AI-powered recommendation system

---

📄 License
---------

[](#-license)

This module is licensed under the MIT License. See [LICENSE](LICENSE) file for details.

---

👨‍💻 Author
----------

[](#‍-author)

**Navin D. Bhudiya**

- Email:
- GitHub: [@navindbhudiya](https://github.com/navindbhudiya-aws)
- Magento Certified: 4x
- AWS Certified: 2x

---

🙏 Acknowledgments
-----------------

[](#-acknowledgments)

- Magento 2 Community
- ChromaDB Team
- Anthropic (Claude AI)
- OpenAI

---

📞 Support
---------

[](#-support)

- **Issues**: [GitHub Issues](https://github.com/navindbhudiya-aws/magento2-ai-product-recommendations/issues)
- **Documentation**: [Wiki](https://github.com/navindbhudiya-aws/magento2-ai-product-recommendations/wiki)
- **Email**:

---

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance73

Regular maintenance activity

Popularity8

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

151d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/18b8c30f0537efcf8a0ce7b3862b904922f7a962509115577cba8761463cc4af?d=identicon)[navindbhudiya](/maintainers/navindbhudiya)

---

Top Contributors

[![navinmagento](https://avatars.githubusercontent.com/u/49339423?v=4)](https://github.com/navinmagento "navinmagento (1 commits)")

---

Tags

aiopenaimachine learningclaudellmmagento2magento 2embeddingschromadbvector-databasepersonalizationrelated productscross-sellproduct recommendationup-sell

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/navindbhudiya-module-product-recommendation/health.svg)

```
[![Health](https://phpackages.com/badges/navindbhudiya-module-product-recommendation/health.svg)](https://phpackages.com/packages/navindbhudiya-module-product-recommendation)
```

###  Alternatives

[mollie/magento2

Mollie Payment Module for Magento 2

1121.6M10](/packages/mollie-magento2)[dotdigital/dotdigital-magento2-extension

Dotdigital for Magento 2

50374.2k18](/packages/dotdigital-dotdigital-magento2-extension)[run-as-root/magento2-prometheus-exporter

Magento2 Prometheus Exporter

69344.4k](/packages/run-as-root-magento2-prometheus-exporter)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)