"""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()}, }