"""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"]