feat: working TOM agent
This commit is contained in:
0
app/__init__.py
Normal file
0
app/__init__.py
Normal file
8
app/main.py
Normal file
8
app/main.py
Normal file
@@ -0,0 +1,8 @@
|
||||
"""The target operating model agent's entrypoint: `python -m app.main`."""
|
||||
|
||||
from execution_engine.main import serve
|
||||
|
||||
from app.operating_model.workflow import ROOT, build
|
||||
|
||||
if __name__ == "__main__":
|
||||
serve(build(ROOT), ROOT)
|
||||
0
app/operating_model/__init__.py
Normal file
0
app/operating_model/__init__.py
Normal file
153
app/operating_model/catalogue.py
Normal file
153
app/operating_model/catalogue.py
Normal file
@@ -0,0 +1,153 @@
|
||||
"""The capability catalogue and the register of frameworks it cites.
|
||||
|
||||
Both are files of the `operating-capabilities` Skill. Code reads them to check that
|
||||
every entry cites a registered framework, to propose the entries that apply to an
|
||||
operating spec, and to check that a Capability names an entry that exists.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
from app.operating_model import spec
|
||||
|
||||
SKILL = "operating-capabilities"
|
||||
|
||||
|
||||
class CatalogueError(ValueError):
|
||||
"""A catalogue or register that cannot be used; the message lists every fault."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Entry:
|
||||
id: str
|
||||
name: str
|
||||
domain: str
|
||||
purpose: str
|
||||
applies_when: Mapping[str, Any]
|
||||
follows_support_hours: bool
|
||||
typical_checks: tuple[str, ...]
|
||||
sources: tuple[Mapping[str, str], ...]
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Catalogue:
|
||||
entries: Mapping[str, Entry]
|
||||
frameworks: Mapping[str, Mapping[str, Any]]
|
||||
verified: bool # whether a person has checked the references
|
||||
|
||||
def applicable(self, scope: Mapping[str, Any]) -> list[str]:
|
||||
"""The entries that apply to an operating spec, in the catalogue's order.
|
||||
|
||||
A proposal: the Specialist decides, and says why one it leaves out does
|
||||
not apply.
|
||||
"""
|
||||
kinds = {str(item.get("kind")) for item in spec.items(scope)}
|
||||
frameworks = {
|
||||
str(name) for name in spec.value(scope, "compliance.frameworks") or []
|
||||
}
|
||||
sourcing = spec.value(scope, "sourcing.model")
|
||||
engagement = scope.get("kind") or spec.value(scope, "engagement.kind")
|
||||
found = []
|
||||
for entry in self.entries.values():
|
||||
when = entry.applies_when
|
||||
if (
|
||||
when.get("always")
|
||||
or kinds & set(when.get("item_kinds") or ())
|
||||
or frameworks & set(when.get("compliance") or ())
|
||||
or sourcing in (when.get("sourcing") or ())
|
||||
or engagement in (when.get("engagement_kinds") or ())
|
||||
):
|
||||
found.append(entry.id)
|
||||
return found
|
||||
|
||||
|
||||
def _mapping(path: Path) -> dict[str, Any]:
|
||||
data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
|
||||
if not isinstance(data, dict):
|
||||
raise CatalogueError(f"{path.name}: must be a mapping")
|
||||
return data
|
||||
|
||||
|
||||
def load(skill_dir: Path) -> Catalogue:
|
||||
"""Read the catalogue and its register from the Skill's folder, and check them."""
|
||||
register = _mapping(skill_dir / "assets" / "sources.yaml")
|
||||
frameworks = register.get("frameworks") or {}
|
||||
problems = [
|
||||
f"sources.yaml: {name} needs {field}"
|
||||
for name, framework in frameworks.items()
|
||||
for field in ("name", "publisher", "licence")
|
||||
if not (framework or {}).get(field)
|
||||
]
|
||||
raw = _mapping(skill_dir / "assets" / "catalogue.yaml").get("capabilities") or []
|
||||
entries: dict[str, Entry] = {}
|
||||
for index, item in enumerate(raw):
|
||||
where = f"catalogue.yaml[{index}]"
|
||||
if not isinstance(item, Mapping) or not item.get("id"):
|
||||
problems.append(f"{where}: needs an id")
|
||||
continue
|
||||
identifier = str(item["id"])
|
||||
where = f"catalogue.yaml: {identifier}"
|
||||
if identifier in entries:
|
||||
problems.append(f"{where} is listed more than once")
|
||||
problems += [
|
||||
f"{where} needs {field}"
|
||||
for field in ("name", "domain", "purpose", "applies_when")
|
||||
if not item.get(field)
|
||||
]
|
||||
sources = [s for s in item.get("sources") or [] if isinstance(s, Mapping)]
|
||||
if not sources:
|
||||
problems.append(f"{where} cites no source")
|
||||
for source in sources:
|
||||
if source.get("framework") not in frameworks:
|
||||
problems.append(
|
||||
f"{where} cites {source.get('framework')!r}, which is not in "
|
||||
"the register"
|
||||
)
|
||||
if not source.get("reference"):
|
||||
problems.append(
|
||||
f"{where} cites {source.get('framework')} with no reference"
|
||||
)
|
||||
entries[identifier] = Entry(
|
||||
id=identifier,
|
||||
name=str(item.get("name", "")),
|
||||
domain=str(item.get("domain", "")),
|
||||
purpose=str(item.get("purpose", "")),
|
||||
applies_when=dict(item.get("applies_when") or {}),
|
||||
follows_support_hours=bool(item.get("follows_support_hours")),
|
||||
typical_checks=tuple(str(c) for c in item.get("typical_checks") or ()),
|
||||
sources=tuple(
|
||||
{
|
||||
"framework": str(s.get("framework")),
|
||||
"reference": str(s.get("reference")),
|
||||
}
|
||||
for s in sources
|
||||
),
|
||||
)
|
||||
if problems:
|
||||
raise CatalogueError("; ".join(problems))
|
||||
return Catalogue(
|
||||
entries=entries,
|
||||
frameworks=dict(frameworks),
|
||||
verified=register.get("status") == "verified",
|
||||
)
|
||||
|
||||
|
||||
def cited(catalogue: Catalogue, entry_ids: Sequence[str]) -> list[str]:
|
||||
"""How the entries' sources are cited, one line a framework, for a reader."""
|
||||
by_framework: dict[str, list[str]] = {}
|
||||
for identifier in entry_ids:
|
||||
entry = catalogue.entries.get(identifier)
|
||||
for source in entry.sources if entry else ():
|
||||
references = by_framework.setdefault(source["framework"], [])
|
||||
if source["reference"] not in references:
|
||||
references.append(source["reference"])
|
||||
return [
|
||||
f"{catalogue.frameworks[name]['name']}: {'; '.join(references)}"
|
||||
for name, references in by_framework.items()
|
||||
]
|
||||
240
app/operating_model/chain.py
Normal file
240
app/operating_model/chain.py
Normal file
@@ -0,0 +1,240 @@
|
||||
"""The data files along the chain, and what each must hold.
|
||||
|
||||
operational-requirements.json what running the solution must achieve, each
|
||||
traced to what the customer stated
|
||||
capabilities.json what the operating organisation must be able to
|
||||
do, each serving requirements and covering Items
|
||||
target-operating-model.json who does it (see graph.py)
|
||||
verdicts.json the verdict on each Check
|
||||
|
||||
Each checker returns what is wrong, one entry per fault, so a Specialist can fix it
|
||||
and submit again. `upstream` is the Deliverables a submission builds on, by kind.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Callable, Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from app.operating_model import spec
|
||||
from app.operating_model.catalogue import Catalogue
|
||||
from app.operating_model.names import (
|
||||
CAPABILITIES_FILE,
|
||||
CAPABILITY_MODEL,
|
||||
CUSTOM,
|
||||
HOURS,
|
||||
OPERATIONAL_REQUIREMENTS,
|
||||
REQUIREMENTS_FILE,
|
||||
wider,
|
||||
)
|
||||
from app.operating_model.spec import Upstream
|
||||
|
||||
REQUIREMENT_KINDS = (
|
||||
"service_level",
|
||||
"process",
|
||||
"organisation",
|
||||
"tooling",
|
||||
"compliance",
|
||||
)
|
||||
DataCheck = Callable[[Mapping[str, str], Upstream | None], list[str]]
|
||||
|
||||
|
||||
def objects(text: str, name: str) -> tuple[list[dict[str, Any]], list[str]]:
|
||||
"""The file's entries, and what is wrong with it as a list of objects with ids."""
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError as exc:
|
||||
return [], [f"{name}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, list):
|
||||
return [], [f"{name}: must be a JSON list"]
|
||||
problems = [
|
||||
f"{name}[{index}]: must be an object with an id"
|
||||
for index, item in enumerate(data)
|
||||
if not isinstance(item, dict) or not str(item.get("id") or "").strip()
|
||||
]
|
||||
accepted = [
|
||||
item
|
||||
for item in data
|
||||
if isinstance(item, dict) and str(item.get("id") or "").strip()
|
||||
]
|
||||
seen = [str(item["id"]) for item in accepted]
|
||||
problems += [
|
||||
f"{name}: id {identifier} is used more than once"
|
||||
for identifier in sorted({i for i in seen if seen.count(i) > 1})
|
||||
]
|
||||
return accepted, problems
|
||||
|
||||
|
||||
def read(upstream: Upstream | None, kind: str, name: str) -> list[dict[str, Any]]:
|
||||
"""An upstream data file's entries; none when it is absent or unreadable."""
|
||||
text = ((upstream or {}).get(kind) or {}).get("attachments", {}).get(name, "")
|
||||
return objects(text, name)[0] if text else []
|
||||
|
||||
|
||||
def requirements(upstream: Upstream | None) -> list[dict[str, Any]]:
|
||||
return read(upstream, OPERATIONAL_REQUIREMENTS, REQUIREMENTS_FILE)
|
||||
|
||||
|
||||
def capabilities(upstream: Upstream | None) -> list[dict[str, Any]]:
|
||||
return read(upstream, CAPABILITY_MODEL, CAPABILITIES_FILE)
|
||||
|
||||
|
||||
def _strings(item: Mapping[str, Any], field: str) -> list[str]:
|
||||
found = item.get(field)
|
||||
return [str(entry) for entry in found] if isinstance(found, list) else []
|
||||
|
||||
|
||||
def check_requirements(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
"""Every Operational requirement is traced to what the customer stated, and
|
||||
everything they stated that binds is carried by one."""
|
||||
name = REQUIREMENTS_FILE
|
||||
entries, problems = objects(attachments[name], name)
|
||||
if not entries and not problems:
|
||||
return [f"{name}: lists no Operational requirements"]
|
||||
scope = spec.agreed(upstream)
|
||||
stated = set(spec.ids(spec.stated_requirements(scope)))
|
||||
# A business outcome may be what a requirement comes from. It need not be: what
|
||||
# shows each outcome is served is a Measure, checked on the operating model.
|
||||
outcomes = set(spec.ids(spec.business_outcomes(scope)))
|
||||
kept_true = set(spec.ids(spec.conditions(scope)))
|
||||
named: set[str] = set()
|
||||
for entry in entries:
|
||||
where = f"{name}: {entry['id']}"
|
||||
if not str(entry.get("statement") or "").strip():
|
||||
problems.append(f"{where} needs a statement")
|
||||
if entry.get("kind") not in REQUIREMENT_KINDS:
|
||||
problems.append(
|
||||
f"{where}: kind must be one of {', '.join(REQUIREMENT_KINDS)}"
|
||||
)
|
||||
sources = _strings(entry, "source")
|
||||
if not sources:
|
||||
problems.append(
|
||||
f"{where} has no source: name the stated requirement, the Condition "
|
||||
"or the field of the operating spec it comes from"
|
||||
)
|
||||
for source in sources:
|
||||
named.add(source)
|
||||
known = (
|
||||
source in stated
|
||||
or source in outcomes
|
||||
or source in kept_true
|
||||
or spec.settled(scope, source)
|
||||
)
|
||||
if scope and not known:
|
||||
problems.append(
|
||||
f"{where}: source {source} is not a stated requirement, a "
|
||||
"Condition or a settled field of the operating spec"
|
||||
)
|
||||
if scope:
|
||||
problems += [
|
||||
f"{name}: the customer's requirement {identifier} is carried by no "
|
||||
"Operational requirement"
|
||||
for identifier in sorted(stated - named)
|
||||
]
|
||||
problems += [
|
||||
f"{name}: the customer stated {path}, and no Operational requirement "
|
||||
"names it as a source"
|
||||
for path in spec.binding(scope)
|
||||
if path not in named
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_capabilities(catalogue: Catalogue) -> DataCheck:
|
||||
"""Every Capability comes from the catalogue, serves a requirement and covers
|
||||
Items; every Item is covered and every requirement served."""
|
||||
|
||||
def check(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]:
|
||||
name = CAPABILITIES_FILE
|
||||
entries, problems = objects(attachments[name], name)
|
||||
if not entries and not problems:
|
||||
return [f"{name}: lists no Capabilities"]
|
||||
scope = spec.agreed(upstream)
|
||||
known_items = set(spec.ids(spec.items(scope)))
|
||||
known_requirements = {str(r["id"]) for r in requirements(upstream)}
|
||||
support = spec.value(scope, "operations.support_hours")
|
||||
covered: set[str] = set()
|
||||
served: set[str] = set()
|
||||
for entry in entries:
|
||||
where = f"{name}: {entry['id']}"
|
||||
entry_id = entry.get("catalogue")
|
||||
listed = catalogue.entries.get(str(entry_id))
|
||||
if entry_id == CUSTOM:
|
||||
if not str(entry.get("reason") or "").strip():
|
||||
problems.append(f"{where} is custom and gives no reason")
|
||||
if not str(entry.get("name") or "").strip():
|
||||
problems.append(f"{where} is custom and needs a name")
|
||||
elif listed is None:
|
||||
problems.append(
|
||||
f"{where}: {entry_id!r} is not in the capability catalogue; "
|
||||
f"use an entry's id, or {CUSTOM} with a reason"
|
||||
)
|
||||
serves, on = _strings(entry, "serves"), _strings(entry, "items")
|
||||
if not serves:
|
||||
problems.append(f"{where} serves no Operational requirement")
|
||||
served.update(serves)
|
||||
covered.update(on)
|
||||
if upstream is not None:
|
||||
problems += [
|
||||
f"{where} serves {identifier}, which is not an Operational requirement"
|
||||
for identifier in serves
|
||||
if identifier not in known_requirements
|
||||
]
|
||||
problems += [
|
||||
f"{where} covers {identifier}, which is not an Item of the operating spec"
|
||||
for identifier in on
|
||||
if identifier not in known_items
|
||||
]
|
||||
hours = entry.get("hours")
|
||||
if hours not in HOURS:
|
||||
problems.append(f"{where}: hours must be one of {', '.join(HOURS)}")
|
||||
elif (
|
||||
listed is not None
|
||||
and listed.follows_support_hours
|
||||
and support in HOURS
|
||||
and wider(str(support), str(hours))
|
||||
):
|
||||
problems.append(
|
||||
f"{where}: faults are responded to {support}, and {listed.name} "
|
||||
f"is staffed only {hours}"
|
||||
)
|
||||
effort = entry.get("effort_hours_per_month")
|
||||
if (
|
||||
isinstance(effort, bool)
|
||||
or not isinstance(effort, (int, float))
|
||||
or effort <= 0
|
||||
):
|
||||
problems.append(
|
||||
f"{where}: effort_hours_per_month must be a number above zero"
|
||||
)
|
||||
if not str(entry.get("basis") or "").strip():
|
||||
problems.append(f"{where} needs a basis for its effort")
|
||||
if upstream is not None:
|
||||
problems += [
|
||||
f"{name}: Item {identifier} is covered by no Capability"
|
||||
for identifier in sorted(known_items - covered)
|
||||
]
|
||||
problems += [
|
||||
f"{name}: Operational requirement {identifier} is served by no Capability"
|
||||
for identifier in sorted(known_requirements - served)
|
||||
]
|
||||
return problems
|
||||
|
||||
return check
|
||||
|
||||
|
||||
def names_of(
|
||||
capabilities_list: Sequence[Mapping[str, Any]], catalogue: Catalogue
|
||||
) -> dict[str, str]:
|
||||
"""Each Capability's name: its catalogue entry's, or its own when it is custom."""
|
||||
return {
|
||||
str(entry["id"]): (
|
||||
catalogue.entries[str(entry.get("catalogue"))].name
|
||||
if str(entry.get("catalogue")) in catalogue.entries
|
||||
else str(entry.get("name") or entry["id"])
|
||||
)
|
||||
for entry in capabilities_list
|
||||
}
|
||||
413
app/operating_model/digest.py
Normal file
413
app/operating_model/digest.py
Normal file
@@ -0,0 +1,413 @@
|
||||
"""Digesting a solution architecture into an operating spec, in code.
|
||||
|
||||
The solution architecture agent delivers its design as data files. This reads the
|
||||
ones an operating model depends on and writes the operating spec's fields from
|
||||
them: nothing is summarised and nothing is guessed, so what is digested can be
|
||||
counted against what was delivered.
|
||||
|
||||
components.json, products.json each component becomes an Item to be operated,
|
||||
target-architecture.json with the Elements that realise it
|
||||
requirements.json, what each says can only be shown in operation
|
||||
recommendations.json (`outside_code`) becomes a Condition
|
||||
verdicts.json a Check that failed or could not be verified
|
||||
becomes an inherited risk
|
||||
scope.json what the customer stated of operations, and of
|
||||
the solution, is carried across as stated
|
||||
work-breakdown.json, how long the build takes, and what the customer
|
||||
execution.json owns of it
|
||||
|
||||
An Item is a component, not a resource: an organisation operates a hybrid
|
||||
connectivity gateway, not each of its six routers and attachments. A Condition is
|
||||
what the architecture itself says infrastructure code cannot verify: an
|
||||
availability measured in operation, a recovery rehearsed. The settings its Checks
|
||||
verified at build are kept true by configuration management, and are not Conditions.
|
||||
|
||||
Only what the customer stated in the architecture's scope is carried across as
|
||||
stated. What that agent assumed for them is left to be asked again.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import math
|
||||
import re
|
||||
import sys
|
||||
from collections.abc import Mapping, Sequence
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import yaml
|
||||
from execution_engine.workflows.workflow import Digested
|
||||
|
||||
GRAPH = "target-architecture.json"
|
||||
COMPONENTS = "components.json"
|
||||
PRODUCTS = "products.json"
|
||||
REQUIREMENTS = "requirements.json"
|
||||
RECOMMENDATIONS = "recommendations.json"
|
||||
VERDICTS = "verdicts.json"
|
||||
SCOPE = "scope.json"
|
||||
PLAN = "work-breakdown.json"
|
||||
MANIFEST = "execution.json"
|
||||
# Every file the digest reads. A folder is read for these and nothing else.
|
||||
FILES = (
|
||||
MANIFEST,
|
||||
SCOPE,
|
||||
REQUIREMENTS,
|
||||
RECOMMENDATIONS,
|
||||
COMPONENTS,
|
||||
PRODUCTS,
|
||||
GRAPH,
|
||||
VERDICTS,
|
||||
PLAN,
|
||||
)
|
||||
DEFAULT_KIND = "service"
|
||||
SOURCE_PREFIX = "architecture:"
|
||||
_HOURS = {"business_hours": "business", "extended": "extended", "always": "24x7"}
|
||||
_NUMBER = re.compile(r"\d+(?:\.\d+)?")
|
||||
|
||||
|
||||
def _load(sources: Mapping[str, str], name: str) -> Any:
|
||||
if name not in sources:
|
||||
return None
|
||||
try:
|
||||
return json.loads(sources[name])
|
||||
except ValueError as exc:
|
||||
raise ValueError(f"{name}: not valid JSON ({exc})") from exc
|
||||
|
||||
|
||||
def _records(data: Any) -> list[dict[str, Any]]:
|
||||
return (
|
||||
[item for item in data if isinstance(item, dict)]
|
||||
if isinstance(data, list)
|
||||
else []
|
||||
)
|
||||
|
||||
|
||||
def _within(document: Any, path: str) -> Any:
|
||||
for part in path.split("."):
|
||||
if not isinstance(document, Mapping) or part not in document:
|
||||
return None
|
||||
document = document[part]
|
||||
return document
|
||||
|
||||
|
||||
def kind_of(product: str, item_kinds: Mapping[str, Sequence[str]]) -> str:
|
||||
"""What kind of thing a product is, by the words the provider bundle lists."""
|
||||
lowered = product.lower()
|
||||
for kind, words in item_kinds.items():
|
||||
if any(str(word).lower() in lowered for word in words):
|
||||
return kind
|
||||
return DEFAULT_KIND
|
||||
|
||||
|
||||
def item_kinds(root: Path, provider: str) -> dict[str, list[str]]:
|
||||
"""The provider bundle's table of what kind of thing each product is."""
|
||||
path = root / "providers" / f"{provider}.yaml"
|
||||
data = yaml.safe_load(path.read_text(encoding="utf-8")) if path.is_file() else {}
|
||||
kinds = ((data or {}).get("operating") or {}).get("item_kinds") or {}
|
||||
return {
|
||||
str(kind): [str(word) for word in words or []] for kind, words in kinds.items()
|
||||
}
|
||||
|
||||
|
||||
def architecture(
|
||||
sources: Mapping[str, str], kinds: Mapping[str, Sequence[str]] | None = None
|
||||
) -> Digested:
|
||||
"""The operating spec's fields, read from a solution architecture's data files.
|
||||
|
||||
Returns nothing digested when the sources are not a solution architecture.
|
||||
Raises ValueError, saying what is wrong, when they are one that cannot be used.
|
||||
"""
|
||||
if GRAPH not in sources:
|
||||
return Digested({})
|
||||
graph = _load(sources, GRAPH)
|
||||
if not isinstance(graph, dict) or not isinstance(graph.get("elements"), list):
|
||||
# A ValueError is what the engine turns into a refused start.
|
||||
raise ValueError( # noqa: TRY004
|
||||
f"{GRAPH}: must be an object with a list of elements"
|
||||
)
|
||||
manifest = _load(sources, MANIFEST) or {}
|
||||
if manifest and manifest.get("status", "completed") != "completed":
|
||||
raise ValueError(
|
||||
f"{MANIFEST}: the Execution did not complete ({manifest.get('status')}); "
|
||||
"an operating model is designed for an architecture that was approved"
|
||||
)
|
||||
elements = _records(graph["elements"])
|
||||
components = _records(_load(sources, COMPONENTS))
|
||||
product_of = {
|
||||
str(item.get("component")): str(item.get("product"))
|
||||
for item in _records(_load(sources, PRODUCTS))
|
||||
}
|
||||
kinds = kinds or {}
|
||||
notes: dict[str, str] = {}
|
||||
|
||||
# --- Items: one a component, with the Elements that realise it -------------------
|
||||
realised: dict[str, list[dict[str, Any]]] = {}
|
||||
for element in elements:
|
||||
realised.setdefault(str(element.get("component") or ""), []).append(element)
|
||||
if not components:
|
||||
components = [
|
||||
{"id": identifier, "name": identifier, "requirements": []}
|
||||
for identifier in realised
|
||||
if identifier
|
||||
]
|
||||
items: list[dict[str, Any]] = []
|
||||
item_of: dict[str, str] = {}
|
||||
for component in components:
|
||||
component_id = str(component.get("id"))
|
||||
own = realised.get(component_id, [])
|
||||
products = [str(e.get("product")) for e in own if e.get("product")]
|
||||
product = product_of.get(component_id) or (
|
||||
max(set(products), key=products.count) if products else ""
|
||||
)
|
||||
item_id = f"S-{len(items) + 1}"
|
||||
item_of[component_id] = item_id
|
||||
items.append(
|
||||
{
|
||||
"id": item_id,
|
||||
"name": str(component.get("name") or component_id),
|
||||
"kind": kind_of(product, kinds),
|
||||
**({"product": product} if product else {}),
|
||||
"source_ref": component_id,
|
||||
"elements": [str(e.get("id")) for e in own],
|
||||
}
|
||||
)
|
||||
loose = realised.get("", [])
|
||||
if loose:
|
||||
# Elements the architecture filed under no component are still operated.
|
||||
item_id = f"S-{len(items) + 1}"
|
||||
item_of[""] = item_id
|
||||
items.append(
|
||||
{
|
||||
"id": item_id,
|
||||
"name": "Resources outside any component",
|
||||
"kind": DEFAULT_KIND,
|
||||
"elements": [str(e.get("id")) for e in loose],
|
||||
}
|
||||
)
|
||||
if not items:
|
||||
raise ValueError(f"{GRAPH}: lists no Elements to operate")
|
||||
placed = sum(len(item["elements"]) for item in items)
|
||||
if placed != len(elements):
|
||||
unplaced = sorted(
|
||||
str(e.get("id"))
|
||||
for e in elements
|
||||
if str(e.get("component") or "") not in item_of
|
||||
)
|
||||
raise ValueError(
|
||||
f"{GRAPH}: these Elements name a component that {COMPONENTS} does not "
|
||||
f"have: {', '.join(unplaced)}"
|
||||
)
|
||||
notes["solution.items"] = (
|
||||
f"{len(items)} components of the solution architecture, standing for "
|
||||
f"{len(elements)} Elements"
|
||||
)
|
||||
|
||||
# --- Conditions: what can only be shown to hold in operation --------------------
|
||||
serving: dict[str, list[str]] = {}
|
||||
for component in components:
|
||||
for requirement in component.get("requirements") or []:
|
||||
serving.setdefault(str(requirement), []).append(str(component.get("id")))
|
||||
conditions: list[dict[str, Any]] = []
|
||||
stated = 0
|
||||
for name in (REQUIREMENTS, RECOMMENDATIONS):
|
||||
for entry in _records(_load(sources, name)):
|
||||
if entry.get("change") == "removed":
|
||||
continue
|
||||
entry_id = str(entry.get("id"))
|
||||
behind = [str(c) for c in entry.get("components") or []] or serving.get(
|
||||
entry_id, []
|
||||
)
|
||||
on = [item_of[c] for c in behind if c in item_of] or [
|
||||
str(i["id"]) for i in items
|
||||
]
|
||||
for statement in entry.get("outside_code") or []:
|
||||
stated += 1
|
||||
conditions.append(
|
||||
{
|
||||
"id": f"K-{len(conditions) + 1}",
|
||||
"on": on,
|
||||
"condition": " ".join(str(statement).split()),
|
||||
"source_ref": entry_id,
|
||||
}
|
||||
)
|
||||
if len(conditions) != stated:
|
||||
raise ValueError(
|
||||
"a condition the architecture leaves to operation was not placed"
|
||||
)
|
||||
if conditions:
|
||||
notes["solution.conditions"] = (
|
||||
f"{len(conditions)} conditions the solution architecture says cannot be "
|
||||
"verified from infrastructure code"
|
||||
)
|
||||
|
||||
# --- Inherited risks: Checks that did not pass ------------------------------------
|
||||
element_item = {
|
||||
str(e.get("id")): item_of.get(str(e.get("component") or ""), items[0]["id"])
|
||||
for e in elements
|
||||
}
|
||||
check_on = {
|
||||
str(check.get("id")): element_item.get(
|
||||
str(check.get("applies_to")), items[0]["id"]
|
||||
)
|
||||
for check in _records(graph.get("checks"))
|
||||
}
|
||||
statement_of = {
|
||||
str(check.get("id")): str(check.get("statement") or "")
|
||||
for check in _records(graph.get("checks"))
|
||||
}
|
||||
verdicts = _load(sources, VERDICTS) or {}
|
||||
risks = [
|
||||
{
|
||||
"on": check_on.get(str(item.get("check")), items[0]["id"]),
|
||||
"risk": (
|
||||
f"Check {item.get('check')} "
|
||||
+ (
|
||||
"failed"
|
||||
if item.get("verdict") == "fail"
|
||||
else "could not be verified"
|
||||
)
|
||||
+ f" in validation: {statement_of.get(str(item.get('check')), '')} "
|
||||
f"({' '.join(str(item.get('evidence') or '').split())})"
|
||||
).strip(),
|
||||
"source_ref": str(item.get("check")),
|
||||
}
|
||||
for item in _records(
|
||||
verdicts.get("checks") if isinstance(verdicts, dict) else None
|
||||
)
|
||||
if item.get("verdict") in ("fail", "not_verifiable")
|
||||
]
|
||||
|
||||
# --- What the customer stated, carried across as stated --------------------------
|
||||
scope = _load(sources, SCOPE) or {}
|
||||
said = scope.get("stated") if isinstance(scope, dict) else {}
|
||||
spec: dict[str, Any] = {
|
||||
"solution": {
|
||||
"items": items,
|
||||
**({"conditions": conditions} if conditions else {}),
|
||||
}
|
||||
}
|
||||
|
||||
def put(path: str, value: Any, note: str = "") -> None:
|
||||
if value in (None, "", [], {}):
|
||||
return
|
||||
node = spec
|
||||
*parents, last = path.split(".")
|
||||
for part in parents:
|
||||
node = node.setdefault(part, {})
|
||||
node[last] = value
|
||||
if note:
|
||||
notes[path] = note
|
||||
|
||||
if risks:
|
||||
put("solution.inherited_risks", risks, f"{VERDICTS}: Checks that did not pass")
|
||||
execution_id = manifest.get("execution_id")
|
||||
put("metadata.customer_case", manifest.get("customer_case"))
|
||||
put(
|
||||
"metadata.source",
|
||||
f"{SOURCE_PREFIX}{execution_id}"
|
||||
if execution_id
|
||||
else f"{SOURCE_PREFIX}unverified",
|
||||
"the Execution these files are of"
|
||||
if execution_id
|
||||
else f"no {MANIFEST} came with the files, so they are not known to be one "
|
||||
"completed Execution",
|
||||
)
|
||||
put("engagement.kind", scope.get("kind") if isinstance(scope, dict) else None)
|
||||
put(
|
||||
"intent.statement",
|
||||
manifest.get("workflow_request") or _within(said, "intent.statement"),
|
||||
"the request the solution architecture was designed for",
|
||||
)
|
||||
criteria = _within(said, "intent.success_criteria")
|
||||
put(
|
||||
"intent.business_outcomes",
|
||||
[
|
||||
{"id": f"BO-{n}", "outcome": " ".join(str(text).split())}
|
||||
for n, text in enumerate(criteria or [], start=1)
|
||||
if str(text).strip()
|
||||
]
|
||||
if isinstance(criteria, list)
|
||||
else None,
|
||||
f"{SCOPE}: the success criteria the customer stated",
|
||||
)
|
||||
put("solution.cloud_provider", _within(said, "estate.cloud_provider"))
|
||||
hours = _within(said, "operations.support_hours")
|
||||
put("operations.support_hours", _HOURS.get(str(hours)), f"{SCOPE}: {hours}")
|
||||
available = _within(said, "workload.availability.hours")
|
||||
put(
|
||||
"operations.availability_hours",
|
||||
_HOURS.get(str(available)),
|
||||
f"{SCOPE}: {available}",
|
||||
)
|
||||
put("operations.change_process", _within(said, "operations.change_process"))
|
||||
put("operations.monitoring", _within(said, "operations.monitoring"))
|
||||
put("compliance.frameworks", _within(said, "compliance.frameworks"))
|
||||
recovery = _NUMBER.search(
|
||||
str(_within(said, "workload.availability.recovery_time") or "")
|
||||
)
|
||||
put(
|
||||
"service_levels.recovery_time_hours",
|
||||
float(recovery.group()) if recovery else None,
|
||||
)
|
||||
currency = _within(said, "cost.currency")
|
||||
put("commercial.currency", currency if isinstance(currency, str) else None)
|
||||
|
||||
plan = manifest.get("delivery_plan") if isinstance(manifest, dict) else None
|
||||
days = (plan or {}).get("working_days")
|
||||
if isinstance(days, (int, float)) and not isinstance(days, bool):
|
||||
put(
|
||||
"solution.build.duration_days",
|
||||
math.ceil(days),
|
||||
"the build's computed length, in working days",
|
||||
)
|
||||
activities = _records((_load(sources, PLAN) or {}).get("activities"))
|
||||
put(
|
||||
"solution.build.customer_owned",
|
||||
[str(a.get("name")) for a in activities if a.get("owner") == "customer"],
|
||||
f"{PLAN}: the activities the customer owns",
|
||||
)
|
||||
return Digested(
|
||||
spec=spec, used=tuple(n for n in FILES if n in sources), notes=notes
|
||||
)
|
||||
|
||||
|
||||
def read_folder(folder: Path) -> dict[str, str]:
|
||||
"""The data files of an architecture Execution's folder that the digest reads."""
|
||||
return {
|
||||
name: (folder / name).read_text(encoding="utf-8")
|
||||
for name in FILES
|
||||
if (folder / name).is_file()
|
||||
}
|
||||
|
||||
|
||||
def main(arguments: Sequence[str]) -> int:
|
||||
"""`python -m app.operating_model.digest <folder> [provider]`: print the operating
|
||||
spec digested from an architecture Execution's folder, and what is left to settle."""
|
||||
from app.operating_model.workflow import ROOT
|
||||
|
||||
if not arguments:
|
||||
print(main.__doc__, file=sys.stderr)
|
||||
return 2
|
||||
folder = Path(arguments[0])
|
||||
provider = arguments[1] if len(arguments) > 1 else "gcp"
|
||||
sources = read_folder(folder)
|
||||
try:
|
||||
digested = architecture(sources, item_kinds(ROOT, provider))
|
||||
except ValueError as exc:
|
||||
print(f"Cannot digest {folder}: {exc}", file=sys.stderr)
|
||||
return 1
|
||||
if not digested.spec:
|
||||
print(
|
||||
f"{folder} holds no {GRAPH}: it is not a solution architecture.",
|
||||
file=sys.stderr,
|
||||
)
|
||||
return 1
|
||||
print(yaml.safe_dump(dict(digested.spec), sort_keys=False, allow_unicode=True))
|
||||
for path, note in digested.notes.items():
|
||||
print(f"# {path}: {note}", file=sys.stderr)
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv[1:]))
|
||||
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
|
||||
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"
|
||||
66
app/operating_model/names.py
Normal file
66
app/operating_model/names.py
Normal file
@@ -0,0 +1,66 @@
|
||||
"""The names this Workflow is written in: its Phases, its Deliverables and its files."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
# Phases, in order.
|
||||
SCOPING = "scoping"
|
||||
REQUIREMENTS = "operational_requirements"
|
||||
DESIGN = "operating_model_design"
|
||||
VALIDATION = "validation"
|
||||
PACKAGING = "packaging"
|
||||
PHASES = (SCOPING, REQUIREMENTS, DESIGN, VALIDATION, PACKAGING)
|
||||
|
||||
# Deliverable kinds.
|
||||
OPERATING_SCOPE = "operating_scope"
|
||||
OPERATIONAL_REQUIREMENTS = "operational_requirements"
|
||||
CAPABILITY_MODEL = "capability_model"
|
||||
TARGET_OPERATING_MODEL = "target_operating_model"
|
||||
VALIDATION_RESULTS = "validation_results"
|
||||
GUIDE = "operating_model_guide"
|
||||
|
||||
# Data files.
|
||||
SCOPE_DATA_FILE = "scope.json" # the engine's: what every Specialist reads of the spec
|
||||
REQUIREMENTS_FILE = "operational-requirements.json"
|
||||
CAPABILITIES_FILE = "capabilities.json"
|
||||
GRAPH_FILE = "target-operating-model.json"
|
||||
FINDINGS_FILE = "findings.json"
|
||||
STAFFING_FILE = "staffing.json"
|
||||
ORGANISATION_FILE = "organisation.mmd"
|
||||
VERDICTS_FILE = "verdicts.json"
|
||||
SCENARIOS_FILE = "scenarios.json"
|
||||
CHANGES_FILE = "changes.json"
|
||||
GUIDE_FILE = "operating-model-guide.md"
|
||||
CHANGE_REQUEST_FILE = "architecture-change-request.md"
|
||||
|
||||
# Hours a Capability must be staffed for and a Role works, narrowest first.
|
||||
HOURS = ("business", "extended", "24x7")
|
||||
PARTY_KINDS = ("customer", "provider", "supplier", "cloud_provider")
|
||||
CUSTOMER = "customer"
|
||||
ACCOUNTABLE, RESPONSIBLE, CONSULTED, INFORMED = (
|
||||
"accountable",
|
||||
"responsible",
|
||||
"consulted",
|
||||
"informed",
|
||||
)
|
||||
RESPONSIBILITY_KINDS = (ACCOUNTABLE, RESPONSIBLE, CONSULTED, INFORMED)
|
||||
CUSTOM = "custom" # a Capability the catalogue does not have
|
||||
# Team Topologies: the four kinds of team, and the three ways two teams work together.
|
||||
TEAM_TYPES = ("stream_aligned", "platform", "enabling", "complicated_subsystem")
|
||||
COLLABORATION, X_AS_A_SERVICE, FACILITATING = (
|
||||
"collaboration",
|
||||
"x_as_a_service",
|
||||
"facilitating",
|
||||
)
|
||||
INTERACTION_MODES = (COLLABORATION, X_AS_A_SERVICE, FACILITATING)
|
||||
# What a Measure tells about a business outcome. The first three are the layers of
|
||||
# measuring how work flows (DORA, SPACE, DevEx); none stands in for another.
|
||||
OUTCOME_LAYER, GUARDRAIL_LAYER, LEADING_LAYER = "outcome", "guardrail", "leading"
|
||||
DEVELOPER_LAYERS = (OUTCOME_LAYER, GUARDRAIL_LAYER, LEADING_LAYER)
|
||||
MEASURE_LAYERS = (*DEVELOPER_LAYERS, "service_level", "cost")
|
||||
# The catalogue entry whose measures must cover all three developer layers.
|
||||
MEASUREMENT_ENTRY = "delivery-and-developer-experience-measurement"
|
||||
|
||||
|
||||
def wider(first: str, second: str) -> bool:
|
||||
"""Whether `first` hours are wider than `second`."""
|
||||
return HOURS.index(first) > HOURS.index(second)
|
||||
346
app/operating_model/scenarios.py
Normal file
346
app/operating_model/scenarios.py
Normal file
@@ -0,0 +1,346 @@
|
||||
"""Scenario walk-throughs: events the operating model must be able to handle.
|
||||
|
||||
Infrastructure code can be validated by running it. An operating model cannot, so
|
||||
each scenario is generated from the graph and the operating spec and traced through
|
||||
the graph by code: is there a Capability for it, is someone responsible at the hours
|
||||
it happens, is one Role answerable. A broken path is a failed Check. No model writes
|
||||
a scenario or judges one.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from app.operating_model import spec
|
||||
from app.operating_model.catalogue import Catalogue
|
||||
from app.operating_model.names import (
|
||||
ACCOUNTABLE,
|
||||
CONSULTED,
|
||||
CUSTOMER,
|
||||
HOURS,
|
||||
RESPONSIBLE,
|
||||
wider,
|
||||
)
|
||||
|
||||
PREFIX = "SC-" # a scenario's id; the validator gives no verdict under it
|
||||
# The verdict on a Check that cannot hold until a finding is met. It is neither a
|
||||
# failure of the model nor a gap in it: nothing is revised for it, and it is
|
||||
# reported with the finding it waits on.
|
||||
WAITING = "waits_on_finding"
|
||||
HEADING = "Scenario walk-throughs"
|
||||
CHANGE_DOMAIN = "change"
|
||||
|
||||
|
||||
def _scenario(
|
||||
identifier: str, scenario: str, about: str, fault: str | None, path: str
|
||||
) -> dict[str, Any]:
|
||||
return {
|
||||
"id": f"{PREFIX}{identifier}",
|
||||
"scenario": scenario,
|
||||
"about": about,
|
||||
"passes": fault is None,
|
||||
"path": fault or path,
|
||||
}
|
||||
|
||||
|
||||
def walk(
|
||||
graph: Mapping[str, Sequence[Mapping[str, Any]]],
|
||||
capabilities: Sequence[Mapping[str, Any]],
|
||||
scope: Mapping[str, Any],
|
||||
catalogue: Catalogue,
|
||||
staffing: Mapping[str, Any] | None = None,
|
||||
) -> list[dict[str, Any]]:
|
||||
"""Every scenario for this operating model, traced."""
|
||||
roles = {str(r["id"]): r for r in graph["roles"]}
|
||||
parties = {str(p["id"]): p for p in graph["parties"]}
|
||||
by_capability: dict[str, list[Mapping[str, Any]]] = {}
|
||||
for item in graph["responsibilities"]:
|
||||
by_capability.setdefault(str(item.get("capability")), []).append(item)
|
||||
|
||||
def holders(capability: str, kind: str) -> list[Mapping[str, Any]]:
|
||||
return [
|
||||
roles[str(r["role"])]
|
||||
for r in by_capability.get(capability, [])
|
||||
if r.get("kind") == kind and str(r.get("role")) in roles
|
||||
]
|
||||
|
||||
def entry_of(capability: Mapping[str, Any]) -> Any:
|
||||
return catalogue.entries.get(str(capability.get("catalogue")))
|
||||
|
||||
def covering(item: str) -> list[Mapping[str, Any]]:
|
||||
return [c for c in capabilities if item in (c.get("items") or [])]
|
||||
|
||||
support = str(spec.value(scope, "operations.support_hours") or HOURS[0])
|
||||
found = []
|
||||
for item in spec.items(scope):
|
||||
item_id, label = str(item["id"]), f"{item.get('name')} ({item['id']})"
|
||||
|
||||
responders = [
|
||||
c
|
||||
for c in covering(item_id)
|
||||
if entry_of(c) and entry_of(c).follows_support_hours
|
||||
]
|
||||
fault = None
|
||||
if not responders:
|
||||
fault = "No Capability that responds to faults covers it."
|
||||
else:
|
||||
on_hours = [
|
||||
(c, role)
|
||||
for c in responders
|
||||
for role in holders(str(c["id"]), RESPONSIBLE)
|
||||
if str(role.get("hours")) in HOURS
|
||||
and not wider(support, str(role.get("hours")))
|
||||
]
|
||||
answerable = [c for c, _ in on_hours if holders(str(c["id"]), ACCOUNTABLE)]
|
||||
if not on_hours:
|
||||
fault = f"No Role responsible for responding works {support} hours."
|
||||
elif not answerable:
|
||||
fault = "The Capability that responds has no accountable Role."
|
||||
chosen = None if fault else on_hours[0]
|
||||
found.append(
|
||||
_scenario(
|
||||
f"fault-{item_id}",
|
||||
f"{label} fails at an hour faults are responded to ({support}).",
|
||||
item_id,
|
||||
fault,
|
||||
""
|
||||
if chosen is None
|
||||
else f"{chosen[1].get('name')} responds under {chosen[0]['id']}, and "
|
||||
f"{holders(str(chosen[0]['id']), ACCOUNTABLE)[0].get('name')} is "
|
||||
"answerable.",
|
||||
)
|
||||
)
|
||||
|
||||
changers = [
|
||||
c
|
||||
for c in covering(item_id)
|
||||
if entry_of(c)
|
||||
and entry_of(c).domain == CHANGE_DOMAIN
|
||||
and holders(str(c["id"]), RESPONSIBLE)
|
||||
]
|
||||
found.append(
|
||||
_scenario(
|
||||
f"change-{item_id}",
|
||||
f"{label} must be changed.",
|
||||
item_id,
|
||||
None
|
||||
if changers
|
||||
else "No Capability for making changes covers it with a responsible Role.",
|
||||
""
|
||||
if not changers
|
||||
else f"{holders(str(changers[0]['id']), RESPONSIBLE)[0].get('name')} "
|
||||
f"makes the change under {changers[0]['id']}.",
|
||||
)
|
||||
)
|
||||
|
||||
capability_ids = {str(c["id"]) for c in capabilities}
|
||||
for condition in spec.conditions(scope):
|
||||
condition_id = str(condition["id"])
|
||||
carrying = [k for k in graph["checks"] if k.get("source") == condition_id]
|
||||
kept = [
|
||||
k
|
||||
for k in carrying
|
||||
if str(k.get("on")) not in capability_ids
|
||||
or holders(str(k.get("on")), RESPONSIBLE)
|
||||
]
|
||||
found.append(
|
||||
_scenario(
|
||||
f"condition-{condition_id}",
|
||||
f"Condition {condition_id} must be shown to hold: "
|
||||
f"{condition.get('condition')}",
|
||||
condition_id,
|
||||
None
|
||||
if kept
|
||||
else (
|
||||
"No Check carries it."
|
||||
if not carrying
|
||||
else "The Check that carries it is on a Capability nobody is responsible for."
|
||||
),
|
||||
""
|
||||
if not kept
|
||||
else f"Check {kept[0]['id']} on {kept[0].get('on')} keeps it true.",
|
||||
)
|
||||
)
|
||||
|
||||
for party in graph["parties"]:
|
||||
if party.get("kind") == CUSTOMER:
|
||||
continue
|
||||
party_id = str(party["id"])
|
||||
stranded = [
|
||||
str(c["id"])
|
||||
for c in capabilities
|
||||
if any(
|
||||
a.get("party") == party_id for a in holders(str(c["id"]), ACCOUNTABLE)
|
||||
)
|
||||
and not any(
|
||||
parties.get(str(role.get("party")), {}).get("id") != party_id
|
||||
for kind in (RESPONSIBLE, CONSULTED)
|
||||
for role in holders(str(c["id"]), kind)
|
||||
)
|
||||
]
|
||||
found.append(
|
||||
_scenario(
|
||||
f"party-{party_id}",
|
||||
f"{party.get('name')} cannot be reached.",
|
||||
party_id,
|
||||
None
|
||||
if not stranded
|
||||
else "No Role in another Party is responsible or consulted for "
|
||||
+ ", ".join(stranded)
|
||||
+ ".",
|
||||
"Every Capability it is answerable for has a Role in another Party to turn to.",
|
||||
)
|
||||
)
|
||||
|
||||
budget = spec.value(scope, "commercial.monthly_run_budget")
|
||||
if (
|
||||
staffing is not None
|
||||
and isinstance(budget, (int, float))
|
||||
and not isinstance(budget, bool)
|
||||
):
|
||||
cost, currency = staffing["cost_per_month"], staffing["currency"]
|
||||
found.append(
|
||||
_scenario(
|
||||
"budget",
|
||||
f"A month's cost of operating is compared with the budget of {round(budget):,} {currency}.",
|
||||
"commercial.monthly_run_budget",
|
||||
None
|
||||
if cost <= budget
|
||||
else f"The cost is {cost:,} {currency}, over the budget.",
|
||||
f"The cost is {cost:,} {currency}, within the budget.",
|
||||
)
|
||||
)
|
||||
return found
|
||||
|
||||
|
||||
def as_verdicts(scenarios: Sequence[Mapping[str, Any]]) -> list[dict[str, str]]:
|
||||
return [
|
||||
{
|
||||
"check": str(item["id"]),
|
||||
"verdict": "pass" if item["passes"] else "fail",
|
||||
"evidence": f"{item['scenario']} {item['path']}",
|
||||
}
|
||||
for item in scenarios
|
||||
]
|
||||
|
||||
|
||||
def merge(
|
||||
verdicts_text: str,
|
||||
scenarios: Sequence[Mapping[str, Any]],
|
||||
waiting: Mapping[str, str] | None = None,
|
||||
) -> str:
|
||||
"""verdicts.json with the scenarios' verdicts in it, written by code.
|
||||
|
||||
The validator's verdicts on the Checks are kept as given, but for one thing:
|
||||
a Check in `waiting`, which names the finding it depends on, is recorded as
|
||||
waiting on that finding. The overall run is the walk-through: it passes when
|
||||
every scenario does.
|
||||
"""
|
||||
try:
|
||||
data = json.loads(verdicts_text)
|
||||
except ValueError:
|
||||
data = {}
|
||||
if not isinstance(data, dict):
|
||||
data = {}
|
||||
given = [
|
||||
(
|
||||
{**item, "verdict": WAITING, "finding": waiting[str(item.get("check"))]}
|
||||
# Only where the validator found the finding stands. One it failed is
|
||||
# something the operating model can provide itself, and is a fault in it.
|
||||
if waiting
|
||||
and str(item.get("check")) in waiting
|
||||
and item.get("verdict") in ("not_verifiable", WAITING)
|
||||
else item
|
||||
)
|
||||
for item in data.get("checks") or []
|
||||
if isinstance(item, dict) and not str(item.get("check", "")).startswith(PREFIX)
|
||||
]
|
||||
failed = [item for item in scenarios if not item["passes"]]
|
||||
return json.dumps(
|
||||
{
|
||||
"dry_run": {
|
||||
"verdict": "fail" if failed else "pass",
|
||||
"evidence": f"{len(scenarios) - len(failed)} of {len(scenarios)} "
|
||||
"scenario walk-throughs pass.",
|
||||
},
|
||||
"checks": [*given, *as_verdicts(scenarios)],
|
||||
"proposed_additions": data.get("proposed_additions") or [],
|
||||
},
|
||||
indent=2,
|
||||
ensure_ascii=False,
|
||||
)
|
||||
|
||||
|
||||
def render(scenarios: Sequence[Mapping[str, Any]]) -> str:
|
||||
lines = [
|
||||
f"## {HEADING}",
|
||||
"",
|
||||
(
|
||||
"Each scenario is generated from the operating model and traced through "
|
||||
"it by code."
|
||||
),
|
||||
"",
|
||||
"| Scenario | Result | Path |",
|
||||
"| --- | --- | --- |",
|
||||
]
|
||||
lines += [
|
||||
f"| {item['scenario']} | {'pass' if item['passes'] else '**fail**'} | {item['path']} |"
|
||||
for item in scenarios
|
||||
]
|
||||
return "\n".join(lines) + "\n"
|
||||
|
||||
|
||||
def check_verdicts(
|
||||
attachments: Mapping[str, str],
|
||||
graph: Mapping[str, Sequence[Mapping[str, Any]]] | None,
|
||||
name: str,
|
||||
) -> list[str]:
|
||||
"""What is wrong with the validator's verdicts: one on every Check, none on a
|
||||
scenario, and never a pass on a Check that depends on a finding."""
|
||||
try:
|
||||
data = json.loads(attachments[name])
|
||||
except ValueError as exc:
|
||||
return [f"{name}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, dict) or not isinstance(data.get("checks"), list):
|
||||
return [f"{name}: must be an object with a list of checks"]
|
||||
problems = []
|
||||
given: dict[str, str] = {}
|
||||
for index, item in enumerate(data["checks"]):
|
||||
where = f"{name}: checks[{index}]"
|
||||
if not isinstance(item, dict) or not item.get("check"):
|
||||
problems.append(f"{where} needs a check")
|
||||
continue
|
||||
identifier = str(item["check"])
|
||||
if identifier.startswith(PREFIX):
|
||||
continue # the walk-throughs' own, written by code on an earlier attempt
|
||||
if item.get("verdict") == WAITING:
|
||||
# Recorded by code on an earlier attempt; the validator's own verdict
|
||||
# on such a Check is not_verifiable.
|
||||
item = {**item, "verdict": "not_verifiable"}
|
||||
if item.get("verdict") not in ("pass", "fail", "not_verifiable"):
|
||||
problems.append(
|
||||
f"{where} ({identifier}): verdict must be pass, fail or not_verifiable"
|
||||
)
|
||||
if not str(item.get("evidence") or "").strip():
|
||||
problems.append(f"{where} ({identifier}) needs evidence")
|
||||
given[identifier] = str(item.get("verdict"))
|
||||
for check in (graph or {}).get("checks", []):
|
||||
identifier = str(check["id"])
|
||||
if identifier not in given:
|
||||
problems.append(f"{name}: Check {identifier} has no verdict")
|
||||
elif check.get("depends_on_finding") and given[identifier] == "pass":
|
||||
problems.append(
|
||||
f"{name}: Check {identifier} depends on finding "
|
||||
f"{check['depends_on_finding']}. It is not_verifiable while the finding "
|
||||
"stands, or fail when the operating model could meet it itself"
|
||||
)
|
||||
known = {str(check["id"]) for check in (graph or {}).get("checks", [])}
|
||||
if graph is not None:
|
||||
problems += [
|
||||
f"{name}: {identifier} is not a Check of the Target operating model"
|
||||
for identifier in given
|
||||
if identifier not in known
|
||||
]
|
||||
return problems
|
||||
89
app/operating_model/spec.py
Normal file
89
app/operating_model/spec.py
Normal file
@@ -0,0 +1,89 @@
|
||||
"""Reading the agreed operating spec, as every Specialist is given it.
|
||||
|
||||
The engine writes the spec's data file from what the scope analyst recorded: what
|
||||
the customer stated, nested by field; what was assumed for them, as a list; and
|
||||
which stated fields bind. Code that checks a Deliverable against the spec reads it
|
||||
here, and a value counts whichever of the two it came from.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Mapping
|
||||
from typing import Any
|
||||
|
||||
from app.operating_model.names import OPERATING_SCOPE, SCOPE_DATA_FILE
|
||||
|
||||
Upstream = Mapping[str, Mapping[str, Any]]
|
||||
|
||||
|
||||
def agreed(upstream: Upstream | None) -> dict[str, Any]:
|
||||
"""The agreed spec from the Deliverables a submission builds on; {} without one."""
|
||||
text = (
|
||||
((upstream or {}).get(OPERATING_SCOPE) or {})
|
||||
.get("attachments", {})
|
||||
.get(SCOPE_DATA_FILE, "")
|
||||
)
|
||||
try:
|
||||
data = json.loads(text) if text else {}
|
||||
except ValueError:
|
||||
return {}
|
||||
return data if isinstance(data, dict) else {}
|
||||
|
||||
|
||||
def value(scope: Mapping[str, Any], path: str, default: Any = None) -> Any:
|
||||
"""A field's value, stated or assumed; `default` when it is neither."""
|
||||
node: Any = scope.get("stated") or {}
|
||||
for part in path.split("."):
|
||||
if not isinstance(node, Mapping) or part not in node:
|
||||
node = None
|
||||
break
|
||||
node = node[part]
|
||||
if node is not None:
|
||||
return node
|
||||
for item in scope.get("assumed") or []:
|
||||
if isinstance(item, Mapping) and item.get("field") == path:
|
||||
return item.get("value", default)
|
||||
return default
|
||||
|
||||
|
||||
def settled(scope: Mapping[str, Any], path: str) -> bool:
|
||||
return value(scope, path) is not None
|
||||
|
||||
|
||||
def records(scope: Mapping[str, Any], path: str) -> list[dict[str, Any]]:
|
||||
found = value(scope, path)
|
||||
return (
|
||||
[dict(item) for item in found if isinstance(item, Mapping)]
|
||||
if isinstance(found, list)
|
||||
else []
|
||||
)
|
||||
|
||||
|
||||
def items(scope: Mapping[str, Any]) -> list[dict[str, Any]]:
|
||||
"""What is to be operated."""
|
||||
return records(scope, "solution.items")
|
||||
|
||||
|
||||
def conditions(scope: Mapping[str, Any]) -> list[dict[str, Any]]:
|
||||
"""What must be kept true of an Item while it is run."""
|
||||
return records(scope, "solution.conditions")
|
||||
|
||||
|
||||
def business_outcomes(scope: Mapping[str, Any]) -> list[dict[str, Any]]:
|
||||
"""What the customer's business wants from the solution, in their words: what
|
||||
every measure of operations is ultimately for."""
|
||||
return records(scope, "intent.business_outcomes")
|
||||
|
||||
|
||||
def stated_requirements(scope: Mapping[str, Any]) -> list[dict[str, Any]]:
|
||||
return records(scope, "intent.requirements")
|
||||
|
||||
|
||||
def binding(scope: Mapping[str, Any]) -> list[str]:
|
||||
"""The stated fields an operating model must honour."""
|
||||
return [str(path) for path in scope.get("binding") or []]
|
||||
|
||||
|
||||
def ids(entries: list[dict[str, Any]]) -> list[str]:
|
||||
return [str(entry["id"]) for entry in entries if entry.get("id")]
|
||||
280
app/operating_model/staffing.py
Normal file
280
app/operating_model/staffing.py
Normal file
@@ -0,0 +1,280 @@
|
||||
"""Staffing and cost, computed from the Target operating model and the rate card.
|
||||
|
||||
No agent writes a number of people or a cost. A Specialist says what each Capability
|
||||
takes in hours a month, which Roles are responsible for it, and where each Role sits
|
||||
and at what level. Everything else is arithmetic on the service provider's rate card,
|
||||
so the figures cannot disagree with the model they are about.
|
||||
|
||||
effort the hours a month of the Capabilities a Role is responsible for
|
||||
people effort over the productive hours of its country; and, where the
|
||||
Role covers hours wider than a working day, never fewer than the
|
||||
smallest team that can cover them
|
||||
cost a month people, at the day rate for its country and level, for the
|
||||
productive days in a month, with the uplift for its hours, in
|
||||
the currency the operating spec states
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
from app.operating_model.names import CUSTOMER, HOURS, RESPONSIBLE, wider
|
||||
|
||||
SKILL = "rate-card"
|
||||
BUSINESS = HOURS[0]
|
||||
|
||||
|
||||
class RateCardError(ValueError):
|
||||
"""A rate card that cannot be used; the message lists every fault."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Country:
|
||||
name: str
|
||||
productive_days: float
|
||||
hours_per_day: float
|
||||
day_rate: Mapping[str, float]
|
||||
|
||||
@property
|
||||
def productive_hours_a_month(self) -> float:
|
||||
return self.productive_days * self.hours_per_day / 12
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RateCard:
|
||||
name: str
|
||||
version: str
|
||||
currency: str # what its rates are written in
|
||||
conversion: Mapping[str, float] # units of a currency for one of `currency`
|
||||
conversion_as_of: str
|
||||
prices: tuple[str, ...] # the kinds of Party it prices
|
||||
levels: Mapping[str, str]
|
||||
cover: Mapping[str, Mapping[str, float]] # hours -> minimum_roster, uplift
|
||||
countries: Mapping[str, Country]
|
||||
|
||||
@property
|
||||
def is_draft(self) -> bool:
|
||||
return self.version.startswith("draft")
|
||||
|
||||
def currencies(self) -> list[str]:
|
||||
return sorted(self.conversion)
|
||||
|
||||
|
||||
def _number(value: Any) -> bool:
|
||||
return isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0
|
||||
|
||||
|
||||
def load(skill_dir: Path) -> RateCard:
|
||||
"""Read the rate card from the Skill's folder, and check it holds together."""
|
||||
path = skill_dir / "assets" / "rates.yaml"
|
||||
data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
|
||||
if not isinstance(data, dict):
|
||||
raise RateCardError("rates.yaml: must be a mapping")
|
||||
problems = [
|
||||
f"rates.yaml: needs {field}"
|
||||
for field in ("name", "version", "currency", "levels", "cover", "countries")
|
||||
if not data.get(field)
|
||||
]
|
||||
if problems:
|
||||
raise RateCardError("; ".join(problems))
|
||||
levels = {str(name): str(text) for name, text in data["levels"].items()}
|
||||
conversion_data = data.get("conversion") or {}
|
||||
rates = {str(k): v for k, v in (conversion_data.get("rates") or {}).items()}
|
||||
rates.setdefault(str(data["currency"]), 1.0)
|
||||
problems += [
|
||||
f"rates.yaml: the conversion rate for {name} must be a number above zero"
|
||||
for name, rate in rates.items()
|
||||
if not _number(rate)
|
||||
]
|
||||
prices = tuple(str(kind) for kind in data.get("prices") or ())
|
||||
if CUSTOMER in prices:
|
||||
problems.append(
|
||||
"rates.yaml: `prices` lists customer; the customer's own staff are "
|
||||
"never priced"
|
||||
)
|
||||
cover = {str(name): dict(entry or {}) for name, entry in data["cover"].items()}
|
||||
for hours in HOURS:
|
||||
entry = cover.get(hours) or {}
|
||||
if not _number(entry.get("minimum_roster")) or not _number(entry.get("uplift")):
|
||||
problems.append(
|
||||
f"rates.yaml: cover for {hours} needs a minimum_roster and an "
|
||||
"uplift, both above zero"
|
||||
)
|
||||
countries = {}
|
||||
for code, entry in data["countries"].items():
|
||||
entry = entry or {}
|
||||
where = f"rates.yaml: {code}"
|
||||
if not _number(entry.get("productive_days")) or not _number(
|
||||
entry.get("hours_per_day")
|
||||
):
|
||||
problems.append(f"{where} needs productive_days and hours_per_day")
|
||||
continue
|
||||
day_rate = entry.get("day_rate") or {}
|
||||
problems += [
|
||||
f"{where} has no day rate for level {level}"
|
||||
for level in levels
|
||||
if not _number(day_rate.get(level))
|
||||
]
|
||||
countries[str(code)] = Country(
|
||||
name=str(entry.get("name") or code),
|
||||
productive_days=float(entry["productive_days"]),
|
||||
hours_per_day=float(entry["hours_per_day"]),
|
||||
day_rate={str(k): float(v) for k, v in day_rate.items() if _number(v)},
|
||||
)
|
||||
if problems:
|
||||
raise RateCardError("; ".join(problems))
|
||||
return RateCard(
|
||||
name=str(data["name"]),
|
||||
version=str(data["version"]),
|
||||
currency=str(data["currency"]),
|
||||
conversion={name: float(rate) for name, rate in rates.items()},
|
||||
conversion_as_of=str(conversion_data.get("as_of") or ""),
|
||||
prices=prices,
|
||||
levels=levels,
|
||||
cover={
|
||||
name: {
|
||||
"minimum_roster": float(entry["minimum_roster"]),
|
||||
"uplift": float(entry["uplift"]),
|
||||
}
|
||||
for name, entry in cover.items()
|
||||
if name in HOURS
|
||||
},
|
||||
countries=countries,
|
||||
)
|
||||
|
||||
|
||||
def shares(
|
||||
responsibilities: Sequence[Mapping[str, Any]],
|
||||
) -> tuple[dict[tuple[str, str], float], list[str]]:
|
||||
"""Each responsible Role's share of each Capability's effort, and what is wrong
|
||||
with how shares were stated.
|
||||
|
||||
The Roles responsible for a Capability divide its effort equally, unless every
|
||||
one of them states a `share`, and the shares add up to 1.
|
||||
"""
|
||||
by_capability: dict[str, list[Mapping[str, Any]]] = {}
|
||||
for item in responsibilities:
|
||||
if item.get("kind") == RESPONSIBLE:
|
||||
by_capability.setdefault(str(item.get("capability")), []).append(item)
|
||||
result: dict[tuple[str, str], float] = {}
|
||||
problems = []
|
||||
for capability, entries in by_capability.items():
|
||||
stated = [e.get("share") for e in entries if e.get("share") is not None]
|
||||
if not stated:
|
||||
for entry in entries:
|
||||
result[(capability, str(entry.get("role")))] = 1 / len(entries)
|
||||
continue
|
||||
valid = all(
|
||||
isinstance(s, (int, float)) and not isinstance(s, bool) and 0 < s <= 1
|
||||
for s in stated
|
||||
)
|
||||
if len(stated) != len(entries) or not valid:
|
||||
problems.append(
|
||||
f"the Roles responsible for {capability} must all state a share "
|
||||
"between 0 and 1, or none of them"
|
||||
)
|
||||
continue
|
||||
total = sum(float(entry["share"]) for entry in entries)
|
||||
if abs(total - 1) > 0.001:
|
||||
problems.append(f"the shares of {capability} do not add up to 1")
|
||||
continue
|
||||
for entry in entries:
|
||||
result[(capability, str(entry.get("role")))] = float(entry["share"])
|
||||
return result, problems
|
||||
|
||||
|
||||
def compute(
|
||||
graph: Mapping[str, Any],
|
||||
capabilities: Sequence[Mapping[str, Any]],
|
||||
card: RateCard,
|
||||
currency: str,
|
||||
) -> dict[str, Any]:
|
||||
"""People and cost per Role, and the totals. The graph is taken to be sound:
|
||||
`graph.check` refuses one whose Roles the card cannot price."""
|
||||
parties = {str(p.get("id")): p for p in graph.get("parties") or []}
|
||||
effort_of = {
|
||||
str(c["id"]): float(c.get("effort_hours_per_month") or 0) for c in capabilities
|
||||
}
|
||||
hours_of = {str(c["id"]): str(c.get("hours") or BUSINESS) for c in capabilities}
|
||||
share_of, _ = shares(graph.get("responsibilities") or [])
|
||||
rate = card.conversion[currency]
|
||||
|
||||
rows: list[dict[str, Any]] = []
|
||||
by_capability: dict[str, float] = {}
|
||||
for role in graph.get("roles") or []:
|
||||
role_id = str(role.get("id"))
|
||||
country = card.countries[str(role.get("country"))]
|
||||
own = {cap: share for (cap, who), share in share_of.items() if who == role_id}
|
||||
effort = float(
|
||||
sum(effort_of.get(cap, 0.0) * share for cap, share in own.items())
|
||||
)
|
||||
hours = BUSINESS
|
||||
for cap in own:
|
||||
if wider(hours_of.get(cap, BUSINESS), hours):
|
||||
hours = hours_of[cap]
|
||||
people = effort / country.productive_hours_a_month
|
||||
if hours != BUSINESS:
|
||||
# A rota is sized by the hours it must fill, not by the work done in them.
|
||||
people = max(people, card.cover[hours]["minimum_roster"])
|
||||
party = parties.get(str(role.get("party")), {})
|
||||
priced = party.get("kind") != CUSTOMER and party.get("kind") in card.prices
|
||||
cost = (
|
||||
people
|
||||
* country.day_rate[str(role.get("level"))]
|
||||
* country.productive_days
|
||||
/ 12
|
||||
* card.cover[hours]["uplift"]
|
||||
* rate
|
||||
if priced
|
||||
else None
|
||||
)
|
||||
if cost is not None and effort:
|
||||
for cap, share in own.items():
|
||||
portion = effort_of.get(cap, 0.0) * share / effort
|
||||
by_capability[cap] = by_capability.get(cap, 0.0) + cost * portion
|
||||
rows.append(
|
||||
{
|
||||
"role": role_id,
|
||||
"name": str(role.get("name") or role_id),
|
||||
"party": str(role.get("party")),
|
||||
"party_name": str(party.get("name") or role.get("party")),
|
||||
"country": str(role.get("country")),
|
||||
"level": str(role.get("level")),
|
||||
"hours": hours,
|
||||
"effort_hours_per_month": round(effort, 1),
|
||||
"people": round(people, 1),
|
||||
"cost_per_month": None if cost is None else round(cost),
|
||||
}
|
||||
)
|
||||
|
||||
def total(key: str) -> dict[str, int]:
|
||||
sums: dict[str, float] = {}
|
||||
for row in rows:
|
||||
if row["cost_per_month"] is not None:
|
||||
sums[row[key]] = sums.get(row[key], 0.0) + row["cost_per_month"]
|
||||
return {name: round(amount) for name, amount in sums.items()}
|
||||
|
||||
return {
|
||||
"currency": currency,
|
||||
"rate_card": {
|
||||
"name": card.name,
|
||||
"version": card.version,
|
||||
"draft": card.is_draft,
|
||||
},
|
||||
"conversion": {
|
||||
"from": card.currency,
|
||||
"rate": rate,
|
||||
"as_of": card.conversion_as_of,
|
||||
},
|
||||
"roles": rows,
|
||||
"people": round(sum(row["people"] for row in rows), 1),
|
||||
"cost_per_month": round(sum(row["cost_per_month"] or 0 for row in rows)),
|
||||
"by_party": total("party"),
|
||||
"by_country": total("country"),
|
||||
"by_capability": {cap: round(amount) for cap, amount in by_capability.items()},
|
||||
}
|
||||
572
app/operating_model/workflow.py
Normal file
572
app/operating_model/workflow.py
Normal file
@@ -0,0 +1,572 @@
|
||||
"""The target operating model, as a Workflow for the Execution engine.
|
||||
|
||||
`build(root)` reads the capability catalogue and the rate card from the agent's
|
||||
Skills and returns the one value that makes the engine about this subject: the
|
||||
Phases and Deliverables, the checks along the chain, the graph and its views, the
|
||||
scenario walk-throughs that stand in for a dry run, and what a Change request
|
||||
changed.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Mapping
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.workflows.deliverables import DeliverableSpec
|
||||
from execution_engine.workflows.workflow import (
|
||||
Bench,
|
||||
CardText,
|
||||
ChangePolicy,
|
||||
ValidationPolicy,
|
||||
Workflow,
|
||||
)
|
||||
|
||||
from app.operating_model import catalogue as capability_catalogue
|
||||
from app.operating_model import chain, digest, graph, guide, scenarios, spec, staffing
|
||||
from app.operating_model.catalogue import Catalogue
|
||||
from app.operating_model.names import (
|
||||
CAPABILITIES_FILE,
|
||||
CAPABILITY_MODEL,
|
||||
CHANGE_REQUEST_FILE,
|
||||
CHANGES_FILE,
|
||||
DESIGN,
|
||||
FINDINGS_FILE,
|
||||
GRAPH_FILE,
|
||||
GUIDE,
|
||||
GUIDE_FILE,
|
||||
OPERATING_SCOPE,
|
||||
OPERATIONAL_REQUIREMENTS,
|
||||
PACKAGING,
|
||||
PHASES,
|
||||
REQUIREMENTS,
|
||||
REQUIREMENTS_FILE,
|
||||
SCENARIOS_FILE,
|
||||
SCOPE_DATA_FILE,
|
||||
SCOPING,
|
||||
STAFFING_FILE,
|
||||
TARGET_OPERATING_MODEL,
|
||||
VALIDATION,
|
||||
VALIDATION_RESULTS,
|
||||
VERDICTS_FILE,
|
||||
)
|
||||
from app.operating_model.spec import Upstream
|
||||
from app.operating_model.staffing import RateCard
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[2] # the agent's own folder
|
||||
SCOPE_FILE = "scope.yaml" # the engine's: the completed operating spec
|
||||
|
||||
ABOUT = (
|
||||
"I design target operating models. Give me the solution to be operated, as an "
|
||||
"operating spec or as a solution architecture to digest into one, and I will "
|
||||
"work through operational requirements, the Capabilities needed, who is "
|
||||
"accountable and responsible for each, staffing and cost, and a validation of "
|
||||
"the model against the events it must handle, asking for your approval at each "
|
||||
"Phase. Nothing was started for this message."
|
||||
)
|
||||
|
||||
|
||||
def _staffing(deliverables: Upstream) -> dict[str, Any] | None:
|
||||
text = (
|
||||
(deliverables.get(TARGET_OPERATING_MODEL) or {})
|
||||
.get("attachments", {})
|
||||
.get(STAFFING_FILE, "")
|
||||
)
|
||||
try:
|
||||
data = json.loads(text) if text else None
|
||||
except ValueError:
|
||||
return None
|
||||
return data if isinstance(data, dict) else None
|
||||
|
||||
|
||||
def _findings(deliverables: Upstream) -> list[dict[str, Any]]:
|
||||
return graph.findings(
|
||||
(deliverables.get(TARGET_OPERATING_MODEL) or {}).get("attachments", {})
|
||||
)
|
||||
|
||||
|
||||
def _waiting(deliverables: Upstream) -> dict[str, str]:
|
||||
"""The Checks that cannot hold until a finding is met, with the finding."""
|
||||
text = (
|
||||
(deliverables.get(VALIDATION_RESULTS) or {})
|
||||
.get("attachments", {})
|
||||
.get(VERDICTS_FILE, "")
|
||||
)
|
||||
try:
|
||||
data = json.loads(text) if text else {}
|
||||
except ValueError:
|
||||
return {}
|
||||
return {
|
||||
str(item.get("check")): str(item.get("finding"))
|
||||
for item in (data.get("checks") or [] if isinstance(data, dict) else [])
|
||||
if isinstance(item, dict) and item.get("verdict") == scenarios.WAITING
|
||||
}
|
||||
|
||||
|
||||
def approval_facts(phase: str, deliverables: Upstream) -> dict[str, Any]:
|
||||
"""This Workflow's own facts for an Approval summary: counts and cost, as data."""
|
||||
scope = spec.agreed(deliverables)
|
||||
model = graph.read(deliverables)
|
||||
facts: dict[str, Any] = {
|
||||
"counts": {
|
||||
name: count
|
||||
for name, count in (
|
||||
("items", len(spec.items(scope))),
|
||||
("conditions", len(spec.conditions(scope))),
|
||||
("business_outcomes", len(spec.business_outcomes(scope))),
|
||||
("operational_requirements", len(chain.requirements(deliverables))),
|
||||
("capabilities", len(chain.capabilities(deliverables))),
|
||||
("roles", len(model["roles"]) if model else 0),
|
||||
("checks", len(model["checks"]) if model else 0),
|
||||
("measures", len(model["measures"]) if model else 0),
|
||||
)
|
||||
if count
|
||||
}
|
||||
}
|
||||
cost = _staffing(deliverables)
|
||||
if cost:
|
||||
facts["staffing"] = {
|
||||
"people": cost["people"],
|
||||
"cost_per_month": cost["cost_per_month"],
|
||||
"currency": cost["currency"],
|
||||
"rate_card": cost["rate_card"],
|
||||
}
|
||||
found = _findings(deliverables)
|
||||
if found:
|
||||
facts["findings"] = [f"{item['id']}: {item.get('lacks')}" for item in found]
|
||||
waiting = _waiting(deliverables)
|
||||
if waiting:
|
||||
facts["checks_waiting_on_findings"] = waiting
|
||||
return facts
|
||||
|
||||
|
||||
def summary_lines(phase: str, facts: Mapping[str, Any]) -> list[str]:
|
||||
lines = []
|
||||
counts = facts.get("counts") or {}
|
||||
if counts:
|
||||
lines.append(
|
||||
", ".join(
|
||||
f"{count} {name.replace('_', ' ')}" for name, count in counts.items()
|
||||
)
|
||||
+ "."
|
||||
)
|
||||
cost = facts.get("staffing")
|
||||
if cost:
|
||||
lines.append(
|
||||
f"{cost['people']} people, {cost['cost_per_month']:,} {cost['currency']} "
|
||||
"a month"
|
||||
+ (
|
||||
", from placeholder prices."
|
||||
if cost["rate_card"]["draft"]
|
||||
else f", from rate card version {cost['rate_card']['version']}."
|
||||
)
|
||||
)
|
||||
found = facts.get("findings")
|
||||
if found:
|
||||
lines.append(
|
||||
f"{len(found)} findings for whoever owns the design: " + "; ".join(found)
|
||||
)
|
||||
waiting = facts.get("checks_waiting_on_findings")
|
||||
if waiting:
|
||||
lines.append(
|
||||
"Waiting on a finding, and so not yet shown to hold: "
|
||||
+ ", ".join(f"{check} ({finding})" for check, finding in waiting.items())
|
||||
+ "."
|
||||
)
|
||||
return lines
|
||||
|
||||
|
||||
def describe_approval(approval: Mapping[str, Any]) -> str:
|
||||
changes = approval.get("changes")
|
||||
if not changes:
|
||||
return ""
|
||||
lines = [
|
||||
f"This changes the operating model delivered in {approval.get('baseline')}."
|
||||
]
|
||||
lines += [
|
||||
f"- {word} {part.replace('_', ' ')}: {', '.join(ids)}"
|
||||
for part, by_change in changes.items()
|
||||
for word, ids in (
|
||||
("Added", by_change.get("added")),
|
||||
("Removed", by_change.get("removed")),
|
||||
("Changed", by_change.get("changed")),
|
||||
)
|
||||
if ids
|
||||
]
|
||||
return "\n".join(lines) + "\n\n"
|
||||
|
||||
|
||||
# --- what a Change request changed -----------------------------------------------------
|
||||
|
||||
_PARTS = {
|
||||
"operational_requirements": (OPERATIONAL_REQUIREMENTS, REQUIREMENTS_FILE, None),
|
||||
"capabilities": (CAPABILITY_MODEL, CAPABILITIES_FILE, None),
|
||||
"roles": (TARGET_OPERATING_MODEL, GRAPH_FILE, "roles"),
|
||||
"responsibilities": (TARGET_OPERATING_MODEL, GRAPH_FILE, "responsibilities"),
|
||||
"checks": (TARGET_OPERATING_MODEL, GRAPH_FILE, "checks"),
|
||||
}
|
||||
|
||||
|
||||
def _entries(deliverables: Upstream | None, part: str) -> dict[str, dict[str, Any]]:
|
||||
kind, name, within = _PARTS[part]
|
||||
text = ((deliverables or {}).get(kind) or {}).get("attachments", {}).get(name, "")
|
||||
if not text:
|
||||
return {}
|
||||
listed = graph.parse(text)[0][within] if within else chain.objects(text, name)[0]
|
||||
return {str(item["id"]): item for item in listed if item.get("id")}
|
||||
|
||||
|
||||
def change_summary(before: Upstream | None, after: Upstream) -> dict[str, Any]:
|
||||
"""What was added, removed and changed against the Baseline, by id."""
|
||||
summary = {}
|
||||
for part in _PARTS:
|
||||
was, now = _entries(before, part), _entries(after, part)
|
||||
summary[part] = {
|
||||
"added": sorted(set(now) - set(was)),
|
||||
"removed": sorted(set(was) - set(now)),
|
||||
"changed": sorted(k for k in set(was) & set(now) if was[k] != now[k]),
|
||||
}
|
||||
return summary
|
||||
|
||||
|
||||
def changes_empty(summary: Mapping[str, Any]) -> bool:
|
||||
return not any(ids for part in summary.values() for ids in part.values())
|
||||
|
||||
|
||||
def changes_in_words(summary: Mapping[str, Any]) -> str:
|
||||
part = summary.get("operational_requirements") or {}
|
||||
return "\n".join(
|
||||
f"Operational requirement {identifier} was {word}."
|
||||
for word in ("added", "changed", "removed")
|
||||
for identifier in part.get(word) or []
|
||||
)
|
||||
|
||||
|
||||
def changes_for(phase_kinds: list[str], summary: Mapping[str, Any]) -> dict[str, Any]:
|
||||
"""The parts of the summary that belong to a Phase's Deliverables."""
|
||||
return {
|
||||
part: change
|
||||
for part, change in summary.items()
|
||||
if _PARTS[part][0] in phase_kinds and any(change.values())
|
||||
}
|
||||
|
||||
|
||||
# --- the Workflow ----------------------------------------------------------------------
|
||||
|
||||
|
||||
def build(root: Path = ROOT) -> Workflow:
|
||||
"""The Workflow, for the capability catalogue and the rate card under `root`."""
|
||||
catalogue: Catalogue = capability_catalogue.load(
|
||||
root / "skills" / capability_catalogue.SKILL
|
||||
)
|
||||
card: RateCard = staffing.load(root / "skills" / staffing.SKILL)
|
||||
add_views = graph.views(catalogue, card)
|
||||
# Every provider's table of what kind of thing each product is, as one: the
|
||||
# digest names an Item's kind before the operating spec says which provider.
|
||||
kinds: dict[str, list[str]] = {}
|
||||
for bundle in sorted((root / "providers").glob("*.yaml")):
|
||||
for kind, words in digest.item_kinds(root, bundle.stem).items():
|
||||
kinds.setdefault(kind, []).extend(words)
|
||||
|
||||
def with_graph_views(
|
||||
bench: Bench, content: str, attachments: dict[str, str]
|
||||
) -> tuple[str, dict[str, str]]:
|
||||
return add_views(content, attachments, bench.upstream)
|
||||
|
||||
def check_verdicts(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
return scenarios.check_verdicts(
|
||||
attachments, graph.read(upstream), VERDICTS_FILE
|
||||
)
|
||||
|
||||
def with_scenarios(
|
||||
bench: Bench, content: str, attachments: dict[str, str]
|
||||
) -> tuple[str, dict[str, str]]:
|
||||
# The walk-throughs are generated and traced here, and their verdicts
|
||||
# written into the validator's file: no model judges one.
|
||||
upstream = bench.upstream or {}
|
||||
model = graph.read(upstream)
|
||||
if model is None:
|
||||
return content, attachments
|
||||
walked = scenarios.walk(
|
||||
model,
|
||||
chain.capabilities(upstream),
|
||||
spec.agreed(upstream),
|
||||
catalogue,
|
||||
_staffing(upstream),
|
||||
)
|
||||
attachments[SCENARIOS_FILE] = json.dumps(walked, indent=2, ensure_ascii=False)
|
||||
waiting = {
|
||||
str(check["id"]): str(check["depends_on_finding"])
|
||||
for check in model["checks"]
|
||||
if check.get("depends_on_finding")
|
||||
}
|
||||
attachments[VERDICTS_FILE] = scenarios.merge(
|
||||
attachments[VERDICTS_FILE], walked, waiting
|
||||
)
|
||||
content = content.split(f"\n## {scenarios.HEADING}")[0].rstrip()
|
||||
return content + "\n\n" + scenarios.render(walked), attachments
|
||||
|
||||
def with_guide_sections(
|
||||
bench: Bench, content: str, attachments: dict[str, str]
|
||||
) -> tuple[str, dict[str, str]]:
|
||||
return guide.assemble(content, bench.upstream or {}, catalogue), attachments
|
||||
|
||||
def check_ids(upstream: Upstream | None) -> list[str]:
|
||||
model = graph.read(upstream)
|
||||
return [str(item["id"]) for item in model["checks"]] if model else []
|
||||
|
||||
def known_ids(deliverables: Upstream) -> set[str]:
|
||||
return {str(r["id"]) for r in chain.requirements(deliverables)} | set(
|
||||
spec.ids(spec.conditions(spec.agreed(deliverables)))
|
||||
)
|
||||
|
||||
def approval_details(
|
||||
phase: str, deliverables: Upstream, baseline: Mapping[str, Any] | None
|
||||
) -> dict[str, Any]:
|
||||
if not baseline:
|
||||
return {}
|
||||
in_phase = [
|
||||
kind for kind, each in deliverable_specs.items() if each.phase == phase
|
||||
]
|
||||
return {
|
||||
"changes": changes_for(
|
||||
in_phase, change_summary(baseline.get("deliverables"), deliverables)
|
||||
)
|
||||
}
|
||||
|
||||
def task_entries(
|
||||
state: Mapping[str, Any], kind: str
|
||||
) -> tuple[dict[str, Any], dict[str, Any]]:
|
||||
context: dict[str, Any] = {
|
||||
# Which rate card the cost is worked from; its figures are placeholders
|
||||
# while its version is a draft.
|
||||
"rate_card": {"version": card.version, "draft": card.is_draft},
|
||||
}
|
||||
if kind == CAPABILITY_MODEL:
|
||||
# The catalogue's entries that apply to this operating spec, found by
|
||||
# code. Where to start: take each, or say why it does not apply.
|
||||
scope = spec.agreed(state.get("deliverables") or {})
|
||||
context["capabilities_proposed"] = catalogue.applicable(scope)
|
||||
if kind == TARGET_OPERATING_MODEL:
|
||||
context["rate_card"].update(
|
||||
countries=sorted(card.countries), levels=dict(card.levels)
|
||||
)
|
||||
return {}, context
|
||||
|
||||
def outputs(
|
||||
state: Mapping[str, Any], deliverables: Upstream, files: dict[str, str]
|
||||
) -> dict[str, Any]:
|
||||
cost = _staffing(deliverables)
|
||||
found = _findings(deliverables)
|
||||
if found:
|
||||
files[CHANGE_REQUEST_FILE] = change_request(state, found)
|
||||
return {
|
||||
"staffing": None
|
||||
if cost is None
|
||||
else {
|
||||
"people": cost["people"],
|
||||
"cost_per_month": cost["cost_per_month"],
|
||||
"currency": cost["currency"],
|
||||
"rate_card": cost["rate_card"],
|
||||
},
|
||||
"findings": [str(item["id"]) for item in found],
|
||||
"change_request": CHANGE_REQUEST_FILE if found else None,
|
||||
"capability_sources_verified": catalogue.verified,
|
||||
}
|
||||
|
||||
deliverable_specs = {
|
||||
each.kind: each
|
||||
for each in (
|
||||
DeliverableSpec(
|
||||
OPERATING_SCOPE,
|
||||
SCOPING,
|
||||
"scope-analyst",
|
||||
sections=("Scope statement",),
|
||||
attachments=(SCOPE_FILE, SCOPE_DATA_FILE),
|
||||
),
|
||||
DeliverableSpec(
|
||||
OPERATIONAL_REQUIREMENTS,
|
||||
REQUIREMENTS,
|
||||
"operations-analyst",
|
||||
depends_on=(OPERATING_SCOPE,),
|
||||
sections=("Operational requirements", "What was not stated"),
|
||||
attachments=(REQUIREMENTS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
CAPABILITY_MODEL,
|
||||
DESIGN,
|
||||
"capability-modeller",
|
||||
depends_on=(OPERATIONAL_REQUIREMENTS,),
|
||||
sections=("Capabilities", "Sources"),
|
||||
attachments=(CAPABILITIES_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
TARGET_OPERATING_MODEL,
|
||||
DESIGN,
|
||||
"operating-model-architect",
|
||||
depends_on=(CAPABILITY_MODEL,),
|
||||
# The Specialist writes the reasoning and the graph. On submission
|
||||
# code adds the responsibility matrix, the staffing and cost and
|
||||
# the findings to the content, and the organisation chart and the
|
||||
# staffing figures to the attachments.
|
||||
sections=("Design rationale",),
|
||||
attachments=(GRAPH_FILE,),
|
||||
graph=graph.SHAPE,
|
||||
),
|
||||
DeliverableSpec(
|
||||
VALIDATION_RESULTS,
|
||||
VALIDATION,
|
||||
"validator",
|
||||
depends_on=(TARGET_OPERATING_MODEL,),
|
||||
sections=("Check verdicts",),
|
||||
attachments=(VERDICTS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
GUIDE,
|
||||
PACKAGING,
|
||||
"packager",
|
||||
depends_on=(VALIDATION_RESULTS,),
|
||||
# The packager writes the summary; code writes every other
|
||||
# section from the data when the guide is submitted.
|
||||
sections=guide.SECTIONS,
|
||||
reads_in_full=(
|
||||
OPERATING_SCOPE,
|
||||
OPERATIONAL_REQUIREMENTS,
|
||||
CAPABILITY_MODEL,
|
||||
TARGET_OPERATING_MODEL,
|
||||
VALIDATION_RESULTS,
|
||||
),
|
||||
),
|
||||
)
|
||||
}
|
||||
|
||||
return Workflow(
|
||||
name="target-operating-model",
|
||||
about=ABOUT,
|
||||
phases=PHASES,
|
||||
deliverables=deliverable_specs,
|
||||
final=GUIDE,
|
||||
final_file=GUIDE_FILE,
|
||||
data_checks={
|
||||
OPERATIONAL_REQUIREMENTS: (REQUIREMENTS_FILE, chain.check_requirements),
|
||||
CAPABILITY_MODEL: (CAPABILITIES_FILE, chain.check_capabilities(catalogue)),
|
||||
TARGET_OPERATING_MODEL: (
|
||||
GRAPH_FILE,
|
||||
graph.check(card, catalogue.frameworks),
|
||||
),
|
||||
VALIDATION_RESULTS: (VERDICTS_FILE, check_verdicts),
|
||||
},
|
||||
for_readers={
|
||||
TARGET_OPERATING_MODEL: graph.MATRIX_HEADING,
|
||||
VALIDATION_RESULTS: scenarios.HEADING,
|
||||
},
|
||||
spec_deliverable=OPERATING_SCOPE,
|
||||
validation=ValidationPolicy(
|
||||
kind=VALIDATION_RESULTS,
|
||||
data_file=VERDICTS_FILE,
|
||||
# A failed Check is a fault in who does what: the graph is revised. One
|
||||
# that fails twice running is a fault in what the organisation must be
|
||||
# able to do: the capability model is.
|
||||
implementation=TARGET_OPERATING_MODEL,
|
||||
design=CAPABILITY_MODEL,
|
||||
check_ids=check_ids,
|
||||
known_ids=known_ids,
|
||||
),
|
||||
on_submit={
|
||||
TARGET_OPERATING_MODEL: with_graph_views,
|
||||
VALIDATION_RESULTS: with_scenarios,
|
||||
GUIDE: with_guide_sections,
|
||||
},
|
||||
approval_details=approval_details,
|
||||
approval_facts=approval_facts,
|
||||
summary_lines=summary_lines,
|
||||
describe_approval=describe_approval,
|
||||
agreed=lambda deliverables: json.dumps(chain.requirements(deliverables)),
|
||||
changes=ChangePolicy(
|
||||
file=CHANGES_FILE,
|
||||
summary=change_summary,
|
||||
is_empty=changes_empty,
|
||||
in_words=changes_in_words,
|
||||
),
|
||||
subject="a target operating model",
|
||||
describe_design=lambda deliverables: "\n".join(
|
||||
f"- {item.get('name')} ({item.get('kind')}, {item.get('product', '')})"
|
||||
for item in spec.items(spec.agreed(deliverables))
|
||||
),
|
||||
task_entries=task_entries,
|
||||
outputs=outputs,
|
||||
# A solution architecture's data files are read in code. Anything else a
|
||||
# caller supplies is a document for the scope analyst to read.
|
||||
digest=lambda sources: digest.architecture(sources, kinds),
|
||||
card=CardText(
|
||||
description=(
|
||||
"Designs a target operating model with you for a solution: "
|
||||
"operational requirements, the Capabilities needed, who is "
|
||||
"accountable and responsible, staffing and cost from a rate card, "
|
||||
"and a validation against the events it must handle."
|
||||
),
|
||||
skill_id="target-operating-model",
|
||||
skill_name="Target operating model",
|
||||
tags=("operations", "operating-model"),
|
||||
examples=(
|
||||
"Design the operating model for this landing zone, run as a managed service.",
|
||||
"Who runs this platform, at what cost, from which countries?",
|
||||
),
|
||||
),
|
||||
done="The target operating model is complete and approved.",
|
||||
)
|
||||
|
||||
|
||||
def change_request(state: Mapping[str, Any], found: list[dict[str, Any]]) -> str:
|
||||
"""The findings, as a request to whoever owns the design to change it.
|
||||
|
||||
Written by code from the findings. Where the operating spec was digested from a
|
||||
solution architecture, it is in the form that agent accepts as a Change request
|
||||
against the Execution it came from.
|
||||
"""
|
||||
values = ((state.get("scope") or {}).get("working") or {}).get("values") or {}
|
||||
source = str(values.get("metadata.source") or "")
|
||||
lines = ["# Changes operations needs to the solution", ""]
|
||||
if source:
|
||||
lines += [
|
||||
(
|
||||
f"The operating spec was digested from `{source}`. Send what follows to "
|
||||
"the solution architecture agent as a Change request against that "
|
||||
"Execution: the `baseline` is its id, in the same Customer case."
|
||||
),
|
||||
"",
|
||||
]
|
||||
else:
|
||||
lines += [
|
||||
(
|
||||
"The operating spec did not come from a solution architecture this "
|
||||
"agent can name. What follows is for whoever owns the design."
|
||||
),
|
||||
"",
|
||||
]
|
||||
lines += [
|
||||
(
|
||||
"Operating the solution as designed needs these changes to it. Each was "
|
||||
"found while designing its operating model; none was designed around."
|
||||
),
|
||||
"",
|
||||
]
|
||||
for item in found:
|
||||
about = ", ".join(
|
||||
str(i) for i in item.get("source_ref") or item.get("about") or []
|
||||
)
|
||||
lines += [
|
||||
f"## {item['id']}" + (f": {about}" if about else ""),
|
||||
"",
|
||||
f"**What is missing.** {item.get('lacks')}",
|
||||
"",
|
||||
f"**What is asked for.** {item.get('proposed')}",
|
||||
"",
|
||||
]
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
__all__ = ["FINDINGS_FILE", "ROOT", "build", "change_request", "change_summary"]
|
||||
Reference in New Issue
Block a user