A modular, multi-file Python system that simulates a realistic second-floor library environment:

• Irregular bookshelves with per-book (x, y, z) coordinates.
• Multiple stair entrances, study area, computer lab, rest area, reservation desk, and pickup area.
• User behavior with reservation flow, walking paths, timing, and exit rules.
• Policy rule: users without reservation cannot leave with books.
• Staff behavior that periodically relocates reserved books to pickup slots.
• Online-trained model that controls the next staff dispatch interval.
• Holiday calendar, reduced-hour operation days, and exam support mode.
• Real catalog metadata (title/author/category/preferred zone) with zone-specific demand.
• Staff execution delay/drift simulation plus collection rebalancing queue.
• Scale presets (prototype / campus / industrial) with campus as the developer-friendly default.
• Optional Torch dispatch backend (torch-cuda or CPU torch when installed, automatic fallback to the lightweight built-in model).
• Central multi-objective policy controller (traffic, wait time, asset risk, staffing, fines) with online strategy learning.
• Control deployment operations: online learning / online inference, offline training, version snapshots, rollback, and A/B routing.
• Circulation realism: overdue fines, damage wear, lost-book replacement cycle, and repair batches.
• Enterprise UI stack: FastAPI + React + Ant Design Pro + WebSocket, with local static assets and robust real-time updates.

.
|- app.py
|- main.py
|- environment.yml
|- requirements.txt
|- requirements-industrial.txt
|- frontend/
   |- package.json
   |- src/
   |- dist/  (generated by npm build)
|- library_sim/
   |- __init__.py
   |- config.py
   |- entities.py
   |- pathfinding.py
   |- layout.py
   |- reservation.py
   |- trainer.py
   |- simulation.py

conda env create -f environment.yml
conda activate virtual_library_ai

environment.yml installs the backend runtime dependencies, nodejs for the frontend build, and the basic local QA tools (pytest, pyflakes).

conda create -n virtual_library_ai python=3.11 -y
conda activate virtual_library_ai
pip install -r requirements.txt
npm install --prefix frontend

Install these only if you want the optional torch-backed controller/trainer:

pip install -r requirements-industrial.txt

# first-time frontend build (or after frontend changes):
conda activate virtual_library_ai
npm install --prefix frontend
npm run build --prefix frontend

python main.py

Useful overrides:

python main.py --scale prototype
python main.py --scale industrial --cmake-generator Ninja

python main.py --headless --steps 800 --seed 42

python -m pytest
python -m pyflakes app.py library_sim
npm run lint --prefix frontend
npm run test --prefix frontend
npm run build --prefix frontend

• One tick equals 5 simulated minutes (300 simulated seconds).
• Dispatch backend auto-selects the optional torch path when available, otherwise the built-in fallback.
• Active user updates are budgeted per tick so high-traffic mode remains responsive.
• UI refresh uses backend WebSocket snapshots for dashboard state, trends, and tables; only the browser floor map keeps its own floor channel.
• main.py opens the FastAPI-served React dashboard directly when run without arguments.
• Scale profile is configured via VLIB_LIBRARY_SCALE or python main.py --scale ....
• Native CMake generator/arch can be overridden with VLIB_CMAKE_GENERATOR, VLIB_CMAKE_ARCH, or the matching CLI flags in main.py.
• The runtime now includes explicit desk queues, zone resource capacities, exogenous demand shocks, and agenda-based user replanning.
• Simulation can run indefinitely in the UI; use Pause or Stop at any time.