pyworkforce 0.5.2__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.
Files changed (70) hide show
  1. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/LICENSE +21 -21
  2. pyworkforce-0.5.4/PKG-INFO +390 -0
  3. pyworkforce-0.5.4/README.md +356 -0
  4. pyworkforce-0.5.4/pyproject.toml +102 -0
  5. pyworkforce-0.5.4/pyworkforce/__init__.py +21 -0
  6. pyworkforce-0.5.4/pyworkforce/_version.py +1 -0
  7. pyworkforce-0.5.4/pyworkforce/base.py +47 -0
  8. pyworkforce-0.5.4/pyworkforce/breaks/__init__.py +3 -0
  9. pyworkforce-0.5.4/pyworkforce/breaks/break_scheduler.py +362 -0
  10. pyworkforce-0.5.4/pyworkforce/breaks/tests/test_break_scheduler.py +286 -0
  11. pyworkforce-0.5.4/pyworkforce/queuing/__init__.py +5 -0
  12. pyworkforce-0.5.4/pyworkforce/queuing/abandonment.py +497 -0
  13. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/queuing/erlang.py +283 -290
  14. pyworkforce-0.5.4/pyworkforce/queuing/erlang_b.py +279 -0
  15. pyworkforce-0.5.4/pyworkforce/queuing/tests/test_abandonment.py +129 -0
  16. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/queuing/tests/test_erlang.py +98 -91
  17. pyworkforce-0.5.4/pyworkforce/queuing/tests/test_erlang_b.py +211 -0
  18. pyworkforce-0.5.4/pyworkforce/queuing/tests/test_multi_abandonment.py +82 -0
  19. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/queuing/tests/test_multi_erlang.py +130 -89
  20. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/rostering/__init__.py +3 -3
  21. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/rostering/binary_programming.py +246 -211
  22. pyworkforce-0.5.4/pyworkforce/rostering/tests/rostering_data.json +159 -0
  23. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/rostering/tests/test_rostering.py +38 -37
  24. pyworkforce-0.5.4/pyworkforce/rostering/tests/test_validation.py +70 -0
  25. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/scheduling/__init__.py +3 -3
  26. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/scheduling/base.py +82 -49
  27. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/scheduling/shifts_selection.py +224 -223
  28. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/scheduling/tests/test_shifts.py +181 -180
  29. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/scheduling/tests/test_utils.py +31 -30
  30. pyworkforce-0.5.4/pyworkforce/scheduling/tests/test_validation.py +70 -0
  31. pyworkforce-0.5.4/pyworkforce/scheduling/utils.py +9 -0
  32. pyworkforce-0.5.4/pyworkforce/shifts/__init__.py +15 -0
  33. pyworkforce-0.5.4/pyworkforce/shifts/coverage.py +266 -0
  34. pyworkforce-0.5.4/pyworkforce/shifts/tests/__init__.py +0 -0
  35. pyworkforce-0.5.4/pyworkforce/shifts/tests/test_coverage.py +166 -0
  36. pyworkforce-0.5.4/pyworkforce/staffing/__init__.py +3 -0
  37. pyworkforce-0.5.4/pyworkforce/staffing/multi_skill.py +251 -0
  38. pyworkforce-0.5.4/pyworkforce/staffing/tests/__init__.py +0 -0
  39. pyworkforce-0.5.4/pyworkforce/staffing/tests/test_multi_skill.py +293 -0
  40. pyworkforce-0.5.4/pyworkforce/tests/__init__.py +0 -0
  41. pyworkforce-0.5.4/pyworkforce/tests/test_base.py +54 -0
  42. pyworkforce-0.5.4/pyworkforce/utils/__init__.py +15 -0
  43. pyworkforce-0.5.4/pyworkforce/utils/frames.py +66 -0
  44. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/utils/grid.py +113 -112
  45. pyworkforce-0.5.4/pyworkforce/utils/tests/__init__.py +0 -0
  46. pyworkforce-0.5.4/pyworkforce/utils/tests/test_frames.py +46 -0
  47. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce/utils/tests/test_parameter_grid.py +71 -69
  48. pyworkforce-0.5.4/pyworkforce/utils/tests/test_validation.py +53 -0
  49. pyworkforce-0.5.4/pyworkforce/utils/validation.py +108 -0
  50. pyworkforce-0.5.4/pyworkforce.egg-info/PKG-INFO +390 -0
  51. pyworkforce-0.5.4/pyworkforce.egg-info/SOURCES.txt +57 -0
  52. pyworkforce-0.5.4/pyworkforce.egg-info/requires.txt +10 -0
  53. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/setup.cfg +4 -4
  54. pyworkforce-0.5.2/PKG-INFO +0 -238
  55. pyworkforce-0.5.2/README.md +0 -202
  56. pyworkforce-0.5.2/pyworkforce/__init__.py +0 -13
  57. pyworkforce-0.5.2/pyworkforce/_version.py +0 -1
  58. pyworkforce-0.5.2/pyworkforce/queuing/__init__.py +0 -3
  59. pyworkforce-0.5.2/pyworkforce/scheduling/utils.py +0 -14
  60. pyworkforce-0.5.2/pyworkforce/utils/__init__.py +0 -3
  61. pyworkforce-0.5.2/pyworkforce.egg-info/PKG-INFO +0 -238
  62. pyworkforce-0.5.2/pyworkforce.egg-info/SOURCES.txt +0 -30
  63. pyworkforce-0.5.2/pyworkforce.egg-info/requires.txt +0 -4
  64. pyworkforce-0.5.2/setup.py +0 -48
  65. {pyworkforce-0.5.2/pyworkforce/queuing → pyworkforce-0.5.4/pyworkforce/breaks}/tests/__init__.py +0 -0
  66. {pyworkforce-0.5.2/pyworkforce/rostering → pyworkforce-0.5.4/pyworkforce/queuing}/tests/__init__.py +0 -0
  67. {pyworkforce-0.5.2/pyworkforce/scheduling → pyworkforce-0.5.4/pyworkforce/rostering}/tests/__init__.py +0 -0
  68. {pyworkforce-0.5.2/pyworkforce/utils → pyworkforce-0.5.4/pyworkforce/scheduling}/tests/__init__.py +0 -0
  69. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/pyworkforce.egg-info/dependency_links.txt +0 -0
  70. {pyworkforce-0.5.2 → pyworkforce-0.5.4}/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,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
+ [![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)
36
+ [![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)
37
+ [![PyPI Version](https://badge.fury.io/py/pyworkforce.svg)](https://badge.fury.io/py/pyworkforce)
38
+ [![Python Version](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/downloads/)
39
+ [![Docs](https://img.shields.io/badge/docs-pyworkforce.rodrigo--arenas.com-blue)](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
+ ![Planning workflow](https://raw.githubusercontent.com/rodrigo-arenas/pyworkforce/main/docs/images/planning_pipeline.svg)
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
+ ![Erlang C queue system](https://raw.githubusercontent.com/rodrigo-arenas/pyworkforce/main/docs/images/erlangc_queue_system.svg)
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
+ ![Erlang A queue system — with abandonment](https://raw.githubusercontent.com/rodrigo-arenas/pyworkforce/main/docs/images/erlanga_queue_system.svg)
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
+ ![Erlang B loss system](https://raw.githubusercontent.com/rodrigo-arenas/pyworkforce/main/docs/images/erlangb_loss_system.svg)
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).