Files
tom_analysis_agent/app/operating_model/guide.py

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"