Files
tom_analysis_agent/app/operating_model/graph.py

720 lines
28 KiB
Python

"""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