Coverage for src/governed_harness/orchestration/intent_convergence.py: 100%

78 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-12 16:06 +0000

1"""The converging agent review of a task in INTENT (#79). 

2 

3In the 2.0.0 pilot the agent review raised new questions on every answered revision, so a run 

4under a small model never left INTENT. Under the object form of ``intake.ambiguityReview`` the 

5review converges: 

6 

7* the ``clarify`` request carries every question already asked about the task and the answer it 

8 got (``previousQuestions``), the round number and the limits, and asks only for blocking 

9 ambiguity that the latest revision introduced or left open; 

10* a question already asked (same rule and normalised text) is dropped, also within a round, and 

11 a round asks at most ``maxQuestions``; 

12* after ``maxRounds`` rounds a person answered, the points the agent still raises are recorded, 

13 under ``onExhausted: assume``, as explicit assumptions in a new task revision 

14 (``metadata.assumptions``), where the operational contract, the decision brief and the gate 

15 contract show them; under ``block`` they are asked again and INTENT stays blocked. 

16 

17A round is one clarification a person answered in this run that included agent questions 

18(rule ``A1``).""" 

19 

20from __future__ import annotations 

21 

22import re 

23from dataclasses import dataclass 

24from typing import TYPE_CHECKING, Any 

25 

26from governed_harness.configuration.agent_results import AmbiguityReviewConfig 

27from governed_harness.domain.models import ( 

28 ClarificationRecord, 

29 ClarificationRequest, 

30 Execution, 

31 Task, 

32) 

33from governed_harness.intake import task_digest 

34 

35if TYPE_CHECKING: 

36 from governed_harness.orchestration.hosts import ResultsHost 

37 

38AGENT_RULE = "A1" 

39ASSUMPTIONS_KEY = "assumptions" 

40MAX_HISTORY = 80 

41_HISTORY_TEXT = 500 

42_WORD = re.compile(r"[^\W_]+") 

43"""A run of letters or digits, in any script.""" 

44 

45CONVERGE_SUFFIX = ( 

46 "This is round {round} of at most {maxRounds} rounds of questions. previousQuestions lists " 

47 "every question already asked about this task and the answer it got (null when nobody " 

48 "answered it). Never ask again about a point a previous answer settles, in any wording. " 

49 "Ask only about blocking ambiguity that the latest revision introduced or left open: a " 

50 "point on which two reasonable implementations would behave differently in a way an " 

51 "acceptance test can observe. Do not ask about style, preferences or details the " 

52 "implementer can decide. Ask at most {maxQuestions} questions, the most blocking first; " 

53 "ask nothing when the task can be implemented and verified as it stands." 

54) 

55 

56ASSUMPTION_TEXT = ( 

57 "Not answered after {rounds} round(s) of clarification: the implementation takes the " 

58 "reading most consistent with the requirements and acceptance criteria and states the " 

59 "choice in its summary." 

60) 

61 

62Item = tuple[str, str, str] 

63"""``(category, target, text)`` of an agent question.""" 

64 

65 

66def normalized(text: str) -> str: 

67 """The words of a question in lower case, without punctuation or spacing differences.""" 

68 return " ".join(_WORD.findall(text.lower())) 

69 

70 

71@dataclass(frozen=True) 

72class Convergence: 

73 """What the converging review knows before a round: the settings, the questions asked about 

74 the task before this revision with their answers, and the rounds already answered.""" 

75 

76 settings: AmbiguityReviewConfig 

77 history: tuple[dict[str, Any], ...] 

78 seen: frozenset[tuple[str, str]] 

79 rounds: int 

80 

81 @property 

82 def round(self) -> int: 

83 return self.rounds + 1 

84 

85 @property 

86 def exhausted(self) -> bool: 

87 return self.rounds >= self.settings.rounds 

88 

89 def payload(self) -> dict[str, Any]: 

90 return { 

91 "previousQuestions": list(self.history[-MAX_HISTORY:]), 

92 "round": self.round, 

93 "maxRounds": self.settings.rounds, 

94 "maxQuestions": self.settings.questions, 

95 } 

96 

97 def suffix(self) -> str: 

98 return CONVERGE_SUFFIX.format( 

99 round=self.round, 

100 maxRounds=self.settings.rounds, 

101 maxQuestions=self.settings.questions, 

102 ) 

