PHPackages                             gtstudio/module-ai-data-query - 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 &amp; Helpers](/categories/utility)
4. /
5. gtstudio/module-ai-data-query

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

gtstudio/module-ai-data-query
=============================

Natural-language data query interface for Magento 2. Lets admin users ask questions in plain English; the AI extracts intent and queries Magento entities locally — no raw store data sent to the LLM.

1.0.3(2w ago)05↓100%BUSL-1.1PHPPHP &gt;=8.1

Since Mar 9Pushed todayCompare

[ Source](https://github.com/gabrielgts/module-ai-data-query)[ Packagist](https://packagist.org/packages/gtstudio/module-ai-data-query)[ RSS](/packages/gtstudio-module-ai-data-query/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (3)Versions (4)Used By (0)

Gtstudio\_AiDataQuery
=====================

[](#gtstudio_aidataquery)

Natural-language data query interface for Magento 2. Ask questions in plain English — the AI figures out what to query, the query runs locally, and results are returned directly to the browser. **No store data is ever sent to the LLM.**

Preview
-------

[](#preview)

[![AiDataQuery — asking plain-English questions and getting store analytics results](docs/images/aidataquery-preview.gif)](docs/images/aidataquery-preview.gif)

AI Studio Ecosystem
-------------------

[](#ai-studio-ecosystem)

Part of the **AI Studio** suite for Magento 2. See all modules:

ModuleRepositoryDescription**Gtstudio\_AiConnector**[module-aiconnector](https://github.com/gabrielgts/module-aiconnector)Core AI provider abstraction**Gtstudio\_AiAgents**[module-ai-agents](https://github.com/gabrielgts/module-ai-agents)Agent &amp; tool orchestration, cron scheduling, execution log**Gtstudio\_AiWidgets**[module-ai-widgets](https://github.com/gabrielgts/module-ai-widgets)Floating admin chat widget + PageBuilder AI generator**Gtstudio\_AiDataQuery***(this module)*Natural-language store analytics (privacy-first)**Gtstudio\_AiKnowledgeBase**[module-ai-knowledge-base](https://github.com/gabrielgts/module-ai-knowledge-base)Document upload &amp; RAG retrieval for agents**Gtstudio\_AiDashboard**[module-ai-dashboard](https://github.com/gabrielgts/module-ai-dashboard)AI-powered KPI dashboard with ML insightsWhat It Does
------------

[](#what-it-does)

- Admin chat page where users type questions like *"Show me the top 10 orders from last month"* or *"Which products have less than 5 units in stock?"*
- Two-phase privacy-first architecture:
    - **Phase 1** — LLM receives only the user's question and returns a structured intent (which tool to call, which parameters)
    - **Phase 2** — the server executes the query locally using the resolved intent and returns results directly to the browser
- Built-in query tools: order analytics, customer lifetime value, product performance, and a general entity query
- Token cost display in the chat interface

Privacy Architecture
--------------------

[](#privacy-architecture)

The LLM sees **nothing** about your store data. It only:

- Receives the user's natural-language question
- Returns a JSON object describing which analytical tool to call and with what parameters

All actual database queries run on your server. Results are displayed to the user without routing back through the AI provider.

Requirements
------------

[](#requirements)

- Magento 2.4.4+
- PHP 8.1+
- `Gtstudio_AiConnector` enabled and configured
- `Gtstudio_AiAgents` enabled

Installation
------------

[](#installation)

```
composer require gtstudio/module-ai-data-query
php bin/magento module:enable Gtstudio_AiDataQuery
php bin/magento setup:upgrade
```

A database agent record with code `data_query` is created automatically via a data patch.

Usage
-----

[](#usage)

Navigate to *AI Studio → Data Query*.

**Example questions:**

- *"Show total sales for the last 30 days"*
- *"What are my top 5 customers by revenue?"*
- *"List orders with status Pending from this week"*
- *"Show products with inventory below 10 units"*
- *"What is the average order value for this month?"*

Built-in Query Tools
--------------------

[](#built-in-query-tools)

Tool CodeDescription`order_analytics`Sales totals, order status distribution, average order value, top customers`customer_lifetime_value`LTV ranking, RFM analysis, acquisition trends`product_performance`Top sellers, low performers, revenue by category, inventory alerts`query_entity`General-purpose query against any Magento entityExtensibility
-------------

[](#extensibility)

### Registering a Custom Query Tool

[](#registering-a-custom-query-tool)

1. Implement `Gtstudio\AiAgents\Api\ToolExecutorInterface`:

```
namespace Vendor\Module\Model\Tool;

use Gtstudio\AiAgents\Api\ToolExecutorInterface;

class StoreRevenueExecutor implements ToolExecutorInterface
{
    public function execute(array $parameters): string|array
    {
        $storeId = (int) ($parameters['store_id'] ?? 0);
        // ... query DB, return formatted results
        return "Revenue for store #{$storeId}: $12,500.00";
    }
}
```

2. Create a tool record in *AI Studio → Tools* with matching code (e.g. `store_revenue`).
3. Register the executor via `di.xml`:

```

                Vendor\Module\Model\Tool\StoreRevenueExecutor

```

4. Update the `data_query` agent's Background or Steps in the admin to describe your new tool so the LLM knows when to choose it.

### Registering a Queryable Entity

[](#registering-a-queryable-entity)

The `query_entity` tool dispatches to registered entity handlers. Add a new entity:

```

                Vendor\Module\Model\Tool\MyEntityHandler

```

Implement the handler to return a collection, field list, and filter map.

### Customising the Planner Prompt

[](#customising-the-planner-prompt)

The system prompt that instructs the LLM is built in `DataQueryChatService::buildPlannerPrompt()`. Override the service:

```

```

ACL Resources
-------------

[](#acl-resources)

ResourceControls`Gtstudio_AiDataQuery::management`Access to the Data Query page and its API endpoints

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance99

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

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

Every ~1 days

Total

3

Last Release

14d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ab1f0030c21bebf4e87187df361e770ffaa2c0d3cdcd0cd45c77a79db5836156?d=identicon)[gtstudio](/maintainers/gtstudio)

---

Top Contributors

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

### Embed Badge

![Health badge](/badges/gtstudio-module-ai-data-query/health.svg)

```
[![Health](https://phpackages.com/badges/gtstudio-module-ai-data-query/health.svg)](https://phpackages.com/packages/gtstudio-module-ai-data-query)
```

###  Alternatives

[baldwin/magento2-module-url-data-integrity-checker

Magento 2 module which can find potential url related problems in your catalog data

281756.4k](/packages/baldwin-magento2-module-url-data-integrity-checker)[yireo/magento2-webp2

Magento 2 module to add WebP support to the Magento frontend

2091.2M7](/packages/yireo-magento2-webp2)[smile/module-store-delivery

Smile Store Delivery

23344.3k1](/packages/smile-module-store-delivery)[webrotate360/module-product-viewer-standard

WebRotate 360 Product Viewer Standard Integration for Magento 2. This extension allows integrating embedded 360-degree or 3D product views into standard gallery on product pages in Magento 2. The product views can be created using our free publishing software available on webrotate360.com.

1357.2k](/packages/webrotate360-module-product-viewer-standard)[magenerds/richsnippet

This module provides rich snippet functionality

1024.8k](/packages/magenerds-richsnippet)[graycore/magento2-graphql-introspection-cache

1014.9k](/packages/graycore-magento2-graphql-introspection-cache)

PHPackages © 2026

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