Aura of Clarity Magento 2 Manual | Installation, Configuration & Diagnostics

Chapter 01

Overview

Aura of Clarity is not a separate search application and not a chatbot layered over the shop. The extension enhances the existing Hyvä search directly in the Magento frontend while preserving the existing search box and theme.

The basic principleMagento product data is transformed into a local knowledge index. Text queries are evaluated semantically and lexically and then reranked locally by intent. For visual search, product images and customer images are compared with a local vision model.

What is processed locally

Text embeddings for semantic product search
Magento full text signals for exact and lexical matches
Intent reranking with a local mMARCO model
Image vectors and image search queries with a local CLIP model
Typo tolerance, hybrid ranking and Clarity logic
Query caching and protection against duplicate simultaneous calculation of identical queries

What can optionally be processed externally

Only the optional Product Knowledge enrichment with Claude Sonnet uses an external AI service. Only the designated product data is processed there. Customer search queries are not sent to Claude.

Chapter 02

Requirements

Component	Requirement	Notes
Magento	Magento 2.4.6 or newer	Aura integrates with product data, store views, search results and Magento indexers.
PHP	PHP 8.2 or newer	The release audit checks the active PHP version.
Frontend	Hyvä Theme	The existing Hyvä search box is enhanced in place.
PHP extensions	`curl`, `ffi`, `gd`, `mbstring`	FFI is required for local ONNX inference.
GD	JPEG and PNG, plus WebP for WebP uploads	Missing WebP support only prevents WebP search images.
ONNX PHP runtime	`ankane/onnxruntime ^0.3.6`	The runtime is installed separately through Composer.
Cron	Working Magento cron	Required for the recommended Update by Schedule indexer mode.

No additional search infrastructure required. Aura does not require a Python process, separate vector database, Docker container or external embedding service. If OpenSearch with k-NN is already available, Aura can use that vector path. Otherwise it uses the PHP Native vector path.

Local models

The local models and tokenizers must be present in the documented locations. The PHP ONNX runtime binding itself is not bundled with the extension and is installed as a regular Composer dependency.

Function	Model	Target file	Dimension
Text Perception	Xenova/multilingual-e5-small	`Model/ML/models/text/model.onnx`	384
Text Tokenizer	matching E5 Unigram tokenizer	`Model/ML/models/text/tokenizer.json`	-
Intent Perception	SugoLabs/mmarco-mMiniLMv2-L12-H384-v1	`Model/ML/models/reranker/model.onnx`	-
Intent Tokenizer	matching XLM-R Unigram tokenizer	`Model/ML/models/reranker/tokenizer.json`	-
Visual Perception	Xenova/clip-vit-base-patch32	`Model/ML/models/vision/vision_model.onnx`	512

Chapter 03

Installation

The extension is installed in app/code/Vermonta/AuraOfClarity. The PHP ONNX runtime binding is installed separately through Composer.

Copy the extension

Extract Aura of Clarity to app/code/Vermonta/AuraOfClarity.

Install the ONNX PHP runtime

Install the Composer dependency required by Aura.

Provide the local models

Place the text model, vision model, reranker and tokenizers in the documented directories.

Enable the Magento module

Enable the module and run Magento setup.

Configure the indexer

Update by Schedule is recommended for normal operation.

Configure Aura and build the first index

Enable Aura, optionally add the recommended Claude API key and then build the knowledge index.

Run the release audit

Verify runtime, models, upload capacity and index readiness.

Warm the Query Cache

After installation, warm the most important queries so common searches can be served directly from the Aura Query Cache.

Composer dependency

Shell

composer require ankane/onnxruntime:^0.3.6

Magento installation

Shell

php bin/magento module:enable Vermonta_AuraOfClarity
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

Set the indexer to Update by Schedule

Shell

php bin/magento indexer:set-mode schedule vermonta_auraofclarity_vectors

Build the initial full index

Shell

php bin/magento indexer:reindex vermonta_auraofclarity_vectors

Verify the installation

Shell

php bin/magento aura:release:audit --store=2
php bin/magento aura:license:check

Replace 2 with the store view ID you want to check.

Keep model files during updates. If the module directory is replaced, existing ONNX models and tokenizers must be preserved and restored to the same locations unless they are part of the delivered package.

Chapter 04

Configuration

Aura is deliberately designed so merchants do not need to tune search weights, thresholds or a large collection of technical parameters.

Enable it. Add an optional API key. Add Shop Knowledge when useful.Normal operation only requires Aura to be enabled. A Claude Sonnet API key can optionally enrich Product Knowledge. Shop Knowledge adds merchant specific expertise that cannot reliably be inferred from Magento data or general AI knowledge.

