Getting Started

Getting Started with ShelfWise

This guide walks you through running ShelfWise locally and processing your first UPC batch.

Prerequisites

• Python 3.12–3.14 or Docker Desktop
• Git
• (Optional) API keys for Azure OpenAI, GitHub Models, Brave Search, or Google Custom Search

Option 1: Run with Docker (Recommended)

cd agents-league-shelfwise
docker-compose up --build

Open http://localhost:8000/app in your browser.

To stop:

Ctrl+C

Option 2: Run with Python

cd agents-league-shelfwise
pip install -r requirements.txt
cd backend
python -m uvicorn main:app --host 127.0.0.1 --port 8000

Open http://localhost:8000/app.

First UPC Batch

1. Open the app at /app.
2. Paste one or more UPCs into the textarea (one per line).
3. Click Process UPCs.
4. Watch the live progress bar as sources are queried and products are enriched.
5. Browse the product cards, view reasoning traces, and export to your preferred marketplace format.

Upload a POS CSV

ShelfWise accepts CSV files with a required upc column. Optional columns are preserved and merged into the export.

Example CSV:

upc,name,department,quantity
049000050088,Coca-Cola 12pk,Beverages,24
038000183005,Kellogg's Frosted Flakes 14oz,Grocery,12

1. Click Choose CSV File.
2. Select your POS export.
3. Click Upload CSV.

Use case: Restaurants, convenience stores, and grocery merchants can download a UPC list from their POS system and upload it to generate listings for Uber Eats, DoorDash, Grubhub, or their own website.

Run the Demo

No UPCs handy? Click Load Demo to populate the app with three canonical products and see the full enrichment pipeline in action.

Next Steps

• Configuration — enable optional AI and search APIs.
• API Reference — integrate ShelfWise into your own workflow.
• Testing — run the test suite.