pyworkforce 0.5.3__tar.gz → 0.6.0__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 (66) hide show
  1. pyworkforce-0.6.0/PKG-INFO +221 -0
  2. pyworkforce-0.6.0/README.md +183 -0
  3. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyproject.toml +16 -3
  4. pyworkforce-0.6.0/pyworkforce/_version.py +1 -0
  5. pyworkforce-0.6.0/pyworkforce/plotting.py +73 -0
  6. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/queuing/erlang.py +39 -3
  7. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/queuing/tests/test_erlang.py +28 -0
  8. pyworkforce-0.6.0/pyworkforce/scheduling/base.py +213 -0
  9. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/scheduling/shifts_selection.py +33 -59
  10. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/scheduling/tests/test_shifts.py +121 -9
  11. pyworkforce-0.6.0/pyworkforce/tests/test_plotting.py +53 -0
  12. pyworkforce-0.6.0/pyworkforce.egg-info/PKG-INFO +221 -0
  13. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce.egg-info/SOURCES.txt +2 -0
  14. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce.egg-info/requires.txt +3 -0
  15. pyworkforce-0.5.3/PKG-INFO +0 -319
  16. pyworkforce-0.5.3/README.md +0 -285
  17. pyworkforce-0.5.3/pyworkforce/_version.py +0 -1
  18. pyworkforce-0.5.3/pyworkforce/scheduling/base.py +0 -97
  19. pyworkforce-0.5.3/pyworkforce.egg-info/PKG-INFO +0 -319
  20. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/LICENSE +0 -0
  21. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/__init__.py +0 -0
  22. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/base.py +0 -0
  23. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/breaks/__init__.py +0 -0
  24. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/breaks/break_scheduler.py +0 -0
  25. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/breaks/tests/__init__.py +0 -0
  26. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/breaks/tests/test_break_scheduler.py +0 -0
  27. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/queuing/__init__.py +0 -0
  28. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/queuing/abandonment.py +0 -0
  29. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/queuing/erlang_b.py +0 -0
  30. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/queuing/tests/__init__.py +0 -0
  31. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/queuing/tests/test_abandonment.py +0 -0
  32. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/queuing/tests/test_erlang_b.py +0 -0
  33. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/queuing/tests/test_multi_abandonment.py +0 -0
  34. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/queuing/tests/test_multi_erlang.py +0 -0
  35. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/rostering/__init__.py +0 -0
  36. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/rostering/binary_programming.py +0 -0
  37. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/rostering/tests/__init__.py +0 -0
  38. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/rostering/tests/rostering_data.json +0 -0
  39. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/rostering/tests/test_rostering.py +0 -0
  40. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/rostering/tests/test_validation.py +0 -0
  41. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/scheduling/__init__.py +0 -0
  42. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/scheduling/tests/__init__.py +0 -0
  43. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/scheduling/tests/test_utils.py +0 -0
  44. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/scheduling/tests/test_validation.py +0 -0
  45. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/scheduling/utils.py +0 -0
  46. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/shifts/__init__.py +0 -0
  47. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/shifts/coverage.py +0 -0
  48. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/shifts/tests/__init__.py +0 -0
  49. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/shifts/tests/test_coverage.py +0 -0
  50. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/staffing/__init__.py +0 -0
  51. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/staffing/multi_skill.py +0 -0
  52. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/staffing/tests/__init__.py +0 -0
  53. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/staffing/tests/test_multi_skill.py +0 -0
  54. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/tests/__init__.py +0 -0
  55. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/tests/test_base.py +0 -0
  56. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/utils/__init__.py +0 -0
  57. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/utils/frames.py +0 -0
  58. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/utils/grid.py +0 -0
  59. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/utils/tests/__init__.py +0 -0
  60. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/utils/tests/test_frames.py +0 -0
  61. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/utils/tests/test_parameter_grid.py +0 -0
  62. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/utils/tests/test_validation.py +0 -0
  63. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce/utils/validation.py +0 -0
  64. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce.egg-info/dependency_links.txt +0 -0
  65. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/pyworkforce.egg-info/top_level.txt +0 -0
  66. {pyworkforce-0.5.3 → pyworkforce-0.6.0}/setup.cfg +0 -0
