Copilot Module
The Copilot module is a global, read-only assistant built inside the admin shell. In simple words, it is a side panel that helps the user understand what the current dashboard or report means without changing any business data. It reads the current analytical screen, collects the most important facts, and then returns an explanation in plain language.
Overview
Copilot works as a right-side slide-over panel that can be opened from the top navigation bar. Once opened, it asks one main question: "Which page is the user on right now?" After that, it prepares a structured summary of the current screen before generating an answer.
This means Copilot does not behave like a free-form robot with access to the whole internet or direct database control. It only talks about the facts that were already prepared by the application from dashboard and report data.
A read-only analytical assistant for dashboard and report understanding.
It is not an auto-pilot, not a record editor, and not a direct database querying console.
Where It Works
Copilot is page-aware. That means it gives different answers depending on where the user opens it. The panel currently understands the following contexts:
- Dashboard: overall command-center explanation.
- Executive Summary: management-level risk and attention overview.
- Inventory Valuation: product economics, stock value, profit, and loss signals.
- Inventory Valuation Detail: one-product deep analysis including batches and movements.
- Purchase Cost Intelligence: purchase spend, cost averages, and variance patterns.
- Supplier Spend & Dependency: supplier concentration and spend mix analysis.
- Expiry & Batch Risk: expiry pressure and value-at-risk explanation.
- Loss & Stock-Out Reasons: leakage and reason analysis.
- Stock Movement Summary: inflow, outflow, and balance interpretation.
- Adjustment Variance: stock correction and variance interpretation.
How Copilot Understands the Current Page
Copilot does not read the screen the way a human reads a screenshot. Instead, the application creates a structured context packet for it.
- Screen name: which page the user is on.
- Context label: a plain-language title such as Dashboard or Supplier Spend.
- Facts: short business statements prepared from the current analytics.
- KPIs: headline metrics from the current screen.
- Top rows: the most important evidence rows that the answer is allowed to reference.
- Suggested questions: prompt ideas relevant to that specific page.
- Source links: direct links back to the pages or records behind the answer.
This is a very important design decision. It keeps Copilot focused, safer, and easier to trust. Instead of inventing answers from hidden data, it only explains curated facts already collected by the application.
Hybrid AI Mode vs Analytics-Only Mode
Copilot supports two runtime modes so the feature remains useful even when an AI API key has not been configured.
- The application first prepares structured business facts.
- An AI provider then turns those facts into natural language explanation.
- This mode is best when the user wants more human-like summaries and follow-up questions.
- No provider call is made when AI is disabled or the API key is missing.
- Copilot still works using deterministic summaries from the same facts.
- This prevents the side panel from feeling broken during first setup or on low-connectivity environments.
Opening Copilot
- Login to the admin panel.
- Open the dashboard or any supported report page.
- Click the AI Copilot button in the top navigation bar.
- The right-side slide-over panel appears.
- Read the suggested questions or type a custom question.
Suggested Questions
Copilot does not show the same starter prompts on every page. It generates suggestions based on the current screen. This makes the feature easier for non-technical users.
- Dashboard: What needs attention first right now?
- Inventory Valuation: Which products are locking too much capital?
- Product Detail: Why is this product underperforming?
- Supplier Spend: Is supplier concentration becoming risky?
- Expiry Risk: Which products are the biggest expiry pressure right now?
- Loss Reasons: Which loss reason is costing the most?
Source Cards and Trust
A good analytical assistant should not only answer. It should also show where the answer came from. Copilot does this using source cards and source links.
- They show which report or drill-down the answer is based on.
- They reduce blind trust by giving the user a path back to the evidence.
- They help buyers understand that the feature is analytical, not magical.
Permissions
Copilot is not automatically available to every user. Access is controlled by permissions.
- Use Analytics Copilot: required to open the panel and ask questions.
- Screen permissions still matter: if the user cannot access a report, Copilot should not be treated as a backdoor for that report.
- Export Reports: separate permission used for downloading analytical exports.
Settings and AI Provider
Copilot can be configured from the Settings module. This lets the application owner choose whether AI explanation is enabled and which provider details are used.
- Enabled: turns the provider-backed AI explanation layer on or off.
- Driver: tells the application which provider type to use.
- Base URL: the provider endpoint address.
- API Key: the secret credential required for hybrid AI mode.
- Model: the specific AI model name used for answer generation.
- Temperature: controls how strict or creative the language style feels.
- Test Saved Runtime: checks whether the saved provider configuration is working.
Failure Behavior
Copilot is designed to fail gracefully. If the provider is disabled, the key is missing, or the provider request does not succeed, the user still receives a deterministic summary instead of a blank error-heavy panel.
Example User Flow
- The manager opens the Dashboard.
- The manager opens Copilot and asks, "What needs attention first?"
- Copilot reads dashboard KPI cards, critical product rows, and recent risk signals.
- It answers with a short explanation such as expiry pressure, leakage, or supplier concentration.
- It returns follow-up questions and source links so the manager can drill deeper.
- If the manager moves to Supplier Spend and asks again, the answer becomes supplier-specific instead of dashboard-wide.
Practical Notes
- Copilot is strongest when report data is already clean and current.
- It should be marketed as a decision-support layer, not an autonomous operations engine.
- Its value comes from combining existing analytics with quick explanation and guided follow-up.
- Because chat is saved locally in the browser, recent conversation can survive page navigation without a dedicated database table.