KasiStock AI

Turn limited cash into the right stock.

Comment

Inspiration

KasiStock AI was inspired by a practical challenge faced by many small retailers in South Africa: deciding what to restock when cash is limited and business information is fragmented. I experienced it firsthand, watching my wife who owns a small retail shop struggle to decide what to spend money on.

Most times, she may have only R1,000 or R1,500 available for purchasing stock, while several products are running low at the same time. She must decide which items are most urgent, which supplier offers the best value, how many units to purchase, and which products are likely to sell before the next restocking cycle.

These decisions are often made manually using:

  • visual shelf inspections;
  • handwritten notes;
  • WhatsApp messages;
  • photographed supplier price lists;
  • PDF catalogues;
  • invoices;
  • basic sales spreadsheets;
  • personal experience.

Large retailers solve similar problems using integrated inventory systems, demand forecasting, supplier catalogues, procurement teams, and enterprise resource planning software. Small and informal retailers rarely have access to the same infrastructure.

However, many of these small retailers already have access to a smartphone, photographs, WhatsApp, supplier documents, and basic sales records.

This led to the central question behind KasiStock AI:

Can AI transform the information a small retailer already has into a trustworthy, explainable, and budget-conscious purchasing recommendation?

I did not want to create another general-purpose chatbot. I wanted to build an application that performs a specific, economically meaningful task and produces an immediate business outcome.

The core product promise became:

Turn limited cash into the right stock.

KasiStock AI is designed around the belief that advanced AI should not be limited to large organisations with expensive systems. It should also help small businesses make better decisions using the information and tools already available to them.

What it does

KasiStock AI is an AI-assisted restocking and purchasing application for cash-constrained retailers.

It helps a merchant answer the question:

Given the stock I currently have, my recent sales, available supplier offers, and the amount of money I can spend, what should I buy?

The merchant can provide:

  • a photograph of the shop shelves or stockroom;
  • supplier price lists in image or PDF format;
  • recent sales history in CSV format;
  • a maximum purchasing budget.

KasiStock AI then guides the merchant through a controlled decision workflow.

1. Evidence extraction

GPT-5.6 analyses shelf photographs and supplier documents.

From a shelf image, the system can propose:

  • visible products;
  • brands;
  • pack sizes;
  • estimated quantities;
  • confidence levels;
  • reasons for uncertainty.

From supplier documents, it can extract:

  • product descriptions;
  • case prices;
  • unit prices;
  • case quantities;
  • minimum order quantities;
  • promotional offers;
  • supplier information.

All AI output is validated against strict schemas before it enters the application.

2. Human verification

AI-generated information is treated as proposed evidence rather than final truth.

The merchant can review the original evidence beside the extracted values and:

  • accept an observation;
  • correct a product name;
  • change an estimated quantity;
  • confirm a pack size;
  • mark a field as unknown;
  • reject an unsafe interpretation.

Unresolved or low-confidence evidence cannot silently continue into the purchasing workflow.

Once the merchant accepts or corrects the information, KasiStock AI creates an immutable accepted-evidence snapshot.

3. Product identity reconciliation

Supplier catalogues, shelf images, and sales records often describe the same product differently.

For example:

Coca-Cola Original Taste 2L
Coke PET 2 Litre
Coca Cola Original 2000ml

KasiStock AI reconciles these descriptions against a governed product catalogue using the following hierarchy:

Barcode
→ Governed alias
→ Exact normalised name
→ Fuzzy candidate
→ GPT-5.6 candidate proposal
→ Human confirmation

Exact barcode and governed alias matches can be accepted automatically.

Fuzzy and AI-assisted matches remain unresolved until they are confirmed by a person.

4. Restocking calculations

Once the evidence and product identities are accepted, deterministic TypeScript code calculates the purchasing inputs.

Average daily sales are calculated as:

[

\text{Average Daily Sales}

\frac{\text{Units Sold During the Observation Period}} {\text{Number of Observed Days}} ]

Days of stock cover are calculated as:

[

\text{Days of Cover}

\frac{\text{Current Stock}} {\text{Average Daily Sales}} ]

The reorder requirement is based on:

[

\text{Required Units}

\text{Target Demand} +

\text{Safety Stock}

\text{Current Stock} ]

Supplier prices are normalised using:

[

\text{Effective Unit Cost}

\frac{\text{Case Price}} {\text{Units per Case}} ]

The application then compares suppliers and prepares optimiser-ready product candidates.

5. Budget optimisation

The optimiser selects a combination of products while enforcing the merchant's available budget:

[ \sum_{i=1}^{n} \left( \text{Order Quantity}_i \times \text{Unit Cost}_i \right) \leq \text{Available Budget} ]

