388 lines
14 KiB
Python
388 lines
14 KiB
Python
"""The operating model guide: one document, assembled from every other Deliverable.
|
|
|
|
The packager writes the summary. Every other section is written here, from the data
|
|
the other Deliverables carry: the Items and Conditions, the requirements, the
|
|
Capabilities, who does what, staffing and cost, the verdicts and the findings. A
|
|
table or a figure copied by a model can be copied wrongly; one written from the data
|
|
cannot disagree with it.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import re
|
|
from collections.abc import Mapping, Sequence
|
|
from typing import Any
|
|
|
|
from app.operating_model import catalogue as capability_catalogue
|
|
from app.operating_model import chain, graph, scenarios, spec
|
|
from app.operating_model.catalogue import Catalogue
|
|
from app.operating_model.names import (
|
|
SCENARIOS_FILE,
|
|
STAFFING_FILE,
|
|
TARGET_OPERATING_MODEL,
|
|
VALIDATION_RESULTS,
|
|
VERDICTS_FILE,
|
|
)
|
|
from app.operating_model.spec import Upstream
|
|
|
|
SUMMARY = "Summary"
|
|
KEY_FIGURES = "Key figures"
|
|
# The sections of the guide, in order. The packager writes the first; code writes
|
|
# the rest.
|
|
SECTIONS = (
|
|
SUMMARY,
|
|
"Business outcomes",
|
|
"What is operated",
|
|
"Operational requirements",
|
|
"Capabilities",
|
|
"Who does what",
|
|
"Staffing and cost",
|
|
"Validation",
|
|
"Findings and open questions",
|
|
"Sources",
|
|
)
|
|
_HEADING = re.compile(r"^##\s+(?:\d+(?:\.\d+)*\.?\s+)?(.+?)\s*#*\s*$", re.MULTILINE)
|
|
|
|
|
|
def _json(deliverables: Upstream, kind: str, name: str) -> Any:
|
|
text = (deliverables.get(kind) or {}).get("attachments", {}).get(name, "")
|
|
try:
|
|
return json.loads(text) if text else None
|
|
except ValueError:
|
|
return None
|
|
|
|
|
|
def _cell(value: Any) -> str:
|
|
"""A value as one cell of a table."""
|
|
if isinstance(value, (list, tuple)):
|
|
value = ", ".join(str(item) for item in value)
|
|
return " ".join(str(value if value is not None else "").split()).replace("|", "\\|")
|
|
|
|
|
|
def _table(headers: Sequence[str], rows: Sequence[Sequence[Any]]) -> list[str]:
|
|
return [
|
|
"| " + " | ".join(headers) + " |",
|
|
"| " + " | ".join("---" for _ in headers) + " |",
|
|
*("| " + " | ".join(_cell(value) for value in row) + " |" for row in rows),
|
|
]
|
|
|
|
|
|
def _body(rendered: str) -> str:
|
|
"""A rendered view without its own heading."""
|
|
return (
|
|
rendered.split("\n", 1)[1].strip() if rendered.startswith("## ") else rendered
|
|
)
|
|
|
|
|
|
def business_outcomes(deliverables: Upstream, catalogue: Catalogue) -> str:
|
|
model = graph.read(deliverables) or {
|
|
"roles": [],
|
|
"responsibilities": [],
|
|
"measures": [],
|
|
}
|
|
names = chain.names_of(chain.capabilities(deliverables), catalogue)
|
|
return graph.render_outcomes(model, spec.agreed(deliverables), names)
|
|
|
|
|
|
def what_is_operated(scope: Mapping[str, Any]) -> str:
|
|
lines = _table(
|
|
("Item", "What it is", "Kind", "Product", "From"),
|
|
[
|
|
(
|
|
i["id"],
|
|
i.get("name"),
|
|
i.get("kind"),
|
|
i.get("product"),
|
|
i.get("source_ref"),
|
|
)
|
|
for i in spec.items(scope)
|
|
],
|
|
)
|
|
conditions = spec.conditions(scope)
|
|
if conditions:
|
|
lines += ["", "What must be kept true while it is run:", ""]
|
|
lines += _table(
|
|
("Condition", "On", "What must hold", "From"),
|
|
[
|
|
(c["id"], c.get("on"), c.get("condition"), c.get("source_ref"))
|
|
for c in conditions
|
|
],
|
|
)
|
|
risks = spec.records(scope, "solution.inherited_risks")
|
|
if risks:
|
|
lines += ["", "Known to be unverified or at risk when operations begin:", ""]
|
|
lines += [f"- {r.get('on')}: {r.get('risk')}" for r in risks]
|
|
return "\n".join(lines)
|
|
|
|
|
|
def requirements(deliverables: Upstream) -> str:
|
|
return "\n".join(
|
|
_table(
|
|
("Requirement", "Kind", "What must be achieved", "From"),
|
|
[
|
|
(r["id"], r.get("kind"), r.get("statement"), r.get("source"))
|
|
for r in chain.requirements(deliverables)
|
|
],
|
|
)
|
|
)
|
|
|
|
|
|
def capabilities(deliverables: Upstream, catalogue: Catalogue) -> str:
|
|
listed = chain.capabilities(deliverables)
|
|
names = chain.names_of(listed, catalogue)
|
|
return "\n".join(
|
|
_table(
|
|
("Capability", "What it is", "Serves", "Covers", "Hours", "Effort a month"),
|
|
[
|
|
(
|
|
c["id"],
|
|
names[str(c["id"])],
|
|
c.get("serves"),
|
|
c.get("items"),
|
|
c.get("hours"),
|
|
f"{c.get('effort_hours_per_month')} h",
|
|
)
|
|
for c in listed
|
|
],
|
|
)
|
|
)
|
|
|
|
|
|
def who_does_what(deliverables: Upstream, catalogue: Catalogue) -> str:
|
|
model = graph.read(deliverables)
|
|
if model is None:
|
|
return ""
|
|
party = {str(p["id"]): p for p in model["parties"]}
|
|
lines = _table(
|
|
("Role", "Party", "Country", "Level", "Hours"),
|
|
[
|
|
(
|
|
r.get("name"),
|
|
(
|
|
f"{party.get(str(r.get('party')), {}).get('name')} "
|
|
f"({party.get(str(r.get('party')), {}).get('kind')})"
|
|
),
|
|
r.get("country"),
|
|
r.get("level"),
|
|
r.get("hours"),
|
|
)
|
|
for r in model["roles"]
|
|
],
|
|
)
|
|
teams = model.get("teams") or []
|
|
if teams:
|
|
lines += ["", "The teams, as Team Topologies names their kinds:", ""]
|
|
lines += _table(
|
|
("Team", "Kind", "Party", "Roles", "Purpose"),
|
|
[
|
|
(
|
|
team.get("name"),
|
|
str(team.get("type", "")).replace("_", "-"),
|
|
party.get(str(team.get("party")), {}).get("name"),
|
|
[
|
|
r.get("name")
|
|
for r in model["roles"]
|
|
if r.get("team") == team["id"]
|
|
],
|
|
team.get("purpose"),
|
|
)
|
|
for team in teams
|
|
],
|
|
)
|
|
interactions = model.get("interactions") or []
|
|
if interactions:
|
|
named = {str(team["id"]): team.get("name") for team in teams}
|
|
lines += ["", "How the teams work together:", ""]
|
|
lines += _table(
|
|
("From", "To", "Mode", "Until", "Purpose"),
|
|
[
|
|
(
|
|
named.get(str(i.get("from")), i.get("from")),
|
|
named.get(str(i.get("to")), i.get("to")),
|
|
str(i.get("mode", "")).replace("_", "-"),
|
|
i.get("until") or "",
|
|
i.get("purpose"),
|
|
)
|
|
for i in interactions
|
|
],
|
|
)
|
|
names = chain.names_of(chain.capabilities(deliverables), catalogue)
|
|
return "\n".join([*lines, "", _body(graph.render_matrix(model, names))])
|
|
|
|
|
|
def staffing_and_cost(deliverables: Upstream) -> str:
|
|
result = _json(deliverables, TARGET_OPERATING_MODEL, STAFFING_FILE)
|
|
if not isinstance(result, dict):
|
|
return ""
|
|
budget = spec.value(spec.agreed(deliverables), "commercial.monthly_run_budget")
|
|
return _body(graph.render_staffing(result, budget))
|
|
|
|
|
|
def validation(deliverables: Upstream) -> str:
|
|
verdicts = _json(deliverables, VALIDATION_RESULTS, VERDICTS_FILE) or {}
|
|
model = graph.read(deliverables) or {"checks": []}
|
|
condition = {str(c["id"]): c.get("condition") for c in model["checks"]}
|
|
own = [
|
|
item
|
|
for item in verdicts.get("checks") or []
|
|
if isinstance(item, dict)
|
|
and not str(item.get("check", "")).startswith(scenarios.PREFIX)
|
|
]
|
|
lines = _table(
|
|
("Check", "What must hold", "Verdict", "Evidence"),
|
|
[
|
|
(
|
|
v.get("check"),
|
|
condition.get(str(v.get("check"))),
|
|
str(v.get("verdict")).replace("_", " ")
|
|
+ (f" ({v['finding']})" if v.get("finding") else ""),
|
|
v.get("evidence"),
|
|
)
|
|
for v in own
|
|
],
|
|
)
|
|
walked = _json(deliverables, VALIDATION_RESULTS, SCENARIOS_FILE)
|
|
if isinstance(walked, list) and walked:
|
|
lines += ["", _body(scenarios.render(walked))]
|
|
return "\n".join(lines)
|
|
|
|
|
|
def findings_and_questions(deliverables: Upstream) -> str:
|
|
scope = spec.agreed(deliverables)
|
|
found = graph.findings(
|
|
(deliverables.get(TARGET_OPERATING_MODEL) or {}).get("attachments", {})
|
|
)
|
|
lines = []
|
|
if found:
|
|
lines += [_body(graph.render_findings(found)), ""]
|
|
else:
|
|
lines += ["No findings: the solution provides what operating it needs.", ""]
|
|
assumed = [a for a in scope.get("assumed") or [] if isinstance(a, Mapping)]
|
|
if assumed:
|
|
lines += ["Assumed for the customer, and open to change when they answer:", ""]
|
|
lines += [
|
|
f"- `{a.get('field')}`: {_cell(a.get('value'))}. {a.get('why') or ''}".rstrip()
|
|
for a in assumed
|
|
]
|
|
lines.append("")
|
|
undecided = [d for d in scope.get("to_decide") or [] if isinstance(d, Mapping)]
|
|
if undecided:
|
|
lines += ["Left to the agent by the customer, and not yet settled:", ""]
|
|
lines += [
|
|
f"- `{d.get('field')}`: affects {d.get('affects') or 'the operating model'}."
|
|
for d in undecided
|
|
]
|
|
lines.append("")
|
|
# What matters to an operating model and is not known. The optional fields
|
|
# nobody was asked for are not open questions.
|
|
unknown = [
|
|
g
|
|
for g in scope.get("to_ask") or []
|
|
if isinstance(g, Mapping) and g.get("severity") in ("HIGH", "MEDIUM")
|
|
]
|
|
if unknown:
|
|
lines += ["Still unknown:", ""]
|
|
lines += [
|
|
f"- `{g.get('field')}`: {g.get('prompt') or ''}".rstrip() for g in unknown
|
|
]
|
|
return "\n".join(lines).rstrip()
|
|
|
|
|
|
def sources(deliverables: Upstream, catalogue: Catalogue) -> str:
|
|
entries = [str(c.get("catalogue")) for c in chain.capabilities(deliverables)]
|
|
lines = [
|
|
(
|
|
"The Capabilities are from our own capability catalogue, which draws on "
|
|
"these frameworks. It cites them and certifies nothing against them."
|
|
),
|
|
"",
|
|
*(f"- {line}" for line in capability_catalogue.cited(catalogue, entries)),
|
|
]
|
|
if not catalogue.verified:
|
|
lines += [
|
|
"",
|
|
(
|
|
"**These references have not been checked against the frameworks by a "
|
|
"person.** Treat each as a pointer to where to look."
|
|
),
|
|
]
|
|
return "\n".join(lines)
|
|
|
|
|
|
def key_figures(deliverables: Upstream) -> str:
|
|
"""The figures a reader takes from the summary, written from the data."""
|
|
scope = spec.agreed(deliverables)
|
|
cost = _json(deliverables, TARGET_OPERATING_MODEL, STAFFING_FILE)
|
|
walked = _json(deliverables, VALIDATION_RESULTS, SCENARIOS_FILE) or []
|
|
found = graph.findings(
|
|
(deliverables.get(TARGET_OPERATING_MODEL) or {}).get("attachments", {})
|
|
)
|
|
lines = [
|
|
(
|
|
f"- Operated: {len(spec.items(scope))} Items, with "
|
|
f"{len(spec.conditions(scope))} Conditions to keep true."
|
|
),
|
|
f"- Faults responded to: {spec.value(scope, 'operations.support_hours')} hours.",
|
|
f"- Capabilities: {len(chain.capabilities(deliverables))}.",
|
|
]
|
|
if isinstance(cost, dict):
|
|
card = cost["rate_card"]
|
|
lines.append(
|
|
f"- People: {cost['people']}. Cost a month: {cost['cost_per_month']:,} "
|
|
f"{cost['currency']}, from rate card version `{card['version']}`"
|
|
+ (" (placeholder prices: an illustration)." if card["draft"] else ".")
|
|
)
|
|
if walked:
|
|
passed = sum(1 for item in walked if item.get("passes"))
|
|
lines.append(f"- Scenario walk-throughs: {passed} of {len(walked)} pass.")
|
|
outcomes = spec.business_outcomes(scope)
|
|
model = graph.read(deliverables)
|
|
if outcomes:
|
|
shown = {str(m.get("outcome")) for m in (model or {}).get("measures", [])}
|
|
lines.append(
|
|
f"- Business outcomes: {len(outcomes)}, "
|
|
f"{sum(1 for o in outcomes if str(o['id']) in shown)} shown by a Measure."
|
|
)
|
|
else:
|
|
lines.append("- Business outcomes: none stated.")
|
|
lines.append(f"- Findings for whoever owns the design: {len(found)}.")
|
|
return "\n".join(lines)
|
|
|
|
|
|
def assemble(content: str, deliverables: Upstream, catalogue: Catalogue) -> str:
|
|
"""The guide, with every section but the summary written from the data.
|
|
|
|
The packager's summary is kept as written, and the key figures are set under it.
|
|
Whatever it wrote under another heading is replaced.
|
|
"""
|
|
written = {
|
|
"Business outcomes": business_outcomes(deliverables, catalogue),
|
|
"What is operated": what_is_operated(spec.agreed(deliverables)),
|
|
"Operational requirements": requirements(deliverables),
|
|
"Capabilities": capabilities(deliverables, catalogue),
|
|
"Who does what": who_does_what(deliverables, catalogue),
|
|
"Staffing and cost": staffing_and_cost(deliverables),
|
|
"Validation": validation(deliverables),
|
|
"Findings and open questions": findings_and_questions(deliverables),
|
|
"Sources": sources(deliverables, catalogue),
|
|
}
|
|
headings = list(_HEADING.finditer(content))
|
|
title = content[: headings[0].start()].rstrip() if headings else content.rstrip()
|
|
summary = ""
|
|
for index, match in enumerate(headings):
|
|
if match.group(1).strip().lower() == SUMMARY.lower():
|
|
end = (
|
|
headings[index + 1].start()
|
|
if index + 1 < len(headings)
|
|
else len(content)
|
|
)
|
|
summary = content[match.end() : end].strip()
|
|
summary = summary.split(f"\n### {KEY_FIGURES}")[0].rstrip()
|
|
parts = [
|
|
title,
|
|
f"## {SUMMARY}\n\n{summary}\n\n### {KEY_FIGURES}\n\n{key_figures(deliverables)}",
|
|
*(f"## {heading}\n\n{written[heading]}" for heading in SECTIONS[1:]),
|
|
]
|
|
return "\n\n".join(part.rstrip() for part in parts if part.strip()) + "\n"
|