turbotab 0.8.0

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 --contacts-per-interval 25 --aht 180 --shrinkage 0.30 --json

JSON output is the stable agent contract:

{
  "schema_version": "2.2",
  "calculation": "staffing.required",
  "inputs": {
    "aht": 180,
    "contacts_per_interval": 25.0,
    "interval": 600.0,
    "service_time": 20,
    "shrinkage": 0.3,
    "sla": 0.8
  },
  "result": {
    "name": "headcount",
    "unit": "agents",
    "value": {
      "productive_agents": 11,
      "scheduled_agents": 16
    }
  }
}

staffing required and staffing fractional-required emit the headcount chain under schema_version 2.2 (2.1 plus the optional rostered_agents field, present only when --shifts is passed); commands whose inputs or result fields were renamed by the contacts terminology sweep use 1.1; unaffected raw-formula commands (erlang, traffic intensity, trunks number) keep the original 1.0 payloads.

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

This project uses interval-based planning buckets.

Every function or CLI command that accepts contact volume uses contacts_per_interval, not contacts per hour by default.

For hourly semantics, pass --interval 3600:

turbotab staffing required --sla 0.80 --service-time 20 --contacts-per-interval 150 --aht 180 --interval 3600 --shrinkage 0 --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.

With the default 10-minute bucket:

CLI:

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

The queue metrics (sla achieved, queue wait, telecom trunks) take the productive agents — shrinkage covers who is off the phones, not queue behavior.

Expected headline results:

Python API equivalent:

from mod_turbotab.agents.capacity import agents_required
from mod_turbotab.agents.shrinkage import scheduled_agents

productive = agents_required(0.80, 20, 25, 180)
scheduled = scheduled_agents(productive, 0.30)

print(productive, scheduled)  # 11 16

Notation:

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.

The fractional counterpart (max_occupancy on fractional_agents, or --max-occupancy on staffing fractional-required / agents fractional-required) applies the same floor without rounding, leaving all rounding to the caller:

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

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.

The fractional counterpart (scheduled_fractional_agents) applies the same correction without rounding, for chains built on fractional_agents:

N_{\mathrm{scheduled}}^{\mathrm{frac}} = \frac{N_{\mathrm{phones}}^{\mathrm{frac}}}{1 - S}

On the CLI, S is the mandatory --shrinkage flag of staffing required and staffing fractional-required; both emit the full productive_agents/scheduled_agents chain.

Shift/seat multiplier (rostered_agents): scheduled_agents counts seats per interval; covering the operating day takes more than one operator per seat when shifts are shorter than the day. The multiplier M (operators per seat, M >= 1, fractional allowed) is applied on top of the shrinkage chain, rounding step-wise — seats are made whole before multiplying, which never understaffs relative to rounding once at the end:

N_{\mathrm{rostered}} = \left\lceil N_{\mathrm{scheduled}} \cdot M \right\rceil

The fractional counterpart (rostered_fractional_agents) applies the same multiplier without rounding:

N_{\mathrm{rostered}}^{\mathrm{frac}} = N_{\mathrm{scheduled}}^{\mathrm{frac}} \cdot M

On the CLI, M is the optional --shifts flag of staffing required and staffing fractional-required; when passed, the chain extends to productive_agents/scheduled_agents/rostered_agents. M is not Erlang occupancy (rho_max), even though reference spreadsheets sometimes overload that name for it.

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

Import example:

from mod_turbotab.agents.capacity import agents_required

agents = agents_required(
    sla=0.80,
    service_time=20,
    contacts_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", "contacts_per_interval": 25, "aht": 180},
        {"name": "tech",    "contacts_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,
    contacts_per_interval=25,
    aht=180,
    shrinkage=factor,
)  # 14

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

Shift/seat multiplier example — turning scheduled seats into rostered operators:

from mod_turbotab.agents.roster import rostered_agents

# 6 scheduled seats, 12h operation covered by 6h shifts (2 operators per seat)
rostered_agents(6, 2.0)  # 12

Project-specific exceptions live in exceptions.py:

Example:

from mod_turbotab.exceptions import CalculationError, InputValidationError

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