The optimisation considers:

  • sales velocity;
  • current stock;
  • stock-out risk;
  • expected demand;
  • available supplier prices;
  • pack sizes;
  • minimum quantities;
  • product priority;
  • excess-stock risk;
  • expected contribution margin.

The AI does not invent the order quantities or financial totals. These are produced by deterministic code.

6. Approval and purchasing

The merchant reviews the proposed order and can make permitted adjustments.

Before approval, the server rebuilds the draft from authoritative evidence rather than trusting values submitted by the browser.

The draft is then:

  • canonicalised;
  • hashed;
  • signed;
  • displayed to the merchant;
  • explicitly approved;
  • frozen into an immutable approval record.

After approval, KasiStock AI generates:

  • separate purchase orders for each supplier;
  • downloadable PDF purchase orders;
  • WhatsApp-ready supplier messages;
  • a complete audit timeline.

The prepared demonstration scenario uses a budget of R1,500 and produces:

Available budget:         R1,500.00
Approved order total:     R1,399.10
Budget remaining:           R100.90
Selected products:                3
Supplier purchase orders:         2
Supplier messages:                2
Audit events:                     6

How I built it

KasiStock AI was built as a standalone Next.js and TypeScript application.

The primary technologies include:

  • Next.js 16 for the web application, server routes, and production build;
  • React 19 for the interactive merchant workflow;
  • TypeScript for strict domain models and deterministic financial logic;
  • OpenAI Responses API for GPT-5.6 multimodal interpretation;
  • Zod for structured outputs and runtime validation;
  • Vitest for unit, integration, and evaluation tests;
  • Playwright for browser-level workflow tests;
  • PDF generation for supplier purchase orders;
  • PostgreSQL-compatible schemas for the planned persistence model;
  • Vercel-compatible configuration for public deployment.

I built the project incrementally.

Architecture and domain boundaries

The first step was defining the trust boundaries.

I divided the system into three authority layers:

  1. AI-proposed information
  2. Deterministic system calculations
  3. Human-authorised decisions

GPT-5.6 is responsible for interpreting unstructured information.

Deterministic code is responsible for:

  • currency calculations;
  • supplier comparisons;
  • quantity conversions;
  • budget enforcement;
  • optimisation;
  • document integrity;
  • approval integrity.

The merchant remains responsible for accepting uncertain evidence and authorising the final purchase.

Multimodal extraction

The extraction workflow accepts:

  • JPEG;
  • PNG;
  • WebP;
  • PDF;
  • CSV.

Uploaded files are checked for:

  • supported MIME type;
  • valid file signature;
  • size limits;
  • SHA-256 fingerprint;
  • duplicate processing;
  • schema-valid model output.

The original model output is preserved, while merchant corrections are recorded separately.

Structured AI responses

Instead of relying on unstructured prose, GPT-5.6 returns data through schema-constrained outputs.

A shelf observation includes fields such as:

product name
brand
pack size
estimated quantity
confidence
uncertainty reason
evidence description

A supplier offer includes:

raw product name
unit price
case price
case quantity
minimum order quantity
promotion
confidence

This makes AI output testable, auditable, and safe for downstream processing.

Deterministic financial engine

All monetary amounts are represented as integer cents.

For example:

R1,399.10 = 139910 cents

This avoids floating-point errors such as:

0.1 + 0.2 !== 0.3

Supplier unit-cost comparisons also use integer arithmetic and exact cross-multiplication.

Evidence and approval integrity

Important records are protected with deterministic hashes.

An accepted evidence snapshot is represented as:

[ H_E = \operatorname{SHA256} \left( \operatorname{CanonicalJSON} \left( \text{Accepted Evidence} \right) \right) ]

The accepted product mapping set has its own hash:

[ H_M = \operatorname{SHA256} \left( \operatorname{CanonicalJSON} \left( \text{Accepted Mappings} \right) \right) ]

Purchase-order drafts, approvals, and supplier orders are similarly hashed and signed.

If a browser modifies an accepted or signed record, server-side verification fails.

Testing and evaluation

The final application passed:

Automated test files:       17
Automated tests:            34
Test failures:              0
TypeScript checking:        Passed
ESLint warnings:            0
Production build:           Passed
Live GPT-5.6 validation:    Passed
Accessibility violations:  0

The product-matching evaluation achieved:

Product accuracy:          91.67%
Authority-state accuracy:  91.67%
Unsafe automatic merges:   0

The live GPT-5.6 validation returned:

Model:      gpt-5.6-sol
Status:     ready
Latency:    4.397 seconds

Challenges I ran into

Separating AI intelligence from financial authority