Core settings are available under Stores > Configuration > Vermonta > Aura of Clarity.

Setting	Meaning	Recommendation
Enable Aura of Clarity	Enables or disables Aura search in the frontend.	Yes for production use.
Claude API Key	Optional key for additional Product Knowledge enrichment. The value is stored encrypted and is never used for customer search queries.	Optional, but recommended for the best Product Knowledge quality. API keys can be created in the Anthropic Console.

Shop Knowledge

A central free text field is available in the Aura admin area under Experience > Shop Knowledge. Use it for relationships and terminology that customers use in your particular shop but which cannot be derived reliably from product data alone.

Example

When customers search for "cover inserts", they usually mean SKU 5154; SKU 5143 is an alternative.
When customers search for "DN wax sheets", SKUs 3520 and 3522 are especially relevant.

The first SKU receives the stronger priority within the merchant relationship, while additional SKUs can be supplied as alternatives. Shop Knowledge remains an additional signal inside the normal Aura pipeline rather than replacing semantic, lexical or intent ranking.

Keep Shop Knowledge factual and specific to your catalog. It is not intended as a place to program ranking rules. Each entry should describe a genuine relationship between customer language and products.

Clarity status area

Passage to 4th DimensionText Perception

Shows whether the local text model is ready.

Product KnowledgeProducts in the knowledge index

Shows the number of available text vectors.

Visual PerceptionVision model

Shows whether local visual inference is ready.

Intent PerceptionReranker

Shows whether the local intent model can be loaded.

The automatically selected vector path is also displayed: PHP Native or OpenSearch k-NN.

Chapter 05

Licensing and purchase process

Aura of Clarity is licensed for a registered shop domain. No license key has to be entered in Magento Admin. Vermonta activates the agreed domain.

One domain including true subdomainsIf shop.com is activated, the license also covers related subdomains such as www.shop.com, dev.shop.com or staging.shop.com. Separate root domains require their own license.

Purchase process

Request Aura

The Buy button on the Aura product page opens the Vermonta contact form.

Confirm requirements and domain

Vermonta briefly checks the technical requirements and confirms the shop domain to be licensed.

Activate the license

After purchase, the agreed domain is activated on the Vermonta licensing service.

Install the software

Install Aura of Clarity according to this manual.

License checks during operation

Aura periodically checks the license through the Vermonta licensing service. Temporary connection problems do not immediately disable Aura. If no valid license is available, only Aura functionality is disabled. Magento and the regular Hyvä product search remain available.

Check license

php bin/magento aura:license:check

Changing the root domain: If the shop permanently moves to another root domain, contact Vermonta so the license can be transferred.

Request Aura of Clarity through the Vermonta contact form →

Chapter 06

Product Knowledge and Shop Knowledge

Product Knowledge is the knowledge layer from which Aura creates semantic and lexical search signals. It already works without an external API key. Shop Knowledge adds the merchant's own catalog expertise.

Local product knowledge from Magento

Aura uses product name, SKU, category path, short description, description and up to 24 meaningful customer facing product attributes. Suitable text, textarea, select, multiselect and boolean attributes are included when they are visible, searchable, filterable or used in product listings. For select and multiselect attributes Aura uses the visible option labels rather than internal option IDs.

Optional enrichment with Claude Sonnet

When a Claude API key is configured, Aura can derive additional customer oriented meaning from existing product data, such as product type, purpose, typical situations, target groups, synonyms and natural customer phrasing.

The enrichment must not invent unsupported technical facts. If enrichment fails for a batch, indexing continues with local Magento product knowledge.

Hash and cache logic

Aura stores enriched product knowledge together with a hash of the relevant source data and a store view specific scope. As long as the relevant product data does not change, the existing knowledge is reused.

A reindex does not automatically create new API costs for every product. Unchanged products reuse the existing knowledge cache.

Shop Knowledge as a third knowledge layer

Magento data describes objective product facts. Optional AI enrichment adds general meaning and customer language. Shop Knowledge is the third layer: concrete terms, relationships and experience that only the merchant knows from the catalog and customer behavior.

Chapter 07

Indexing

The indexer ID is vermonta_auraofclarity_vectors and it appears in Magento as Aura of Clarity - Knowledge Index.

What a full run creates

Product Knowledge per active store view
normalized semantic text vectors
lexical search documents for Magento full text search
image vectors when a usable product image is available
optionally enriched and cached Claude Product Knowledge

The full index processes all active store views separately. Product data, locale, categories and knowledge scope are store view specific.

Recommended operating mode

Use Update by Schedule and make sure Magento cron runs reliably.

Check status

