feat: working TOM agent
This commit is contained in:
280
app/operating_model/staffing.py
Normal file
280
app/operating_model/staffing.py
Normal file
@@ -0,0 +1,280 @@
|
||||
"""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()},
|
||||
}
|
||||
Reference in New Issue
Block a user