Blame for README.md

---
title: TalentFlow
emoji: ✨
colorFrom: purple
colorTo: indigo
sdk: static
app_file: index.html
pinned: false
license: mit
short_description: Workforce planning and staffing simulation.
---

# TalentFlow

### Workforce Intelligence Studio

**A professional, fully client-side workforce planning laboratory for examining capacity, staffing, skill readiness, employee turnover, and operating cost under synthetic scenarios.**

TalentFlow is an original static Hugging Face Spaces application. It gives users an inspectable, editable demonstration environment for understanding staffing tradeoffs, with transparent calculations and no external services.

**Short description:** Workforce planning and staffing simulation.

> **Demonstration only.** The eight example teams, workloads, labor costs, readiness scores, and attrition rates are fictional. They are not verified workforce data or validated forecasts. The application does **not** contain a trained machine learning model.

## Features

| Workspace | Included capabilities |
| --- | --- |
| **Command center** | Executive metrics, monthly capacity versus demand, staffing-shortfall signals, and an at-a-glance comparison of scenario coverage. |
| **Workforce forecast** | 12-month projections for headcount equivalents, team-level and aggregate capacity, demand, labor cost, and unserved hours, with a CSV export. |
| **Scenario studio** | Four editable presets: steady state, growth acceleration, retention pressure, and productivity boost. Sliders control demand, annual attrition, quarterly hires, and productivity. Includes a deterministic 300-run sensitivity band and comparison CSV export. |
| **Team registry** | Create, edit, archive, restore, and search workforce teams. Customize workload, monthly growth, FTE, annual attrition, quarterly hires, per-FTE cost, and skill readiness. Export as CSV. |
| **Methodology** | In-app explanations of simulation equations, limitations, data handling, and portability. |

Additional features: light/dark mode, responsive desktop and mobile design, browser-local persistence, versioned JSON backup and import, and form validation.

## Deploy on Hugging Face Spaces