php bin/magento indexer:status vermonta_auraofclarity_vectors
php bin/magento indexer:show-mode vermonta_auraofclarity_vectors

Rebuild text knowledge only

Shell

php bin/magento aura:index:text-rebuild

Existing Claude knowledge and existing image vectors remain available.

Query Cache after index changes. Aura invalidates search cache entries on relevant index changes so stale rankings are not kept indefinitely.

Chapter 08

Text search

Aura combines multiple signals instead of replacing Magento search with a single AI model.

1. Query normalization and typo tolerance

Aura normalizes queries and can conservatively correct clear typos in longer, product relevant terms. Short tokens, pure numbers and SKU like values are not aggressively changed. The original and corrected forms remain part of the evaluation.

2. Lexical retrieval

Magento full text search provides precise signals for product names, SKUs and terms from the generated Product Knowledge document. Shop Knowledge can add merchant relevance.

3. Semantic retrieval

The local multilingual E5 model creates a query vector and searches for products with a semantically similar knowledge space.

4. Hybrid ranking

Lexical and semantic candidates are merged. Exact product signals remain available while natural problem descriptions and situations can also be understood.

5. Intent Perception

A local mMARCO Cross Encoder evaluates the strongest candidates again together with the actual customer query. Additional requirement signals are already used during recall; production reranking evaluates the complete customer query.

6. Results and Layered Navigation

On the full Aura results page, Magento filters for categories, price and configured product attributes remain available. These filters operate on the product IDs already found by Aura, preserving Aura relevance order.

Aura finds. Magento filters.The semantic result set is not intersected again with Magento full text search. Layered Navigation operates on the result pool already selected by Aura.

Flyout

The flyout displays the strongest matches directly below the Hyvä search box. The Show all results link appears only when additional relevant products exist beyond those already visible in the flyout.

Frontend fallback. If the Aura frontend enhancer cannot be loaded or Aura is disabled, the existing Hyvä or Magento search remains available as the base experience.

Chapter 09

Query Cache and Cache Warmer

Local ONNX models provide strong search quality but fully cold queries require compute time. Aura therefore stores the calculated product ID order in Magento cache. Product rendering, prices, URLs and images are still loaded fresh from Magento when results are hydrated.

Query Cache

Cache scope includes the store view, query and Aura search mode.
Changes to Shop Knowledge are reflected in the cache identity.
Empty results can also be cached.
The current default TTL is 24 hours.
If Magento cache is unavailable, search continues without the Query Cache.

Concurrency Lock

If several identical cold queries arrive at nearly the same time, Aura calculates the query only once. Other identical requests briefly wait for the resulting cache entry. Different queries are not globally blocked by this mechanism.

Cache Warmer

The Cache Warmer prepares common searches serially through the same search path used by the frontend. It first collects terms from Shop Knowledge and then adds real Magento search history from search_query, prioritized by popularity.

Queries for which Magento itself returned no results are not automatically discarded. These can be especially useful for Aura's semantic search. Empty values, pure numbers and obvious technical noise are filtered.

Dry run

php bin/magento aura:cache:warm --store=2 --limit=100 --dry-run

The dry run shows the selected terms without executing ONNX searches.

Warm top 100

php bin/magento aura:cache:warm --store=2 --limit=100

Existing valid cache entries are skipped.

Recalculate

php bin/magento aura:cache:warm --store=2 --limit=100 --force

--force intentionally recalculates the selected queries.

All eligible terms

php bin/magento aura:cache:warm --store=2 --limit=0

Do not use --limit=0 as the default. It includes all eligible search history terms. Large shops can contain tens of thousands of historical queries, so a limited set prioritized by popularity is usually the better production choice.

After a Magento cache flush

The Aura Query Cache currently resides in Magento cache and is therefore also cleared by php bin/magento cache:flush. After deployments or an intentional cache flush, run the Cache Warmer again.

Chapter 10

Visual Perception

Visual search enhances the existing Hyvä search with a camera icon. Customers can upload an image without knowing the product name.

Supported uploads

Formats	JPEG, PNG, WebP
Default limit	5 MB
Maximum pixels	25 megapixels
Minimum dimensions	16 × 16 pixels
Vision input	RGB, 224 × 224, ONNX tensor `[batch, 3, 224, 224]`
Vision output	normalized 512 dimensional image vector

Aura does not trust the browser filename or browser supplied MIME type. The actual image header, upload source, file size, image dimensions and available GD decoder are validated server side before inference starts.

Visual Confidence

The Confidence Gate is applied to raw CLIP cosine scores before Visual Clarity. This prevents semantic family similarity from creating artificial confidence for an unsuitable image.

