335 lines
12 KiB
Python
335 lines
12 KiB
Python
"""The scope analyst's tools: completing the scope spec (ADR-0008).
|
|
|
|
The spec is kept in the scope Deliverable's working memory as plain data, seeded
|
|
from what the customer supplied. The analyst reads what is settled and what is
|
|
not, and records each value it settles with where the value came from. Code checks
|
|
every value against the catalogue as it is recorded, and writes the completed copy
|
|
and the information register from what is there when the Deliverable is submitted:
|
|
the spec the customer approves cannot disagree with what was recorded.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
from collections.abc import Mapping, MutableMapping, Sequence
|
|
from dataclasses import dataclass, field
|
|
from typing import Any
|
|
|
|
import yaml
|
|
|
|
from execution_engine.adk.runtime import ToolResult, ToolSpec
|
|
from execution_engine.scope import (
|
|
ANSWERED,
|
|
ASK,
|
|
ASSUMED,
|
|
DECIDE,
|
|
DIGESTED,
|
|
ESSENTIAL,
|
|
GIVEN,
|
|
IMPORTANT,
|
|
MARKERS,
|
|
NOT_APPLICABLE,
|
|
REQUEST,
|
|
SOURCES,
|
|
SUPPLIED,
|
|
UNDER_REVIEW,
|
|
Catalogue,
|
|
Scope,
|
|
ScopeError,
|
|
_fault,
|
|
_plain,
|
|
read_scope,
|
|
)
|
|
|
|
SCOPE_FILE = "scope.yaml" # the completed spec
|
|
SCOPE_DATA_FILE = "scope.json" # what every Specialist reads of it
|
|
SCOPE_KEY = "scope_spec" # working memory: the spec as it is being completed
|
|
REGISTER_HEADING = "Information register"
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Scoping:
|
|
"""What reading and completing a scope spec needs."""
|
|
|
|
catalogue: Catalogue
|
|
provider_values: Mapping[str, Sequence[str]] = field(default_factory=dict)
|
|
skill: str | None = None
|
|
|
|
|
|
def to_working(scope: Scope) -> dict[str, Any]:
|
|
"""A spec as working memory: plain data that survives a checkpoint."""
|
|
return {
|
|
"kind": scope.kind,
|
|
"values": dict(scope.values),
|
|
"states": dict(scope.states),
|
|
"sources": dict(scope.sources),
|
|
"notes": dict(scope.notes),
|
|
}
|
|
|
|
|
|
def from_working(memory: Mapping[str, Any], catalogue: Catalogue) -> Scope:
|
|
values = dict(memory.get("values") or {})
|
|
states = {
|
|
path: (memory.get("states") or {}).get(path, ASK)
|
|
for path in catalogue.fields
|
|
if path not in values
|
|
}
|
|
kind = values.get("engagement.kind")
|
|
return Scope(
|
|
catalogue,
|
|
str(kind) if kind in catalogue.kinds else None,
|
|
values=values,
|
|
states=states,
|
|
sources=dict(memory.get("sources") or {}),
|
|
notes=dict(memory.get("notes") or {}),
|
|
)
|
|
|
|
|
|
def working_from_completed(text: str, scoping: Scoping) -> dict[str, Any] | None:
|
|
"""A completed scope spec as working memory, with where each value came from.
|
|
None when it cannot be read: a Change request then drafts the scope afresh."""
|
|
try:
|
|
scope = read_scope(
|
|
text, scoping.catalogue, provider_values=scoping.provider_values
|
|
)
|
|
document = yaml.safe_load(text) or {}
|
|
except (ScopeError, yaml.YAMLError):
|
|
return None
|
|
recorded = document.get("provenance") if isinstance(document, Mapping) else None
|
|
scope.sources = {
|
|
path: str(source)
|
|
for path, source in (recorded or {}).items()
|
|
if path in scope.values and source in SOURCES
|
|
}
|
|
return to_working(scope)
|
|
|
|
|
|
def working_scope(working: MutableMapping[str, Any]) -> dict[str, Any]:
|
|
return working.setdefault(SCOPE_KEY, {"values": {}, "states": {}})
|
|
|
|
|
|
def unsettled(working: Mapping[str, Any], scoping: Scoping) -> list[str]:
|
|
"""The essential fields a submission may not leave unknown."""
|
|
scope = from_working(working.get(SCOPE_KEY) or {}, scoping.catalogue)
|
|
return [gap["field"] for gap in scope.gaps(ESSENTIAL)]
|
|
|
|
|
|
def attachments(working: Mapping[str, Any], scoping: Scoping) -> dict[str, str]:
|
|
"""The Deliverable's two files, written from what was recorded."""
|
|
scope = from_working(working.get(SCOPE_KEY) or {}, scoping.catalogue)
|
|
return {
|
|
SCOPE_FILE: yaml.safe_dump(
|
|
scope.completed(UNDER_REVIEW), sort_keys=False, allow_unicode=True
|
|
),
|
|
SCOPE_DATA_FILE: json.dumps(scope.for_context(), indent=2, ensure_ascii=False),
|
|
}
|
|
|
|
|
|
_FROM = {
|
|
SUPPLIED: "the scope spec",
|
|
DIGESTED: "the sources supplied",
|
|
REQUEST: "the request",
|
|
ANSWERED: "the customer's answer",
|
|
ASSUMED: "assumed",
|
|
}
|
|
|
|
|
|
def render_register(working: Mapping[str, Any], scoping: Scoping) -> str:
|
|
"""The information register, readiness and open questions, as markdown written
|
|
by code from what was recorded."""
|
|
scope = from_working(working.get(SCOPE_KEY) or {}, scoping.catalogue)
|
|
counts = scope.readiness()
|
|
lines = [
|
|
f"## {REGISTER_HEADING}",
|
|
"",
|
|
(
|
|
f"{counts[SUPPLIED]} stated by the customer, "
|
|
+ (
|
|
f"{counts[DIGESTED]} digested from the sources supplied, "
|
|
if counts.get(DIGESTED)
|
|
else ""
|
|
)
|
|
+ f"{counts[ANSWERED]} answered "
|
|
f"in conversation, {counts[ASSUMED]} assumed, {counts['unknown']} "
|
|
f"unknown, {counts[NOT_APPLICABLE]} not applicable."
|
|
),
|
|
"",
|
|
"| Field | Value | From |",
|
|
"| --- | --- | --- |",
|
|
]
|
|
for path, value in scope.values.items():
|
|
if path.startswith(("run.", "metadata.")):
|
|
continue
|
|
shown = (
|
|
json.dumps(value, ensure_ascii=False)
|
|
if isinstance(value, (list, dict))
|
|
else str(value)
|
|
)
|
|
shown = " ".join(shown.split()).replace("|", "\\|")
|
|
lines.append(f"| {path} | {shown[:200]} | {_FROM[scope.source(path)]} |")
|
|
assumed = scope.assumptions()
|
|
if assumed:
|
|
lines += [
|
|
"",
|
|
"### Assumptions",
|
|
"",
|
|
"| Id | Assumption | If it is wrong |",
|
|
"| --- | --- | --- |",
|
|
]
|
|
lines += [
|
|
f"| {item['id']} | {item['statement']} | {item['impact_if_invalid']} |"
|
|
for item in assumed
|
|
]
|
|
gaps = scope.gaps(ESSENTIAL, IMPORTANT)
|
|
if gaps:
|
|
lines += [
|
|
"",
|
|
"### Still to confirm with the customer",
|
|
"",
|
|
"| Field | Question | Severity |",
|
|
"| --- | --- | --- |",
|
|
]
|
|
lines += [
|
|
f"| {gap['field']} | {gap['prompt']} | {gap['severity']} |" for gap in gaps
|
|
]
|
|
return "\n".join(lines) + "\n"
|
|
|
|
|
|
def scope_tools(working: MutableMapping[str, Any], scoping: Scoping) -> list[ToolSpec]:
|
|
catalogue = scoping.catalogue
|
|
|
|
async def scope_read() -> ToolResult:
|
|
scope = from_working(working_scope(working), catalogue)
|
|
counts = scope.readiness()
|
|
lines = [
|
|
f"Kind of engagement: {scope.kind or 'not settled'}",
|
|
(
|
|
f"{counts[SUPPLIED]} stated, "
|
|
+ (f"{counts[DIGESTED]} digested, " if counts.get(DIGESTED) else "")
|
|
+ f"{counts[ANSWERED]} answered, "
|
|
f"{counts[ASSUMED]} assumed, {counts['unknown']} unknown."
|
|
),
|
|
]
|
|
for severity, title in (("HIGH", "Essential"), ("MEDIUM", "Important")):
|
|
gaps = [gap for gap in scope.gaps() if gap["severity"] == severity]
|
|
if gaps:
|
|
lines.append(f"{title}, not settled:")
|
|
lines += [f" {gap['field']}: {gap['prompt']}" for gap in gaps]
|
|
left = [
|
|
path
|
|
for path, state in scope.states.items()
|
|
if state == DECIDE and not path.startswith("run.")
|
|
]
|
|
if left:
|
|
lines.append("Left to you to decide: " + ", ".join(left))
|
|
lines.append("Settled: " + (", ".join(scope.values) or "nothing yet"))
|
|
return ToolResult("\n".join(lines))
|
|
|
|
async def scope_set(entries: Any = None) -> ToolResult:
|
|
if not isinstance(entries, list) or not entries:
|
|
return ToolResult("Refused: `entries` is a list of fields to record.")
|
|
memory = working_scope(working)
|
|
values, states = (
|
|
memory.setdefault("values", {}),
|
|
memory.setdefault("states", {}),
|
|
)
|
|
sources, notes = (
|
|
memory.setdefault("sources", {}),
|
|
memory.setdefault("notes", {}),
|
|
)
|
|
problems, done = [], []
|
|
for entry in entries:
|
|
if not isinstance(entry, Mapping):
|
|
problems.append("each entry needs a field")
|
|
continue
|
|
path = str(entry.get("field", ""))
|
|
spec = catalogue.fields.get(path)
|
|
if spec is None:
|
|
problems.append(f"{path} is not a field of the scope spec")
|
|
continue
|
|
source, value = str(entry.get("source", "")), entry.get("value")
|
|
note = " ".join(str(entry.get("note") or "").split())
|
|
if value in MARKERS:
|
|
if path in values and sources.get(path, SUPPLIED) in GIVEN:
|
|
problems.append(f"{path} was stated in the scope spec; it stays")
|
|
continue
|
|
values.pop(path, None)
|
|
states[path] = value
|
|
done.append(path)
|
|
continue
|
|
if source not in SOURCES or source in GIVEN:
|
|
problems.append(
|
|
f"{path}: `source` is request (the customer's request says it), "
|
|
"answered (they told you) or assumed (you chose)"
|
|
)
|
|
continue
|
|
if (
|
|
path in values
|
|
and sources.get(path, SUPPLIED) in GIVEN
|
|
and source != ANSWERED
|
|
):
|
|
problems.append(
|
|
f"{path} was stated in the scope spec; only the customer's own "
|
|
"answer changes it"
|
|
)
|
|
continue
|
|
if source == ASSUMED and not note:
|
|
problems.append(f"{path}: an assumption needs a note saying why")
|
|
continue
|
|
fault = _fault(spec, value, scoping.provider_values.get(path, ()))
|
|
if fault:
|
|
problems.append(f"{path}: {fault}")
|
|
continue
|
|
values[path] = _plain(value)
|
|
states.pop(path, None)
|
|
sources[path] = source
|
|
if note:
|
|
notes[path] = note
|
|
done.append(path)
|
|
message = f"Recorded {len(done)}: {', '.join(done) or 'none'}."
|
|
if problems:
|
|
message += " Not recorded: " + "; ".join(problems) + "."
|
|
return ToolResult(message)
|
|
|
|
return [
|
|
ToolSpec(
|
|
"scope_read",
|
|
"What the scope spec settles so far, and what is not settled, with the "
|
|
"question to ask for each.",
|
|
{"type": "object", "properties": {}, "required": []},
|
|
scope_read,
|
|
tier="execution",
|
|
),
|
|
ToolSpec(
|
|
"scope_set",
|
|
"Record fields of the scope spec. Each entry has `field`, `value`, "
|
|
"`source` (request, answered or assumed) and, for an assumption, a "
|
|
"`note` saying why. A `value` of ask, decide or not_applicable marks the "
|
|
"field instead. Record several fields in one call.",
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"entries": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"field": {"type": "string"},
|
|
"value": {},
|
|
"source": {
|
|
"type": "string",
|
|
"enum": [REQUEST, ANSWERED, ASSUMED],
|
|
},
|
|
"note": {"type": "string"},
|
|
},
|
|
"required": ["field", "value"],
|
|
},
|
|
}
|
|
},
|
|
"required": ["entries"],
|
|
},
|
|
scope_set,
|
|
tier="execution",
|
|
),
|
|
]
|