The most important design challenge was determining which decisions GPT-5.6 should make and which decisions must remain deterministic.

It would have been much simpler to provide all the evidence to the model and ask it to generate a final shopping list.

However, that approach would make the result harder to reproduce, validate, and audit.

I redesigned the workflow so that GPT-5.6 interprets evidence and proposes possible relationships, while deterministic code controls money, quantities, constraints, and approval.

This required more engineering, but it produced a far safer system.

Reconciling inconsistent product descriptions

The same product can appear under several names across shelf observations, sales records, and supplier catalogues.

Exact matching alone was not sufficient.

Unrestricted fuzzy or AI matching was also too risky because it could silently merge different products.

I solved this using a staged matching process that escalates uncertainty rather than hiding it.

The evaluation suite included one uncertain product that the system did not match correctly. Importantly, it remained unresolved instead of being merged automatically.

I treated that conservative failure as safer than false confidence.

Designing meaningful human oversight

Human review could not be a decorative confirmation screen.

The workflow had to guarantee that:

  • unresolved evidence could not continue;
  • unconfirmed product mappings could not enter calculations;
  • modified signed data would be rejected;
  • edited orders could not exceed the budget;
  • purchase orders could not be generated before approval.

Implementing these guarantees required explicit workflow states, immutable records, hashing, signing, and server-side reconstruction.

Handling money accurately

JavaScript floating-point behaviour created a risk for purchasing calculations.

Representing currency as integer cents solved this problem and made totals reproducible.

Pack-size and supplier-cost comparisons also had to avoid floating-point equality checks.

Building a portable dependency package

During local installation, the package lockfile contained absolute download links to an internal build registry.

The package versions were correct, but the URLs were inaccessible from an external Windows machine.

I repaired the lockfile so that all dependencies resolve from:

https://registry.npmjs.org/

This highlighted an important lesson: reproducibility depends on both dependency versions and portable package sources.

Toolchain and workspace detection

Next.js detected a lockfile in a parent directory and initially inferred the wrong project root.

The application still compiled, but the warning could have affected Turbopack behaviour.

I resolved it by explicitly setting the project root in the Next.js configuration.

Browser automation limitations

The build environment could not initially download or launch Playwright Chromium.

Rather than claiming browser coverage that had not occurred, I:

  • retained the complete browser-test suite;
  • ran production-route verification;
  • generated deterministic judging previews;
  • performed accessibility audits;
  • created real submission screenshots;
  • documented the remaining browser command transparently.

Maintaining scope discipline

The project could easily have expanded into:

  • full inventory management;
  • multi-tenancy;
  • accounting;
  • supplier onboarding;
  • WhatsApp Business integration;
  • delivery logistics;
  • advanced forecasting.

I deliberately focused on one complete vertical workflow:

Evidence
→ Verification
→ Product reconciliation
→ Financial calculation
→ Budget optimisation
→ Merchant approval
→ Supplier purchase orders

This allowed me to deliver a coherent and testable product rather than an unfinished platform.

Accomplishments that I am proud of

I am proud that KasiStock AI is more than a chatbot or prompt wrapper.

It combines:

  • multimodal image and document interpretation;
  • structured model outputs;
  • evidence validation;
  • human verification;
  • governed product matching;
  • deterministic financial calculations;
  • constrained budget optimisation;
  • explicit merchant approval;
  • cryptographic integrity controls;
  • supplier-specific PDF generation;
  • WhatsApp-ready messaging;
  • evaluation datasets;
  • accessibility and deployment engineering.

I am particularly proud of the trust architecture.

AI output cannot directly authorise a purchase. The application clearly separates:

  • what the AI proposes;
  • what the system calculates;
  • what the merchant approves.

I am also proud that the system achieved zero unsafe automatic product merges in the evaluation dataset.

When the system was uncertain, it remained unresolved instead of pretending to know the answer.

The purchasing workflow also passed deliberate tampering tests.

A modified signed purchase-order draft was rejected with:

HTTP 400
INVALID_DRAFT_SIGNATURE

A modified accepted mapping set was rejected with:

HTTP 400
INVALID_MAPPING_HASH

The final project also achieved:

34 automated tests passed
0 test failures
0 ESLint warnings
0 recorded accessibility violations
Successful production build
Successful live GPT-5.6 Sol validation

Most importantly, I am proud that the application addresses a clear economic need.

It demonstrates how advanced AI can help a small retailer use limited working capital more effectively without removing the merchant's control over the final decision.

What I learned

AI applications need explicit authority boundaries

The most important lesson was that model output should not automatically become business truth.

An AI application that affects money or operations must clearly define:

  • what the model may propose;
  • what deterministic code must verify;
  • what a human must approve;
  • what evidence must be retained;
  • what actions require immutable records.

