turbotab 0.2.0

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:

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.

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

{
  "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
  }
}

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

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

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

from mod_turbotab.agents.capacity import agents_required

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

\mu = \frac{I}{h}

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

\rho = \frac{A}{N}

B_0 = 1

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

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

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

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

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

from mod_turbotab.agents.capacity import agents_required

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

from mod_turbotab.exceptions import CalculationError, InputValidationError

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

Occupancy cap

Erlang C alone can recommend staffing levels that drive sustained occupancy above 90%, which is associated with burnout and attrition. agents_required accepts an optional max_occupancy ceiling that lifts the headcount whenever the Erlang result would breach it; defaults are unchanged when the parameter is omitted.

CLI:

turbotab staffing required --sla 0.80 --service-time 20 --calls-per-interval 100 --aht 180 --max-occupancy 0.85 --json
# {"...": "...", "inputs": {"max_occupancy": 0.85, "...": "..."}, "result": {"name": "agents", "unit": "agents", "value": 36}}

Python API:

from mod_turbotab.agents.capacity import (
    agents_required,
    occupancy,
    is_within_occupancy,
)

agents_required(0.80, 20, 25, 180)                          # 11 (no cap)
agents_required(0.80, 20, 25, 180, max_occupancy=0.85)      # 11 (already under 85%)
agents_required(0.80, 20, 100, 180, max_occupancy=0.85)     # 36 (lifted from Erlang result to keep A/N <= 0.85)

occupancy(11, 25, 180)                                      # 0.6818  (A/N)
is_within_occupancy(33, 100, 180, 0.85)                     # False
is_within_occupancy(36, 100, 180, 0.85)                     # True

The cap is max(erlang_c, ceil(A / max_occupancy)) where A = calls_per_interval * aht / interval.

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.
• Shrinkage, absenteeism, and intraday simulation are tracked as future work — see issues labeled roadmap.