⚡ ZYRON AI

Evidence-First Retail Intelligence Copilot

Ask → Analyze → Explain → Act

A production-grade, enterprise retail decision-support platform designed to give store managers instant morning operational clarity with zero hallucination and 100% mathematical auditability.

---

🌟 Overview

In modern multi-store retail, store managers are rich in data but rushed in time. Critical signals—imminent stock-outs before freight cutoffs, capital trapped in stagnant dead stock, sudden demand spikes, and cross-store inventory imbalances—are buried across static spreadsheets.

ZYRON AI bridges this gap. It is not a naive chatbot wrapping raw data; it is an enterprise decision-support copilot powered by deterministic arithmetic in Python and grounded reasoning via Google Gemini:

• 🛡️ Zero Number Hallucination: Every single metric (units, coverage days, percentages, rupees) is calculated deterministically by pure Python algorithms.
• 🔗 Evidence-First Traceability: Every recommendation links to an immutable evidence record (EVD-INV-xxx, EVD-SALES-xxx) with exact raw inputs, mathematical formulas, and explicit assumptions.
• 🚫 Strict Anti-Hallucination Guardrails: Refuses to guess or fabricate answers when asked about data dimensions outside the dataset (e.g., product profit margins or wholesale costs).
• 🚀 Single-Command Launch: Served completely on port 8000 through FastAPI and a pre-compiled React 18 frontend.

---

🏗️ System Architecture

🧩 Architectural Highlights & Layer Decoupling

Layer	Component	Technology	Primary Function
Presentation Tier	Store Manager Dashboard	React 18, Vite, Tailwind CSS, Recharts	Glassmorphic executive UI with zero-blur dynamic tiles, interactive charts, and drill-down audit modals.
API Gateway	Unified Application Server	FastAPI (ASGI / Uvicorn, port 8000)	High-performance asynchronous REST endpoints serving static SPA bundles and analytical payloads.
Guardrail Layer	Query Router & Data Sufficiency Guard	Python Rule Engine + Metadata Verifier	Validates whether incoming queries have necessary tabular grounding before triggering cognitive models.
Core Analytics	Deterministic Engine	Pure Python, Pandas, NumPy	Calculates Days of Inventory (DOI), velocity shifts, and the 0–100 Store Pulse Score with zero numeric hallucination.
Audit Ledger	Verifiable Evidence Store	Cryptographic JSON Store	Generates immutable records (EVD-INV-xxx, EVD-SALES-xxx) detailing exact formulas, source rows, and parameter thresholds.
Cognitive Engine	Grounded Retail Copilot	Google Gemini 1.5 Flash	Grounded semantic summarization, root cause reasoning, and contextual operational advisory strictly bounded by evidence.
Decision Support	What-If Scenario Simulator	Deterministic Simulation Engine	Evaluates hypothetical demand shifts (±50%) and lead-time delays (+10d) to stress-test inventory buffers.

---

🚀 One-Command Run

In accordance with official NexusTiq competition rules, running the entire project requires only one command:

# 1. Install dependencies
pip install -r requirements.txt

# 2. (Optional) Provide your Gemini API key
# Windows PowerShell:
$env:GEMINI_API_KEY="your_api_key_here"
# Linux / macOS:
export GEMINI_API_KEY="your_api_key_here"

# 3. Start the entire application
python app.py

Open your browser at:
👉 http://localhost:8000

Note

Graceful Fallback Mode: If GEMINI_API_KEY is not provided, ZYRON AI runs in Deterministic High-Fidelity Mode. All analytics, priorities, What-If simulations, and evidence chains remain 100% operational with zero crashes.

---

🎯 Features & Navigation

Tab	Feature	Description
📊 Dashboard	Executive Morning Briefing	Live 0–100 Retail Pulse Score, "Why this score?" audit modal, 4 key KPI cards, Today's Top Priorities, and 14-day sales velocity chart.
✨ AI Copilot	Conversational Command Center	Natural language queries with suggested prompt chips, structured executive answers, metric badges, verified findings, and audit links.
⚡ Today's Priorities	Ranked Action Register	Prioritizes morning issues: Critical Stockouts > Demand Surges with Thin Buffers > Overstock > Dead Stock.
📦 Inventory	Inventory Intelligence	Days of Inventory ($\text{DOI} = \text{Stock}/\text{ADS}_{14}$), lead-time comparisons, color-coded badges (HIGH RISK, WATCH, HEALTHY, OVERSTOCK, SLOW MOVING, NON MOVING).
📈 Sales	Sales Velocity Intelligence	Compares 14-day recent velocity vs. 30-day baseline to detect Spikes ($\ge +50%$) and Drops ($\le -40%$).
🏬 Stores	Multi-Store Benchmark	Side-by-side performance cards for Downtown Flagship, Central Mall Store, and Airport Express.
🔮 What-If	Scenario Simulator	Interactive sliders for Demand Shift ($-50%$ to $+100%$) and Supplier Delay ($-3$ to $+10$ days) with real-time risk recalculation.
🔍 Evidence	Audit Registry	Searchable repository of proofs with source CSV row references, observed numbers, exact formulas, and JSON export.

---

📐 Deterministic Formulas

1. Days of Inventory (DOI / Coverage)

$$\text{DOI} = \frac{\text{Current Stock}}{\text{Average Daily Sales (14d trailing)}}$$ Zero-Division Protection: If $\text{ADS} = 0$, DOI is safely classified as Non-Moving / Dead Stock without crashing.

