StockSense AI

StockSense AI is a retail analytics MVP open-sourced on GitHub by developer sleepyaishik69, with the repository at https://github.com/sleepyaishik69/Stock-Sense

StockSense AI's core design principle is that the traditional analytics backend is responsible for generating evidence, and the optional local language model is only responsible for explaining the evidence; if the model is unavailable, the core dashboard works as usual

StockSense uses Python's Decimal type rather than floating point for monetary calculations, because binary floating point cannot exactly represent decimal fractions like 0.1, and after repeated accumulation, cent-level deviations appear

StockSense's AI path is invoked through a local Ollama service, with the configured model gemma2:2b, and the model has no SQL tool permissions and cannot modify inventory or place orders

StockSense's interface indicates whether the answer comes from the core analytics, the Gemma model, or the core analytics fallback, and displays the date range and the supporting metrics, products, and inventory evidence

StockSense's net sales are defined as gross sales minus discounts minus refunds; taxes are stored but not included in net sales

StockSense uses an append-only inventory movement ledger, recording opening counts, physical counts, arrivals, damages, and corrections, and sales imports will not quietly overwrite the day's inventory

StockSense's inventory ledger can only record changes after the user starts entering data, and cannot reconstruct inventory history that was never captured.

StockSense's tech stack is: frontend Next.js 16, React 19, TypeScript, Tailwind CSS, Recharts; API is Python, FastAPI, SQLAlchemy, Pydantic; SQLite for local development, PostgreSQL for the Docker Compose path; uses Alembic migrations.

StockSense's marketing view presents basket co-purchase patterns using support, confidence, and lift metrics, and only works when usable transaction IDs exist; these descriptive patterns cannot prove causality.

StockSense's replenishment estimates use the average daily units for the selected period, lead time, and the configured replenishment threshold, and do not model seasonality, confirmed purchase orders, supplier packaging specifications, or demand uncertainty, nor will they ever automatically generate purchase orders.

StockSense's import process accepts CSV and Excel files, with date, quantity, and unit price as required, and transaction ID, SKU, product name, category, discount, tax, unit cost, and return flag as optional; the backend rejects non-positive quantities and duplicate rows, and can record rejected rows and reasons in the import history.

Early versions of StockSense had problems such as a user asking "which product sells the most" but getting a response that it could not be determined while the evidence panel showed total sales, and asking "how to sell more" and getting broad marketing advice unrelated to the products and data.