Parastore: an isometric sandbox for LLM shoppers, with the accuracy claim stated up front

The gap Parastore is trying to close between survey personas and store floors

Intellicia generates synthetic consumers as virtual personas and runs surveys against them in place of, or alongside, real respondents. Parastore is the company's attempt to push that idea from a questionnaire into a physical space. The README frames the question directly: if a synthetic shopper can answer a survey question, can the same construct walk through a store, pick items up, and end up paying for something? The repository is the answer in prototype form. It is aimed at people who already accept LLM personas as a research instrument and want to see whether the instrument survives contact with floor plans, aisles, and entry points. The README lists three intended uses: A/B testing store layout and circulation, testing product placement and its effect on conversion, and prototyping layouts for acquisitions or remodels before physical resources are committed. Those are all comparison tasks. The project is built to tell you whether layout A beats layout B under a synthetic population, not to tell you what next quarter's revenue will be.

Two processes, one timeline: how a persona becomes a path through the store

The stack splits cleanly. The backend is Python 3.13 with FastAPI, Pydantic, LiteLLM, Instructor, a pathfinding library, pandas, and openpyxl. The frontend is React 19 with Vite, TypeScript, React Three Fiber over Three.js, TanStack Router and Query, Zustand, Tailwind v4, shadcn/ui, Recharts, and ExcelJS. LiteLLM is the provider abstraction, which is why the default model can be swapped by editing one config file rather than rewriting call sites. Instructor sits in front of the LLM calls to coerce responses into Pydantic shapes, which matters here because the pipeline needs structured output (a traffic profile per weekday, individual personas per hour) rather than prose. The data flow described in the walkthrough runs in one direction: an address and a one-line customer-profile description go in, the LLM analyzes the trade area, produces a daily traffic profile per weekday, and then generates personas for each hour of operation. Those personas are what walk the floor. During a run, the 3D view animates their paths in real time against a wall-clock timeline, and the pathfinding dependency is what turns a persona's intent into a route around shelves and counters. The dashboard aggregates visitor count, conversion rate, dwell time, and per-rack engagement as the run proceeds. Generation is batched and parallelized, and the README estimates a minute or two depending on store size and provider latency.

Getting it running: uv, pnpm, and one API key

The requirements are explicit: Python 3.13 or newer with uv, Node 20 or newer with pnpm 10.33.0 as pinned in frontend/package.json, and an LLM provider API key. The default model is gemini/gemini-3.1-pro-preview through LiteLLM, so a GEMINI_API_KEY works without further configuration. The quick start is two lines: copy backend/.env.example to backend/.env and add the key, then run ./scripts/dev.sh. That script starts uvicorn on port 8000 and vite on port 5173 together, and Ctrl-C stops both. The app is then at http://localhost:5173. If you prefer to run the sides separately, the backend is cd backend, uv sync, then uv run uvicorn store_emulator.server.main:app --reload; the health endpoint is curl http://localhost:8000/api/health and interactive OpenAPI docs sit at http://localhost:8000/docs. The frontend is cd frontend, pnpm install, pnpm dev, with VITE_API_URL available to point at a different host. Production builds are frontend-only: cd frontend && pnpm build, while the backend has no build step and is meant to run uvicorn behind a process manager. To change providers you edit backend/src/store_emulator/application/config.py and supply the matching *_API_KEY variable. There is also a USAGE.md aimed at AI coding assistants, which the README says documents the inputs the simulation hinges on, the LLM call count for a given persona size, and silent-failure modes worth catching before a run.

The persona cap is the design constraint, not a footnote

Parastore caps persona generation at 100 per day by default, controlled by the PERSONA_DAILY_CAP environment variable. The README explains why: the goal is to compare layout and product-placement variants, not to reproduce a real store's full customer flow. That single default shapes everything downstream. A store with hundreds of daily visitors is being sampled, not reproduced, so any metric on the dashboard inherits the sampling error of a hundred agents before it inherits any error from the LLM. The README also warns that generating a week of personas for a modest store can run to hundreds of LLM calls and that provider cost and latency are real, so raising the cap is a budget decision, not just a config tweak. There is a second constraint the README is candid about: no ground-truth calibration. Outputs are described as LLM-grounded plausibility rather than validated forecasts, and the numbers are meant to be read as illustrative. The published accuracy figures compound this. The chart comparing actual sales history at a convenience store against Parastore simulations covers 500 real customers and 109 products, and reports Spearman correlation of 0.955 by category, JS-Similarity of 0.802, and NDCG@all of 0.868. The note under that table states the results were generated via Intellicia's own synthetic consumers, not the synthesis method published in this repository. So the headline numbers are not a claim about the code you would clone.

