281 lines
11 KiB
Python
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()},
|
|
}
|