🛒 Choufli Data

Tunisian Retail Analytics Dashboard & Derja-Speaking AI Business Consultant

Bech tchouf datek b'3in okhra 🇹🇳 — See your data through different eyes.

---

💡 What is this?

Most BI portfolio projects analyze the same Superstore CSV in USD. Choufli Data is different: a complete retail analytics application built for the Tunisian market, featuring Sami — an AI business consultant that answers questions about your live, filtered dashboard data in Tunisian Derja (Arabic script and Arabizi).

💰 Currency	Tunisian Dinar (TND), millime precision
🗺️ Geography	12 governorates, weighted by economic reality
🧾 Taxes	Real Tunisian TVA brackets: 7% / 13% / 19%
📅 Seasonality	Ramadan & Aïd demand spikes (Hijri calendar drift included!), official February/August soldes
💳 Payments	Espèces, Carte Bancaire, D17, Flouci, Chèque
🛍️ Products	Local brands: Délice, Safia, Warda, Le Phare, Sidi Daoud…
🤖 AI Agent	Speaks Derja, mirrors your script (عربي ↔ arabizi), cites real numbers from the filtered dashboard

💬 Talk to Sami

You:  Chnia a7sen gouvernorat fil ventes ?
Sami: Ahla ! 🇹🇳 Selon el dashboard, Tunis houa el awel b'158 000 TND,
      w baadou Sfax b'105 000 TND. El Sahel (Sousse + Monastir) zeda
      9awi barcha...
      💡 Recommandation : ركّز el stock mte3 el Électroménager fi Tunis
      w Sfax — houma eli yjibou akber panier moyen.

Sami is data-aware: every question is answered against a numeric summary of the currently filtered dashboard — change the sidebar filters and his answers change too. He never invents numbers; if it's not in the data, he says « Ma3andich el chiffre hedha fil dashboard ».

🏗️ Architecture

choufli-data/
├── generate_data.py      # Synthetic data engine (seeded → reproducible)
│                         #   governorate weights · TVA math · Hijri seasonality
├── data/
│   └── ventes_tunisie.csv
├── app.py                # Streamlit UI: KPI row · filters · 3 tabs
├── charts.py             # Plotly figures (CVD-safe validated palette)
├── ai_agent.py           # Derja system prompt · data summary · Gemini streaming
└── .streamlit/
    ├── config.toml       # Tunisian-flag theme (UI chrome only, never data marks)
    └── secrets.toml.example

Data flow for the AI (RAG-lite): sidebar filters → filtered DataFrame → compact numeric summary (construire_resume) → injected into the system prompt → Gemini Flash (gemini-flash-latest, overridable via GEMINI_MODEL) → streamed Derja answer.

🚀 Quickstart

git clone https://github.com/1hamzaachour-ai/choufli-data.git
cd choufli-data

python -m venv .venv
.venv\Scripts\activate          # Windows  (macOS/Linux: source .venv/bin/activate)
pip install -r requirements.txt

python generate_data.py         # regenerate the dataset (optional — CSV included)
streamlit run app.py

Enable the AI consultant (free):

1. Get a free API key at Google AI Studio — no credit card needed.
2. Either paste it directly in the app (Consultant IA tab — kept in session memory only), or save it permanently: copy .streamlit/secrets.toml.example → .streamlit/secrets.toml and paste it there (secrets.toml is gitignored — it never leaves your machine). GEMINI_API_KEY/GOOGLE_API_KEY environment variables work too.

☁️ Deploy to Streamlit Community Cloud (free)

1. Push this repo to GitHub (make sure secrets.toml is not committed — the .gitignore already protects it).
2. Go to share.streamlit.io → New app → select your repo, branch main, file app.py.
3. In App settings → Secrets, paste: GEMINI_API_KEY = "your_key"
4. Deploy. Your dashboard is live with a shareable URL. 🎉

📊 Dataset dictionary

Column	Description
id_commande	Order ID (CMD-00001…)
date	Order date (Jan 2025 → Jun 2026)
gouvernorat	One of 12 governorates, economically weighted
canal	Magasin (75%) / En ligne (25%)
categorie / produit	7 categories, 27 localized products
prix_unitaire_tnd	Unit price in TND (3 decimals = millimes)
quantite, remise_pct	Quantity; discounts spike during soldes (Feb/Aug)
total_ht_tnd, tva_pct, montant_tva_tnd, total_ttc_tnd	Tax math: TTC = HT + TVA, exact
mode_paiement	Espèces / Carte / D17 / Flouci / Chèque

Built-in insights to explore 👀 — the Ramadan revenue spike moves ~11 days earlier each year (Hijri drift: March 2025 → February 2026); Électroménager is ~6% of orders but the largest revenue share (classic Pareto); discount rate jumps from 8% to 45% in soldes months.

🧠 Prompt-engineering notes (the Derja agent)

• Instructions in French, style in Derja — the model follows structured French instructions more reliably, while few-shot examples pin down the Derja voice.
• Script mirroring — the prompt tells Sami to detect the user's script: Arabic script → Derja in Arabic letters; Latin/arabizi (chnia, 9adech, 3lech) → arabizi; French/English → arabizi with French business terms (natural Tunisian code-switching).
• Anti-hallucination rule — the data summary is declared the only source of truth, with an explicit fallback phrase when data is missing.
• Provider-agnostic — swap Gemini for OpenAI/Anthropic by rewriting one function (repondre_stream); the prompt and summary are untouched.

🗺️ Roadmap

• Choropleth map of Tunisia (governorate GeoJSON)
• Sales forecasting (Prophet / scikit-learn) with Ramadan regressors
• Sami "voice mode" (Derja TTS)
• Export PDF report generator

👤 Author

Hamza Achour — Management Information Systems student (BI specialization), Tunisia 🇹🇳

Licensed under the MIT License. "YOLO Test"