# ppl/module-search-intelligence-core

> Shared Search Intelligence engine, indexing, Magento integration and response contracts for the Luma and Hyva storefront adapters.

`composer require ppl/module-search-intelligence-core`

Canonical URL: https://packagento.com/ppl/module-search-intelligence-core

## At a glance

- **Vendor**: Pawel Pliousnin Digital Solutions (https://packagento.com/ppl.md)
- **Latest version**: 1.3.0 — released 2026-07-12
- **Pricing**: $249.00/year, subscription
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

This is a paid package. The Packagento install flow is licence-gated, so a Composer install needs a licence + project + project credentials in place first.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Purchase the package.** Open https://packagento.com/ppl/module-search-intelligence-core, add it to your cart, and complete checkout. A licence is minted automatically once payment clears.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require ppl/module-search-intelligence-core:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Shared Search Intelligence engine, indexing, Magento integration and response contracts for the Luma and Hyva storefront adapters.

## README

PPL Search Intelligence Core is the single shared backend for the Luma and Hyva storefront adapters. It owns query understanding, product truth, schema, configuration, admin UI, routes, indexing, ranking, redirects, cron, queues and the stable storefront response contract.

### What It Adds
- Canonical search-page and overlay product truth
- Magento full and incremental indexing, MySQL/OpenSearch routing and optional Redis cache data
- Query rules, synonyms, corrections, redirects, recovery, ranking, merchandising and diagnostics
- One admin/configuration/schema/cron/queue implementation shared by both storefront adapters

### Requirements And Dependencies
- PHP >=8.1 and Magento Open Source or Adobe Commerce 2.4.9
- `Ppl_Hub` and the Magento modules declared in `composer.json`
- Exactly one storefront adapter: `Ppl_SearchIntelligence` for Luma or `Ppl_SearchIntelligenceHV` for Hyva
- Do not enable with `Ppl_ScoredSearch`; both modules own the same search surface

### Installation
Install one storefront adapter. Composer installs this Core package transitively.

```bash
## Luma
composer require ppl/module-hub ppl/module-search-intelligence
bin/magento module:enable Ppl_Hub Ppl_SearchIntelligenceCore Ppl_SearchIntelligence

## Or Hyva
composer require ppl/module-hub ppl/module-search-intelligence-hv
bin/magento module:enable Ppl_Hub Ppl_SearchIntelligenceCore Ppl_SearchIntelligenceHV

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:clean
```

For manual `app/code` installation, copy `Ppl/Hub`, `Ppl/SearchIntelligenceCore` and exactly one adapter into `app/code/Ppl`, then enable the same three modules in that order.

### First Use
- Disable `Ppl_ScoredSearch` and ensure only one Search Intelligence adapter is active.
- Run `ppl:search-intelligence:signals:rebuild` and `ppl:search-intelligence:index:rebuild` before enabling storefront suggestions or search-page ownership.
- Keep Magento cron running. Async rebuilding additionally requires AMQP/RabbitMQ; without it rebuilds remain synchronous.
- Pair the active adapter with the corresponding Discovery Filters frontend when overlay facets are required.

Admin entry: `PPL Hub > PPL Search Intelligence`.

### Integrations And Boundaries
- Cooperates with Discovery Filters only through PPL Hub capability contracts and the neutral filter integration event.
- Luma and Hyva call the same application service and receive the same versioned payload; only templates, JavaScript, CSS and adapter ViewModels differ.
- Queue XML is transport-neutral so setup and synchronous operation work without RabbitMQ. Heavy async indexing is enabled only after the AMQP queue is reachable and provisioned.

### Localization
The package includes translation CSV files for 12 locales: de_DE, en_US, es_ES, fr_FR, it_IT, ja_JP, nl_NL, pl_PL, pt_BR, ru_RU, tr_TR, zh_CN.

### Customer Documentation
Customer-facing User Guides and Marketplace Long Descriptions are maintained outside the Magento module package in the repository-level `docs/user_guides` and `docs/long_descriptions` folders. The module package itself intentionally keeps only this technical README plus developer-relevant files.

### Support
Support contact: pliousnin@ppl-ds.com. Include the module version, Magento version, enabled PPL companion modules, and the relevant admin or storefront screenshot when reporting an issue.

## Changelog

### 1.3.0
- Extracted the single shared backend used by the Luma and Hyva storefront adapters; schema, routes,
  configuration, admin UI, controllers, cron, queues, indexing, ranking and response contracts now
  have one owner.
- Added live product-truth validation, current customer-group pricing/tax formatting, MSI salability,
  deterministic recovery behavior and version-aware candidate totals.
- Added Magento indexer/mview product updates for catalog, price, inventory, category, rule and review
  changes; removed the unused reserved index-queue table and exposed the working indexer setting.
- Made queue XML transport-neutral while retaining the explicit AMQP capability gate for heavy async
  rebuilds, and bounded result-set cleanup with a non-blocking process lock.
- Added the shared overlay application service and stable versioned AJAX/profiler payload contract.
- Added Magento Open Source and Adobe Commerce 2.4.9 compatibility and PPL Hub 1.3 integration.

### 1.2.0

- Initial release.
- Added query understanding, MySQL candidate provider, explainable ranking and product signal rebuilds.
- Added admin Test Lab, hub-only configuration sections, CLI commands, cron jobs and core schema tables.
- Added optional configurable storefront suggestions, Discovery Filters integration and read-only internal provider status.
- Search result pages use Search Intelligence as the canonical product basis for product list rendering, Discovery Filters, toolbar totals, pagination and sorting.
- Added overlay fast-path payload mapping, action payload slimming, optional payload pruning and profiler payload parity.
- Added behavior-aware ranking gates that consume aggregated behavior signals; storefront behavior collection, impression tracking and purchase/return attribution are owned by the optional Ppl_Tracking module.
- Added Smart Discovery P0 payload support as an additive, read-only overlay field.
- Added Test Lab timing help and request-path details while keeping winner/loser row backgrounds neutral and limiting colored highlights to metric cells.
- Routed Search Intelligence <-> Discovery Filters cooperation through neutral Ppl_Hub capabilities: SI exposes the canonical search product set via the Hub SearchPageProductSetProviderInterface bridge and reads facet/filter data via the Hub FilterIndexReaderInterface, instead of reading a sibling module's tables.
- Declared an explicit magento/module-cron dependency and Magento_Cron load-order sequence so the bundled cron jobs (index bootstrap/rebuild, signal rebuild, knowledge-pack compile, result-set purge, async dispatch/advance) load deterministically.
- Normalized every ranking component to a common [0,1] scale before weighting, retuned the shipped default weights, and added a data patch that calibrates stored per-scope weight overrides onto the new scale so existing merchant tuning is preserved.
- Added optional async index rebuilds that fan a catalog rebuild out to the Magento message queue (one message per product batch, version-swapped only when complete) with a transactional outbox, per-minute dispatch/advance cron jobs and a broker-availability probe; falls back to the synchronous rebuild when no broker is configured.
- Extended product signal scoring with freshness (recency), return-rate, click-through and search-conversion terms and lifted the signal scale cap so strong products no longer saturate.
- Added search smoke/profile/recall diagnostic and corpus/benchmark/seed CLI commands that exercise the live SI + Discovery Filters result path through the Hub filter-index reader.

## Recent Versions

| Version | Released |
|---|---|
| 1.3.0 | 2026-07-12 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| ext-ctype | * |
| ext-curl | * |
| ext-hash | * |
| ext-mbstring | * |
| guzzlehttp/guzzle | ^7.5 |
| magento/framework | >=103.0.7 <104.0.0 |
| magento/module-advanced-search | >=100.4.0 <101.0.0 |
| magento/module-backend | >=102.0.0 <103.0.0 |
| magento/module-catalog | >=104.0.0 <105.0.0 |
| magento/module-catalog-inventory | >=100.4.0 <101.0.0 |
| magento/module-catalog-search | >=102.0.0 <103.0.0 |
| magento/module-checkout | >=100.4.0 <101.0.0 |
| magento/module-config | >=101.2.0 <102.0.0 |
| magento/module-configurable-product | >=100.4.0 <101.0.0 |
| magento/module-cron | >=100.4.0 <101.0.0 |
| magento/module-customer | >=103.0.0 <104.0.0 |
| magento/module-eav | >=102.1.0 <103.0.0 |
| magento/module-inventory-api | >=1.2.0 <2.0.0 |
| magento/module-inventory-reservations | >=1.2.0 <2.0.0 |
| magento/module-inventory-reservations-api | >=1.2.0 <2.0.0 |
| magento/module-inventory-sales | >=1.2.0 <2.0.0 |
| magento/module-inventory-sales-api | >=1.2.0 <2.0.0 |
| magento/module-message-queue | >=100.4.0 <101.0.0 |
| magento/module-review | >=100.4.0 <101.0.0 |
| magento/module-sales | >=103.0.0 <104.0.0 |
| magento/module-search | >=101.1.0 <102.0.0 |
| magento/module-store | >=101.1.0 <102.0.0 |
| magento/module-tax | >=100.4.0 <101.0.0 |
| magento/module-ui | >=101.2.0 <102.0.0 |
| magento/module-url-rewrite | >=102.0.0 <103.0.0 |
| magento/module-wishlist | >=101.2.0 <102.0.0 |
| php | >=8.1 |
| php-amqplib/php-amqplib | ^3.0 |
| ppl/module-hub | ^1.3 |
| psr/log | ^1.0 \|\| ^2.0 \|\| ^3.0 |
| symfony/console | ^6.4 \|\| ^7.0 |
| symfony/process | ^6.4 \|\| ^7.0 |

### Conflict

| Package | Constraint |
|---|---|
| ppl/scored_search | ^1.3 |

## Quality

Latest release (1.3.0) passes the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Warning | 5 | 5 warnings (ruleset: Magento2) |
| PHPMD | Warning | 65 | 65 rule violations (UnusedFormalParameter:33, MissingImport:16, ExcessiveClassComplexity:6, UnusedPrivateMethod:4, TooManyMethods:2) |
| Cpd | Warning | 18 | 18 duplicated chunks spanning 487 total lines (min-lines=5, min-tokens=70) |
| Composer validate | Info | 1 | valid; 1 advisory note (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | N/A | 0 | no resolvable dependency tree to audit: Your requirements could not be resolved to an installable set of packages. Problem 1 |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Subscription — $249.00/year, auto-renews until cancelled. Includes all minor + patch upgrades within the licensed major. One licence per project; cancelling stops auto-renewal but the existing licence keeps working until its end date.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["ppl/module-search-intelligence-core"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

Pawel Pliousnin Digital Solutions is a Magento 2 vendor on Packagento. See https://packagento.com/ppl.md for their full catalogue.