mod-turbotab 0.1.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 --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.

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

Python API equivalent:

from mod_turbotab.agents.capacity import agents_required

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

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.

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

Project-specific exceptions live in exceptions.py:

Example:

from mod_turbotab.exceptions import CalculationError, InputValidationError

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