turbotab 0.4.0

TurboTable-style contact-center planning calculations for Python and CLI workflows.

CLI-first TurboTable-style calculations for contact-center planning.

mod_turbotab keeps the historical name known by call-center planning and traffic analysts, while exposing turbotab as the primary interface for humans, scripts, and AI agents.

turbotab staffing required --sla 0.80 --service-time 20 --calls-per-interval 25 --aht 180 --json

{"calculation": "staffing.required", "inputs": {"aht": 180, "calls_per_interval": 25.0, "interval": 600.0, "service_time": 20, "sla": 0.8}, "result": {"name": "agents", "unit": "agents", "value": 11}, "schema_version": "1.0"}

Why

mod_turbotab answers operational questions that show up constantly in contact-center planning:

Question	Command
How many agents do I need?	turbotab staffing required ...
What SLA will this staffing achieve?	turbotab sla achieved ...
How long will the queue wait be?	turbotab queue wait ...
How many trunks are required?	turbotab telecom trunks ...
What is the Erlang B/C/A result?	turbotab erlang ...

It provides Erlang B, extended Erlang B, Engset B, Erlang C, Erlang A, queue metrics, staffing metrics, call capacity, and telephony trunk sizing with no third-party runtime dependencies.

Quick Start

Required staffing for 80% SLA in 20 seconds:

turbotab staffing required \
  --sla 0.80 \
  --service-time 20 \
  --calls-per-interval 25 \
  --aht 180 \
  --json

Achieved SLA for a fixed staffing level:

turbotab sla achieved \
  --agents 11 \
  --service-time 20 \
  --calls-per-interval 25 \
  --aht 180 \
  --json

Average queue wait:

turbotab queue wait \
  --agents 11 \
  --calls-per-interval 25 \
  --aht 180 \
  --json

Required trunks:

turbotab telecom trunks \
  --agents 11 \
  --calls-per-interval 25 \
  --aht 180 \
  --json

Every command group falls back to contextual help:

turbotab
turbotab sla
turbotab staffing required --help

CLI

Agent-facing commands are intent-first:

turbotab
├── staffing
│   ├── required
│   ├── asa
│   ├── capacity
│   ├── fractional-required
│   └── fractional-capacity
├── sla
│   ├── achieved
│   └── target-time
├── queue
│   ├── wait
│   ├── size
│   └── probability
└── telecom
    └── trunks

Detailed formula/module commands are also available:

turbotab agents ...
turbotab queues ...
turbotab erlang ...
turbotab traffic ...
turbotab trunks ...

Use --json when calling from agents or automation. Invalid inputs exit non-zero and print a concise error to stderr.

Agent usage

Agents should prefer the CLI with --json instead of parsing text output or importing Python internals.

turbotab staffing required --sla 0.80 --service-time 20 --calls-per-interval 25 --aht 180 --json

JSON output is the stable agent contract:

{
  "schema_version": "1.0",
  "calculation": "staffing.required",
  "inputs": {
    "aht": 180,
    "calls_per_interval": 25.0,
    "interval": 600.0,
    "service_time": 20,
    "sla": 0.8
  },
  "result": {
    "name": "agents",
    "unit": "agents",
    "value": 11
  }
}

The bundled skill lives at skills/mod-turbotab/SKILL.md. It includes command recipes, unit rules, and agent guardrails.

Units and assumptions

This project uses interval-based planning buckets.

Every function or CLI command that accepts call volume uses calls_per_interval, not calls per hour by default.

Parameter	Meaning
calls_per_interval / --calls-per-interval	Arrivals in the planning bucket
interval / --interval	Planning bucket in seconds
Default interval	600 seconds, or 10 minutes
aht / --aht	Average handle time in seconds
service_time / --service-time	Target answer time in seconds
sla / --sla	Ratio, for example 0.80 for 80%

For hourly semantics, pass --interval 3600:

turbotab staffing required --sla 0.80 --service-time 20 --calls-per-interval 150 --aht 180 --interval 3600 --json

Traffic intensity is computed as:

A = \frac{\lambda \cdot h}{I}

where A is offered traffic in erlangs, lambda is arrivals per interval, h is AHT in seconds, and I is interval length in seconds.

Worked example

With the default 10-minute bucket:

Input	Value
Calls	25 per 10 minutes
AHT	180 seconds
Target SLA	0.80
Target answer time	20 seconds

CLI:

turbotab staffing required --sla 0.80 --service-time 20 --calls-per-interval 25 --aht 180 --json
turbotab sla achieved --agents 11 --service-time 20 --calls-per-interval 25 --aht 180 --json
turbotab queue wait --agents 11 --calls-per-interval 25 --aht 180 --json
turbotab telecom trunks --agents 11 --calls-per-interval 25 --aht 180 --json

Expected headline results:

Metric	Result
Required agents	11
Achieved SLA	0.880836
Average queue wait	51 seconds
Required trunks	18

Python API equivalent:

from mod_turbotab.agents.capacity import agents_required

print(agents_required(0.80, 20, 25, 180))

Mathematical model

Notation:

Symbol	Meaning
N	Agents, servers, or trunks depending on context
lambda	Arrival volume per configured interval
h	Average handle time in seconds
I	Planning interval in seconds
mu	Service completions per interval per server
A	Offered traffic in erlangs
rho	Utilization
B(N, A)	Erlang B blocking probability
C(N, A)	Erlang C queueing probability
rho_max	Optional occupancy cap (max_occupancy)
s	Multi-skill sharing factor (sharing_factor)
S	Shrinkage factor (shrinkage)

