[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81473":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":22,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":35,"readmeContent":36,"aiSummary":37,"trendingCount":15,"starSnapshotCount":15,"syncStatus":38,"lastSyncTime":39,"discoverSource":40},81473,"parastore","intellicia-public\u002Fparastore","intellicia-public","Draw a store, generate LLM personas, and watch them shop — an isometric 3D sandbox for synthetic-consumer experiments.","",null,"TypeScript",598,13,9,0,10,556,568,66,7.44,"MIT License",false,"main",[25,26,27,28,29,30,31,32,33,34],"agent-simulation","fastapi","isometric","litellm","llm","pathfinding","react-three-fiber","retail","synthetic-data","three-js","2026-06-12 02:04:15","\u003Cdiv align=\"center\">\n\n![Parastore](.\u002F.github\u002Fassets\u002Fparastore_hero.png)\n\n\u003Ch1>Parastore\u003C\u002Fh1>\n\nBuild, simulate, and optimize retail spaces with synthetic consumers.\n\n\u003Cbr>\n\n![Parastore](.\u002F.github\u002Fassets\u002Fintellicia_logo.png)\n\n\u003C\u002Fdiv>\n\n## Overview\n\n[intellicia](https:\u002F\u002Fintellicia.co) builds tooling around _synthetic\nconsumers_ — virtual personas generated by LLMs that we run surveys against\nin place of (or alongside) real respondents. Parastore is an experiment in\nextending that idea from surveys to **physical retail**: if we can simulate\nhow a synthetic shopper answers a survey question, can we also simulate how\nthey walk through a store, what they pick up, and what they end up paying\nfor?\n\nThis repository is a **prototype**, not a production forecasting tool. A\nrigorous offline-sales model would need POS history, real foot-traffic data,\nSKU-level taxonomies, weather\u002Fseasonality signals, queueing dynamics, and a\nlot more than what is wired up here. Parastore is closer to a sketch — a\n\"what if we tried it this way?\" — than a finished product. We are open\nsourcing it because the sketch itself might be useful: as a starting point\nfor your own experiments, as a reference for how to wire up an LLM-driven\nagent simulation end-to-end, or simply as something fun to play with.\n\n\n## Screenshots\n\n\u003Cdiv align=\"center\">\n\u003Ctable>\n\u003Ctr>\n\u003Ctd width=\"50%\">\u003Cimg src=\".\u002F.github\u002Fassets\u002Fscreenshot_1.png\">\u003C\u002Ftd>\n\u003Ctd width=\"50%\">\u003Cimg src=\".\u002F.github\u002Fassets\u002Fscreenshot_2.png\">\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd width=\"50%\">\u003Cimg src=\".\u002F.github\u002Fassets\u002Fscreenshot_3.png\">\u003C\u002Ftd>\n\u003Ctd width=\"50%\">\u003Cimg src=\".\u002F.github\u002Fassets\u002Fscreenshot_4.png\">\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\n## Use Cases\n\nParastore goes beyond simple 3D visualization. By combining LLM-driven synthetic consumers with physical space simulation, it allows you to test retail strategies in a risk-free environment. \n\n- **Store Layout & Circulation A\u002FB Testing:** Experiment with different aisle structures, entry points, and customer pathways to optimize traffic flow and eliminate dead zones.\n- **Product Placement & Conversion Testing:** Simulate how moving high-margin items or changing rack categories impacts customer engagement and overall purchase conversion rates within the store environment.\n- **Acquisition & Renewal Valuation:** Rapidly prototype and evaluate potential store layouts for new acquisitions or upcoming remodels before committing physical resources.\n\n## Simulation Accuracy\n\n\u003Cdiv align=\"center\">\n\u003Cimg src=\".\u002F.github\u002Fassets\u002Fpredicted_vs_actual_sales.png\" width=\"80%\">\n\u003C\u002Fdiv>\n\nTo evaluate performance, this chart compares **actual sales history from a physical convenience store** with **synthetic consumer simulations driven by Parastore**. The analysis covers 500 real customers and 109 different products.\n\n| Metric | Value | Scope |\n| :--- | :--- | :--- |\n| **Spearman Correlation** | `0.955` | By category |\n| **JS-Similarity** | `0.802` | Across all 109 products |\n| **NDCG@all** | `0.868` | Across all 109 products |\n\n>_Note: These results were generated via Intellicia's own synthetic consumers, not the synthesis method published in this repo._\n\n## Demo video\n\n\u003Cdiv align=\"center\">\n\n**▶️ Click to Watch the Full Demo Video:**\n\u003Ca href=\"https:\u002F\u002Fyoutu.be\u002Fq_96OIBJTBQ?si=0gMDBfdbokAwhXXo\">\n\u003Cimg src=\".\u002F.github\u002Fassets\u002Fvideo_thumbnail.png\" width=\"80%\">\n\u003C\u002Fa>\n\u003C\u002Fdiv>\n\n## Tech stack\n\n- **Backend:** Python 3.13, FastAPI, Pydantic, LiteLLM, Instructor, pathfinding, pandas, openpyxl.\n- **Frontend:** React 19, Vite, TypeScript, React Three Fiber (Three.js), TanStack Router\u002FQuery, Zustand, Tailwind v4, shadcn\u002Fui, Recharts, ExcelJS.\n\n## Requirements\n\n- Python **3.13+** with [uv](https:\u002F\u002Fgithub.com\u002Fastral-sh\u002Fuv)\n- Node **20+** with **pnpm 10.33.0** (pinned in `frontend\u002Fpackage.json`)\n- An LLM provider API key. The default model is `gemini\u002Fgemini-3.1-pro-preview`\n  via LiteLLM, so a `GEMINI_API_KEY` works out of the box. To switch\n  providers, edit `backend\u002Fsrc\u002Fstore_emulator\u002Fapplication\u002Fconfig.py` and\n  supply the matching `*_API_KEY`.\n\n## Quick start\n\n```bash\ncp backend\u002F.env.example backend\u002F.env   # add your LLM API key — DO NOT commit real keys\n.\u002Fscripts\u002Fdev.sh\n```\n\n`scripts\u002Fdev.sh` runs backend (`uvicorn` on `:8000`) and frontend (`vite` on\n`:5173`) together. `Ctrl-C` stops both. Open `http:\u002F\u002Flocalhost:5173` in a\nbrowser.\n\n### Running each side separately\n\n**Backend**\n\n```bash\ncd backend\nuv sync\nuv run uvicorn store_emulator.server.main:app --reload\n```\n\nHealth check: `curl http:\u002F\u002Flocalhost:8000\u002Fapi\u002Fhealth`. The interactive\nOpenAPI docs are at `http:\u002F\u002Flocalhost:8000\u002Fdocs`.\n\n**Frontend**\n\n```bash\ncd frontend\npnpm install\npnpm dev\n```\n\nOverride the API URL with `VITE_API_URL=http:\u002F\u002Fmy-host:port pnpm dev`.\n\n### Build for production\n\n```bash\ncd frontend && pnpm build\n# backend: no build step — run uvicorn behind a process manager\n```\n\n## Usage walkthrough\n\nThe \"golden path\" through the app, end to end:\n\n1. **Create a project.** From the home screen, start a new project and supply\n   a real-world store address plus a one-line customer-profile description\n   (e.g. _\"a small convenience store in a residential neighborhood\"_). The\n   address grounds the LLM's trade-area analysis.\n2. **Generate personas.** On the second page of the create-store wizard,\n   trigger the persona pipeline. The LLM analyzes the trade area, builds a\n   daily traffic profile per weekday, and produces individual personas for\n   each hour of operation. Generation is batched and parallelized; expect\n   this to take a minute or two depending on store size and provider latency.\n3. **Draw the store layout.** Once the project is created, use the isometric\n   grid editor to place shelves, fridges, counters, walls, and entry points.\n   Assign product categories to each rack.\n4. **Run the simulation.** Hit play. Personas walk in on a wall-clock\n   timeline; the 3D view animates their paths in real time. Use the playback\n   controls to scrub, pause, or change speed.\n5. **Inspect results.** Watch the live dashboard for aggregate metrics\n   (visitor count, conversion rate, dwell time, per-rack engagement).\n\n> **Running parastore with the help of an AI assistant** (Claude Code,\n> Cursor, …)? Point it at [`USAGE.md`](.\u002FUSAGE.md). That guide explains\n> which inputs the simulation hinges on, the LLM call count for a given\n> persona size, and the silent-failure modes worth catching before\n> triggering a run.\n\n## Limitations and non-goals\n\nThis is a prototype. To set expectations honestly:\n\n- **No ground-truth calibration.** Outputs are LLM-grounded plausibility, not\n  validated forecasts. Treat the numbers as illustrative, not predictive.\n- **LLM cost and latency are real.** Generating a week of personas for a\n  modest store can be hundreds of LLM calls. Plan your provider budget\n  accordingly. Persona generation is capped at **100 per day** by default\n  (`PERSONA_DAILY_CAP` env var) to keep call counts manageable — the goal\n  of the simulator is to compare layout and product-placement variants,\n  not to reproduce a real store's full footfall, so a smaller sample is\n  usually enough. Raise the cap if you want denser runs and are willing\n  to pay the extra LLM cost.\n- **Single store, single configuration.** No multi-store fleet view, no\n  longitudinal dynamics across weeks, no holiday\u002Fseasonality modelling beyond\n  what the LLM infers from the address.\n- **Product taxonomy is LLM-derived.** There is no real SKU master, pricing\n  feed, or inventory model — categories and prices come from the persona\n  pipeline.\n- **No crowd dynamics.** Pathfinding is per-customer; queueing, congestion,\n  and customer-customer interactions are not modeled.\n- **APIs and data shapes are not stable.** Expect breaking changes between\n  commits.\n\n## License\n\nMIT — see [`LICENSE`](.\u002FLICENSE). Dependencies retain their own licenses; see\n[`LICENSES-BACKEND.md`](.\u002FLICENSES-BACKEND.md) and\n[`LICENSES-FRONTEND.txt`](.\u002FLICENSES-FRONTEND.txt).\n\nIn short: take it, modify it, ship it, sell it — just keep the copyright\nnotice. No warranty.\n\n## Credits\n\n3D assets in `frontend\u002Fpublic\u002Fassets\u002F` are from [Kenney](https:\u002F\u002Fkenney.nl)\nand are licensed CC0 1.0 (public domain). No attribution is required, but\nhuge thanks to Kenney for making these assets freely available — they are\nthe reason this project looks the way it does.\n\n- `assets\u002Fmarket\u002F` — [Mini Market](https:\u002F\u002Fkenney.nl\u002Fassets\u002Fmini-market)\n- `assets\u002Fcharacters\u002F` — [Mini Characters](https:\u002F\u002Fkenney.nl\u002Fassets\u002Fmini-characters)\n- `assets\u002Fghost\u002F` — [Graveyard Kit](https:\u002F\u002Fkenney.nl\u002Fassets\u002Fgraveyard-kit)\n\n## Contributing\n\nParastore was built as a side project alongside our main work at intellicia,\nand we're publishing it as a snapshot rather than as an actively staffed\nopen-source project. Issues and PRs are still welcome — we read them and\nwill engage when we can — but please understand that responses are\nbest-effort and may take a while, and we may decline changes that don't fit\nthe direction we use it for internally. If you have a bigger idea in mind,\nforks are very much encouraged.\n","Parastore 是一个用于构建、模拟和优化零售空间的3D沙盒工具，通过生成由大语言模型驱动的虚拟消费者来模拟购物行为。项目使用TypeScript开发，并结合了FastAPI、React Three Fiber等技术，支持等距视角展示、路径寻找等功能。它特别适合零售业中的店铺布局设计与顾客流动分析、商品摆放策略测试等场景，使用户能够在无风险的环境中尝试不同的零售策略。尽管目前仍处于原型阶段，但已具备一定的实验价值，可以作为相关研究或实际应用的起点。",2,"2026-06-11 04:05:11","CREATED_QUERY"]