feat: working TOM agent
This commit is contained in:
719
app/operating_model/graph.py
Normal file
719
app/operating_model/graph.py
Normal file
@@ -0,0 +1,719 @@
|
||||
"""The Target operating model: one explicit graph, checked before anything is derived.
|
||||
|
||||
parties the organisations with a part in operating the solution
|
||||
teams optional: the teams within a Party, each of one of Team
|
||||
Topologies' four kinds
|
||||
roles positions in a Party, each in a country and at a level, and
|
||||
in a team when there are teams
|
||||
interactions optional: how two teams work together, in one of Team
|
||||
Topologies' three modes; a collaboration says when it ends
|
||||
measures what is measured to show each business outcome the customer
|
||||
stated is being served, at which layer, and by which
|
||||
Capability
|
||||
responsibilities a Role's part in a Capability: accountable, responsible,
|
||||
consulted or informed
|
||||
checks numbered, verifiable conditions on a Capability, a Role or a
|
||||
Responsibility, each traced to what it comes from
|
||||
|
||||
The Capabilities are the capability model's, by id. A submission is refused while
|
||||
the graph does not hold together, so what the customer approves is complete: every
|
||||
Capability has one Role answerable for it and someone to do it at the hours it is
|
||||
needed, and everything the customer said must be kept true is carried by a Check.
|
||||
|
||||
The responsibility matrix, the organisation chart and the staffing and cost are
|
||||
written from the graph by code, as views of it.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Callable, Collection, Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.workflows.deliverables import GraphShape, ListShape
|
||||
|
||||
from app.operating_model import chain, spec, staffing
|
||||
from app.operating_model.catalogue import Catalogue
|
||||
from app.operating_model.names import (
|
||||
ACCOUNTABLE,
|
||||
COLLABORATION,
|
||||
DEVELOPER_LAYERS,
|
||||
FINDINGS_FILE,
|
||||
GRAPH_FILE,
|
||||
HOURS,
|
||||
INTERACTION_MODES,
|
||||
MEASURE_LAYERS,
|
||||
MEASUREMENT_ENTRY,
|
||||
PARTY_KINDS,
|
||||
RESPONSIBILITY_KINDS,
|
||||
RESPONSIBLE,
|
||||
TARGET_OPERATING_MODEL,
|
||||
TEAM_TYPES,
|
||||
wider,
|
||||
)
|
||||
from app.operating_model.spec import Upstream
|
||||
from app.operating_model.staffing import RateCard
|
||||
|
||||
LISTS = (
|
||||
"parties",
|
||||
"teams",
|
||||
"roles",
|
||||
"responsibilities",
|
||||
"interactions",
|
||||
"measures",
|
||||
"checks",
|
||||
)
|
||||
OUTCOMES_HEADING = "Business outcomes"
|
||||
MATRIX_HEADING = "Responsibility matrix"
|
||||
STAFFING_HEADING = "Staffing and cost"
|
||||
FINDINGS_HEADING = "Findings"
|
||||
_LETTER = {"accountable": "A", "responsible": "R", "consulted": "C", "informed": "I"}
|
||||
|
||||
# The graph as the operating-model architect builds it, a few items at a time.
|
||||
SHAPE = GraphShape(
|
||||
attachment=GRAPH_FILE,
|
||||
lists={
|
||||
"parties": ListShape(("id", "name", "kind"), label="Parties"),
|
||||
"teams": ListShape(
|
||||
("id", "party", "name", "type"), optional=("purpose",), label="Teams"
|
||||
),
|
||||
"roles": ListShape(
|
||||
("id", "party", "name", "country", "level", "hours"),
|
||||
optional=("skills", "team"),
|
||||
label="Roles",
|
||||
),
|
||||
"interactions": ListShape(
|
||||
("id", "from", "to", "mode"),
|
||||
optional=("purpose", "until"),
|
||||
label="Interactions",
|
||||
),
|
||||
"measures": ListShape(
|
||||
("id", "name", "layer", "outcome", "measured_by"),
|
||||
optional=("framework", "target"),
|
||||
label="Measures",
|
||||
),
|
||||
"responsibilities": ListShape(
|
||||
("id", "capability", "role", "kind"),
|
||||
optional=("share",),
|
||||
label="Responsibilities",
|
||||
),
|
||||
"checks": ListShape(
|
||||
("id", "on", "condition", "source"),
|
||||
optional=("depends_on_finding",),
|
||||
label="Checks",
|
||||
),
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
def parse(text: str) -> tuple[dict[str, list[dict[str, Any]]], list[str]]:
|
||||
"""The graph's four lists, and what is wrong with the file's shape."""
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError as exc:
|
||||
return {name: [] for name in LISTS}, [f"{GRAPH_FILE}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, dict):
|
||||
return {name: [] for name in LISTS}, [
|
||||
f"{GRAPH_FILE}: must be an object with {', '.join(LISTS)}"
|
||||
]
|
||||
graph: dict[str, list[dict[str, Any]]] = {}
|
||||
problems = []
|
||||
for name in LISTS:
|
||||
entries = data.get(name) or []
|
||||
if not isinstance(entries, list):
|
||||
problems.append(f"{GRAPH_FILE}: {name} must be a list")
|
||||
entries = []
|
||||
graph[name] = [dict(item) for item in entries if isinstance(item, dict)]
|
||||
for index, item in enumerate(entries):
|
||||
where = f"{GRAPH_FILE}: {name}[{index}]"
|
||||
if not isinstance(item, dict):
|
||||
problems.append(f"{where} must be an object")
|
||||
continue
|
||||
missing = [
|
||||
field
|
||||
for field in SHAPE.lists[name].required
|
||||
if not str(item.get(field) or "").strip()
|
||||
]
|
||||
if missing:
|
||||
problems.append(
|
||||
f"{where} ({item.get('id', 'no id')}) needs {', '.join(missing)}"
|
||||
)
|
||||
seen = [str(item.get("id")) for item in graph[name] if item.get("id")]
|
||||
problems += [
|
||||
f"{GRAPH_FILE}: id {identifier} is used more than once in {name}"
|
||||
for identifier in sorted({i for i in seen if seen.count(i) > 1})
|
||||
]
|
||||
return graph, problems
|
||||
|
||||
|
||||
def read(upstream: Upstream | None) -> dict[str, list[dict[str, Any]]] | None:
|
||||
"""The submitted graph from the Deliverables a submission builds on."""
|
||||
text = (
|
||||
((upstream or {}).get(TARGET_OPERATING_MODEL) or {})
|
||||
.get("attachments", {})
|
||||
.get(GRAPH_FILE, "")
|
||||
)
|
||||
return parse(text)[0] if text else None
|
||||
|
||||
|
||||
def findings(attachments: Mapping[str, str]) -> list[dict[str, Any]]:
|
||||
text = attachments.get(FINDINGS_FILE, "")
|
||||
return chain.objects(text, FINDINGS_FILE)[0] if text.strip() else []
|
||||
|
||||
|
||||
def check(card: RateCard, frameworks: Collection[str] = ()) -> chain.DataCheck:
|
||||
"""What is wrong with a Target operating model, against the capability model,
|
||||
the operating spec and the rate card. `frameworks` are the register's, which a
|
||||
Measure may name."""
|
||||
|
||||
def checked(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]:
|
||||
graph, problems = parse(attachments[GRAPH_FILE])
|
||||
if problems:
|
||||
return problems
|
||||
name = GRAPH_FILE
|
||||
scope = spec.agreed(upstream)
|
||||
capabilities = chain.capabilities(upstream)
|
||||
capability_ids = {str(c["id"]) for c in capabilities}
|
||||
requirement_ids = {str(r["id"]) for r in chain.requirements(upstream)}
|
||||
conditions = spec.ids(spec.conditions(scope))
|
||||
|
||||
parties = {str(p["id"]): p for p in graph["parties"]}
|
||||
roles = {str(r["id"]): r for r in graph["roles"]}
|
||||
for party in graph["parties"]:
|
||||
if party.get("kind") not in PARTY_KINDS:
|
||||
problems.append(
|
||||
f"{name}: Party {party['id']}: kind must be one of "
|
||||
f"{', '.join(PARTY_KINDS)}"
|
||||
)
|
||||
allowed = [
|
||||
str(c) for c in spec.value(scope, "sourcing.delivery_countries") or []
|
||||
]
|
||||
for role in graph["roles"]:
|
||||
where = f"{name}: Role {role['id']}"
|
||||
if role.get("party") not in parties:
|
||||
problems.append(
|
||||
f"{where} is in {role.get('party')}, which is not a Party"
|
||||
)
|
||||
if role.get("hours") not in HOURS:
|
||||
problems.append(f"{where}: hours must be one of {', '.join(HOURS)}")
|
||||
country = str(role.get("country"))
|
||||
if country not in card.countries:
|
||||
problems.append(
|
||||
f"{where} sits in {country}, which the rate card does not have: "
|
||||
f"{', '.join(sorted(card.countries))}"
|
||||
)
|
||||
elif allowed and country not in allowed:
|
||||
problems.append(
|
||||
f"{where} sits in {country}; the customer allows only "
|
||||
f"{', '.join(allowed)}"
|
||||
)
|
||||
if str(role.get("level")) not in card.levels:
|
||||
problems.append(
|
||||
f"{where} is at level {role.get('level')}, which the rate card "
|
||||
f"does not have: {', '.join(card.levels)}"
|
||||
)
|
||||
|
||||
problems += check_teams(graph, parties, name)
|
||||
|
||||
by_capability: dict[str, list[dict[str, Any]]] = {}
|
||||
for item in graph["responsibilities"]:
|
||||
where = f"{name}: Responsibility {item['id']}"
|
||||
if item.get("kind") not in RESPONSIBILITY_KINDS:
|
||||
problems.append(
|
||||
f"{where}: kind must be one of {', '.join(RESPONSIBILITY_KINDS)}"
|
||||
)
|
||||
if item.get("role") not in roles:
|
||||
problems.append(
|
||||
f"{where} names {item.get('role')}, which is not a Role"
|
||||
)
|
||||
if upstream is not None and item.get("capability") not in capability_ids:
|
||||
problems.append(
|
||||
f"{where} names {item.get('capability')}, which is not a "
|
||||
"Capability of the capability model"
|
||||
)
|
||||
by_capability.setdefault(str(item.get("capability")), []).append(item)
|
||||
|
||||
for capability in capabilities:
|
||||
identifier = str(capability["id"])
|
||||
held = by_capability.get(identifier, [])
|
||||
accountable = [r for r in held if r.get("kind") == ACCOUNTABLE]
|
||||
responsible = [r for r in held if r.get("kind") == RESPONSIBLE]
|
||||
if len(accountable) != 1:
|
||||
problems.append(
|
||||
f"{name}: Capability {identifier} has {len(accountable)} "
|
||||
"accountable Roles; it needs exactly one"
|
||||
)
|
||||
if not responsible:
|
||||
problems.append(
|
||||
f"{name}: Capability {identifier} has no responsible Role"
|
||||
)
|
||||
continue
|
||||
needed = str(capability.get("hours"))
|
||||
worked = [
|
||||
str(roles[str(r["role"])].get("hours"))
|
||||
for r in responsible
|
||||
if r.get("role") in roles
|
||||
]
|
||||
if (
|
||||
needed in HOURS
|
||||
and worked
|
||||
and all(hours in HOURS and wider(needed, hours) for hours in worked)
|
||||
):
|
||||
problems.append(
|
||||
f"{name}: Capability {identifier} is needed {needed}, and no "
|
||||
"Role responsible for it works those hours"
|
||||
)
|
||||
problems += [
|
||||
f"{name}: {fault}"
|
||||
for fault in staffing.shares(graph["responsibilities"])[1]
|
||||
]
|
||||
|
||||
found = findings(attachments)
|
||||
finding_ids = {str(item["id"]) for item in found}
|
||||
on = (
|
||||
capability_ids
|
||||
| set(roles)
|
||||
| {str(r["id"]) for r in graph["responsibilities"]}
|
||||
| {str(team["id"]) for team in graph["teams"]}
|
||||
| {str(i["id"]) for i in graph["interactions"]}
|
||||
| {str(m["id"]) for m in graph["measures"]}
|
||||
)
|
||||
carried: set[str] = set()
|
||||
for item in graph["checks"]:
|
||||
where = f"{name}: Check {item['id']}"
|
||||
source = str(item.get("source"))
|
||||
carried.add(source)
|
||||
if upstream is not None and item.get("on") not in on:
|
||||
problems.append(
|
||||
f"{where} is on {item.get('on')}, which is not a Capability, a "
|
||||
"Role or a Responsibility"
|
||||
)
|
||||
if upstream is not None and source not in requirement_ids | set(conditions):
|
||||
problems.append(
|
||||
f"{where}: source {source} is not an Operational requirement "
|
||||
"or a Condition"
|
||||
)
|
||||
depends = item.get("depends_on_finding")
|
||||
if depends and depends not in finding_ids:
|
||||
problems.append(f"{where} depends on {depends}, which is not a finding")
|
||||
problems += [
|
||||
f"{name}: Condition {identifier} is carried by no Check"
|
||||
for identifier in conditions
|
||||
if identifier not in carried
|
||||
]
|
||||
problems += check_measures(
|
||||
graph, scope, capabilities, by_capability, roles, frameworks, name
|
||||
)
|
||||
problems += check_findings(
|
||||
attachments,
|
||||
scope,
|
||||
on | {str(c["id"]) for c in graph["checks"]} | requirement_ids,
|
||||
)
|
||||
return problems
|
||||
|
||||
return checked
|
||||
|
||||
|
||||
def check_teams(
|
||||
graph: Mapping[str, Sequence[Mapping[str, Any]]],
|
||||
parties: Mapping[str, Any],
|
||||
name: str,
|
||||
) -> list[str]:
|
||||
"""What is wrong with the teams and how they work together.
|
||||
|
||||
Teams are optional. When there are any, each is of one of Team Topologies' four
|
||||
kinds, a Role in a team belongs to that team's Party, and two teams work
|
||||
together in one of its three modes. A collaboration is a stage, not a standing
|
||||
arrangement: it says when it ends.
|
||||
"""
|
||||
problems = []
|
||||
teams = {str(team["id"]): team for team in graph["teams"]}
|
||||
for team in graph["teams"]:
|
||||
where = f"{name}: Team {team['id']}"
|
||||
if team.get("type") not in TEAM_TYPES:
|
||||
problems.append(f"{where}: type must be one of {', '.join(TEAM_TYPES)}")
|
||||
if team.get("party") not in parties:
|
||||
problems.append(f"{where} is in {team.get('party')}, which is not a Party")
|
||||
for role in graph["roles"]:
|
||||
team_id = role.get("team")
|
||||
if not team_id:
|
||||
continue
|
||||
found = teams.get(str(team_id))
|
||||
if found is None:
|
||||
problems.append(
|
||||
f"{name}: Role {role['id']} is in {team_id}, which is not a Team"
|
||||
)
|
||||
elif found.get("party") != role.get("party"):
|
||||
problems.append(
|
||||
f"{name}: Role {role['id']} is in {role.get('party')}, and its team "
|
||||
f"{team_id} is in {found.get('party')}"
|
||||
)
|
||||
for item in graph["interactions"]:
|
||||
where = f"{name}: Interaction {item['id']}"
|
||||
if item.get("mode") not in INTERACTION_MODES:
|
||||
problems.append(
|
||||
f"{where}: mode must be one of {', '.join(INTERACTION_MODES)}"
|
||||
)
|
||||
for end in ("from", "to"):
|
||||
if item.get(end) not in teams:
|
||||
problems.append(f"{where}: {end} {item.get(end)} is not a Team")
|
||||
if item.get("from") == item.get("to"):
|
||||
problems.append(f"{where} is between a team and itself")
|
||||
if (
|
||||
item.get("mode") == COLLABORATION
|
||||
and not str(item.get("until") or "").strip()
|
||||
):
|
||||
problems.append(
|
||||
f"{where} is a collaboration and does not say when it ends: give "
|
||||
"`until`, and what the teams work in after"
|
||||
)
|
||||
return problems
|
||||
|
||||
|
||||
def check_measures(
|
||||
graph: Mapping[str, Sequence[Mapping[str, Any]]],
|
||||
scope: Mapping[str, Any],
|
||||
capabilities: Sequence[Mapping[str, Any]],
|
||||
by_capability: Mapping[str, Sequence[Mapping[str, Any]]],
|
||||
roles: Mapping[str, Any],
|
||||
frameworks: Collection[str],
|
||||
name: str,
|
||||
) -> list[str]:
|
||||
"""Every business outcome the customer stated is shown by something measured,
|
||||
and everything measured shows one: nothing is measured for its own sake.
|
||||
|
||||
A Measure is taken by a Capability someone is responsible for. Where the model
|
||||
measures how work flows, it measures all three layers: delivery outcomes,
|
||||
sustainable productivity and friction. No one of them stands in for the others.
|
||||
"""
|
||||
problems = []
|
||||
outcomes = {str(o["id"]): o for o in spec.business_outcomes(scope)}
|
||||
capability_ids = {str(c["id"]) for c in capabilities}
|
||||
measured: set[str] = set()
|
||||
for item in graph["measures"]:
|
||||
where = f"{name}: Measure {item['id']}"
|
||||
if item.get("layer") not in MEASURE_LAYERS:
|
||||
problems.append(
|
||||
f"{where}: layer must be one of {', '.join(MEASURE_LAYERS)}"
|
||||
)
|
||||
outcome = str(item.get("outcome"))
|
||||
measured.add(outcome)
|
||||
if outcome not in outcomes:
|
||||
problems.append(
|
||||
f"{where} shows {outcome}, which is not a business outcome the "
|
||||
"customer stated"
|
||||
+ (f": {', '.join(outcomes)}" if outcomes else "; none were stated")
|
||||
)
|
||||
taker = str(item.get("measured_by"))
|
||||
if taker not in capability_ids:
|
||||
problems.append(
|
||||
f"{where} is measured by {taker}, which is not a Capability"
|
||||
)
|
||||
elif not any(
|
||||
r.get("kind") == "responsible" and r.get("role") in roles
|
||||
for r in by_capability.get(taker, ())
|
||||
):
|
||||
problems.append(
|
||||
f"{where} is measured by {taker}, and nobody is responsible for it"
|
||||
)
|
||||
if item.get("framework") and frameworks and item["framework"] not in frameworks:
|
||||
problems.append(
|
||||
f"{where} names framework {item['framework']}, which is not in the register"
|
||||
)
|
||||
problems += [
|
||||
f"{name}: business outcome {identifier} ({outcomes[identifier].get('outcome')}) "
|
||||
"is shown by no Measure"
|
||||
for identifier in outcomes
|
||||
if identifier not in measured
|
||||
]
|
||||
measurers = {
|
||||
str(c["id"]) for c in capabilities if c.get("catalogue") == MEASUREMENT_ENTRY
|
||||
}
|
||||
# Only once there is an outcome to tie Measures to: with none, no Measure can
|
||||
# be accepted, and asking for three of them could never be met.
|
||||
if measurers and outcomes:
|
||||
layers = {
|
||||
str(m.get("layer"))
|
||||
for m in graph["measures"]
|
||||
if m.get("measured_by") in measurers
|
||||
}
|
||||
missing = [layer for layer in DEVELOPER_LAYERS if layer not in layers]
|
||||
if missing:
|
||||
problems.append(
|
||||
f"{name}: {', '.join(sorted(measurers))} measures how work flows and has "
|
||||
f"no Measure at the {', '.join(missing)} layer; each layer answers a "
|
||||
"different question and none stands in for another"
|
||||
)
|
||||
return problems
|
||||
|
||||
|
||||
def render_outcomes(
|
||||
graph: Mapping[str, Sequence[Mapping[str, Any]]],
|
||||
scope: Mapping[str, Any],
|
||||
names: Mapping[str, str],
|
||||
) -> str:
|
||||
"""Each business outcome, with what shows it is served and who answers for it."""
|
||||
outcomes = spec.business_outcomes(scope)
|
||||
if not outcomes:
|
||||
return (
|
||||
"The customer stated no business outcomes, so nothing in this operating "
|
||||
"model is tied to one. Ask what the business wants from the solution, "
|
||||
"and how it would know."
|
||||
)
|
||||
roles = {str(r["id"]): r for r in graph["roles"]}
|
||||
answerable: dict[str, str] = {}
|
||||
for item in graph["responsibilities"]:
|
||||
if item.get("kind") == "accountable" and item.get("role") in roles:
|
||||
answerable[str(item.get("capability"))] = str(
|
||||
roles[str(item["role"])].get("name")
|
||||
)
|
||||
lines = []
|
||||
for outcome in outcomes:
|
||||
target = f" Target: {outcome['target']}." if outcome.get("target") else ""
|
||||
lines += [f"**{outcome['id']}: {outcome.get('outcome')}**{target}", ""]
|
||||
shown = [m for m in graph["measures"] if m.get("outcome") == outcome["id"]]
|
||||
if not shown:
|
||||
lines += ["Nothing measured shows this outcome.", ""]
|
||||
continue
|
||||
lines += [
|
||||
"| Measure | Layer | Framework | Target | Measured by | Answerable |",
|
||||
"| --- | --- | --- | --- | --- | --- |",
|
||||
]
|
||||
lines += [
|
||||
f"| {m.get('name')} | {str(m.get('layer', '')).replace('_', ' ')} | "
|
||||
f"{m.get('framework') or ''} | {m.get('target') or ''} | "
|
||||
f"{names.get(str(m.get('measured_by')), m.get('measured_by'))} | "
|
||||
f"{answerable.get(str(m.get('measured_by')), '')} |"
|
||||
for m in shown
|
||||
]
|
||||
lines.append("")
|
||||
return "\n".join(lines).rstrip()
|
||||
|
||||
|
||||
def check_findings(
|
||||
attachments: Mapping[str, str], scope: Mapping[str, Any], known: set[str]
|
||||
) -> list[str]:
|
||||
"""What is wrong with findings.json. It may be an empty list."""
|
||||
text = attachments.get(FINDINGS_FILE, "")
|
||||
if not text.strip():
|
||||
return []
|
||||
entries, problems = chain.objects(text, FINDINGS_FILE)
|
||||
item_ids = set(spec.ids(spec.items(scope)))
|
||||
for entry in entries:
|
||||
where = f"{FINDINGS_FILE}: {entry['id']}"
|
||||
for field in ("lacks", "proposed"):
|
||||
if not str(entry.get(field) or "").strip():
|
||||
problems.append(f"{where} needs {field}")
|
||||
about = [str(i) for i in entry.get("about") or []]
|
||||
needed_by = [str(i) for i in entry.get("needed_by") or []]
|
||||
if not about:
|
||||
# A finding is about the solution: it names what in it is lacking.
|
||||
problems.append(
|
||||
f"{where} names no Item of the solution under about. What the "
|
||||
"operating model can provide itself, such as staffing, hours, a Role, "
|
||||
"a process or a tool, is not a finding: design it"
|
||||
)
|
||||
if not needed_by:
|
||||
problems.append(f"{where} must say what needs it, under needed_by")
|
||||
problems += [
|
||||
f"{where} is about {identifier}, which is not an Item of the operating spec"
|
||||
for identifier in about
|
||||
if scope and identifier not in item_ids
|
||||
]
|
||||
problems += [
|
||||
f"{where} is needed by {identifier}, which is not in the operating model"
|
||||
for identifier in needed_by
|
||||
if identifier not in known
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
# --- the views code writes -----------------------------------------------------------
|
||||
|
||||
|
||||
def render_matrix(
|
||||
graph: Mapping[str, Sequence[Mapping[str, Any]]], names: Mapping[str, str]
|
||||
) -> str:
|
||||
"""Who is accountable, responsible, consulted and informed for each Capability."""
|
||||
roles = list(graph["roles"])
|
||||
# A Role may hold more than one part in a Capability: answerable for it and
|
||||
# doing it. Both are shown.
|
||||
held: dict[tuple[str, str], str] = {}
|
||||
for item in graph["responsibilities"]:
|
||||
key = (str(item.get("capability")), str(item.get("role")))
|
||||
letter = _LETTER.get(str(item.get("kind")), "?")
|
||||
held[key] = f"{held[key]}/{letter}" if key in held else letter
|
||||
header = "| Capability | " + " | ".join(str(r.get("name")) for r in roles) + " |"
|
||||
rule = "| --- | " + " | ".join("---" for _ in roles) + " |"
|
||||
rows = [
|
||||
f"| {name} ({identifier}) | "
|
||||
+ " | ".join(held.get((identifier, str(r["id"])), "") for r in roles)
|
||||
+ " |"
|
||||
for identifier, name in names.items()
|
||||
]
|
||||
legend = "A accountable, R responsible, C consulted, I informed."
|
||||
return "\n".join([f"## {MATRIX_HEADING}", "", header, rule, *rows, "", legend, ""])
|
||||
|
||||
|
||||
def _node(identifier: Any) -> str:
|
||||
return str(identifier).replace("-", "_")
|
||||
|
||||
|
||||
def _role_node(role: Mapping[str, Any], indent: str) -> str:
|
||||
return (
|
||||
f'{indent}{_node(role["id"])}["{role.get("name")}<br/>{role.get("country")}, '
|
||||
f'{role.get("level")}, {role.get("hours")}"]'
|
||||
)
|
||||
|
||||
|
||||
def render_organisation(graph: Mapping[str, Sequence[Mapping[str, Any]]]) -> str:
|
||||
"""The Parties, their teams and the Roles in each, and how the teams work
|
||||
together, as a Mermaid chart."""
|
||||
teams = graph.get("teams") or []
|
||||
lines = ["flowchart TB"]
|
||||
for party in graph["parties"]:
|
||||
lines.append(
|
||||
f' subgraph {_node(party["id"])}["{party.get("name")} ({party.get("kind")})"]'
|
||||
)
|
||||
for team in teams:
|
||||
if team.get("party") != party["id"]:
|
||||
continue
|
||||
kind = str(team.get("type", "")).replace("_", "-")
|
||||
lines.append(
|
||||
f' subgraph {_node(team["id"])}["{team.get("name")} ({kind} team)"]'
|
||||
)
|
||||
lines += [
|
||||
_role_node(role, " ")
|
||||
for role in graph["roles"]
|
||||
if role.get("team") == team["id"]
|
||||
]
|
||||
lines.append(" end")
|
||||
lines += [
|
||||
_role_node(role, " ")
|
||||
for role in graph["roles"]
|
||||
if role.get("party") == party["id"] and not role.get("team")
|
||||
]
|
||||
lines.append(" end")
|
||||
for item in graph.get("interactions") or []:
|
||||
mode = str(item.get("mode", "")).replace("_", "-")
|
||||
label = mode + (f" until {item['until']}" if item.get("until") else "")
|
||||
lines.append(f' {_node(item["from"])} -- "{label}" --> {_node(item["to"])}')
|
||||
return "\n".join(lines) + "\n"
|
||||
|
||||
|
||||
def _money(amount: Any, currency: str) -> str:
|
||||
return "not priced" if amount is None else f"{amount:,} {currency}"
|
||||
|
||||
|
||||
def render_staffing(result: Mapping[str, Any], budget: Any = None) -> str:
|
||||
"""People and cost per Role and in total, with the prices they were worked from."""
|
||||
currency = str(result["currency"])
|
||||
card = result["rate_card"]
|
||||
conversion = result["conversion"]
|
||||
lines = [
|
||||
f"## {STAFFING_HEADING}",
|
||||
"",
|
||||
"| Role | Party | Country | Level | Hours | Effort a month | People | Cost a month |",
|
||||
"| --- | --- | --- | --- | --- | --- | --- | --- |",
|
||||
]
|
||||
lines += [
|
||||
f"| {row['name']} | {row.get('party_name', row['party'])} | "
|
||||
f"{row['country']} | {row['level']} | "
|
||||
f"{row['hours']} | {row['effort_hours_per_month']} h | {row['people']} | "
|
||||
f"{_money(row['cost_per_month'], currency)} |"
|
||||
for row in result["roles"]
|
||||
]
|
||||
lines += [
|
||||
"",
|
||||
(
|
||||
f"{result['people']} people in all. Cost a month: "
|
||||
f"{_money(result['cost_per_month'], currency)}."
|
||||
),
|
||||
]
|
||||
if isinstance(budget, (int, float)) and not isinstance(budget, bool):
|
||||
over = result["cost_per_month"] - budget
|
||||
lines.append(
|
||||
f"The monthly budget is {_money(round(budget), currency)}: "
|
||||
+ (
|
||||
f"this is over it by {_money(round(over), currency)}."
|
||||
if over > 0
|
||||
else "this is within it."
|
||||
)
|
||||
)
|
||||
lines += [
|
||||
"",
|
||||
f"Worked from rate card `{card['name']}`, version `{card['version']}`"
|
||||
+ (
|
||||
". **Its figures are placeholders: no price has been set, and this cost "
|
||||
"is an illustration.**"
|
||||
if card["draft"]
|
||||
else "."
|
||||
),
|
||||
]
|
||||
if conversion["from"] != currency:
|
||||
lines.append(
|
||||
f"Converted from {conversion['from']} at {conversion['rate']}, a rate "
|
||||
f"set on {conversion['as_of']}."
|
||||
)
|
||||
lines += [
|
||||
(
|
||||
"The customer's own staff are counted and not priced. A Role that covers "
|
||||
"hours wider than a working day is never smaller than the team that can "
|
||||
"cover them."
|
||||
),
|
||||
"",
|
||||
]
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def render_findings(found: Sequence[Mapping[str, Any]]) -> str:
|
||||
if not found:
|
||||
return ""
|
||||
lines = [
|
||||
f"## {FINDINGS_HEADING}",
|
||||
"",
|
||||
(
|
||||
"What operating this solution needs that the solution, as described, does "
|
||||
"not provide. Nothing here was designed around: each is for whoever owns "
|
||||
"the design."
|
||||
),
|
||||
"",
|
||||
]
|
||||
lines += [
|
||||
f"- **{item['id']}** ({', '.join(str(i) for i in item.get('about') or []) or 'the solution'}): "
|
||||
f"{item.get('lacks')} Proposed: {item.get('proposed')}"
|
||||
for item in found
|
||||
]
|
||||
return "\n".join(lines) + "\n"
|
||||
|
||||
|
||||
Views = Callable[[str, dict[str, str], Upstream | None], tuple[str, dict[str, str]]]
|
||||
|
||||
|
||||
def views(catalogue: Catalogue, card: RateCard) -> Views:
|
||||
"""Add the matrix, the staffing and the findings to an accepted submission."""
|
||||
from app.operating_model.names import ORGANISATION_FILE, STAFFING_FILE
|
||||
|
||||
def add(
|
||||
content: str, attachments: dict[str, str], upstream: Upstream | None
|
||||
) -> tuple[str, dict[str, str]]:
|
||||
graph, _ = parse(attachments[GRAPH_FILE])
|
||||
scope = spec.agreed(upstream)
|
||||
capabilities = chain.capabilities(upstream)
|
||||
currency = str(spec.value(scope, "commercial.currency") or card.currency)
|
||||
result = staffing.compute(graph, capabilities, card, currency)
|
||||
found = findings(attachments)
|
||||
# A Revision replaces these sections, never stacks a second copy.
|
||||
content = content.split(f"\n## {MATRIX_HEADING}")[0].rstrip()
|
||||
parts = [
|
||||
content,
|
||||
render_matrix(graph, chain.names_of(capabilities, catalogue)),
|
||||
render_staffing(result, spec.value(scope, "commercial.monthly_run_budget")),
|
||||
render_findings(found),
|
||||
]
|
||||
attachments[ORGANISATION_FILE] = render_organisation(graph)
|
||||
attachments[STAFFING_FILE] = json.dumps(result, indent=2, ensure_ascii=False)
|
||||
attachments.setdefault(FINDINGS_FILE, "[]")
|
||||
return "\n\n".join(part.rstrip() for part in parts if part) + "\n", attachments
|
||||
|
||||
return add
|
||||
Reference in New Issue
Block a user