2. Stockout Risk Classification

$$\text{Status} = \begin{cases} \text{HIGH RISK} & \text{if } \text{DOI} \le \text{Lead Time (days)} \ \text{WATCH} & \text{if } \text{Lead Time} < \text{DOI} \le 1.5 \times \text{Lead Time} \ \text{HEALTHY} & \text{if } 1.5 \times \text{Lead Time} < \text{DOI} \le 60\text{ days} \ \text{OVERSTOCK} & \text{if } \text{DOI} > 60\text{ days} \end{cases}$$

3. Sales Anomaly Deviation

$$\Delta% = \left(\frac{\text{Recent 14d ADS} - \text{Historical 30d Baseline}}{\text{Historical 30d Baseline}}\right) \times 100$$

• Spike: $\Delta% \ge +50%$ and absolute change $\ge 5\text{ units/day}$.
• Drop: $\Delta% \le -40%$ and baseline $\ge 3\text{ units/day}$.

4. Composite Retail Pulse Score (0–100)

$$\text{Pulse} = 0.25 \cdot S_{\text{inv_health}} + 0.25 \cdot S_{\text{stockout_safety}} + 0.20 \cdot S_{\text{momentum}} + 0.15 \cdot S_{\text{capital_efficiency}} + 0.15 \cdot S_{\text{stability}}$$

---

🧪 Engineered Scenarios

The included dataset in data/ features 50 products and 3 stores over 60 days (9,000 daily sales records) specifically pre-engineered to test edge cases:

Scenario	Target Product	Condition & Observation	System Behavior
A. Critical Stockout	Coca-Cola 500ml (P101) at Downtown	Stock = 30, ADS = 10, Lead Time = 5d	HIGH RISK ($\text{DOI} = 3.0\text{d} < 5\text{d}$). Creates EVD-INV-001.
B. Severe Overstock	Bio-Clean Washing Powder 2kg (P135)	Stock = 500, ADS = 2.0	OVERSTOCK ($\text{DOI} = 250\text{d} > 60\text{d}$ limit).
C. Slow-Moving	Cold Pressed Olive Oil (P122)	Stock = 95, ADS = 0.2 u/d	SLOW MOVING ($\text{DOI} = 475\text{d}$).
D. Dead Stock	Universal Travel Adapter (P148)	Stock = 40, Sales in 30d = 0	NON MOVING with safe undefined DOI.
E. Demand Surge	Red Bull Energy Drink (P103) at Airport	Baseline = 12 u/d, Recent = 28 u/d	SPIKE (+133%), rapid buffer depletion.
F. Sales Drop	Belgian Chocolate Box (P115)	Baseline = 18 u/d, Recent = 5 u/d	DROP (-72%), warns to check shelf facings.
G. Healthy SKU	Artisanal Sourdough Bread (P120)	Stock = 60, Lead Time = 2d, ADS = 15	HEALTHY ($2\times \text{ Lead Time}$ buffer).
H. Cross-Store	Organic Green Tea (P107)	Fast at Downtown, Dead at Airport	Highlights district stock rebalance opportunity.
I. Out of Scope	Question: "Highest profit margin?"	Cost/margin fields not in dataset	Strict Refusal: Explains data boundaries.

---

🛡️ Anti-Hallucination Guarantee

A critical requirement of the competition is that the AI must never guess or invent information.

When a user asks:

"Which product gives us the highest profit margin?"

ZYRON AI's Query Router identifies that product cost / margins are not part of the dataset and responds:

I cannot answer this question because 'Product Cost / Margin / Profitability' is not present in our retail dataset.

Available Dimensions:
- Daily Sales Units
- Inventory On-Hand
- Reorder Points
- Supplier Lead Times
- Selling Prices & Stores

---

✅ Testing

Run the automated test suite verifying all 9 core mathematical and safety guarantees:

pytest tests/ -v

============================= test session starts =============================
tests/test_anti_hallucination.py::test_anti_hallucination_refusal_on_profit_margin PASSED [ 11%]
tests/test_anti_hallucination.py::test_anti_hallucination_refusal_on_cogs PASSED          [ 22%]
tests/test_anti_hallucination.py::test_clarification_on_ambiguous_query PASSED           [ 33%]
tests/test_inventory.py::test_inventory_stockout_risk_scenario_a PASSED                  [ 44%]
tests/test_inventory.py::test_inventory_overstock_scenario_b PASSED                      [ 55%]
tests/test_inventory.py::test_inventory_dead_stock_scenario_d PASSED                     [ 66%]
tests/test_sales.py::test_sales_spike_scenario_e PASSED                                  [ 77%]
tests/test_sales.py::test_sales_drop_scenario_f PASSED                                   [ 88%]
tests/test_what_if.py::test_what_if_demand_surge_escalates_risk PASSED                   [100%]

============================== 9 passed in 1.42s ==============================

---

📋 Submission Compliance

• Track Identifier: TRACK_ID=PS03 (strictly line 1 of README).
• One Command Execution: pip install -r requirements.txt && python app.py on port 8000.
• Pre-Built Frontend: Compiled static files committed in frontend/dist/.
• Zero 3rd-Party Cloud RAG: Local in-memory TF-IDF index over knowledge/.
• External API Compliance: Google Gemini is the sole external network dependency.
• Demo Video: [Link to 2-3 Minute Demonstration Video]

---

**Built by ❤️ B.MUGILAN. Lead Architecture • AI Grounding • Operational Excellence