@@ -0,0 +1,221 @@
1
+ Metadata-Version: 2.4
2
+ Name: pyworkforce
3
+ Version: 0.6.0
4
+ Summary: Practical workforce planning tools for queue staffing, shift scheduling, rostering, breaks, and operations research in Python
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/stable/release-notes
11
+ Keywords: workforce management,workforce planning,call center,contact center,call center staffing,contact center staffing,erlang,erlang c,erlang a,erlang b,scheduling,shift scheduling,rostering,employee rostering,operations research,or-tools,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: Topic :: Scientific/Engineering :: Mathematics
17
+ Classifier: Topic :: Office/Business :: Scheduling
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Requires-Python: <3.15,>=3.12
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: numpy>=1.23
27
+ Requires-Dist: pandas>=2.2.0
28
+ Requires-Dist: ortools>=9.6
29
+ Requires-Dist: joblib>=1.4.2
30
+ Provides-Extra: plot
31
+ Requires-Dist: matplotlib>=3.8; extra == "plot"
32
+ Provides-Extra: dev
33
+ Requires-Dist: pytest>=9.1.1; extra == "dev"
34
+ Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
35
+ Requires-Dist: ruff>=0.15.20; extra == "dev"
36
+ Requires-Dist: twine>=6.2.0; extra == "dev"
37
+ Dynamic: license-file
38
+
39
+ [![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)
40
+ [![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)
41
+ [![PyPI Version](https://badge.fury.io/py/pyworkforce.svg)](https://pypi.org/project/pyworkforce/)
42
+ [![Python Version](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/downloads/)
43
+ [![Docs](https://img.shields.io/badge/docs-pyworkforce.rodrigo--arenas.com-blue)](https://pyworkforce.rodrigo-arenas.com/stable/)
44
+
45
+ # pyworkforce
46
+
47
+ **Practical workforce planning in Python: queue staffing, shift scheduling, rostering, and breaks.**
48
+
49
+ pyworkforce helps teams turn variable demand into staffing decisions with a friendly,
50
+ scikit-learn-like API. It combines Erlang queueing models and OR-Tools
51
+ constraint programming so workforce analysts, data scientists, operations
52
+ researchers, and Python developers can move from forecast volumes to workable
53
+ staffing plans without building every solver from scratch.
54
+
55
+ It is useful for contact centers and call centers, but the same patterns apply
56
+ to healthcare staffing, retail operations, logistics, support teams, service
57
+ desks, and field operations.
58
+
59
+ **Docs:** [pyworkforce.rodrigo-arenas.com](https://pyworkforce.rodrigo-arenas.com/stable/)
60
+ **Package:** [PyPI](https://pypi.org/project/pyworkforce/)
61
+ **Examples:** [examples/](examples/)
62
+
63
+ ## Why pyworkforce?
64
+
65
+ - **More practical than spreadsheets:** reusable models, scenario sweeps, tested
66
+ calculations, and outputs that fit naturally into pandas workflows.
67
+ - **Faster than custom scripts:** common workforce planning steps are packaged
68
+ behind consistent constructors, `solve()` methods, validation, and clear
69
+ result dictionaries.
70
+ - **Lighter than enterprise WFM tools:** use it inside notebooks, pipelines,
71
+ internal apps, simulations, or decision-support workflows without adopting a
72
+ full platform.
73
+ - **Built on proven methods:** Erlang C, Erlang A, and Erlang B for queue
74
+ staffing; OR-Tools CP-SAT for scheduling, rostering, and break placement.
75
+ - **Designed for adoption:** small examples, copy-paste tutorials, and APIs that
76
+ feel familiar to Python users.
77
+
78
+ ## Installation
79
+
80
+ ```bash
81
+ pip install pyworkforce
82
+ ```
83
+
84
+ pyworkforce supports Python 3.12, 3.13, and 3.14.
85
+
86
+ Install the plotting extra to explore coverage and Erlang C staffing curves
87
+ with Matplotlib:
88
+
89
+ ```bash
90
+ pip install "pyworkforce[plot]"
91
+ ```
92
+
93
+ The [schedule stress-test tutorial](https://pyworkforce.rodrigo-arenas.com/stable/guide/coverage-scenarios)
94
+ shows how to set staffing limits by shift and compare a solved plan against
95
+ multiple demand forecasts. The [Erlang C staffing curve tutorial](https://pyworkforce.rodrigo-arenas.com/stable/guide/staffing-curve)
96
+ shows how to choose a headcount against service and occupancy targets.
97
+
98
+ ## Planning pipeline
99
+
100
+ ```text
101
+ Forecast demand -> Queue staffing -> Multi-skill staffing -> Shift scheduling -> Rostering -> Break scheduling
102
+ ```
103
+
104
+ ![Planning pipeline](https://raw.githubusercontent.com/rodrigo-arenas/pyworkforce/main/docs/images/planning_pipeline.svg)
105
+
106
+ | Step | Module | Typical question |
107
+ | --- | --- | --- |
108
+ | Queue staffing | `pyworkforce.queuing` | How many agents or channels do we need for a service target? |
109
+ | Multi-skill staffing | `pyworkforce.staffing` | What skill-profile mix covers all queues at minimum cost? |
110
+ | Shift scheduling | `pyworkforce.scheduling` | How many people should work each shift? |
111
+ | Rostering | `pyworkforce.rostering` | Which named people work on which days and shifts? |
112
+ | Break scheduling | `pyworkforce.breaks` | When can breaks happen without dropping below coverage? |
113
+
114
+ ## What can I do in 5 minutes?
115
+
116
+ ### Size a contact-center queue with Erlang C
117
+
118
+ ```python
119
+ from pyworkforce.queuing import ErlangC
120
+
121
+ erlang = ErlangC(
122
+ transactions=100, # calls in the interval
123
+ aht=3, # average handle time, minutes
124
+ asa=20 / 60, # answer-time target, minutes
125
+ interval=30, # interval length, minutes
126
+ shrinkage=0.30,
127
+ )
128
+
129
+ print(erlang.required_positions(service_level=0.80, max_occupancy=0.85))
130
+ ```
131
+
132
+ ```text
133
+ {'raw_positions': 14,
134
+ 'positions': 20,
135
+ 'service_level': 0.8883500191794669,
136
+ 'occupancy': 0.7142857142857143,
137
+ 'waiting_probability': 0.1741319335950498}
138
+ ```
139
+
140
+ `raw_positions` is productive staffing. `positions` adds shrinkage for breaks,
141
+ training, meetings, and other unavailable time.
142
+
143
+ ### Compare staffing scenarios
144
+
145
+ ```python
146
+ from pyworkforce.queuing import MultiErlangC
147
+ from pyworkforce.utils import results_to_dataframe
148
+
149
+ param_grid = {
150
+ "transactions": [80, 100, 120],
151
+ "aht": [3],
152
+ "asa": [20 / 60],
153
+ "interval": [30],
154
+ "shrinkage": [0.20, 0.30],
155
+ }
156
+
157
+ multi = MultiErlangC(param_grid=param_grid, n_jobs=-1)
158
+ results = multi.required_positions({"service_level": [0.80], "max_occupancy": [0.85]})
159
+ df = results_to_dataframe(results, multi.required_positions_params)
160
+ print(df[["transactions", "shrinkage", "positions", "service_level"]])
161
+ ```
162
+
163
+ Use this pattern to compare service levels, shrinkage assumptions, average
164
+ handle time, patience, or arrival forecasts.
165
+
166
+ ### Build shift coverage from clock hours
167
+
168
+ ```python
169
+ from pyworkforce.shifts import shift_coverage_from_hours
170
+
171
+ shifts_coverage = shift_coverage_from_hours(
172
+ {
173
+ "Morning": (6, 14),
174
+ "Afternoon": (14, 22),
175
+ "Night": (22, 6), # wraps past midnight
176
+ },
177
+ num_periods=24,
178
+ )
179
+ ```
180
+
181
+ The result feeds the scheduling solvers directly, avoiding hand-written 0/1
182
+ coverage arrays.
183
+
184
+ ## Main capabilities
185
+
186
+ | Capability | Use it when | Start here |
187
+ | --- | --- | --- |
188
+ | Erlang C staffing | Callers wait and abandonment is ignored or negligible | [Erlang C guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/erlangc) |
189
+ | Erlang A staffing | Callers may abandon before being answered | [Erlang A guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/erlanga) |
190
+ | Erlang B channel sizing | Blocked calls are lost because there is no queue | [Erlang B guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/erlangb) |
191
+ | Multi-skill staffing | Agents can cover different skill combinations | [Staffing guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/staffing) |
192
+ | Shift scheduling | You need shift counts from hourly demand | [Scheduling guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/scheduling) |
193
+ | Employee rostering | You need named assignments with rules and preferences | [Rostering guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/rostering) |
194
+ | Break scheduling | You need meal/rest breaks while maintaining coverage | [Break guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/breaks) |
195
+
196
+ ## Project status
197
+
198
+ pyworkforce is beta-stage open source software. The core models are tested and
199
+ usable for real planning experiments, but workforce policies vary by operation,
200
+ country, and labor agreement. Validate assumptions, units, and constraints
201
+ against your own environment before using results operationally.
202
+
203
+ ## Documentation
204
+
205
+ - [Get Started](https://pyworkforce.rodrigo-arenas.com/stable/guide/introduction)
206
+ - [Quick Start](https://pyworkforce.rodrigo-arenas.com/stable/guide/quickstart)
207
+ - [End-to-end planning tutorial](https://pyworkforce.rodrigo-arenas.com/stable/guide/end-to-end)
208
+ - [Recipes](https://pyworkforce.rodrigo-arenas.com/stable/recipes/)
209
+ - [API Reference](https://pyworkforce.rodrigo-arenas.com/stable/api/queuing)
210
+ - [Release Notes](https://pyworkforce.rodrigo-arenas.com/stable/release-notes)
211
+
212
+ ## Contributing
213
+
214
+ Contributions are welcome: examples, documentation, validation improvements,
215
+ benchmarks, visualization helpers, additional workforce constraints, and bug
216
+ reports all help. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup,
217
+ tests, docs, and roadmap ideas.
218
+
219
+ ## License
220
+
221
+ pyworkforce is released under the [MIT License](LICENSE).
@@ -0,0 +1,183 @@
1
+ [![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)
2
+ [![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)
3
+ [![PyPI Version](https://badge.fury.io/py/pyworkforce.svg)](https://pypi.org/project/pyworkforce/)
4
+ [![Python Version](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/downloads/)
5
+ [![Docs](https://img.shields.io/badge/docs-pyworkforce.rodrigo--arenas.com-blue)](https://pyworkforce.rodrigo-arenas.com/stable/)
6
+
7
+ # pyworkforce
8
+
9
+ **Practical workforce planning in Python: queue staffing, shift scheduling, rostering, and breaks.**
10
+
11
+ pyworkforce helps teams turn variable demand into staffing decisions with a friendly,
12
+ scikit-learn-like API. It combines Erlang queueing models and OR-Tools
13
+ constraint programming so workforce analysts, data scientists, operations
14
+ researchers, and Python developers can move from forecast volumes to workable
15
+ staffing plans without building every solver from scratch.
16
+
17
+ It is useful for contact centers and call centers, but the same patterns apply
18
+ to healthcare staffing, retail operations, logistics, support teams, service
19
+ desks, and field operations.
20
+
21
+ **Docs:** [pyworkforce.rodrigo-arenas.com](https://pyworkforce.rodrigo-arenas.com/stable/)
22
+ **Package:** [PyPI](https://pypi.org/project/pyworkforce/)
23
+ **Examples:** [examples/](examples/)
24
+
25
+ ## Why pyworkforce?
26
+
27
+ - **More practical than spreadsheets:** reusable models, scenario sweeps, tested
28
+ calculations, and outputs that fit naturally into pandas workflows.
29
+ - **Faster than custom scripts:** common workforce planning steps are packaged
30
+ behind consistent constructors, `solve()` methods, validation, and clear
31
+ result dictionaries.
32
+ - **Lighter than enterprise WFM tools:** use it inside notebooks, pipelines,
33
+ internal apps, simulations, or decision-support workflows without adopting a
34
+ full platform.
35
+ - **Built on proven methods:** Erlang C, Erlang A, and Erlang B for queue
36
+ staffing; OR-Tools CP-SAT for scheduling, rostering, and break placement.
37
+ - **Designed for adoption:** small examples, copy-paste tutorials, and APIs that
38
+ feel familiar to Python users.
39
+
40
+ ## Installation
41
+
42
+ ```bash
43
+ pip install pyworkforce
44
+ ```
45
+
46
+ pyworkforce supports Python 3.12, 3.13, and 3.14.
47
+
48
+ Install the plotting extra to explore coverage and Erlang C staffing curves
49
+ with Matplotlib:
50
+
51
+ ```bash
52
+ pip install "pyworkforce[plot]"
53
+ ```
54
+
55
+ The [schedule stress-test tutorial](https://pyworkforce.rodrigo-arenas.com/stable/guide/coverage-scenarios)
56
+ shows how to set staffing limits by shift and compare a solved plan against
57
+ multiple demand forecasts. The [Erlang C staffing curve tutorial](https://pyworkforce.rodrigo-arenas.com/stable/guide/staffing-curve)
58
+ shows how to choose a headcount against service and occupancy targets.
59
+
60
+ ## Planning pipeline
61
+
62
+ ```text
63
+ Forecast demand -> Queue staffing -> Multi-skill staffing -> Shift scheduling -> Rostering -> Break scheduling
64
+ ```
65
+
66
+ ![Planning pipeline](https://raw.githubusercontent.com/rodrigo-arenas/pyworkforce/main/docs/images/planning_pipeline.svg)
67
+
68
+ | Step | Module | Typical question |
69
+ | --- | --- | --- |
70
+ | Queue staffing | `pyworkforce.queuing` | How many agents or channels do we need for a service target? |
71
+ | Multi-skill staffing | `pyworkforce.staffing` | What skill-profile mix covers all queues at minimum cost? |
72
+ | Shift scheduling | `pyworkforce.scheduling` | How many people should work each shift? |
73
+ | Rostering | `pyworkforce.rostering` | Which named people work on which days and shifts? |
74
+ | Break scheduling | `pyworkforce.breaks` | When can breaks happen without dropping below coverage? |
75
+
76
+ ## What can I do in 5 minutes?
77
+
78
+ ### Size a contact-center queue with Erlang C
79
+
80
+ ```python
81
+ from pyworkforce.queuing import ErlangC
82
+
83
+ erlang = ErlangC(
84
+ transactions=100, # calls in the interval
85
+ aht=3, # average handle time, minutes
86
+ asa=20 / 60, # answer-time target, minutes
87
+ interval=30, # interval length, minutes
88
+ shrinkage=0.30,
89
+ )
90
+
91
+ print(erlang.required_positions(service_level=0.80, max_occupancy=0.85))
92
+ ```
93
+
94
+ ```text
95
+ {'raw_positions': 14,
96
+ 'positions': 20,
97
+ 'service_level': 0.8883500191794669,
98
+ 'occupancy': 0.7142857142857143,
99
+ 'waiting_probability': 0.1741319335950498}
100
+ ```
101
+
102
+ `raw_positions` is productive staffing. `positions` adds shrinkage for breaks,
103
+ training, meetings, and other unavailable time.
104
+
105
+ ### Compare staffing scenarios
106
+
107
+ ```python
108
+ from pyworkforce.queuing import MultiErlangC
109
+ from pyworkforce.utils import results_to_dataframe
110
+
111
+ param_grid = {
112
+ "transactions": [80, 100, 120],
113
+ "aht": [3],
114
+ "asa": [20 / 60],
115
+ "interval": [30],
116
+ "shrinkage": [0.20, 0.30],
117
+ }
118
+
119
+ multi = MultiErlangC(param_grid=param_grid, n_jobs=-1)
120
+ results = multi.required_positions({"service_level": [0.80], "max_occupancy": [0.85]})
121
+ df = results_to_dataframe(results, multi.required_positions_params)
122
+ print(df[["transactions", "shrinkage", "positions", "service_level"]])
123
+ ```
124
+
125
+ Use this pattern to compare service levels, shrinkage assumptions, average
126
+ handle time, patience, or arrival forecasts.
127
+
128
+ ### Build shift coverage from clock hours
129
+
130
+ ```python
131
+ from pyworkforce.shifts import shift_coverage_from_hours
132
+
133
+ shifts_coverage = shift_coverage_from_hours(
134
+ {
135
+ "Morning": (6, 14),
136
+ "Afternoon": (14, 22),
137
+ "Night": (22, 6), # wraps past midnight
138
+ },
139
+ num_periods=24,
140
+ )
141
+ ```
142
+
143
+ The result feeds the scheduling solvers directly, avoiding hand-written 0/1
144
+ coverage arrays.
145
+
146
+ ## Main capabilities
147
+
148
+ | Capability | Use it when | Start here |
149
+ | --- | --- | --- |
150
+ | Erlang C staffing | Callers wait and abandonment is ignored or negligible | [Erlang C guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/erlangc) |
151
+ | Erlang A staffing | Callers may abandon before being answered | [Erlang A guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/erlanga) |
152
+ | Erlang B channel sizing | Blocked calls are lost because there is no queue | [Erlang B guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/erlangb) |
153
+ | Multi-skill staffing | Agents can cover different skill combinations | [Staffing guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/staffing) |
154
+ | Shift scheduling | You need shift counts from hourly demand | [Scheduling guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/scheduling) |
155
+ | Employee rostering | You need named assignments with rules and preferences | [Rostering guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/rostering) |
156
+ | Break scheduling | You need meal/rest breaks while maintaining coverage | [Break guide](https://pyworkforce.rodrigo-arenas.com/stable/guide/breaks) |
157
+
158
+ ## Project status
159
+
160
+ pyworkforce is beta-stage open source software. The core models are tested and
161
+ usable for real planning experiments, but workforce policies vary by operation,
162
+ country, and labor agreement. Validate assumptions, units, and constraints
163
+ against your own environment before using results operationally.
164
+
165
+ ## Documentation
166
+
167
+ - [Get Started](https://pyworkforce.rodrigo-arenas.com/stable/guide/introduction)
168
+ - [Quick Start](https://pyworkforce.rodrigo-arenas.com/stable/guide/quickstart)
169
+ - [End-to-end planning tutorial](https://pyworkforce.rodrigo-arenas.com/stable/guide/end-to-end)
170
+ - [Recipes](https://pyworkforce.rodrigo-arenas.com/stable/recipes/)
171
+ - [API Reference](https://pyworkforce.rodrigo-arenas.com/stable/api/queuing)
172
+ - [Release Notes](https://pyworkforce.rodrigo-arenas.com/stable/release-notes)
173
+
174
+ ## Contributing
175
+
176
+ Contributions are welcome: examples, documentation, validation improvements,
177
+ benchmarks, visualization helpers, additional workforce constraints, and bug
178
+ reports all help. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup,
179
+ tests, docs, and roadmap ideas.
180
+
181
+ ## License
182
+
183
+ pyworkforce is released under the [MIT License](LICENSE).
@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
5
5
  [project]
6
6
  name = "pyworkforce"
7
7
  dynamic = ["version"]
8
- description = "Common tools for workforce management, queuing, scheduling, rostering and optimization problems"
8
+ description = "Practical workforce planning tools for queue staffing, shift scheduling, rostering, breaks, and operations research in Python"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12,<3.15"
11
11
  license = "MIT"
@@ -15,11 +15,21 @@ authors = [
15
15
  ]
16
16
  keywords = [
17
17
  "workforce management",
18
+ "workforce planning",
18
19
  "call center",
20
+ "contact center",
21
+ "call center staffing",
22
+ "contact center staffing",
19
23
  "erlang",
24
+ "erlang c",
25
+ "erlang a",
26
+ "erlang b",
20
27
  "scheduling",
28
+ "shift scheduling",
21
29
  "rostering",
30
+ "employee rostering",
22
31
  "operations research",
32
+ "or-tools",
23
33
  "optimization",
24
34
  ]
25
35
  classifiers = [
@@ -27,6 +37,8 @@ classifiers = [
27
37
  "Intended Audience :: Science/Research",
28
38
  "Intended Audience :: Developers",
29
39
  "Topic :: Scientific/Engineering",
40
+ "Topic :: Scientific/Engineering :: Mathematics",
41
+ "Topic :: Office/Business :: Scheduling",
30
42
  "Operating System :: OS Independent",
31
43
  "Programming Language :: Python :: 3",
32
44
  "Programming Language :: Python :: 3.12",
@@ -41,6 +53,7 @@ dependencies = [
41
53
  ]
42
54
 
43
55
  [project.optional-dependencies]
56
+ plot = ["matplotlib>=3.8"]
44
57
  dev = [
45
58
  "pytest>=9.1.1",
46
59
  "pytest-cov>=7.1.0",
@@ -49,10 +62,10 @@ dev = [
49
62
  ]
50
63
 
51
64
  [project.urls]
52
- Documentation = "https://rodrigo-arenas.github.io/pyworkforce/"
65
+ Documentation = "https://pyworkforce.rodrigo-arenas.com/"
53
66
  "Source Code" = "https://github.com/rodrigo-arenas/pyworkforce"
54
67
  "Bug Tracker" = "https://github.com/rodrigo-arenas/pyworkforce/issues"
55
- Changelog = "https://rodrigo-arenas.github.io/pyworkforce/release-notes"
68
+ Changelog = "https://pyworkforce.rodrigo-arenas.com/stable/release-notes"
56
69
 
57
70
  [tool.setuptools]
58
71
  include-package-data = true
@@ -0,0 +1 @@
1
+ __version__ = "0.6.0"
@@ -0,0 +1,73 @@
1
+ """Optional Matplotlib charts for inspecting workforce plans and queue staffing."""
2
+
3
+ import numpy as np
4
+
5
+ __all__ = ["plot_coverage", "plot_staffing_curve"]
6
+
7
+
8
+ def _axes(ax):
9
+ if ax is not None:
10
+ return ax
11
+ try:
12
+ from matplotlib import pyplot as plt
13
+ except ModuleNotFoundError as exc:
14
+ if exc.name != "matplotlib":
15
+ raise
16
+ raise ImportError("Plotting requires Matplotlib. Install pyworkforce[plot].") from exc
17
+ return plt.subplots(layout="constrained")[1]
18
+
19
+
20
+ def plot_coverage(coverage, *, day=0, ax=None):
21
+ """Plot one day from a scheduler's ``coverage()`` DataFrame.
22
+
23
+ Demand and scheduled staffing are drawn as steps. Shading marks shortfalls
24
+ over the full period, including the final interval. Supply a Matplotlib
25
+ Axes to compose charts. Returns the Axes and leaves display to the caller.
26
+ """
27
+ intervals = coverage.loc[coverage["day"] == day].sort_values("period")
28
+ if intervals.empty:
29
+ raise ValueError(f"coverage has no rows for day {day}")
30
+ periods = intervals["period"].to_numpy()
31
+ edges = np.append(periods, periods[-1] + 1)
32
+ required = intervals["required"].to_numpy()
33
+ scheduled = intervals["scheduled"].to_numpy()
34
+ ax = _axes(ax)
35
+ from matplotlib.ticker import MaxNLocator
36
+
37
+ ax.stairs(required, edges, baseline=None, label="Required", color="#25304b", linestyle="--", linewidth=1.8)
38
+ ax.stairs(scheduled, edges, baseline=None, label="Scheduled", color="#3451b2", linewidth=2.2)
39
+ if (scheduled < required).any():
40
+ shortfall_top = np.maximum(required, scheduled)
41
+ ax.fill_between(
42
+ edges, np.append(scheduled, scheduled[-1]), np.append(shortfall_top, shortfall_top[-1]),
43
+ step="post", color="#d0673d", alpha=0.25, label="Shortfall",
44
+ )
45
+ ax.set(title=f"Coverage · day {day}", xlabel="Period boundary", ylabel="People", xlim=(edges[0], edges[-1]))
46
+ ax.xaxis.set_major_locator(MaxNLocator(integer=True))
47
+ ax.yaxis.set_major_locator(MaxNLocator(integer=True))
48
+ ax.set_ylim(bottom=0)
49
+ ax.grid(axis="y", alpha=0.2)
50
+ ax.legend()
51
+ return ax
52
+
53
+
54
+ def plot_staffing_curve(curve, *, ax=None):
55
+ """Plot achieved service level and occupancy from ``ErlangC.staffing_curve()``.
56
+
57
+ Headcounts are drawn in ascending order. Supply a Matplotlib Axes to compose
58
+ charts. Returns the Axes and leaves display to the caller.
59
+ """
60
+ if curve.empty:
61
+ raise ValueError("staffing curve must contain at least one candidate")
62
+ ordered = curve.sort_values("positions")
63
+ ax = _axes(ax)
64
+ from matplotlib.ticker import MaxNLocator, PercentFormatter
65
+
66
+ ax.plot(ordered["positions"], ordered["service_level"], label="Service level", color="#3451b2", marker="o")
67
+ ax.plot(ordered["positions"], ordered["occupancy"], label="Occupancy", color="#a24d32", marker="s", linestyle="--")
68
+ ax.set(title="Erlang C staffing trade-off", xlabel="Positions", ylabel="Rate", ylim=(0, 1.05))
69
+ ax.xaxis.set_major_locator(MaxNLocator(integer=True))
70
+ ax.yaxis.set_major_formatter(PercentFormatter(xmax=1))
71
+ ax.grid(axis="y", alpha=0.2)
72
+ ax.legend()
73
+ return ax
@@ -1,10 +1,11 @@
1
+ from fractions import Fraction
1
2
  from math import ceil, exp, floor
2
3
 
3
4
  from joblib import Parallel, delayed
4
5
 
5
6
  from pyworkforce.base import BaseWorkforce
6
7
  from pyworkforce.utils import ParameterGrid
7
- from pyworkforce.utils.validation import check_in_range, check_positive_float
8
+ from pyworkforce.utils.validation import check_in_range, check_positive_float, check_positive_integer
8
9
 
9
10
 
10
11
  class ErlangC(BaseWorkforce):
@@ -65,9 +66,13 @@ class ErlangC(BaseWorkforce):
65
66
  def n_transactions(self):
66
67
  return self.transactions
67
68
 
69
+ def _available_fraction(self):
70
+ # Keep decimal shrinkage exact at whole-headcount boundaries.
71
+ return 1 - Fraction(str(self.shrinkage))
72
+
68
73
  def _productive_positions(self, positions: int, scale_positions: bool = False):
69
74
  if scale_positions:
70
- productive_positions = floor((1 - self.shrinkage) * positions)
75
+ productive_positions = floor(self._available_fraction() * Fraction(str(positions)))
71
76
  else:
72
77
  productive_positions = positions
73
78
 
@@ -119,6 +124,9 @@ class ErlangC(BaseWorkforce):
119
124
  productive_positions = self._productive_positions(positions, scale_positions)
120
125
 
121
126
  probability_wait = self.waiting_probability(productive_positions, scale_positions=False)
127
+ return self._service_level_from_wait(productive_positions, probability_wait)
128
+
129
+ def _service_level_from_wait(self, productive_positions, probability_wait):
122
130
  exponential = exp(-(productive_positions - self.intensity) * (self.asa / self.aht))
123
131
  return max(0, 1 - (probability_wait * exponential))
124
132
 
@@ -140,6 +148,34 @@ class ErlangC(BaseWorkforce):
140
148
 
141
149
  return self.intensity / productive_positions
142
150
 
151
+ def staffing_curve(self, positions, *, scale_positions=False):
152
+ """Return a DataFrame of service and occupancy metrics by candidate headcount.
153
+
154
+ ``positions`` is a non-empty iterable of positive integers in the order
155
+ to report. Set ``scale_positions=True`` to evaluate scheduled headcounts
156
+ after subtracting shrinkage. The frame includes both the input count
157
+ (``positions``) and the productive count (``raw_positions``).
158
+ Candidates whose productive count cannot support the offered load raise
159
+ ``ValueError``. Probabilities and occupancy are fractions in [0, 1].
160
+ """
161
+ import pandas as pd
162
+
163
+ rows = []
164
+ for headcount in positions:
165
+ check_positive_integer("positions", headcount)
166
+ raw = self._productive_positions(headcount, scale_positions)
167
+ waiting = self.waiting_probability(raw)
168
+ rows.append({
169
+ "positions": headcount,
170
+ "raw_positions": raw,
171
+ "service_level": self._service_level_from_wait(raw, waiting),
172
+ "occupancy": self.intensity / raw,
173
+ "waiting_probability": waiting,
174
+ })
175
+ if not rows:
176
+ raise ValueError("positions must contain at least one headcount")
177
+ return pd.DataFrame(rows)
178
+
143
179
  def required_positions(self, service_level: float, max_occupancy: float = 1.0):
144
180
  """
145
181
  Computes the required positions for a target service level.
@@ -187,7 +223,7 @@ class ErlangC(BaseWorkforce):
187
223
  achieved_service_level = self.service_level(raw_positions)
188
224
 
189
225
  waiting_probability = self.waiting_probability(positions=raw_positions)
190
- positions = ceil(raw_positions / (1 - self.shrinkage))
226
+ positions = ceil(raw_positions / self._available_fraction())
191
227
 
192
228
  return {"raw_positions": raw_positions,
193
229
  "positions": positions,
@@ -3,6 +3,34 @@ import pytest
3
3
  from pyworkforce.queuing import ErlangC
4
4
 
5
5
 
6
+ def test_staffing_curve_reports_metrics_at_each_scheduled_headcount():
7
+ erlang = ErlangC(transactions=100, asa=20 / 60, aht=3, interval=30, shrinkage=0.3)
8
+ curve = erlang.staffing_curve([19, 20], scale_positions=True)
9
+ assert list(curve.columns) == ['positions', 'raw_positions', 'service_level', 'occupancy', 'waiting_probability']
10
+ assert curve['positions'].tolist() == [19, 20]
11
+ assert curve['raw_positions'].tolist() == [13, 14]
12
+ assert curve['service_level'].tolist() == pytest.approx([0.7956, 0.8884], abs=0.0001)
13
+ assert curve['occupancy'].tolist() == pytest.approx([10 / 13, 10 / 14])
14
+ assert curve['waiting_probability'].tolist() == pytest.approx([0.28526988, 0.17413193], abs=0.0001)
15
+ assert erlang.staffing_curve([14]).iloc[0]['raw_positions'] == 14
16
+
17
+
18
+ @pytest.mark.parametrize(('positions', 'message'), [([], 'at least one'), ([True], 'positive integer'), ([10], 'traffic intensity')])
19
+ def test_staffing_curve_rejects_missing_invalid_or_unstable_headcount(positions, message):
20
+ erlang = ErlangC(transactions=100, asa=20 / 60, aht=3, interval=30)
21
+ with pytest.raises(ValueError, match=message):
22
+ erlang.staffing_curve(positions)
23
+
24
+
25
+ def test_shrinkage_preserves_exact_headcount_boundaries():
26
+ erlang = ErlangC(transactions=25, aht=1, asa=0.5, interval=20, shrinkage=0.8)
27
+ target = erlang.service_level(2)
28
+ row = erlang.staffing_curve([10], scale_positions=True).iloc[0]
29
+ assert row['raw_positions'] == 2
30
+ assert row['service_level'] == pytest.approx(target)
31
+ assert erlang.required_positions(service_level=target)['positions'] == 10
32
+
33
+
6
34
  def test_expected_erlangc_results():
7
35
  erlang = ErlangC(transactions=100, asa=0.33, aht=3, interval=30, shrinkage=0.3)
8
36
  results = erlang.required_positions(service_level=0.8, max_occupancy=0.85)