README.md

metadata

title: ShiftForge | Workforce Scheduling Intelligence
emoji: 📅
colorFrom: green
colorTo: blue
sdk: static
app_file: index.html
pinned: false
license: mit
short_description: Offline workforce scheduling and coverage analysis
tags:
  - operations-research
  - workforce-scheduling
  - optimization
  - business-intelligence
  - decision-support
  - javascript

ShiftForge | Workforce Scheduling Intelligence

ShiftForge is an offline-first operations research laboratory for scheduling workers to seven days of morning, evening and night shifts. It solves a constrained minimum-cost flow assignment problem and compares the exact modeled optimum against a deterministic greedy baseline.

What the application does

• Command Center: staffing coverage, shortage counts, labor costs, and model objective compared with a greedy allocator.
• Roster Planner: complete worker-to-shift assignments, qualifications, and per-assignment modeled costs.
• Coverage Heatmap: 7-day × 3-shift coverage matrix and shortage register.
• Workload Balance: hours and shifts by worker and a squared workload concentration penalty.
• Scenario Laboratory: change the shortage penalty, workload balance, night premium, and shift preference penalty, with live recomputation.
• Data & Methodology: import your own data from two validated CSV formats and download audit JSON, roster/gaps/data CSV, and a Markdown methodology report.

No installation required

This is a free Static Hugging Face Space. The only files required in the Space root are:

README.md
index.html
LICENSE

No Python backend, CDN, package manager, external API, login, server-side computation, or paid plan is required. All calculations and uploaded CSV parsing happen inside the visitor's browser. Refreshing the page resets in-memory edits, so export data before leaving.

Demonstration datasets

1. Retail operations.
2. Hospitality front desk.
3. Customer support.

All demonstration data, wages, worker profiles, preferences and demand values are synthetic. No real employee records are included.

Model details

Each demand slot is a specific weekday and one of three shift periods. Demand is a non-negative integer between 0 and 8. Each available worker has a skill level, hourly wage, preferred shift, and maximum number of weekly shifts. The solver enforces all of the following hard constraints:

1. Each assigned worker meets the minimum skill level required by a slot.
2. The worker explicitly marks that slot as available.
3. A worker receives at most one shift per day.
4. Each worker stays within their weekly maximum number of shifts.
5. No slot is assigned more workers than requested.

The objective is the sum of:

• Wage expense per eight-hour shift, with the configurable night shift premium.
• A soft penalty for a shift outside an employee's indicated preference.
• A quadratic per-worker workload concentration penalty, balance × (number of assigned shifts)^2.
• A penalty for every unfilled required shift.

The exact min-cost flow construction represents the quadratic workload term with successive marginal edges. It includes the possibility of leaving shifts unfilled at a penalty, making the objective feasible even when demand exceeds eligible supply. The algorithm is exact for this model and these constraints, not for the broader real-world workforce scheduling problem. Money values are illustrative model amounts, denominated in USD.

The standalone greedy comparison uses a locally cheapest eligible worker at each slot and may produce a higher objective because it lacks global look-ahead. The objective is not the payroll figure. The payroll metric excludes the preference and coverage penalties.

Import your data

Workers CSV, with columns in any order (all required):

id,name,skill,wage,cap,pref,available

Example:

id,name,skill,wage,cap,pref,available
W01,Alex,2,20,5,0,0:0|0:1|1:0|2:0
W02,Jordan,3,25,4,2,0:2|1:2|2:2

• skill: integer 1–3; wage: non-negative hourly cost (max 250).
• cap: maximum shifts in a week, integer 0–7.
• pref: 0 = Morning, 1 = Evening, 2 = Night.
• available: pipe-separated weekday/shift keys where weekday 0 = Monday, 6 = Sunday, and shift 0 = Morning, 2 = Night. Do not include extra delimiters.
• Worker IDs must be unique, and contain only letters, numbers, underscores or hyphens.
• Workers accepted: 1–35.

Demand CSV, exactly 21 unique rows:

day,shift,required,skill

• day: integer 0–6.
• shift: integer 0–2.
• required: workers requested for that slot, integer 0–8.
• skill: minimum level, integer 1–3.

A malformed CSV, invalid skill, duplicate ID, invalid availability, or incomplete demand grid is rejected before replacing current in-memory data. Download the bundled examples via the workers template and demand template actions.

Statistical and ethical limitations

This prototype does not model mandatory inter-day rest, collective bargaining rules, overtime premiums, break periods, labor law, vacations, worker consent, different shift lengths, commuting, or discrimination and protected-category fairness. A manager must verify labor regulations, contracts, actual skills and employee needs before any operational use. Higher balance penalties only discourage uneven shift counts; they are not demographic fairness or equitable employment guarantees.

The application does not integrate live schedules, attendance systems, or HR databases. No employee data is transmitted. For sensitive records, use only in an appropriately secured local environment, consider anonymization, and do not upload private personal information to a public Space repository. Data imported by a visitor remains in their own browser until that page is closed or refreshed.

Reproducibility and testing

Tested locally in Chromium on desktop and mobile. Additional independent small-case exhaustive search tests compare the objective against the actual optimum. See the separate technical source and tests package for reproducibility scripts and local test results. Browser checks do not replace a post-publication review of the Hugging Face app.

License

MIT (see LICENSE). © 2026 Hugdrigo.