mod-turbotab

mod_turbotab

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

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.

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`
`agents.capacity`	`agents_required`, `asa`, `agents_asa`, `nb_agents`, `call_capacity`, `fractional_agents`, `fractional_call_capacity`
`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,
)

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.
Shrinkage, absenteeism, occupancy caps, and intraday simulation are tracked as future work in coming_soon/.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mod_turbotab-0.1.0.tar.gz (56.0 kB view details)

Uploaded Jul 23, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

mod_turbotab-0.1.0-py3-none-any.whl (43.3 kB view details)

Uploaded Jul 23, 2026 Python 3

File details

Details for the file mod_turbotab-0.1.0.tar.gz.

File metadata

Download URL: mod_turbotab-0.1.0.tar.gz
Upload date: Jul 23, 2026
Size: 56.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for mod_turbotab-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`372efcecc61b6895e726422df0be15b9e31ac2bc5a1db2334636cca03a1304be`
MD5	`2d568ae1f3fda020a4a84e15b2157310`
BLAKE2b-256	`136ab08fb58dd9fcc8fba87887cdb39c0ed97ad16efb32a016845f703891bb7e`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mod_turbotab-0.1.0.tar.gz:

Publisher: publish.yml on gstvbatista/mod_turbotab

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: mod_turbotab-0.1.0.tar.gz
- Subject digest: 372efcecc61b6895e726422df0be15b9e31ac2bc5a1db2334636cca03a1304be
- Sigstore transparency entry: 2226333544
- Sigstore integration time: Jul 23, 2026
Source repository:
- Permalink: gstvbatista/mod_turbotab@e102528c46cbd95a8cd7a3ffa32d424efe2c955b
- Branch / Tag: refs/heads/main
- Owner: https://github.com/gstvbatista
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@e102528c46cbd95a8cd7a3ffa32d424efe2c955b
- Trigger Event: workflow_dispatch

File details

Details for the file mod_turbotab-0.1.0-py3-none-any.whl.

File metadata

Download URL: mod_turbotab-0.1.0-py3-none-any.whl
Upload date: Jul 23, 2026
Size: 43.3 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for mod_turbotab-0.1.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`af74e068f909ae563adf6921cc3fbe4bc1ff4913137f031e68d0ec5ad958f215`
MD5	`6074a4c8c25cd98765cf209eb140803a`
BLAKE2b-256	`e3cd07ff3d800b5fb256d281cd0dcd77bc4fde48ee7b3e14f3d503ea82f1180c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mod_turbotab-0.1.0-py3-none-any.whl:

Publisher: publish.yml on gstvbatista/mod_turbotab

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: mod_turbotab-0.1.0-py3-none-any.whl
- Subject digest: af74e068f909ae563adf6921cc3fbe4bc1ff4913137f031e68d0ec5ad958f215
- Sigstore transparency entry: 2226334063
- Sigstore integration time: Jul 23, 2026
Source repository:
- Permalink: gstvbatista/mod_turbotab@e102528c46cbd95a8cd7a3ffa32d424efe2c955b
- Branch / Tag: refs/heads/main
- Owner: https://github.com/gstvbatista
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@e102528c46cbd95a8cd7a3ffa32d424efe2c955b
- Trigger Event: workflow_dispatch

Release history Release notifications | RSS feed

This release

0.1.0

Jul 23, 2026

mod-turbotab 0.1.0

Why

Quick Start

CLI

Limitations

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed