RetailMind

• 

  onboarding

• 

  image digest

• 

Inspiration

Small and mid-size retailers in Africa—mini-marts, kiosks, local pharmacies, and boutiques—are the backbone of the economy. They actually generate a lot of sales data, which they save in simple CSV exports, POS tools, or manual Google Sheets. But they lack a dedicated business analyst to tell them what the data means. Shopkeepers are busy running their stores, managing inventory, and dealing with customers. They don't have the time or background to log into complex BI dashboards. We wanted to build something that meets them where they already live: WhatsApp. An AI partner that reads their numbers, computes critical metrics, and sends them direct, action-first insights—completely chat-driven

What it does

RetailMind connects directly to a retailer's existing sales data (Google Sheets or CSV) and operates as an autonomous COO:

1. Conversational Onboarding: The user initiates a conversation on WhatsApp. An LLM agent asks for their name and shop details, then drops a secure, short Google OAuth link.
2. Google Sheet Picker: The user signs in and selects their spreadsheet via a secure Google Picker. We request only drive.file scope to maintain trust.
3. Daily WhatsApp Digest: Every morning in their local timezone, they get a warm, brief summary: total revenue, week-over-week performance, top sellers, and stock alerts.
4. Proactive Anomaly Alerts: A background engine regularly polls the data. If it detects a sudden sales spike, drop, or impending stockout, it proactively sends a high-priority alert.
5. Interactive Q&A Agent: The retailer can reply to any message or ask questions like "what was my best seller last week?" or "how much sugar do I have left?". The AI responds using custom tools linked to a local Python analytics engine.

How we built it

FastAPI Backend: Manages webhook requests from Wuzapi, OAuth callbacks, and scheduled tasks. Pandas Analytics Engine: Computes all sales trends, velocity, low-stock forecasts, and anomaly Z-scores deterministically. LLM Layer: Powered by openai/gpt-oss-120b hosted on Groq Cloud for blazing-fast inference (~250–500 tok/s). We invoke it with a "reasoning_effort": "low" configuration to balance reasoning capability with quick WhatsApp conversational turns. The system separates computation from prose: all numbers are computed by Pandas, and the LLM only narrates the findings. This prevents AI hallucinations. Supabase Database: Houses tenant information, PKCE OAuth states, conversation messages for chat history, stock snapshots, and long-term shop notes. Wuzapi Gateway: A lightweight self-hosted Go-based WhatsApp gateway using the whatsmeow library. Emulates a linked web device, exposing a REST API locally for sending messages, and routing inbound texts to our FastAPI webhooks. Google OAuth 2.0 (with PKCE) & Google Picker API: Renders the file selector securely so the user doesn't have to share their entire Drive folder. Tunnels: Used ngrok and cloudflared to route local webhooks and callbacks during development.

Challenges we ran into

Hallucination Prevention: Financial/sales data requires 100% accuracy. We solved this by designing a strict policy: the LLM never calculates a metric. It must call tools that run on a deterministic Pandas engine. Messy Spreadsheet Formats: Shopkeepers don't write headers the same way. One writes Qty, another Quantity, another unit_price. We built a fuzzy schema auto-mapper in Python that standardizes header columns and strips currency symbols automatically. Frictionless Onboarding: We didn't want users to ever see a website except for the Google Picker. We designed a clean, robust Finite State Machine (FSM) inside the LLM onboarding agent that extracts metadata natively in chat.

Accomplishments that we're proud of

Trustworthy AI Architecture: A zero-hallucination guarantee on numbers by keeping the engine deterministic and using the LLM strictly as an interface. Conversational Google OAuth: Seamlessly transitioning from a WhatsApp text to Google Authentication and back into the chat. Fuzzy Schema Mapping: Making it incredibly easy to connect any standard sales sheet without manual database configuration.

What we learned

The power of prompt caching to reduce latency and API costs. Structuring LLM tool definitions so they return clean, grounded JSON data directly to the agent. How to run robust local testing pipelines using lightweight SQLite/Supabase combinations.

What's next for RetailMind

Paper Ledger OCR: A huge number of micro-retailers still write sales in physical notebooks. We plan to let them snap a photo of a ledger page on WhatsApp and have the AI parse and digitize the sales automatically. POS Integrations: Direct API syncs with Loyverse (the most popular free POS in Africa) and others. Multi-language Support: Code-switching prompts for Swahili, Pidgin, Hausa, and French. Automated Purchase Orders: Draft a purchase order when stock is low, and with one tap, send it directly to the supplier on WhatsApp.

Built With

• google-drive/sheets-api-(google-picker-widget-via-google-oauth-2.0-with-pkce)
• groq-cloud-api-(openai/gpt-oss-120b-reasoning-model)
• pandas
• python-(fastapi)
• supabase-(postgres-&-oauth-state-fsm-persistence)
• wuzapi-(go/whatsmeow-self-hosted-whatsapp-bridge)