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