feat: working TOM agent
This commit is contained in:
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
|
||||
}
|
||||
Reference in New Issue
Block a user