pyworkforce 0.5.2__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.
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/LICENSE +21 -21
- pyworkforce-0.5.3/PKG-INFO +319 -0
- pyworkforce-0.5.3/README.md +285 -0
- pyworkforce-0.5.3/pyproject.toml +102 -0
- pyworkforce-0.5.3/pyworkforce/__init__.py +21 -0
- pyworkforce-0.5.3/pyworkforce/_version.py +1 -0
- pyworkforce-0.5.3/pyworkforce/base.py +47 -0
- pyworkforce-0.5.3/pyworkforce/breaks/__init__.py +3 -0
- pyworkforce-0.5.3/pyworkforce/breaks/break_scheduler.py +362 -0
- pyworkforce-0.5.3/pyworkforce/breaks/tests/test_break_scheduler.py +286 -0
- pyworkforce-0.5.3/pyworkforce/queuing/__init__.py +5 -0
- pyworkforce-0.5.3/pyworkforce/queuing/abandonment.py +497 -0
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/queuing/erlang.py +283 -290
- pyworkforce-0.5.3/pyworkforce/queuing/erlang_b.py +279 -0
- pyworkforce-0.5.3/pyworkforce/queuing/tests/test_abandonment.py +129 -0
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/queuing/tests/test_erlang.py +98 -91
- pyworkforce-0.5.3/pyworkforce/queuing/tests/test_erlang_b.py +211 -0
- pyworkforce-0.5.3/pyworkforce/queuing/tests/test_multi_abandonment.py +82 -0
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/queuing/tests/test_multi_erlang.py +130 -89
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/rostering/__init__.py +3 -3
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/rostering/binary_programming.py +246 -211
- pyworkforce-0.5.3/pyworkforce/rostering/tests/rostering_data.json +159 -0
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/rostering/tests/test_rostering.py +38 -37
- pyworkforce-0.5.3/pyworkforce/rostering/tests/test_validation.py +70 -0
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/scheduling/__init__.py +3 -3
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/scheduling/base.py +82 -49
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/scheduling/shifts_selection.py +224 -223
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/scheduling/tests/test_shifts.py +181 -180
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/scheduling/tests/test_utils.py +31 -30
- pyworkforce-0.5.3/pyworkforce/scheduling/tests/test_validation.py +70 -0
- pyworkforce-0.5.3/pyworkforce/scheduling/utils.py +9 -0
- pyworkforce-0.5.3/pyworkforce/shifts/__init__.py +15 -0
- pyworkforce-0.5.3/pyworkforce/shifts/coverage.py +266 -0
- pyworkforce-0.5.3/pyworkforce/shifts/tests/__init__.py +0 -0
- pyworkforce-0.5.3/pyworkforce/shifts/tests/test_coverage.py +166 -0
- pyworkforce-0.5.3/pyworkforce/staffing/__init__.py +3 -0
- pyworkforce-0.5.3/pyworkforce/staffing/multi_skill.py +251 -0
- pyworkforce-0.5.3/pyworkforce/staffing/tests/__init__.py +0 -0
- pyworkforce-0.5.3/pyworkforce/staffing/tests/test_multi_skill.py +293 -0
- pyworkforce-0.5.3/pyworkforce/tests/__init__.py +0 -0
- pyworkforce-0.5.3/pyworkforce/tests/test_base.py +54 -0
- pyworkforce-0.5.3/pyworkforce/utils/__init__.py +15 -0
- pyworkforce-0.5.3/pyworkforce/utils/frames.py +66 -0
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/utils/grid.py +113 -112
- pyworkforce-0.5.3/pyworkforce/utils/tests/__init__.py +0 -0
- pyworkforce-0.5.3/pyworkforce/utils/tests/test_frames.py +46 -0
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce/utils/tests/test_parameter_grid.py +71 -69
- pyworkforce-0.5.3/pyworkforce/utils/tests/test_validation.py +53 -0
- pyworkforce-0.5.3/pyworkforce/utils/validation.py +108 -0
- pyworkforce-0.5.3/pyworkforce.egg-info/PKG-INFO +319 -0
- pyworkforce-0.5.3/pyworkforce.egg-info/SOURCES.txt +57 -0
- pyworkforce-0.5.3/pyworkforce.egg-info/requires.txt +10 -0
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/setup.cfg +4 -4
- pyworkforce-0.5.2/PKG-INFO +0 -238
- pyworkforce-0.5.2/README.md +0 -202
- pyworkforce-0.5.2/pyworkforce/__init__.py +0 -13
- pyworkforce-0.5.2/pyworkforce/_version.py +0 -1
- pyworkforce-0.5.2/pyworkforce/queuing/__init__.py +0 -3
- pyworkforce-0.5.2/pyworkforce/scheduling/utils.py +0 -14
- pyworkforce-0.5.2/pyworkforce/utils/__init__.py +0 -3
- pyworkforce-0.5.2/pyworkforce.egg-info/PKG-INFO +0 -238
- pyworkforce-0.5.2/pyworkforce.egg-info/SOURCES.txt +0 -30
- pyworkforce-0.5.2/pyworkforce.egg-info/requires.txt +0 -4
- pyworkforce-0.5.2/setup.py +0 -48
- {pyworkforce-0.5.2/pyworkforce/queuing → pyworkforce-0.5.3/pyworkforce/breaks}/tests/__init__.py +0 -0
- {pyworkforce-0.5.2/pyworkforce/rostering → pyworkforce-0.5.3/pyworkforce/queuing}/tests/__init__.py +0 -0
- {pyworkforce-0.5.2/pyworkforce/scheduling → pyworkforce-0.5.3/pyworkforce/rostering}/tests/__init__.py +0 -0
- {pyworkforce-0.5.2/pyworkforce/utils → pyworkforce-0.5.3/pyworkforce/scheduling}/tests/__init__.py +0 -0
- {pyworkforce-0.5.2 → pyworkforce-0.5.3}/pyworkforce.egg-info/dependency_links.txt +0 -0
- {pyworkforce-0.5.2 → 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
|
+
[](https://github.com/rodrigo-arenas/pyworkforce/actions/workflows/ci-tests.yml)
|
|
37
|
+
[](https://codecov.io/github/rodrigo-arenas/pyworkforce?branch=main)
|
|
38
|
+
[](https://badge.fury.io/py/pyworkforce)
|
|
39
|
+
[](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
|
+

|
|
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
|
+
[](https://github.com/rodrigo-arenas/pyworkforce/actions/workflows/ci-tests.yml)
|
|
3
|
+
[](https://codecov.io/github/rodrigo-arenas/pyworkforce?branch=main)
|
|
4
|
+
[](https://badge.fury.io/py/pyworkforce)
|
|
5
|
+
[](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
|
+

|
|
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).
|