"""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 app.engine.runtime import ToolResult, ToolSpec from app.core.scope import ( ANSWERED, ASK, ASSUMED, DECIDE, ESSENTIAL, IMPORTANT, MARKERS, NOT_APPLICABLE, REQUEST, SOURCES, SUPPLIED, UNDER_REVIEW, Catalogue, Scope, ScopeError, _fault, _plain, read_scope, ) from app.core.chain import SCOPE_DATA_FILE, SCOPE_FILE 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", 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, {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, {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) == SUPPLIED: 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 == SUPPLIED: 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) == SUPPLIED 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", ), ]