Where the abstraction breaks: address grounding and the missing signals

The create-store wizard takes a real-world store address plus a one-line customer-profile description, and the README says the address grounds the LLM's trade-area analysis. That is a thin input for a demographic model. Everything the simulator believes about who lives nearby and when they shop is inferred from a string you typed. Two users describing the same corner store in different words can get different persona populations, and nothing in the documented pipeline checks the inference against census data, foot traffic, or anything else. The README's own list of what a rigorous offline-sales model would need is the clearest statement of the boundary: POS history, real foot-traffic data, SKU-level taxonomies, weather and seasonality signals, and queueing dynamics. None of those are wired up. Queueing is worth calling out separately because it is a retail dynamic that layout changes are supposed to influence. Without queue modeling, a layout that creates a checkout bottleneck will not show the cost of that bottleneck in dwell time or conversion, which means one of the most common reasons to move fixtures is invisible to the simulator. If your question is about throughput under load rather than which shelf placement draws more attention, Parastore is the wrong instrument.

Against a discrete-event simulator: agents that reason versus queues that count

The obvious alternative for layout testing is a discrete-event or agent-based simulation written in something like SimPy or Mesa, where shoppers are stochastic processes and the model is calibrated against observed arrival rates and pick probabilities. The difference in approach is where the behavior comes from. A discrete-event model derives it from distributions you fit to data you already collected. Parastore derives it from an LLM prompted with an address and a profile description. That has two consequences worth weighing. First, Parastore needs no historical data to produce a run, which is exactly why it is usable for a store that does not exist yet, an acquisition target, or a remodel nobody has measured. A calibrated discrete-event model cannot start without the data it is calibrated on. Second, Parastore's behavior is not auditable in the way a fitted distribution is. You can inspect a Poisson arrival rate and argue about it. An LLM's trade-area inference is a black box whose stability across runs is not documented in the material available here. If you have POS history and foot-traffic counts, a discrete-event model will give you a defensible number and Parastore will give you a plausible one. If you have neither, Parastore at least gives you something to look at, provided you remember which of those two things you are holding.

Maintenance surface, licence, and what a fork inherits

The licence is MIT, which permits commercial use, modification, and redistribution with the licence and copyright notice preserved. That is a permissive starting point for a fork, and the README's framing supports it: the project is offered as a starting point for your own experiments, a reference for wiring an LLM-driven agent simulation end to end, or something to play with. Nothing in the supplied material suggests a warranty, and a prototype with no ground-truth calibration should not be treated as one; this is a description of the licence text, not legal advice. On maintenance, the surface area is larger than the language count suggests. There is no release history in the material provided, so versioning and upgrade cadence cannot be assessed from what is available. A fork inherits two moving targets at once: a Python backend pinned to 3.13 that depends on LiteLLM and Instructor, both of which track upstream provider APIs, and a frontend on React 19 and Tailwind v4, both of which are recent major lines. Provider model names are the most brittle part. The default is gemini/gemini-3.1-pro-preview, and preview model identifiers get retired; when that happens, the fix is an edit to backend/src/store_emulator/application/config.py plus the matching key, but any saved project that assumed the old model's output shape is a separate question the documentation does not answer. Budget for the LLM calls as an operating cost, not a one-time setup cost, because every persona run spends them again.

Editorial conclusion

Adopt Parastore if you want a working reference for wiring an LLM agent simulation into a 3D front end, or if you need a throwaway environment to compare two shelf layouts before committing to a remodel. Do not adopt it as a forecasting tool: the README states plainly that outputs are LLM-grounded plausibility rather than validated forecasts, and the accuracy figures it publishes are attributed to Intellicia's own synthetic consumers, not to the synthesis method in this repository. Before triggering a run, verify three things in your own checkout: that backend/.env holds a working key for the provider named in backend/src/store_emulator/application/config.py, that PERSONA_DAILY_CAP matches the persona volume you intend to generate, and that the address you typed into the create-store wizard actually corresponds to the trade area you care about, since that string is what grounds the analysis.

Official sources

1. intellicia-public/parastore on GitHub
2. Issues
3. License: MIT
4. README