Core conversions:

\mu = \frac{I}{h}

A = \frac{\lambda}{\mu} = \frac{\lambda h}{I}

\rho = \frac{A}{N}

Erlang B recurrence:

B_0 = 1

B_n = \frac{A B_{n-1}}{n + A B_{n-1}}

Erlang C:

C(N, A) = \frac{B(N, A)}{\left(\frac{A}{N}\right) B(N, A) + \left(1 - \frac{A}{N}\right)}

Queue wait:

W_q = \frac{1}{N \mu (1 - \rho)}

SLA:

\mathrm{SLA}(t) = 1 - C(N, A)\exp\left(-\frac{N - A}{h}t\right)

ASA:

\mathrm{ASA} = \frac{C(N, A)}{N \mu (1 - \rho)}

Erlang A extends Erlang C with abandonment through average patience. When patience=None, pure Erlang C is used.

Occupancy cap, when max_occupancy is set on agents_required (or --max-occupancy on the CLI):

N = \max\left(N_{\mathrm{Erlang}},\ \left\lceil \frac{A}{\rho_{\max}} \right\rceil\right)

With max_occupancy=None the cap is skipped and the Erlang result is returned unchanged.

Multi-skill dimensioning (agents_required_multi, Option A): each skill group k is first sized as an independent Erlang C queue, giving N_k^{C}. Skills served by at least one cross-skilled pool then receive the sharing factor s, floored so per-skill utilization stays strictly below 100%:

N_k = \max\left(\left\lceil A_k \right\rceil + 1,\ \left\lceil s \cdot N_k^{C} \right\rceil\right)

Skills served only by dedicated pools keep N_k = N_k^{C}, reproducing the single-skill result.

Shrinkage (scheduled_agents, agents_required_with_shrinkage, Option A): the Erlang result counts agents on the phones; scheduling must also cover breaks, training, meetings, absenteeism and downtime. The standard workforce-management correction is applied post-calculation, leaving the core Erlang math unchanged:

N_{\mathrm{scheduled}} = \left\lceil \frac{N_{\mathrm{phones}}}{1 - S} \right\rceil

S must be in [0, 1) and can be composed from individual components with shrinkage_factor (components are additive slices of paid time off the phones). With S = 0 the result is the unchanged Erlang headcount.

API reference

The CLI is the primary interface, but the Python API remains available.

Module	Public functions
calculations.erlang	erlang_b, erlang_b_ext, engset_b, erlang_c, erlang_a
calculations.traffic	traffic, looping_traffic
calculations.multi_skill	agents_required_multi
agents.capacity	agents_required, asa, agents_asa, nb_agents, call_capacity, fractional_agents, fractional_call_capacity, occupancy, is_within_occupancy
agents.shrinkage	scheduled_agents, shrinkage_factor, agents_required_with_shrinkage
queues.queues	queued, queue_size, queue_time, service_time, sla_metric
trunks.trunks	number_trunks, trunks_required
utils	min_max, int_ceiling, secs

Import example:

from mod_turbotab.agents.capacity import agents_required

agents = agents_required(
    sla=0.80,
    service_time=20,
    calls_per_interval=25,
    aht=180,
)

Multi-skill example — dedicated pools plus a cross-skilled pool sharing billing and tech:

from mod_turbotab.calculations.multi_skill import agents_required_multi

result = agents_required_multi(
    skill_groups=[
        {"name": "billing", "calls_per_interval": 25, "aht": 180},
        {"name": "tech",    "calls_per_interval": 20, "aht": 240},
    ],
    agent_pools=[
        {"skills": ["billing"],         "count": 8},
        {"skills": ["tech"],            "count": 9},
        {"skills": ["billing", "tech"], "count": 6},
    ],
    sla=0.80,
    service_time=20,
)

result["totals"]  # {"naive_total_hc": 22, "adjusted_total_hc": 20, "savings_hc": 2, ...}

Shrinkage example — turning "agents on phones" into "agents to schedule":

from mod_turbotab.agents.shrinkage import (
    agents_required_with_shrinkage,
    scheduled_agents,
    shrinkage_factor,
)

factor = shrinkage_factor(breaks=0.07, training=0.04, absenteeism=0.08)  # 0.19

# One call: Erlang C + shrinkage on top
agents_required_with_shrinkage(
    sla=0.80,
    service_time=20,
    calls_per_interval=25,
    aht=180,
    shrinkage=factor,
)  # 14

# Or compose manually from an existing headcount
scheduled_agents(11, factor)  # 14

Exceptions

Project-specific exceptions live in exceptions.py:

Exception	Meaning
InputValidationError	Invalid argument values
CalculationError	Calculation failed or search could not converge

Example:

from mod_turbotab.exceptions import CalculationError, InputValidationError

try:
    ...
except InputValidationError:
    ...
except CalculationError:
    ...

Limitations

• number_trunks() uses a fixed blocking threshold of 0.001.
• Some zero-value edge cases still return wrapped calculation errors instead of purpose-built validation messages.
• Intraday simulation is tracked as future work — see issues labeled roadmap.