103 

104 def converge(self, items: list[Item]) -> tuple[list[Item], int]: 

105 """The questions of a round without those already asked (same rule and normalised 

106 text, also within the round), at most ``maxQuestions``; and how many were dropped.""" 

107 seen = set(self.seen) 

108 kept: list[Item] = [] 

109 for item in items: 

110 key = (AGENT_RULE, normalized(item[2])) 

111 if key in seen: 

112 continue 

113 seen.add(key) 

114 kept.append(item) 

115 bounded = kept[: self.settings.questions] 

116 return bounded, len(items) - len(bounded) 

117 

118 

119def _trimmed(text: str | None) -> str | None: 

120 return None if text is None else text[:_HISTORY_TEXT] 

121 

122 

123def convergence( 

124 results: ResultsHost, execution: Execution, task: Task, settings: AmbiguityReviewConfig 

125) -> Convergence: 

126 """The history of the task's questions and the rounds of this run (see the module).""" 

127 state = results.s.state 

128 digest = task_digest(task) 

129 records = [ 

130 item 

131 for item in state.list("clarification", ClarificationRecord, project_id=task.project_id) 

132 if item.task_id == task.task_id 

133 ] 

134 answered = { 

135 (record.request_id, answer.question_id): answer.answer 

136 for record in records 

137 for answer in record.answers 

138 } 

139 requests = sorted( 

140 ( 

141 item 

142 for item in state.list( 

143 "clarification_request", ClarificationRequest, project_id=task.project_id 

144 ) 

145 if item.task_id == task.task_id and item.task_digest != digest 

146 ), 

147 key=lambda item: item.created_at, 

148 ) 

149 history = tuple( 

150 { 

151 "ruleId": question.rule_id, 

152 "category": question.category, 

153 "target": question.target, 

154 "question": _trimmed(question.text), 

155 "answer": _trimmed(answered.get((request.request_id, question.question_id))), 

156 } 

157 for request in requests 

158 for question in request.questions 

159 ) 

160 seen = frozenset((str(item["ruleId"]), normalized(str(item["question"]))) for item in history) 

161 rounds = sum( 

162 1 

163 for record in records 

164 if record.execution_id == execution.execution_id 

165 and any(answer.rule_id == AGENT_RULE for answer in record.answers) 

166 ) 

167 return Convergence(settings, history, seen, rounds) 

168 

169 

170def assumptions_of(task: Task) -> list[dict[str, Any]]: 

171 """The assumptions a task revision records (``metadata.assumptions``).""" 

172 value = task.metadata.get(ASSUMPTIONS_KEY) 

173 if not isinstance(value, list): 

174 return [] 

175 return [item for item in value if isinstance(item, dict)] 

176 

177 

178def with_assumptions( 

179 task: Task, items: list[Item], rounds: int 

180) -> tuple[Task, list[dict[str, Any]]]: 

181 """The task revision that records ``items`` as assumptions (those it does not record 

182 yet), and the new assumptions.""" 

183 existing = assumptions_of(task) 

184 known = {normalized(str(item.get("question") or "")) for item in existing} 

185 added: list[dict[str, Any]] = [] 

186 for category, target, text in items: 

187 if normalized(text) in known: 

188 continue 

189 known.add(normalized(text)) 

190 added.append( 

191 { 

192 "assumptionId": f"AS-{len(existing) + len(added) + 1}", 

193 "category": category, 

194 "target": target, 

195 "question": text, 

196 "assumption": ASSUMPTION_TEXT.format(rounds=rounds), 

197 "rounds": rounds, 

198 } 

199 ) 

200 if not added: 

201 return task, [] 

202 data = task.model_dump(mode="json") 

203 data["metadata"] = {**task.metadata, ASSUMPTIONS_KEY: [*existing, *added]} 

204 return Task.model_validate(data), added 

205 

206 

207__all__ = [ 

208 "AGENT_RULE", 

209 "ASSUMPTIONS_KEY", 

210 "ASSUMPTION_TEXT", 

211 "CONVERGE_SUFFIX", 

212 "Convergence", 

213 "assumptions_of", 

214 "convergence", 

215 "normalized", 

216 "with_assumptions", 

217]