pyworkforce 0.5.3__tar.gz → 0.5.4__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.4/PKG-INFO +390 -0
- pyworkforce-0.5.4/README.md +356 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyproject.toml +2 -2
- pyworkforce-0.5.4/pyworkforce/_version.py +1 -0
- pyworkforce-0.5.4/pyworkforce.egg-info/PKG-INFO +390 -0
- pyworkforce-0.5.3/PKG-INFO +0 -319
- pyworkforce-0.5.3/README.md +0 -285
- pyworkforce-0.5.3/pyworkforce/_version.py +0 -1
- pyworkforce-0.5.3/pyworkforce.egg-info/PKG-INFO +0 -319
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/LICENSE +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/base.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/breaks/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/breaks/break_scheduler.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/breaks/tests/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/breaks/tests/test_break_scheduler.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/queuing/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/queuing/abandonment.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/queuing/erlang.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/queuing/erlang_b.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/queuing/tests/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/queuing/tests/test_abandonment.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/queuing/tests/test_erlang.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/queuing/tests/test_erlang_b.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/queuing/tests/test_multi_abandonment.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/queuing/tests/test_multi_erlang.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/rostering/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/rostering/binary_programming.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/rostering/tests/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/rostering/tests/rostering_data.json +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/rostering/tests/test_rostering.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/rostering/tests/test_validation.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/scheduling/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/scheduling/base.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/scheduling/shifts_selection.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/scheduling/tests/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/scheduling/tests/test_shifts.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/scheduling/tests/test_utils.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/scheduling/tests/test_validation.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/scheduling/utils.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/shifts/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/shifts/coverage.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/shifts/tests/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/shifts/tests/test_coverage.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/staffing/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/staffing/multi_skill.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/staffing/tests/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/staffing/tests/test_multi_skill.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/tests/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/tests/test_base.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/utils/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/utils/frames.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/utils/grid.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/utils/tests/__init__.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/utils/tests/test_frames.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/utils/tests/test_parameter_grid.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/utils/tests/test_validation.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce/utils/validation.py +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce.egg-info/SOURCES.txt +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce.egg-info/dependency_links.txt +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce.egg-info/requires.txt +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/pyworkforce.egg-info/top_level.txt +0 -0
- {pyworkforce-0.5.3 → pyworkforce-0.5.4}/setup.cfg +0 -0
|
@@ -0,0 +1,390 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pyworkforce
|
|
3
|
+
Version: 0.5.4
|
|
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://pyworkforce.rodrigo-arenas.com/
|
|
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://pyworkforce.rodrigo-arenas.com/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
|
+
[](https://github.com/rodrigo-arenas/pyworkforce/actions/workflows/ci-tests.yml)
|
|
36
|
+
[](https://codecov.io/github/rodrigo-arenas/pyworkforce?branch=main)
|
|
37
|
+
[](https://badge.fury.io/py/pyworkforce)
|
|
38
|
+
[](https://www.python.org/downloads/)
|
|
39
|
+
[](https://pyworkforce.rodrigo-arenas.com/stable/)
|
|
40
|
+
|
|
41
|
+
# pyworkforce
|
|
42
|
+
|
|
43
|
+
**Workforce management, made practical.** Covers the full planning pipeline from
|
|
44
|
+
queue staffing to named rosters and break scheduling — built on Erlang queuing
|
|
45
|
+
theory and OR-Tools constraint programming, with a scikit-learn-style API.
|
|
46
|
+
|
|
47
|
+
> Geared toward contact / call centres, but the same techniques apply to
|
|
48
|
+
> hospitals, retail, logistics and any operation matching variable demand to
|
|
49
|
+
> finite resources.
|
|
50
|
+
|
|
51
|
+
📖 **Full documentation:** [pyworkforce.rodrigo-arenas.com](https://pyworkforce.rodrigo-arenas.com/stable/)
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Installation
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pip install pyworkforce
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Requires Python 3.12 – 3.14. conda-forge support is pending an update to the
|
|
62
|
+
`ortools-python` feedstock for Python 3.12.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## The planning workflow
|
|
67
|
+
|
|
68
|
+
pyworkforce covers five sequential planning steps:
|
|
69
|
+
|
|
70
|
+

|
|
71
|
+
|
|
72
|
+
| Step | Module | Key classes | Question answered |
|
|
73
|
+
|------|--------|-------------|-------------------|
|
|
74
|
+
| 1 | `pyworkforce.queuing` | `ErlangC`, `ErlangA`, `ErlangB` | How many agents / channels are needed? |
|
|
75
|
+
| 2 | `pyworkforce.staffing` | `MultiSkillStaffing` | What is the optimal skill-profile mix? |
|
|
76
|
+
| 3 | `pyworkforce.scheduling` | `MinRequiredResources`, `MinAbsDifference` | How many agents per shift? |
|
|
77
|
+
| 4 | `pyworkforce.rostering` | `MinHoursRoster` | Who works on which day and shift? |
|
|
78
|
+
| 5 | `pyworkforce.breaks` | `BreakScheduler` | When do individual breaks happen? |
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 1 — Queuing
|
|
83
|
+
|
|
84
|
+
Estimate the number of agents (or channels) needed to meet a service target given
|
|
85
|
+
an incoming demand.
|
|
86
|
+
|
|
87
|
+
### Erlang C — infinite patience
|
|
88
|
+
|
|
89
|
+
The classic M/M/c queue: Poisson arrivals, exponential handling times, unlimited
|
|
90
|
+
waiting room.
|
|
91
|
+
|
|
92
|
+

|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
from pyworkforce.queuing import ErlangC
|
|
96
|
+
|
|
97
|
+
erlang = ErlangC(transactions=100, aht=3, asa=20/60, interval=30, shrinkage=0.3)
|
|
98
|
+
|
|
99
|
+
result = erlang.required_positions(service_level=0.8, max_occupancy=0.85)
|
|
100
|
+
print(result)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
{'raw_positions': 14,
|
|
105
|
+
'positions': 20,
|
|
106
|
+
'service_level': 0.8884,
|
|
107
|
+
'occupancy': 0.7143,
|
|
108
|
+
'waiting_probability': 0.1741}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Erlang A — finite patience (abandonment)
|
|
112
|
+
|
|
113
|
+
Adds a `patience` parameter: callers who wait too long hang up.
|
|
114
|
+
Typically requires fewer agents than Erlang C.
|
|
115
|
+
|
|
116
|
+

|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
from pyworkforce.queuing import ErlangA
|
|
120
|
+
|
|
121
|
+
erlang = ErlangA(transactions=100, aht=3, asa=20/60, interval=30,
|
|
122
|
+
patience=5, shrinkage=0.3)
|
|
123
|
+
|
|
124
|
+
result = erlang.required_positions(service_level=0.8, max_occupancy=0.85,
|
|
125
|
+
max_abandonment=0.05)
|
|
126
|
+
print(result)
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
{'raw_positions': 13,
|
|
131
|
+
'positions': 19,
|
|
132
|
+
'service_level': 0.8584,
|
|
133
|
+
'occupancy': 0.7500,
|
|
134
|
+
'abandonment_probability': 0.0253,
|
|
135
|
+
'waiting_probability': 0.2265,
|
|
136
|
+
'average_speed_of_answer': 0.1258}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Erlang B — pure loss (no waiting room)
|
|
140
|
+
|
|
141
|
+
M/M/c/c queue: blocked calls are shed immediately.
|
|
142
|
+
Use this for SIP trunk sizing, IVR channel capacity and overflow links.
|
|
143
|
+
|
|
144
|
+

|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
from pyworkforce.queuing import ErlangB
|
|
148
|
+
|
|
149
|
+
erlang = ErlangB(transactions=100, aht=3, interval=30, shrinkage=0.3)
|
|
150
|
+
|
|
151
|
+
result = erlang.required_positions(max_blocking=0.02)
|
|
152
|
+
print(result)
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
```
|
|
156
|
+
{'raw_positions': 17,
|
|
157
|
+
'positions': 25,
|
|
158
|
+
'blocking_probability': 0.0183,
|
|
159
|
+
'occupancy': 0.9375}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Running many scenarios at once
|
|
163
|
+
|
|
164
|
+
`MultiErlangC`, `MultiErlangA` and `MultiErlangB` sweep a parameter grid in
|
|
165
|
+
parallel (scikit-learn style) and `results_to_dataframe` turns the output into a
|
|
166
|
+
tidy table:
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
from pyworkforce.queuing import MultiErlangC
|
|
170
|
+
from pyworkforce.utils import results_to_dataframe
|
|
171
|
+
|
|
172
|
+
param_grid = {"transactions": [100], "aht": [3], "interval": [30],
|
|
173
|
+
"asa": [20/60], "shrinkage": [0.3]}
|
|
174
|
+
multi = MultiErlangC(param_grid=param_grid, n_jobs=-1)
|
|
175
|
+
|
|
176
|
+
results = multi.required_positions({"service_level": [0.80, 0.85, 0.90],
|
|
177
|
+
"max_occupancy": [0.85]})
|
|
178
|
+
|
|
179
|
+
df = results_to_dataframe(results, multi.required_positions_params)
|
|
180
|
+
print(df[["service_level", "positions", "occupancy"]].round(4).to_string(index=False))
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
```
|
|
184
|
+
service_level positions occupancy
|
|
185
|
+
0.80 20 0.7143
|
|
186
|
+
0.85 20 0.7143
|
|
187
|
+
0.90 22 0.6667
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## 2 — Multi-skill staffing
|
|
193
|
+
|
|
194
|
+
When agents handle multiple contact types (e.g. English, Billing, Technical),
|
|
195
|
+
`MultiSkillStaffing` finds the cheapest mix of skill profiles that meets every
|
|
196
|
+
skill's coverage requirement. Flexible (multi-skilled) agents count towards all
|
|
197
|
+
skills they hold.
|
|
198
|
+
|
|
199
|
+
```python
|
|
200
|
+
from pyworkforce.staffing import MultiSkillStaffing
|
|
201
|
+
|
|
202
|
+
skills = ["Billing", "Technical"]
|
|
203
|
+
profiles = [
|
|
204
|
+
{"name": "Billing_only", "skills": ["Billing"], "cost": 1.0},
|
|
205
|
+
{"name": "Technical_only", "skills": ["Technical"], "cost": 1.0},
|
|
206
|
+
{"name": "Flexible", "skills": ["Billing", "Technical"], "cost": 1.5},
|
|
207
|
+
]
|
|
208
|
+
required = {"Billing": 5, "Technical": 3}
|
|
209
|
+
|
|
210
|
+
ms = MultiSkillStaffing(skills=skills, profiles=profiles, required_positions=required)
|
|
211
|
+
result = ms.solve()
|
|
212
|
+
|
|
213
|
+
print(f"status={result['status']} total={result['total_agents']} cost={result['cost']}")
|
|
214
|
+
for entry in result["agents_per_profile"]:
|
|
215
|
+
print(f" {entry['profile']:18s}: {entry['agents']}")
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
```
|
|
219
|
+
status=OPTIMAL total=5 cost=6.5
|
|
220
|
+
Billing_only : 2
|
|
221
|
+
Technical_only : 0
|
|
222
|
+
Flexible : 3
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
3 flexible + 2 billing-only = cost 6.5, vs 8.0 for pure dedicated agents.
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## 3 — Shift coverage helpers
|
|
230
|
+
|
|
231
|
+
Build the `shifts_coverage` arrays the schedulers expect from clock hours instead
|
|
232
|
+
of writing 0/1 arrays by hand:
|
|
233
|
+
|
|
234
|
+
```python
|
|
235
|
+
from pyworkforce.shifts import shift_coverage_from_hours
|
|
236
|
+
|
|
237
|
+
shifts_coverage = shift_coverage_from_hours({
|
|
238
|
+
"Morning": (6, 14),
|
|
239
|
+
"Afternoon": (14, 22),
|
|
240
|
+
"Night": (22, 6), # wraps past midnight
|
|
241
|
+
}, num_periods=24)
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
See also `shift_coverage_from_spans`, `shift_coverage_from_periods`,
|
|
245
|
+
`validate_shift_coverage` and `coverage_to_dataframe`.
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## 4 — Scheduling
|
|
250
|
+
|
|
251
|
+
Given the required resources per period, decide how many agents to place on each
|
|
252
|
+
shift using constraint programming (OR-Tools):
|
|
253
|
+
|
|
254
|
+
```python
|
|
255
|
+
from pyworkforce.scheduling import MinRequiredResources
|
|
256
|
+
|
|
257
|
+
# One row per day; each value = required agents for that hour
|
|
258
|
+
required_resources = [
|
|
259
|
+
[9, 11, 17, 9, 7, 12, 5, 11, 8, 9, 18, 17, 8, 12, 16, 8, 7, 12, 11, 10, 13, 19, 16, 7],
|
|
260
|
+
[13, 13, 12, 15, 18, 20, 13, 16, 17, 8, 13, 11, 6, 19, 11, 20, 19, 17, 10, 13, 14, 23, 16, 8],
|
|
261
|
+
]
|
|
262
|
+
shifts_coverage = {
|
|
263
|
+
"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],
|
|
264
|
+
"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],
|
|
265
|
+
"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],
|
|
266
|
+
"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],
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
scheduler = MinRequiredResources(
|
|
270
|
+
num_days=2, periods=24,
|
|
271
|
+
shifts_coverage=shifts_coverage,
|
|
272
|
+
required_resources=required_resources,
|
|
273
|
+
max_period_concurrency=27, max_shift_concurrency=25,
|
|
274
|
+
)
|
|
275
|
+
solution = scheduler.solve()
|
|
276
|
+
print(solution["status"], solution["cost"])
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
```
|
|
280
|
+
OPTIMAL 113.0
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
`MinAbsDifference` minimises the absolute difference between required and
|
|
284
|
+
scheduled; `MinRequiredResources` minimises total agents (optionally weighted by
|
|
285
|
+
shift cost).
|
|
286
|
+
|
|
287
|
+
---
|
|
288
|
+
|
|
289
|
+
## 5 — Rostering
|
|
290
|
+
|
|
291
|
+
Assign **named** people to days and shifts while respecting individual rules:
|
|
292
|
+
|
|
293
|
+
```python
|
|
294
|
+
from pyworkforce.rostering import MinHoursRoster
|
|
295
|
+
|
|
296
|
+
roster = MinHoursRoster(
|
|
297
|
+
num_days=2,
|
|
298
|
+
resources=["ana@co", "ben@co", "cara@co", "dan@co", "eve@co"],
|
|
299
|
+
shifts=["Morning", "Night"],
|
|
300
|
+
shifts_hours=[8, 8],
|
|
301
|
+
min_working_hours=8,
|
|
302
|
+
max_resting=1,
|
|
303
|
+
required_resources={"Morning": [2, 2], "Night": [1, 1]},
|
|
304
|
+
banned_shifts=[{"resource": "ana@co", "shift": "Night", "day": 0}],
|
|
305
|
+
resources_preferences=[{"resource": "ana@co", "shift": "Morning"}],
|
|
306
|
+
)
|
|
307
|
+
|
|
308
|
+
solution = roster.solve()
|
|
309
|
+
print(solution["status"])
|
|
310
|
+
for a in solution["resource_shifts"][:3]:
|
|
311
|
+
print(a)
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
```
|
|
315
|
+
OPTIMAL
|
|
316
|
+
{'resource': 'ana@co', 'day': 0, 'shift': 'Morning'}
|
|
317
|
+
{'resource': 'ana@co', 'day': 1, 'shift': 'Morning'}
|
|
318
|
+
{'resource': 'ben@co', 'day': 0, 'shift': 'Night'}
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
`ana@co` is assigned her preferred shift and never `Night` on day 0, exactly
|
|
322
|
+
as configured.
|
|
323
|
+
|
|
324
|
+
---
|
|
325
|
+
|
|
326
|
+
## 6 — Break scheduling
|
|
327
|
+
|
|
328
|
+
Assign break start times to agent slots within each shift, ensuring that
|
|
329
|
+
simultaneous breaks never drop coverage below the required minimum:
|
|
330
|
+
|
|
331
|
+
```python
|
|
332
|
+
from pyworkforce.breaks import BreakScheduler
|
|
333
|
+
|
|
334
|
+
shifts_coverage = {"Morning": [1,1,1,1,1,1,1,1,0,0,0,0,0,0,0,0],
|
|
335
|
+
"Afternoon": [0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1]}
|
|
336
|
+
scheduled_resources = {"Morning": [3], "Afternoon": [2]}
|
|
337
|
+
breaks = [{"name": "Lunch", "duration_periods": 2,
|
|
338
|
+
"min_start_after": 2, "max_end_before": 2}]
|
|
339
|
+
min_coverage = [[2,2,2,2,2,2,2,2,1,1,1,1,1,1,1,1]]
|
|
340
|
+
|
|
341
|
+
scheduler = BreakScheduler(
|
|
342
|
+
num_days=1, periods=16,
|
|
343
|
+
shifts_coverage=shifts_coverage,
|
|
344
|
+
scheduled_resources=scheduled_resources,
|
|
345
|
+
breaks=breaks, min_coverage=min_coverage,
|
|
346
|
+
)
|
|
347
|
+
result = scheduler.solve()
|
|
348
|
+
print(result["status"])
|
|
349
|
+
for entry in result["break_schedule"]:
|
|
350
|
+
print(entry)
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
```
|
|
354
|
+
OPTIMAL
|
|
355
|
+
{'shift': 'Morning', 'day': 0, 'slot': 0, 'break_name': 'Lunch', 'start_period': 2, 'end_period': 4}
|
|
356
|
+
{'shift': 'Morning', 'day': 0, 'slot': 1, 'break_name': 'Lunch', 'start_period': 4, 'end_period': 6}
|
|
357
|
+
{'shift': 'Morning', 'day': 0, 'slot': 2, 'break_name': 'Lunch', 'start_period': 2, 'end_period': 4}
|
|
358
|
+
{'shift': 'Afternoon', 'day': 0, 'slot': 0, 'break_name': 'Lunch', 'start_period': 10, 'end_period': 12}
|
|
359
|
+
{'shift': 'Afternoon', 'day': 0, 'slot': 1, 'break_name': 'Lunch', 'start_period': 12, 'end_period': 14}
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
---
|
|
363
|
+
|
|
364
|
+
## Documentation
|
|
365
|
+
|
|
366
|
+
The [documentation site](https://pyworkforce.rodrigo-arenas.com/stable/)
|
|
367
|
+
includes narrative guides, a full API reference, and self-contained tutorials
|
|
368
|
+
with real outputs:
|
|
369
|
+
|
|
370
|
+
- **[End-to-end tutorial](https://pyworkforce.rodrigo-arenas.com/stable/guide/end-to-end)**
|
|
371
|
+
— demand forecast → queuing → staffing mix → shift coverage → schedule → roster
|
|
372
|
+
- **[Comparing scenarios](https://pyworkforce.rodrigo-arenas.com/stable/guide/scenarios)**
|
|
373
|
+
— grids, DataFrames, and service-level sweeps
|
|
374
|
+
- **[API reference](https://pyworkforce.rodrigo-arenas.com/stable/api/queuing)**
|
|
375
|
+
|
|
376
|
+
Background reading on the underlying techniques:
|
|
377
|
+
[workforce planning](https://towardsdatascience.com/workforce-planning-optimization-using-python-69af0ef9011a)
|
|
378
|
+
and [scheduling](https://towardsdatascience.com/how-to-solve-scheduling-problems-in-python-36a9af8de451).
|
|
379
|
+
|
|
380
|
+
---
|
|
381
|
+
|
|
382
|
+
## Contributing
|
|
383
|
+
|
|
384
|
+
Contributions are very welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the
|
|
385
|
+
local development setup, how to run the tests and linter, and the pull-request
|
|
386
|
+
workflow.
|
|
387
|
+
|
|
388
|
+
## License
|
|
389
|
+
|
|
390
|
+
pyworkforce is released under the [MIT License](LICENSE).
|