Structured output is more valuable than persuasive prose

GPT-5.6 became much more useful when its responses were constrained by schemas.

Structured outputs made it possible to:

  • validate model responses;
  • identify missing fields;
  • detect uncertainty;
  • write repeatable tests;
  • connect model output safely to deterministic logic.

Safe uncertainty improves trust

An AI system should be allowed to say that it does not know.

Statuses such as:

Needs review
Insufficient evidence
No safe product match

are valuable product features.

They communicate uncertainty honestly and invite human judgement.

AI and deterministic software are complementary

AI was most effective for:

  • reading messy documents;
  • understanding image content;
  • interpreting language variations;
  • proposing possible matches;
  • explaining recommendations.

Deterministic code was most effective for:

  • calculating prices;
  • enforcing budgets;
  • converting quantities;
  • comparing suppliers;
  • applying constraints;
  • protecting workflow integrity.

The system became stronger when both approaches were given clearly defined responsibilities.

Human oversight must change system authority

A confirmation button alone does not create meaningful oversight.

Human review should create an explicit change in authority.

In KasiStock AI, accepted evidence and confirmed mappings become immutable, versioned records that are then permitted to enter the calculation engine.

Conservative failure can be a success

In product matching, an unresolved result is safer than an incorrect automatic merge.

The evaluation process taught me to value safe failure modes rather than optimising only for headline accuracy.

A narrow product can still demonstrate significant depth

By focusing on one complete workflow, I was able to include multimodal AI, optimisation, approval controls, cryptographic evidence, PDF generation, evaluations, deployment readiness, and accessibility.

Scope discipline allowed me to build something coherent and credible.

What's next for KasiStock AI

The current release is designed as a focused public demonstration, but the architecture supports a much broader product.

Durable production persistence

The first priority is moving all accepted evidence, product mappings, restocking scenarios, approvals, supplier orders, and audit events into a production PostgreSQL database.

This will support:

  • long-term merchant history;
  • order retrieval;
  • auditability;
  • recovery after interruptions;
  • operational reporting.

WhatsApp Business integration

KasiStock AI is naturally suited to WhatsApp.

A merchant could:

  • send a shelf photograph;
  • forward a supplier catalogue;
  • enter a budget;
  • review uncertain items;
  • approve a purchase plan;
  • send orders to suppliers.

A WhatsApp interface would make the application accessible without requiring merchants to learn a new business system.

Live supplier integrations

Future versions could connect directly to supplier catalogues and availability systems.

This would allow the application to:

  • retrieve current prices;
  • confirm stock availability;
  • detect promotions;
  • compare delivery fees;
  • submit orders electronically;
  • reconcile supplier confirmations.

Continuous inventory and sales history

Instead of relying only on uploaded snapshots, KasiStock AI could maintain continuous inventory and sales records.

This would improve:

  • demand estimates;
  • reorder timing;
  • stock-out prediction;
  • seasonal planning;
  • supplier-performance analysis.

Expiry-aware and storage-aware purchasing

The optimiser could incorporate:

  • product expiry dates;
  • shelf-life risk;
  • storage capacity;
  • refrigeration limits;
  • product-specific safety stock;
  • delivery schedules.

Multi-store and multi-tenant support

A production version could support:

  • multiple stores;
  • store-specific catalogues;
  • multiple employees;
  • role-based approvals;
  • central purchasing;
  • merchant organisations;
  • supplier networks.

Community buying

Several small retailers could combine purchasing demand to unlock:

  • bulk discounts;
  • shared delivery;
  • better supplier terms;
  • regional purchasing groups.

Invoice and delivery reconciliation

The workflow could continue after approval by:

  • reading supplier invoices;
  • comparing invoices to approved purchase orders;
  • detecting substitutions;
  • recording received quantities;
  • identifying price discrepancies;
  • updating stock after delivery.

Improved forecasting and evaluations

Future work will expand the labelled evaluation datasets and introduce:

  • larger product catalogues;
  • multilingual product descriptions;
  • OCR noise;
  • regional product aliases;
  • promotional pricing;
  • real merchant sales patterns;
  • seasonal demand forecasting.

The long-term vision is to give small retailers access to evidence-driven purchasing support that has traditionally been available only to large businesses.

KasiStock AI will continue to follow the same principle that guided the initial project:

AI should make complex information easier to understand, while people retain authority over consequential decisions.

Built With

  • codex
  • next.js-16
  • openai-responses-api
  • pdf-generation
  • playwright
  • postgresql
  • react-19
  • typescript
  • vercel
  • vitest
  • vscode
  • zod
Share this project:

Updates