turbotab 0.5.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 --calls-per-interval 25 --aht 180 --shrinkage 0.30 --json

JSON output is the stable agent contract:

{
  "schema_version": "2.0",
  "calculation": "staffing.required",
  "inputs": {
    "aht": 180,
    "calls_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.0; all other commands keep their single-value 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 call volume uses calls_per_interval, not calls per hour by default.

For hourly semantics, pass --interval 3600:

turbotab staffing required --sla 0.80 --service-time 20 --calls-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 --calls-per-interval 25 --aht 180 --shrinkage 0.30 --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

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.

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.

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,
    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

Project-specific exceptions live in exceptions.py:

Example:

from mod_turbotab.exceptions import CalculationError, InputValidationError

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