VendingMachine

Modern C++20 multi-archetype vending-machine simulator with built-in AI augmentation: per-slot demand forecasting, anomaly detection, and an LLM-powered admin chat. Successor to the 2016 CPSC 246 student project; see docs/MIGRATION_FROM_V0.md for a side-by-side of what changed.

Features

• Five machine archetypes from one codebase: snack, beverage, coffee, refrigerated, contactless. See docs/MACHINE_TYPES.md.
• Hardware ports: TouchScreen, CoinAcceptor, BillValidator, plus PaymentProvider for card/contactless. Default desktop adapters (ConsoleTouchScreen, KeyboardCoinAcceptor, KeyboardBillValidator) ship and run without any peripherals; real MDB/ccTalk/DSI drivers drop in by implementing the same interfaces. See docs/HARDWARE.md.
• Cents-based decimal Money type — no floating-point arithmetic in change-making.
• Dynamic-programming change maker that detects unsolvable change requests (the V0 main.cpp greedy loop spun forever in this case).
• Holt-Winters per-slot 7-day demand forecasting (pure C++; no ML deps).
• Composite anomaly detector: jam, stockout streak, cash drift, expired item, brew failure, plus rolling Z-score on per-slot revenue.
• LLM-powered admin chat with tool-calling against an OpenAI-compatible HTTP endpoint. Configured by env vars; see docs/AI_FEATURES.md.
• Backwards-compatible CSV inventory format (V0's name,cost,quantity).
• CI matrix: Linux × {gcc-13, clang-17}, macOS × clang, Windows × MSVC.

Build

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failure

All third-party deps (GoogleTest, fmt, spdlog, nlohmann::json, CLI11, cpp-httplib) are fetched via CMake FetchContent — no vcpkg or conan required.

Quick start: snack archetype (V0-compatible)

build/vending buy --machine snack --inventory examples/snack_machine.csv

The examples/ directory ships an example CSV per archetype. The CSV format is the same as V0:

Doritos,1.25,5
Snickers,1.00,12
Chips,0.50,7

After purchase the CLI writes endReport.txt in the V0-compatible footer format (5-line Five Dollar Bills:N / One Dollar Bills:N / Quarters:N / Dimes:N / Nickels:N).

Quick start: other archetypes

# Beverage
build/vending buy --machine beverage --inventory examples/beverage_machine.csv

# Coffee
build/vending buy --machine coffee --inventory examples/coffee_machine.csv

# Refrigerated
build/vending audit --machine refrigerated --inventory examples/refrigerated_machine.csv

# Contactless (mock card provider — always approves)
build/vending buy --machine contactless --inventory examples/contactless_machine.csv

AI commands

build/vending forecast --machine snack --inventory examples/snack_machine.csv --horizon 7
build/vending alerts   --machine snack --inventory examples/snack_machine.csv --since 24
LLM_API_BASE_URL=https://api.openai.com/v1 \
LLM_API_KEY=sk-... \
LLM_MODEL=gpt-4o-mini \
  build/vending chat

Tool catalog exposed to the model: get_sales_summary, get_anomalies, get_forecast, get_low_stock_slots. See docs/AI_FEATURES.md.

Project layout

See docs/ARCHITECTURE.md for the full layered architecture (core / machines / ai / adapters / cli / ports).

License

Inherited from the original CPSC 246 / VendingMachine-1 repository.