README.md

metadata

title: QueuePilot | Service Capacity Intelligence Studio
emoji: ⏱️
colorFrom: indigo
colorTo: green
sdk: static
app_file: index.html
pinned: false
license: mit
short_description: Service queue and staffing simulator.
tags:
  - operations-research
  - capacity-planning
  - queueing-theory
  - discrete-event-simulation
  - staffing
  - simulation
  - data-visualization

QueuePilot | Service Capacity Intelligence Studio

Hugdrigo portfolio · Project #92

Short description: Service queue and staffing simulator.

QueuePilot is a professional, local-first browser studio for comparing staffing levels, understanding customer waiting times, and exploring queue performance during an eight-hour service shift. It uses a transparent, reproducible discrete-event queue simulation rather than a black-box machine learning prediction. The project runs as a free Hugging Face Static Space with no server, paid API, GPU, or third-party dependency.

Educational prototype: The six included workload profiles are fictional. Results are stochastic estimates made from simplified assumptions, not measured service performance, validated staffing requirements, or guaranteed SLAs. Do not use QueuePilot as the sole basis for employment, finance, or operational staffing decisions.

Features

• Executive dashboard with daily incoming volume, SLA attainment, average wait, labor costs, and an hourly capacity chart.
• Reproducible first-come, first-served multi-agent queue simulation, with one configurable arrival rate for each of eight shift hours.
• Interactive Capacity Lab with staffing performance curves, SLA thresholds, mean wait and p90 wait, and nominal load ratio.
• Four scenario presets: baseline, +45% demand surge, 20% faster handling, and combined demand/handling pressure.
• Custom demand, handling-time, wage, SLA, and pseudorandom seed controls.
• A bounded staffing recommendation, using the lowest tested number of agents that satisfies both the configured SLA target and nominal load ratio at or below 85%.
• Six synthetic workloads plus custom workload creation, editing, activation, and archiving.
• Local storage, validated JSON backup and import, CSV staffing summary export, and a light/dark responsive interface.
• Transparent methodology, including model exclusions and limitations.

How to run

Hugging Face Spaces: Create a new Space, set SDK to Static, and upload README.md, index.html, and LICENSE to its root. The YAML front matter above configures the Space title, license, metadata, and entry point.

Local: Open index.html with a modern browser. All application assets are self-contained, and the app is usable offline. Browser local storage may be unavailable in restrictive file environments; export JSON backups before relying on local changes.

Pages

Page	Purpose
Overview	Monitor one workload, compare representative staffing alternatives, modify shift agents and wait SLA.
Capacity Lab	Compare 1 to 16 staffing levels (up to 30 depending on the current agent count), change demand and handling assumptions, view recommendation and detailed options.
Workloads	Add, edit, archive and select synthetic service queues; export CSV or backup and restore local JSON.
Methodology	Understand simulation assumptions, metrics, limits and privacy behavior.

Simulation mechanics

1. Time horizon: Eight one-hour periods, starting at 09:00 for visualization. The model processes all requests arriving within the 480-minute shift, including any service completed after the shift ends.
2. Arrivals: Each hour has a piecewise-constant expected request rate. Exponentially distributed interarrival times yield a Poisson count per hour. Arrivals follow chronological order and unfinished queues carry forward between hours.
3. Service: Each of c identical agents handles one request at a time, first-come first-served. Service durations are sampled from an exponential distribution with the selected mean. There are no breaks or interruptions.
4. Randomness: A deterministic mulberry32 pseudorandom generator uses a user-editable seed. Each staffing comparison uses the same generated random sequence for more consistent what-if comparisons. 24 replication runs are performed per staffing option.
5. Wait SLA: Each arriving request is counted as meeting SLA if time from arrival to beginning service is at or below the workload's SLA threshold. The displayed SLA rate, average wait, and 90th-percentile wait are arithmetic means of the corresponding per-run statistics.
6. Labor cost: agents × 8 hours × hourly wage. Excludes overhead, breaks, benefits, overtime pay, and all other operational costs.
7. Nominal load ratio: expected arrivals × mean handling minutes / (agents × 480) × 100. It can exceed 100%; it is not a measured or capped utilization percentage.
8. Recommendation: The first tested staffing level meeting both simulated SLA rate ≥ target SLA rate and nominal load ratio ≤ 85%. If none qualifies, the app reports no qualifying level within its search range. The recommendation is illustrative and sensitive to the random seed and simplified assumptions.

Limitations and safeguards

• No customer abandonment, priorities, call transfers, multiple skills, scheduled agent breaks, downtime, appointments, or staffed-shift spillovers across days.
• No empirical model calibration or actual performance data is shipped. The model is suitable for learning and initial scenario exploration, not validated production forecasting.
• Workloads accept from 1 to 30 agents, an average handling time from 0.5 to 180 minutes, an SLA from 1 to 180 minutes, and eight expected hourly rates between 0 and 150; at least one hourly value must be positive.
• Incoming JSON backups are limited to 300 KB and validated for expected fields, bounded numeric values, unique IDs, and the supported backup version.
• User-provided values are escaped before being added to HTML, and CSV text fields are protected against common spreadsheet-formula injection patterns. Like any local browser project, use only trusted devices for sensitive information.
• All calculations run on-device. No uploads, analytics, tracking pixels, account signup, or network APIs are used.

Project structure

QueuePilot_Project_92/
├── README.md       # Space metadata and complete documentation
├── index.html      # Fully self-contained application, CSS and JavaScript
└── LICENSE         # MIT license

Testing

The application was checked locally with Chromium browser automation using document-based rendering because the browser environment blocked direct local web server navigation. Tested workflows include scenario switching, editing staff/SLA and global assumptions, adding/editing/archiving workloads, CSV and JSON downloads, validating/restoring backups, HTML injection attempts, layout checks at six viewport widths, and checking for browser JavaScript exceptions. Numeric/invariant tests also cover probability constraints, nominal load calculations, repeatability, and the monotonic staffing property under identical random streams.

Publishing remains a separate step: local browser tests do not prove that a deployed Hugging Face Space is running correctly; check the public Space after upload.

License

MIT. See LICENSE.

Created for the Hugdrigo open-source portfolio.