Files
tom_analysis_agent/app/operating_model/workflow.py

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