573 lines
21 KiB
Python
573 lines
21 KiB
Python
"""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"]
|