Files
tom_analysis_agent/app/operating_model/staffing.py

281 lines
11 KiB
Python

"""Staffing and cost, computed from the Target operating model and the rate card.
No agent writes a number of people or a cost. A Specialist says what each Capability
takes in hours a month, which Roles are responsible for it, and where each Role sits
and at what level. Everything else is arithmetic on the service provider's rate card,
so the figures cannot disagree with the model they are about.
effort the hours a month of the Capabilities a Role is responsible for
people effort over the productive hours of its country; and, where the
Role covers hours wider than a working day, never fewer than the
smallest team that can cover them
cost a month people, at the day rate for its country and level, for the
productive days in a month, with the uplift for its hours, in
the currency the operating spec states
"""
from __future__ import annotations
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from pathlib import Path
from typing import Any
import yaml
from app.operating_model.names import CUSTOMER, HOURS, RESPONSIBLE, wider
SKILL = "rate-card"
BUSINESS = HOURS[0]
class RateCardError(ValueError):
"""A rate card that cannot be used; the message lists every fault."""
@dataclass(frozen=True)
class Country:
name: str
productive_days: float
hours_per_day: float
day_rate: Mapping[str, float]
@property
def productive_hours_a_month(self) -> float:
return self.productive_days * self.hours_per_day / 12
@dataclass(frozen=True)
class RateCard:
name: str
version: str
currency: str # what its rates are written in
conversion: Mapping[str, float] # units of a currency for one of `currency`
conversion_as_of: str
prices: tuple[str, ...] # the kinds of Party it prices
levels: Mapping[str, str]
cover: Mapping[str, Mapping[str, float]] # hours -> minimum_roster, uplift
countries: Mapping[str, Country]
@property
def is_draft(self) -> bool:
return self.version.startswith("draft")
def currencies(self) -> list[str]:
return sorted(self.conversion)
def _number(value: Any) -> bool:
return isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0
def load(skill_dir: Path) -> RateCard:
"""Read the rate card from the Skill's folder, and check it holds together."""
path = skill_dir / "assets" / "rates.yaml"
data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
if not isinstance(data, dict):
raise RateCardError("rates.yaml: must be a mapping")
problems = [
f"rates.yaml: needs {field}"
for field in ("name", "version", "currency", "levels", "cover", "countries")
if not data.get(field)
]
if problems:
raise RateCardError("; ".join(problems))
levels = {str(name): str(text) for name, text in data["levels"].items()}
conversion_data = data.get("conversion") or {}
rates = {str(k): v for k, v in (conversion_data.get("rates") or {}).items()}
rates.setdefault(str(data["currency"]), 1.0)
problems += [
f"rates.yaml: the conversion rate for {name} must be a number above zero"
for name, rate in rates.items()
if not _number(rate)
]
prices = tuple(str(kind) for kind in data.get("prices") or ())
if CUSTOMER in prices:
problems.append(
"rates.yaml: `prices` lists customer; the customer's own staff are "
"never priced"
)
cover = {str(name): dict(entry or {}) for name, entry in data["cover"].items()}
for hours in HOURS:
entry = cover.get(hours) or {}
if not _number(entry.get("minimum_roster")) or not _number(entry.get("uplift")):
problems.append(
f"rates.yaml: cover for {hours} needs a minimum_roster and an "
"uplift, both above zero"
)
countries = {}
for code, entry in data["countries"].items():
entry = entry or {}
where = f"rates.yaml: {code}"
if not _number(entry.get("productive_days")) or not _number(
entry.get("hours_per_day")
):
problems.append(f"{where} needs productive_days and hours_per_day")
continue
day_rate = entry.get("day_rate") or {}
problems += [
f"{where} has no day rate for level {level}"
for level in levels
if not _number(day_rate.get(level))
]
countries[str(code)] = Country(
name=str(entry.get("name") or code),
productive_days=float(entry["productive_days"]),
hours_per_day=float(entry["hours_per_day"]),
day_rate={str(k): float(v) for k, v in day_rate.items() if _number(v)},
)
if problems:
raise RateCardError("; ".join(problems))
return RateCard(
name=str(data["name"]),
version=str(data["version"]),
currency=str(data["currency"]),
conversion={name: float(rate) for name, rate in rates.items()},
conversion_as_of=str(conversion_data.get("as_of") or ""),
prices=prices,
levels=levels,
cover={
name: {
"minimum_roster": float(entry["minimum_roster"]),
"uplift": float(entry["uplift"]),
}
for name, entry in cover.items()
if name in HOURS
},
countries=countries,
)
def shares(
responsibilities: Sequence[Mapping[str, Any]],
) -> tuple[dict[tuple[str, str], float], list[str]]:
"""Each responsible Role's share of each Capability's effort, and what is wrong
with how shares were stated.
The Roles responsible for a Capability divide its effort equally, unless every
one of them states a `share`, and the shares add up to 1.
"""
by_capability: dict[str, list[Mapping[str, Any]]] = {}
for item in responsibilities:
if item.get("kind") == RESPONSIBLE:
by_capability.setdefault(str(item.get("capability")), []).append(item)
result: dict[tuple[str, str], float] = {}
problems = []
for capability, entries in by_capability.items():
stated = [e.get("share") for e in entries if e.get("share") is not None]
if not stated:
for entry in entries:
result[(capability, str(entry.get("role")))] = 1 / len(entries)
continue
valid = all(
isinstance(s, (int, float)) and not isinstance(s, bool) and 0 < s <= 1
for s in stated
)
if len(stated) != len(entries) or not valid:
problems.append(
f"the Roles responsible for {capability} must all state a share "
"between 0 and 1, or none of them"
)
continue
total = sum(float(entry["share"]) for entry in entries)
if abs(total - 1) > 0.001:
problems.append(f"the shares of {capability} do not add up to 1")
continue
for entry in entries:
result[(capability, str(entry.get("role")))] = float(entry["share"])
return result, problems
def compute(
graph: Mapping[str, Any],
capabilities: Sequence[Mapping[str, Any]],
card: RateCard,
currency: str,
) -> dict[str, Any]:
"""People and cost per Role, and the totals. The graph is taken to be sound:
`graph.check` refuses one whose Roles the card cannot price."""
parties = {str(p.get("id")): p for p in graph.get("parties") or []}
effort_of = {
str(c["id"]): float(c.get("effort_hours_per_month") or 0) for c in capabilities
}
hours_of = {str(c["id"]): str(c.get("hours") or BUSINESS) for c in capabilities}
share_of, _ = shares(graph.get("responsibilities") or [])
rate = card.conversion[currency]
rows: list[dict[str, Any]] = []
by_capability: dict[str, float] = {}
for role in graph.get("roles") or []:
role_id = str(role.get("id"))
country = card.countries[str(role.get("country"))]
own = {cap: share for (cap, who), share in share_of.items() if who == role_id}
effort = float(
sum(effort_of.get(cap, 0.0) * share for cap, share in own.items())
)
hours = BUSINESS
for cap in own:
if wider(hours_of.get(cap, BUSINESS), hours):
hours = hours_of[cap]
people = effort / country.productive_hours_a_month
if hours != BUSINESS:
# A rota is sized by the hours it must fill, not by the work done in them.
people = max(people, card.cover[hours]["minimum_roster"])
party = parties.get(str(role.get("party")), {})
priced = party.get("kind") != CUSTOMER and party.get("kind") in card.prices
cost = (
people
* country.day_rate[str(role.get("level"))]
* country.productive_days
/ 12
* card.cover[hours]["uplift"]
* rate
if priced
else None
)
if cost is not None and effort:
for cap, share in own.items():
portion = effort_of.get(cap, 0.0) * share / effort
by_capability[cap] = by_capability.get(cap, 0.0) + cost * portion
rows.append(
{
"role": role_id,
"name": str(role.get("name") or role_id),
"party": str(role.get("party")),
"party_name": str(party.get("name") or role.get("party")),
"country": str(role.get("country")),
"level": str(role.get("level")),
"hours": hours,
"effort_hours_per_month": round(effort, 1),
"people": round(people, 1),
"cost_per_month": None if cost is None else round(cost),
}
)
def total(key: str) -> dict[str, int]:
sums: dict[str, float] = {}
for row in rows:
if row["cost_per_month"] is not None:
sums[row[key]] = sums.get(row[key], 0.0) + row["cost_per_month"]
return {name: round(amount) for name, amount in sums.items()}
return {
"currency": currency,
"rate_card": {
"name": card.name,
"version": card.version,
"draft": card.is_draft,
},
"conversion": {
"from": card.currency,
"rate": rate,
"as_of": card.conversion_as_of,
},
"roles": rows,
"people": round(sum(row["people"] for row in rows), 1),
"cost_per_month": round(sum(row["cost_per_month"] or 0 for row in rows)),
"by_party": total("party"),
"by_country": total("country"),
"by_capability": {cap: round(amount) for cap, amount in by_capability.items()},
}