1. Open [Create a new Space](https://huggingface.co/new-space).
2. Select owner `Hugdrigo`.
3. Name the Space `talentflow-workforce-intelligence`.
4. Choose **Static** SDK, **Public** visibility, and **MIT** license.
5. Extract the ZIP and upload **all three files** (`README.md`, `index.html`, `LICENSE`) directly to the Space repository root. **Do not upload the ZIP itself.**
6. Open the Space to check that it loads and test its settings and exports in the public deployment.

This `README.md` provides the Hugging Face Spaces configuration front matter. No build step, `requirements.txt`, package installation, API token, backend, GPU, or paid service is required.

## Local operation

Open `index.html` in a current browser. For normal browser-local persistence, a standard HTTPS or localhost origin is preferable. Storage access can vary for local `file://` pages. All calculations run in JavaScript without network requests.

## Model definition

Each team has eight numeric attributes: current FTE, monthly workload hours, monthly demand growth %, annual attrition %, quarterly hires, cost per FTE per month in USD, and skill readiness %. Archived teams are excluded from simulations while remaining editable and restorable.

### 1. Effective capacity

The model assumes 140 productive base hours per FTE per month and a simplified readiness adjustment:

```text
readiness_factor = 0.65 + 0.35 * readiness_percent / 100
monthly_capacity_hours = expected_FTE * 140 * readiness_factor
                       * (1 + productivity_uplift_percent / 100)
```

Skill readiness is an illustrative planning coefficient, **not** a directly measured employee performance multiplier.

### 2. Expected workforce evolution

The first month begins with the team's input FTE. For months 2 to 12:

```text
annual_attrition_effective = clamp(team_attrition + scenario_attrition, 0%, 85%)
next_month_FTE = previous_month_FTE * (1 - annual_attrition_effective / 12)

For months 3, 6, 9, 12 only:
    next_month_FTE += max(0, team_hires_per_quarter + scenario_hiring_adjustment)
```

FTE is a continuously valued expected headcount, so it can be fractional. This does not mean fractional employees are literally hired or dismissed. Quarterly hires are modeled as instantly productive when added.

### 3. Demand and coverage

```text
month_m_demand = team_starting_demand * (1 + monthly_growth_rate)^(m - 1)
               * (1 + scenario_demand_adjustment)

served_hours = min(month_m_demand, monthly_capacity_hours)
unserved_hours_by_team = max(0, month_m_demand - monthly_capacity_hours)

month_coverage = sum(served_hours across teams) / sum(demand across teams)
annual_coverage = sum(served_hours across all months and teams)
                / sum(demand across all months and teams)
```

If total demand is zero, coverage defaults to 100% by convention. Excess capacity in one team **does not** offset shortfall in a different team. Therefore, the sum of team-level unserved hours may exceed an aggregate `max(total demand − total capacity, 0)` calculation.

### 4. Labor spend and indicative staffing gap

```text
monthly_labor_spend = sum(expected_FTE * assumed_monthly_cost_per_FTE)

first_month_FTE_gap_by_team = max(0, demand - capacity)
                             / (140 * readiness_factor * productivity_factor)
```

Cost totals are illustrative, exclude recruiting and overhead expenses, and assume constant per-FTE wages. Gap estimates presume immediate availability and constant productivity; they are *not* operational hiring recommendations.

### 5. Four scenario presets

| Preset | Demand adjustment | Attrition adjustment | Quarterly hires adjustment | Productivity uplift |
| --- | ---: | ---: | ---: | ---: |
| Steady state | 0% | 0 pp | 0 | 0% |
| Growth acceleration | +30% | +2 pp | +1 per team | 0% |
| Retention pressure | +8% | +16 pp | 0 | 0% |
| Productivity boost | +12% | -2 pp | 0 | +22% |

Scenario adjustments are assumption changes, not probability-based forecasts. Slider overrides can be reset to the chosen preset.

### 6. Sensitivity illustration

The scenario studio performs **300 deterministic seeded calculations** using the selected parameter values plus hypothetical, bounded perturbations in demand and attrition. The displayed P10, median and P90 of annual modeled coverage are **not calibrated prediction intervals**. Repeating the same dataset and parameters produces identical values.

## Validation

The packaged application was tested locally using headless Chromium and independent Python calculations:

- **14,221 numerical assertions**, including 220 randomized model comparisons of 12 months and five aggregate quantities against an independent Python implementation, annual coverage comparisons, parameter monotonicity, and deterministic sensitivity reproducibility.
- **47 functional checks**, covering navigation, model calculations, team creation/editing/archiving/restoration, scenarios, slider overrides, CSV and JSON downloads, JSON backup validation and restoration, HTML escaping, CSV formula escaping, browser-local state writes, reset, theme toggling, and six viewport widths.
- **35 additional responsive checks**, covering five views at seven viewport widths ranging from 320 to 1512 pixels, with no document-level horizontal overflow detected.
- No uncaught JavaScript errors detected in the tested workflows; JavaScript syntax check passed.

**Scope:** These are local software checks, not an external security assessment, a statistical validation of assumptions, a benchmark against human-resource outcomes, or a successful public Spaces deployment.

## Data, safety, and limitations

- All app computations run in the browser. No external fonts, packages, data APIs, telemetry, or tracking are used.
- Per-browser persistence uses `localStorage`, where supported; clearing browser data may erase unsaved edits.
- Version 1 JSON import is limited to 300 KB and 1–40 teams. Values have type and range checks, teams must have unique IDs, and imports require user confirmation before replacement.
- Names and categories are escaped during HTML display. CSV output quotes cells and prefixes formulas or suspicious spreadsheet formula triggers with an apostrophe. This is a limited defensive measure, not a complete security audit.
- The application does not access live workforce systems, salaries, HR records, skills assessments, staffing vendors, payroll APIs, or employee-specific personal data.
- It does not model labor-law constraints, hiring pipelines, recruiting lead times, employee absence, part-time scheduling, holidays, time-zone constraints, service-level routing, staff ramp-up, or performance outcomes.
- For real organizational use, validate model assumptions, anonymize or aggregate data, and review decisions with qualified professionals.

## Files

```text
README.md    Documentation and Hugging Face Space metadata
index.html   Complete offline application, interface and simulation engine
LICENSE      MIT License
```

**License:** MIT. See `LICENSE`.

**Portfolio:** [Hugdrigo](https://huggingface.co/Hugdrigo)  
**Project:** 95 · TalentFlow