Status	Internal zone	Frontend behavior
LOW	Top score < 0.700	No forced product suggestions.
UNCERTAIN	0.700 to < 0.750	No clear match message first; similar products can be revealed deliberately.
HIGH	0.750 and above	Normal visual results are shown.

These thresholds are internal release heuristics. They are deliberately not merchant settings.

Full visual results

For the full results page, Aura stores only ordered product IDs behind a random, time limited result token. The uploaded image itself is not stored permanently.

Chapter 11

Privacy and data flow

Aura technically separates local customer search from optional product data enrichment.

Local

Text queries

Processed on the shop server and not sent to Claude or an external embedding service for search.

Local & temporary

Search images

Validated and vectorized locally. Aura removes the temporary upload file after vector extraction.

Optional external

Product data

Only designated product data is processed externally when Claude Sonnet Product Knowledge enrichment is enabled.

Public search endpoints

Text and image AJAX responses use no-store, no-cache and nosniff headers. Aura search result pages are also not indexable.

Chapter 12

Store views and languages

Aura indexes active Magento store views separately and uses the respective store locale for Product Knowledge and search.

Locale	Language
`de_DE`	German
`de_CH`	German, Switzerland
`en_US`	English
`fr_FR`	French
`it_IT`	Italian

Optional Claude enrichment also uses a store view specific knowledge cache, allowing the same product to have language specific Product Knowledge in different store views.

Chapter 13

CLI tools

Aura includes diagnostic and maintenance commands for installation, operation, search quality and cache maintenance.

aura:release:audit

Checks PHP, extensions, ONNX runtime, models, upload capacity, vector path and store view specific index readiness.

aura:license:check

Checks the current domain license and displays its status.

aura:cache:warm

Warms important Shop Knowledge terms and frequent real Magento searches into the Aura Query Cache.

aura:search:diagnose

Shows the stages of text search for a specific query.

aura:semantic:probe

Compares a query with selected product IDs and Product Knowledge data.

aura:index:text-rebuild

Rebuilds text knowledge and text vectors without recalculating image vectors.

aura:image:diagnose

Diagnoses raw visual matches, Visual Confidence and Visual Clarity.

aura:image:benchmark

Processes a fixed image folder for visual regression tests.

Release audit

Shell

php bin/magento aura:release:audit --store=2

Cache Warmer

Shell

php bin/magento aura:cache:warm --store=2 --limit=100 --dry-run
php bin/magento aura:cache:warm --store=2 --limit=100

Diagnose text search

Shell

php bin/magento aura:search:diagnose "keep my bees calm without unnecessary stress" --store=2 --limit=10

Diagnose visual search

Local image

php bin/magento aura:image:diagnose /path/to/image.jpg --store=2 --limit=20 --pool=30

Chapter 14

Troubleshooting

Aura shows “WAITING FOR MODEL”

Run the release audit first. Missing model or tokenizer files and an unavailable ONNX PHP runtime are listed separately.

Shell

php bin/magento aura:release:audit --store=2

Text search returns no semantic matches

Check that the text encoder is ready in the audit and that Product Knowledge vectors exist for the affected store view. Then inspect the query with aura:search:diagnose.

A known query is slow again after a cache flush

Magento cache:flush also clears the Aura Query Cache. Run the Cache Warmer again.

Shell

php bin/magento aura:cache:warm --store=2 --limit=100

New or changed products are missing

Check the Aura indexer status and Magento cron.

Shell

php bin/magento indexer:status vermonta_auraofclarity_vectors
php bin/magento cron:run

Claude enrichment fails

Aura continues indexing with local Magento product knowledge. Check the API key, network access and Magento logs. Customer search queries do not depend on Claude.

OpenSearch k-NN is unavailable

This is not an error. Aura falls back to PHP Native. The active vector path is shown in Admin and in the release audit.

Chapter 15

Updates

Before replacing the module directory, preserve local model and tokenizer files if they are not part of the delivered package.

Typical steps after an update

php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush
php bin/magento aura:release:audit --store=2
php bin/magento aura:cache:warm --store=2 --limit=100

Whether a full Aura reindex is required depends on the release. Follow the release notes supplied with the version you received.

Optional update and compatibility service. Updates and ongoing compatibility can be booked for EUR 250 net per year. The already installed and licensed version remains usable without renewal.

Chapter 16

Support

Warranty and defect correction cover genuine software defects and security issues in the unmodified Aura extension. Individual customizations, integrations and general Magento consulting are not included.

Vermonta IT- & Media Agencyinfo@vermonta.de
www.vermonta.de

For efficient technical analysis, provide the Magento version, affected store view ID and the output of aura:release:audit.