pyworkforce 0.5.1__tar.gz → 0.5.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/LICENSE +21 -21
  2. pyworkforce-0.5.3/PKG-INFO +319 -0
  3. pyworkforce-0.5.3/README.md +285 -0
  4. pyworkforce-0.5.3/pyproject.toml +102 -0
  5. pyworkforce-0.5.3/pyworkforce/__init__.py +21 -0
  6. pyworkforce-0.5.3/pyworkforce/_version.py +1 -0
  7. pyworkforce-0.5.3/pyworkforce/base.py +47 -0
  8. pyworkforce-0.5.3/pyworkforce/breaks/__init__.py +3 -0
  9. pyworkforce-0.5.3/pyworkforce/breaks/break_scheduler.py +362 -0
  10. pyworkforce-0.5.3/pyworkforce/breaks/tests/test_break_scheduler.py +286 -0
  11. pyworkforce-0.5.3/pyworkforce/queuing/__init__.py +5 -0
  12. pyworkforce-0.5.3/pyworkforce/queuing/abandonment.py +497 -0
  13. pyworkforce-0.5.3/pyworkforce/queuing/erlang.py +351 -0
  14. pyworkforce-0.5.3/pyworkforce/queuing/erlang_b.py +279 -0
  15. pyworkforce-0.5.3/pyworkforce/queuing/tests/test_abandonment.py +129 -0
  16. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce/queuing/tests/test_erlang.py +129 -92
  17. pyworkforce-0.5.3/pyworkforce/queuing/tests/test_erlang_b.py +211 -0
  18. pyworkforce-0.5.3/pyworkforce/queuing/tests/test_multi_abandonment.py +82 -0
  19. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce/queuing/tests/test_multi_erlang.py +144 -95
  20. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce/rostering/__init__.py +3 -3
  21. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce/rostering/binary_programming.py +272 -236
  22. pyworkforce-0.5.3/pyworkforce/rostering/tests/rostering_data.json +159 -0
  23. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce/rostering/tests/test_rostering.py +38 -37
  24. pyworkforce-0.5.3/pyworkforce/rostering/tests/test_validation.py +70 -0
  25. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce/scheduling/__init__.py +3 -3
  26. pyworkforce-0.5.3/pyworkforce/scheduling/base.py +97 -0
  27. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce/scheduling/shifts_selection.py +254 -251
  28. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce/scheduling/tests/test_shifts.py +181 -180
  29. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce/scheduling/tests/test_utils.py +31 -30
  30. pyworkforce-0.5.3/pyworkforce/scheduling/tests/test_validation.py +70 -0
  31. pyworkforce-0.5.3/pyworkforce/scheduling/utils.py +9 -0
  32. pyworkforce-0.5.3/pyworkforce/shifts/__init__.py +15 -0
  33. pyworkforce-0.5.3/pyworkforce/shifts/coverage.py +266 -0
  34. pyworkforce-0.5.3/pyworkforce/shifts/tests/__init__.py +0 -0
  35. pyworkforce-0.5.3/pyworkforce/shifts/tests/test_coverage.py +166 -0
  36. pyworkforce-0.5.3/pyworkforce/staffing/__init__.py +3 -0
  37. pyworkforce-0.5.3/pyworkforce/staffing/multi_skill.py +251 -0
  38. pyworkforce-0.5.3/pyworkforce/staffing/tests/__init__.py +0 -0
  39. pyworkforce-0.5.3/pyworkforce/staffing/tests/test_multi_skill.py +293 -0
  40. pyworkforce-0.5.3/pyworkforce/tests/__init__.py +0 -0
  41. pyworkforce-0.5.3/pyworkforce/tests/test_base.py +54 -0
  42. pyworkforce-0.5.3/pyworkforce/utils/__init__.py +15 -0
  43. pyworkforce-0.5.3/pyworkforce/utils/frames.py +66 -0
  44. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce/utils/grid.py +114 -113
  45. pyworkforce-0.5.3/pyworkforce/utils/tests/__init__.py +0 -0
  46. pyworkforce-0.5.3/pyworkforce/utils/tests/test_frames.py +46 -0
  47. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce/utils/tests/test_parameter_grid.py +84 -75
  48. pyworkforce-0.5.3/pyworkforce/utils/tests/test_validation.py +53 -0
  49. pyworkforce-0.5.3/pyworkforce/utils/validation.py +108 -0
  50. pyworkforce-0.5.3/pyworkforce.egg-info/PKG-INFO +319 -0
  51. pyworkforce-0.5.3/pyworkforce.egg-info/SOURCES.txt +57 -0
  52. pyworkforce-0.5.3/pyworkforce.egg-info/requires.txt +10 -0
  53. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/setup.cfg +4 -4
  54. pyworkforce-0.5.1/PKG-INFO +0 -207
  55. pyworkforce-0.5.1/README.md +0 -186
  56. pyworkforce-0.5.1/pyworkforce/__init__.py +0 -13
  57. pyworkforce-0.5.1/pyworkforce/_version.py +0 -1
  58. pyworkforce-0.5.1/pyworkforce/queuing/__init__.py +0 -3
  59. pyworkforce-0.5.1/pyworkforce/queuing/erlang.py +0 -354
  60. pyworkforce-0.5.1/pyworkforce/scheduling/base.py +0 -62
  61. pyworkforce-0.5.1/pyworkforce/scheduling/utils.py +0 -14
  62. pyworkforce-0.5.1/pyworkforce/utils/__init__.py +0 -3
  63. pyworkforce-0.5.1/pyworkforce.egg-info/PKG-INFO +0 -207
  64. pyworkforce-0.5.1/pyworkforce.egg-info/SOURCES.txt +0 -30
  65. pyworkforce-0.5.1/pyworkforce.egg-info/requires.txt +0 -4
  66. pyworkforce-0.5.1/setup.py +0 -49
  67. {pyworkforce-0.5.1/pyworkforce/queuing → pyworkforce-0.5.3/pyworkforce/breaks}/tests/__init__.py +0 -0
  68. {pyworkforce-0.5.1/pyworkforce/rostering → pyworkforce-0.5.3/pyworkforce/queuing}/tests/__init__.py +0 -0
  69. {pyworkforce-0.5.1/pyworkforce/scheduling → pyworkforce-0.5.3/pyworkforce/rostering}/tests/__init__.py +0 -0
  70. {pyworkforce-0.5.1/pyworkforce/utils → pyworkforce-0.5.3/pyworkforce/scheduling}/tests/__init__.py +0 -0
  71. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce.egg-info/dependency_links.txt +0 -0
  72. {pyworkforce-0.5.1 → pyworkforce-0.5.3}/pyworkforce.egg-info/top_level.txt +0 -0
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2021 Rodrigo Arenas
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2021 Rodrigo Arenas
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,319 @@
1
+ Metadata-Version: 2.4
2
+ Name: pyworkforce
3
+ Version: 0.5.3
4
+ Summary: Common tools for workforce management, queuing, scheduling, rostering and optimization problems
5
+ Author-email: Rodrigo Arenas <rodrigo.arenas456@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Documentation, https://rodrigo-arenas.github.io/pyworkforce/
8
+ Project-URL: Source Code, https://github.com/rodrigo-arenas/pyworkforce
9
+ Project-URL: Bug Tracker, https://github.com/rodrigo-arenas/pyworkforce/issues
10
+ Project-URL: Changelog, https://rodrigo-arenas.github.io/pyworkforce/release-notes
11
+ Keywords: workforce management,call center,erlang,scheduling,rostering,operations research,optimization
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Topic :: Scientific/Engineering
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Requires-Python: <3.15,>=3.12
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: numpy>=1.23
25
+ Requires-Dist: pandas>=2.2.0
26
+ Requires-Dist: ortools>=9.6
27
+ Requires-Dist: joblib>=1.4.2
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest>=9.1.1; extra == "dev"
30
+ Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
31
+ Requires-Dist: ruff>=0.15.20; extra == "dev"
32
+ Requires-Dist: twine>=6.2.0; extra == "dev"
33
+ Dynamic: license-file
34
+
35
+
36
+ [![Tests](https://github.com/rodrigo-arenas/pyworkforce/actions/workflows/ci-tests.yml/badge.svg?branch=main)](https://github.com/rodrigo-arenas/pyworkforce/actions/workflows/ci-tests.yml)
37
+ [![Codecov](https://codecov.io/gh/rodrigo-arenas/pyworkforce/branch/main/graphs/badge.svg?branch=main&service=github)](https://codecov.io/github/rodrigo-arenas/pyworkforce?branch=main)
38
+ [![PyPI Version](https://badge.fury.io/py/pyworkforce.svg)](https://badge.fury.io/py/pyworkforce)
39
+ [![Python Version](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/downloads/)
40
+
41
+
42
+ # pyworkforce
43
+ Tools for workforce management problems such as queue staffing, shift scheduling,
44
+ rostering, and operations research optimization. It is geared toward call /
45
+ contact centers, but the same techniques apply to hospitals, retail, logistics,
46
+ network capacity planning and any operation that has to match a variable demand
47
+ with a finite number of resources.
48
+
49
+ 📖 **Full documentation and tutorials:**
50
+ [rodrigo-arenas.github.io/pyworkforce](https://rodrigo-arenas.github.io/pyworkforce/)
51
+
52
+ ## Installation
53
+
54
+ pyworkforce supports Python 3.12, 3.13, and 3.14.
55
+
56
+ **pip**
57
+
58
+ ```bash
59
+ pip install pyworkforce
60
+ ```
61
+
62
+ **conda** (via [conda-forge](https://conda-forge.org/))
63
+
64
+ ```bash
65
+ conda install -c conda-forge pyworkforce
66
+ ```
67
+
68
+
69
+ For runnable examples, see the
70
+ [examples folder](https://github.com/rodrigo-arenas/pyworkforce/tree/main/examples).
71
+
72
+ ## Features
73
+
74
+ pyworkforce is organized around three planning steps — *how many resources do I
75
+ need?* → *how many per shift?* → *who works when?* — plus helpers that tie them
76
+ together:
77
+
78
+ - **Queuing**
79
+ - `ErlangC` — the classic M/M/c queue (infinite patience).
80
+ - `ErlangA` — the M/M/c+M queue with customer **abandonment** (patience),
81
+ computed exactly from the birth–death stationary distribution.
82
+ - `ErlangB` — the M/M/c/c **loss queue** (no waiting room): blocked calls are
83
+ shed. Use this for trunk / SIP channel sizing.
84
+ - `MultiErlangC` / `MultiErlangA` / `MultiErlangB` — evaluate many scenarios
85
+ from a parameter grid in parallel, scikit-learn style.
86
+ - **Shift coverage helpers** (`pyworkforce.shifts`) — build the `shifts_coverage`
87
+ arrays the schedulers expect from clock hours, spans or explicit periods,
88
+ instead of hand-writing 0/1 arrays.
89
+ - **Scheduling** (`pyworkforce.scheduling`) — `MinAbsDifference` and
90
+ `MinRequiredResources` decide how many people to place on each shift, built on
91
+ [OR-Tools](https://developers.google.com/optimization).
92
+ - **Rostering** (`pyworkforce.rostering`) — `MinHoursRoster` assigns named people
93
+ to days and shifts while respecting banned shifts, rest days, minimum hours,
94
+ non-sequential shifts and preferences.
95
+ - **Break scheduling** (`pyworkforce.breaks`) — `BreakScheduler` assigns break
96
+ start times to agent slots within each shift, preventing overlapping breaks
97
+ and guaranteeing that breaks never drop coverage below the required minimum.
98
+ - **A scikit-learn-friendly API** — consistent constructors with clear validation
99
+ messages, `get_params()` and readable `repr()` on every estimator, the last
100
+ result stored as `solution_`, and `results_to_dataframe` to turn grid results
101
+ into tidy `pandas` DataFrames.
102
+
103
+ A brief introduction to the queuing and scheduling ideas can be found in these
104
+ posts:
105
+ [workforce planning](https://towardsdatascience.com/workforce-planning-optimization-using-python-69af0ef9011a)
106
+ and [scheduling](https://towardsdatascience.com/how-to-solve-scheduling-problems-in-python-36a9af8de451).
107
+
108
+ ## Queuing
109
+
110
+ Estimate how many resources are required to handle incoming work, for example
111
+ calls arriving at a call center.
112
+
113
+ ![queue_system](https://raw.githubusercontent.com/rodrigo-arenas/pyworkforce/main/docs/images/erlangc_queue_system.png)
114
+
115
+ ### Erlang C
116
+
117
+ ```python
118
+ from pyworkforce.queuing import ErlangC
119
+
120
+ erlang = ErlangC(transactions=100, asa=20/60, aht=3, interval=30, shrinkage=0.3)
121
+
122
+ positions_requirements = erlang.required_positions(service_level=0.8, max_occupancy=0.85)
123
+ print("positions_requirements: ", positions_requirements)
124
+ ```
125
+ Output:
126
+ ```
127
+ >> positions_requirements: {'raw_positions': 14,
128
+ 'positions': 20,
129
+ 'service_level': 0.8883500191794669,
130
+ 'occupancy': 0.7142857142857143,
131
+ 'waiting_probability': 0.1741319335950498}
132
+ ```
133
+
134
+ ### Erlang A (modeling abandonment)
135
+
136
+ Real customers hang up if they wait too long. `ErlangA` adds a `patience`
137
+ parameter and reports the abandonment probability, typically requiring fewer
138
+ agents than Erlang C:
139
+
140
+ ```python
141
+ from pyworkforce.queuing import ErlangA
142
+
143
+ erlang = ErlangA(transactions=100, asa=20/60, aht=3, interval=30, patience=5, shrinkage=0.3)
144
+
145
+ requirements = erlang.required_positions(service_level=0.8, max_occupancy=0.85, max_abandonment=0.05)
146
+ print("requirements: ", requirements)
147
+ ```
148
+ Output:
149
+ ```
150
+ >> requirements: {'raw_positions': 13,
151
+ 'positions': 19,
152
+ 'service_level': 0.858...,
153
+ 'occupancy': 0.750...,
154
+ 'abandonment_probability': 0.025...,
155
+ 'waiting_probability': 0.226...,
156
+ 'average_speed_of_answer': 0.125...}
157
+ ```
158
+
159
+ ### Many scenarios at once
160
+
161
+ `MultiErlangC` / `MultiErlangA` evaluate a parameter grid in parallel, and
162
+ `results_to_dataframe` turns the results into a tidy table:
163
+
164
+ ```python
165
+ from pyworkforce.queuing import MultiErlangC
166
+ from pyworkforce.utils import results_to_dataframe
167
+
168
+ param_grid = {"transactions": [100], "aht": [3], "interval": [30], "asa": [20 / 60], "shrinkage": [0.3]}
169
+ multi_erlang = MultiErlangC(param_grid=param_grid, n_jobs=-1)
170
+
171
+ scenarios = {"service_level": [0.8, 0.85, 0.9], "max_occupancy": [0.8]}
172
+ results = multi_erlang.required_positions(scenarios)
173
+
174
+ df = results_to_dataframe(results, multi_erlang.required_positions_params)
175
+ print(df[["service_level", "positions", "service_level_result", "occupancy"]].round(4).to_string(index=False))
176
+ ```
177
+ Output:
178
+ ```
179
+ service_level positions service_level_result occupancy
180
+ 0.80 20 0.8884 0.7143
181
+ 0.85 20 0.8884 0.7143
182
+ 0.90 22 0.9415 0.6667
183
+ ```
184
+
185
+ The input target stays under `service_level`; the achieved value is kept as
186
+ `service_level_result`.
187
+
188
+ ## Shift coverage helpers
189
+
190
+ Describe shifts by their clock hours instead of writing 0/1 arrays. Overnight
191
+ shifts wrap past midnight:
192
+
193
+ ```python
194
+ from pyworkforce.shifts import shift_coverage_from_hours
195
+
196
+ shifts_coverage = shift_coverage_from_hours({
197
+ "Morning": (6, 14),
198
+ "Afternoon": (14, 22),
199
+ "Night": (22, 6),
200
+ }, num_periods=24)
201
+ ```
202
+
203
+ The output plugs straight into the schedulers below. See also
204
+ `shift_coverage_from_spans`, `shift_coverage_from_periods`,
205
+ `validate_shift_coverage` and `coverage_to_dataframe`.
206
+
207
+ ## Scheduling
208
+
209
+ Given the required resources per period, decide how many people to place on each
210
+ predefined shift.
211
+
212
+ ```python
213
+ from pyworkforce.scheduling import MinAbsDifference, MinRequiredResources
214
+
215
+ # Rows are days. Each value is the number of required positions for one hour of the day.
216
+ required_resources = [
217
+ [9, 11, 17, 9, 7, 12, 5, 11, 8, 9, 18, 17, 8, 12, 16, 8, 7, 12, 11, 10, 13, 19, 16, 7],
218
+ [13, 13, 12, 15, 18, 20, 13, 16, 17, 8, 13, 11, 6, 19, 11, 20, 19, 17, 10, 13, 14, 23, 16, 8]
219
+ ]
220
+
221
+ # Each shift has 24 entries, one per hour. Use 1 if the shift covers that hour, otherwise 0.
222
+ shifts_coverage = {"Morning": [0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
223
+ "Afternoon": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0],
224
+ "Night": [1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1],
225
+ "Mixed": [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0]}
226
+
227
+ # Minimize the absolute difference between required and scheduled resources
228
+ difference_scheduler = MinAbsDifference(num_days=2,
229
+ periods=24,
230
+ shifts_coverage=shifts_coverage,
231
+ required_resources=required_resources,
232
+ max_period_concurrency=27,
233
+ max_shift_concurrency=25)
234
+ difference_solution = difference_scheduler.solve()
235
+
236
+ # Minimize the (optionally weighted) number of scheduled resources while covering every period
237
+ requirements_scheduler = MinRequiredResources(num_days=2,
238
+ periods=24,
239
+ shifts_coverage=shifts_coverage,
240
+ required_resources=required_resources,
241
+ max_period_concurrency=27,
242
+ max_shift_concurrency=25)
243
+ requirements_solution = requirements_scheduler.solve()
244
+
245
+ print("difference_solution :", difference_solution["status"], difference_solution["cost"])
246
+ print("requirements_solution :", requirements_solution["status"], requirements_solution["cost"])
247
+ ```
248
+ Output:
249
+ ```
250
+ >> difference_solution: {'status': 'OPTIMAL',
251
+ 'cost': 157.0,
252
+ 'resources_shifts': [{'day': 0, 'shift': 'Morning', 'resources': 8},
253
+ {'day': 0, 'shift': 'Afternoon', 'resources': 11},
254
+ {'day': 0, 'shift': 'Night', 'resources': 9},
255
+ {'day': 0, 'shift': 'Mixed', 'resources': 1},
256
+ ... ]}
257
+
258
+ >> requirements_solution: {'status': 'OPTIMAL',
259
+ 'cost': 113.0,
260
+ 'resources_shifts': [{'day': 0, 'shift': 'Morning', 'resources': 15},
261
+ {'day': 0, 'shift': 'Afternoon', 'resources': 13},
262
+ ... ]}
263
+ ```
264
+
265
+ `MinRequiredResources` also accepts a `cost_dict` to weight shifts differently
266
+ (for example, more expensive night shifts).
267
+
268
+ ## Rostering
269
+
270
+ Assign **named** people to days and shifts while respecting individual rules and
271
+ preferences.
272
+
273
+ ```python
274
+ from pyworkforce.rostering import MinHoursRoster
275
+
276
+ roster = MinHoursRoster(
277
+ num_days=2,
278
+ resources=["ana@co", "ben@co", "cara@co", "dan@co", "eve@co"],
279
+ shifts=["Morning", "Night"],
280
+ shifts_hours=[8, 8],
281
+ min_working_hours=8,
282
+ max_resting=1,
283
+ required_resources={"Morning": [2, 2], "Night": [1, 1]},
284
+ banned_shifts=[{"resource": "ana@co", "shift": "Night", "day": 0}],
285
+ resources_preferences=[{"resource": "ana@co", "shift": "Morning"}],
286
+ )
287
+
288
+ solution = roster.solve()
289
+ print(solution["status"], solution["resource_shifts"][:2])
290
+ ```
291
+ Output:
292
+ ```
293
+ OPTIMAL [{'resource': 'ana@co', 'day': 0, 'shift': 'Morning'},
294
+ {'resource': 'ana@co', 'day': 1, 'shift': 'Morning'}]
295
+ ```
296
+
297
+ `ana@co` is given her preferred `Morning` shift and never `Night` on day 0,
298
+ exactly as configured.
299
+
300
+ ## Documentation and tutorials
301
+
302
+ The [documentation site](https://rodrigo-arenas.github.io/pyworkforce/) includes
303
+ narrative guides, a full API reference, and self-contained, notebook-style
304
+ tutorials with real outputs:
305
+
306
+ - [End-to-end planning](https://rodrigo-arenas.github.io/pyworkforce/guide/end-to-end)
307
+ — demand → required positions → shift coverage → schedule → roster.
308
+ - [Comparing scenarios](https://rodrigo-arenas.github.io/pyworkforce/guide/scenarios)
309
+ — grids and DataFrames.
310
+
311
+ ## Contributing
312
+
313
+ Contributions are very welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the
314
+ local development setup, how to run the tests and linter, and the pull-request
315
+ workflow.
316
+
317
+ ## License
318
+
319
+ pyworkforce is released under the [MIT License](LICENSE).
@@ -0,0 +1,285 @@
1
+
2
+ [![Tests](https://github.com/rodrigo-arenas/pyworkforce/actions/workflows/ci-tests.yml/badge.svg?branch=main)](https://github.com/rodrigo-arenas/pyworkforce/actions/workflows/ci-tests.yml)
3
+ [![Codecov](https://codecov.io/gh/rodrigo-arenas/pyworkforce/branch/main/graphs/badge.svg?branch=main&service=github)](https://codecov.io/github/rodrigo-arenas/pyworkforce?branch=main)
4
+ [![PyPI Version](https://badge.fury.io/py/pyworkforce.svg)](https://badge.fury.io/py/pyworkforce)
5
+ [![Python Version](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/downloads/)
6
+
7
+
8
+ # pyworkforce
9
+ Tools for workforce management problems such as queue staffing, shift scheduling,
10
+ rostering, and operations research optimization. It is geared toward call /
11
+ contact centers, but the same techniques apply to hospitals, retail, logistics,
12
+ network capacity planning and any operation that has to match a variable demand
13
+ with a finite number of resources.
14
+
15
+ 📖 **Full documentation and tutorials:**
16
+ [rodrigo-arenas.github.io/pyworkforce](https://rodrigo-arenas.github.io/pyworkforce/)
17
+
18
+ ## Installation
19
+
20
+ pyworkforce supports Python 3.12, 3.13, and 3.14.
21
+
22
+ **pip**
23
+
24
+ ```bash
25
+ pip install pyworkforce
26
+ ```
27
+
28
+ **conda** (via [conda-forge](https://conda-forge.org/))
29
+
30
+ ```bash
31
+ conda install -c conda-forge pyworkforce
32
+ ```
33
+
34
+
35
+ For runnable examples, see the
36
+ [examples folder](https://github.com/rodrigo-arenas/pyworkforce/tree/main/examples).
37
+
38
+ ## Features
39
+
40
+ pyworkforce is organized around three planning steps — *how many resources do I
41
+ need?* → *how many per shift?* → *who works when?* — plus helpers that tie them
42
+ together:
43
+
44
+ - **Queuing**
45
+ - `ErlangC` — the classic M/M/c queue (infinite patience).
46
+ - `ErlangA` — the M/M/c+M queue with customer **abandonment** (patience),
47
+ computed exactly from the birth–death stationary distribution.
48
+ - `ErlangB` — the M/M/c/c **loss queue** (no waiting room): blocked calls are
49
+ shed. Use this for trunk / SIP channel sizing.
50
+ - `MultiErlangC` / `MultiErlangA` / `MultiErlangB` — evaluate many scenarios
51
+ from a parameter grid in parallel, scikit-learn style.
52
+ - **Shift coverage helpers** (`pyworkforce.shifts`) — build the `shifts_coverage`
53
+ arrays the schedulers expect from clock hours, spans or explicit periods,
54
+ instead of hand-writing 0/1 arrays.
55
+ - **Scheduling** (`pyworkforce.scheduling`) — `MinAbsDifference` and
56
+ `MinRequiredResources` decide how many people to place on each shift, built on
57
+ [OR-Tools](https://developers.google.com/optimization).
58
+ - **Rostering** (`pyworkforce.rostering`) — `MinHoursRoster` assigns named people
59
+ to days and shifts while respecting banned shifts, rest days, minimum hours,
60
+ non-sequential shifts and preferences.
61
+ - **Break scheduling** (`pyworkforce.breaks`) — `BreakScheduler` assigns break
62
+ start times to agent slots within each shift, preventing overlapping breaks
63
+ and guaranteeing that breaks never drop coverage below the required minimum.
64
+ - **A scikit-learn-friendly API** — consistent constructors with clear validation
65
+ messages, `get_params()` and readable `repr()` on every estimator, the last
66
+ result stored as `solution_`, and `results_to_dataframe` to turn grid results
67
+ into tidy `pandas` DataFrames.
68
+
69
+ A brief introduction to the queuing and scheduling ideas can be found in these
70
+ posts:
71
+ [workforce planning](https://towardsdatascience.com/workforce-planning-optimization-using-python-69af0ef9011a)
72
+ and [scheduling](https://towardsdatascience.com/how-to-solve-scheduling-problems-in-python-36a9af8de451).
73
+
74
+ ## Queuing
75
+
76
+ Estimate how many resources are required to handle incoming work, for example
77
+ calls arriving at a call center.
78
+
79
+ ![queue_system](https://raw.githubusercontent.com/rodrigo-arenas/pyworkforce/main/docs/images/erlangc_queue_system.png)
80
+
81
+ ### Erlang C
82
+
83
+ ```python
84
+ from pyworkforce.queuing import ErlangC
85
+
86
+ erlang = ErlangC(transactions=100, asa=20/60, aht=3, interval=30, shrinkage=0.3)
87
+
88
+ positions_requirements = erlang.required_positions(service_level=0.8, max_occupancy=0.85)
89
+ print("positions_requirements: ", positions_requirements)
90
+ ```
91
+ Output:
92
+ ```
93
+ >> positions_requirements: {'raw_positions': 14,
94
+ 'positions': 20,
95
+ 'service_level': 0.8883500191794669,
96
+ 'occupancy': 0.7142857142857143,
97
+ 'waiting_probability': 0.1741319335950498}
98
+ ```
99
+
100
+ ### Erlang A (modeling abandonment)
101
+
102
+ Real customers hang up if they wait too long. `ErlangA` adds a `patience`
103
+ parameter and reports the abandonment probability, typically requiring fewer
104
+ agents than Erlang C:
105
+
106
+ ```python
107
+ from pyworkforce.queuing import ErlangA
108
+
109
+ erlang = ErlangA(transactions=100, asa=20/60, aht=3, interval=30, patience=5, shrinkage=0.3)
110
+
111
+ requirements = erlang.required_positions(service_level=0.8, max_occupancy=0.85, max_abandonment=0.05)
112
+ print("requirements: ", requirements)
113
+ ```
114
+ Output:
115
+ ```
116
+ >> requirements: {'raw_positions': 13,
117
+ 'positions': 19,
118
+ 'service_level': 0.858...,
119
+ 'occupancy': 0.750...,
120
+ 'abandonment_probability': 0.025...,
121
+ 'waiting_probability': 0.226...,
122
+ 'average_speed_of_answer': 0.125...}
123
+ ```
124
+
125
+ ### Many scenarios at once
126
+
127
+ `MultiErlangC` / `MultiErlangA` evaluate a parameter grid in parallel, and
128
+ `results_to_dataframe` turns the results into a tidy table:
129
+
130
+ ```python
131
+ from pyworkforce.queuing import MultiErlangC
132
+ from pyworkforce.utils import results_to_dataframe
133
+
134
+ param_grid = {"transactions": [100], "aht": [3], "interval": [30], "asa": [20 / 60], "shrinkage": [0.3]}
135
+ multi_erlang = MultiErlangC(param_grid=param_grid, n_jobs=-1)
136
+
137
+ scenarios = {"service_level": [0.8, 0.85, 0.9], "max_occupancy": [0.8]}
138
+ results = multi_erlang.required_positions(scenarios)
139
+
140
+ df = results_to_dataframe(results, multi_erlang.required_positions_params)
141
+ print(df[["service_level", "positions", "service_level_result", "occupancy"]].round(4).to_string(index=False))
142
+ ```
143
+ Output:
144
+ ```
145
+ service_level positions service_level_result occupancy
146
+ 0.80 20 0.8884 0.7143
147
+ 0.85 20 0.8884 0.7143
148
+ 0.90 22 0.9415 0.6667
149
+ ```
150
+
151
+ The input target stays under `service_level`; the achieved value is kept as
152
+ `service_level_result`.
153
+
154
+ ## Shift coverage helpers
155
+
156
+ Describe shifts by their clock hours instead of writing 0/1 arrays. Overnight
157
+ shifts wrap past midnight:
158
+
159
+ ```python
160
+ from pyworkforce.shifts import shift_coverage_from_hours
161
+
162
+ shifts_coverage = shift_coverage_from_hours({
163
+ "Morning": (6, 14),
164
+ "Afternoon": (14, 22),
165
+ "Night": (22, 6),
166
+ }, num_periods=24)
167
+ ```
168
+
169
+ The output plugs straight into the schedulers below. See also
170
+ `shift_coverage_from_spans`, `shift_coverage_from_periods`,
171
+ `validate_shift_coverage` and `coverage_to_dataframe`.
172
+
173
+ ## Scheduling
174
+
175
+ Given the required resources per period, decide how many people to place on each
176
+ predefined shift.
177
+
178
+ ```python
179
+ from pyworkforce.scheduling import MinAbsDifference, MinRequiredResources
180
+
181
+ # Rows are days. Each value is the number of required positions for one hour of the day.
182
+ required_resources = [
183
+ [9, 11, 17, 9, 7, 12, 5, 11, 8, 9, 18, 17, 8, 12, 16, 8, 7, 12, 11, 10, 13, 19, 16, 7],
184
+ [13, 13, 12, 15, 18, 20, 13, 16, 17, 8, 13, 11, 6, 19, 11, 20, 19, 17, 10, 13, 14, 23, 16, 8]
185
+ ]
186
+
187
+ # Each shift has 24 entries, one per hour. Use 1 if the shift covers that hour, otherwise 0.
188
+ shifts_coverage = {"Morning": [0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
189
+ "Afternoon": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0],
190
+ "Night": [1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1],
191
+ "Mixed": [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0]}
192
+
193
+ # Minimize the absolute difference between required and scheduled resources
194
+ difference_scheduler = MinAbsDifference(num_days=2,
195
+ periods=24,
196
+ shifts_coverage=shifts_coverage,
197
+ required_resources=required_resources,
198
+ max_period_concurrency=27,
199
+ max_shift_concurrency=25)
200
+ difference_solution = difference_scheduler.solve()
201
+
202
+ # Minimize the (optionally weighted) number of scheduled resources while covering every period
203
+ requirements_scheduler = MinRequiredResources(num_days=2,
204
+ periods=24,
205
+ shifts_coverage=shifts_coverage,
206
+ required_resources=required_resources,
207
+ max_period_concurrency=27,
208
+ max_shift_concurrency=25)
209
+ requirements_solution = requirements_scheduler.solve()
210
+
211
+ print("difference_solution :", difference_solution["status"], difference_solution["cost"])
212
+ print("requirements_solution :", requirements_solution["status"], requirements_solution["cost"])
213
+ ```
214
+ Output:
215
+ ```
216
+ >> difference_solution: {'status': 'OPTIMAL',
217
+ 'cost': 157.0,
218
+ 'resources_shifts': [{'day': 0, 'shift': 'Morning', 'resources': 8},
219
+ {'day': 0, 'shift': 'Afternoon', 'resources': 11},
220
+ {'day': 0, 'shift': 'Night', 'resources': 9},
221
+ {'day': 0, 'shift': 'Mixed', 'resources': 1},
222
+ ... ]}
223
+
224
+ >> requirements_solution: {'status': 'OPTIMAL',
225
+ 'cost': 113.0,
226
+ 'resources_shifts': [{'day': 0, 'shift': 'Morning', 'resources': 15},
227
+ {'day': 0, 'shift': 'Afternoon', 'resources': 13},
228
+ ... ]}
229
+ ```
230
+
231
+ `MinRequiredResources` also accepts a `cost_dict` to weight shifts differently
232
+ (for example, more expensive night shifts).
233
+
234
+ ## Rostering
235
+
236
+ Assign **named** people to days and shifts while respecting individual rules and
237
+ preferences.
238
+
239
+ ```python
240
+ from pyworkforce.rostering import MinHoursRoster
241
+
242
+ roster = MinHoursRoster(
243
+ num_days=2,
244
+ resources=["ana@co", "ben@co", "cara@co", "dan@co", "eve@co"],
245
+ shifts=["Morning", "Night"],
246
+ shifts_hours=[8, 8],
247
+ min_working_hours=8,
248
+ max_resting=1,
249
+ required_resources={"Morning": [2, 2], "Night": [1, 1]},
250
+ banned_shifts=[{"resource": "ana@co", "shift": "Night", "day": 0}],
251
+ resources_preferences=[{"resource": "ana@co", "shift": "Morning"}],
252
+ )
253
+
254
+ solution = roster.solve()
255
+ print(solution["status"], solution["resource_shifts"][:2])
256
+ ```
257
+ Output:
258
+ ```
259
+ OPTIMAL [{'resource': 'ana@co', 'day': 0, 'shift': 'Morning'},
260
+ {'resource': 'ana@co', 'day': 1, 'shift': 'Morning'}]
261
+ ```
262
+
263
+ `ana@co` is given her preferred `Morning` shift and never `Night` on day 0,
264
+ exactly as configured.
265
+
266
+ ## Documentation and tutorials
267
+
268
+ The [documentation site](https://rodrigo-arenas.github.io/pyworkforce/) includes
269
+ narrative guides, a full API reference, and self-contained, notebook-style
270
+ tutorials with real outputs:
271
+
272
+ - [End-to-end planning](https://rodrigo-arenas.github.io/pyworkforce/guide/end-to-end)
273
+ — demand → required positions → shift coverage → schedule → roster.
274
+ - [Comparing scenarios](https://rodrigo-arenas.github.io/pyworkforce/guide/scenarios)
275
+ — grids and DataFrames.
276
+
277
+ ## Contributing
278
+
279
+ Contributions are very welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the
280
+ local development setup, how to run the tests and linter, and the pull-request
281
+ workflow.
282
+
283
+ ## License
284
+
285
+ pyworkforce is released under the [MIT License](LICENSE).