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
« 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).
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:
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.
17A round is one clarification a person answered in this run that included agent questions
18(rule ``A1``)."""
20from __future__ import annotations
22import re
23from dataclasses import dataclass
24from typing import TYPE_CHECKING, Any
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
35if TYPE_CHECKING:
36 from governed_harness.orchestration.hosts import ResultsHost
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."""
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)
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)
62Item = tuple[str, str, str]
63"""``(category, target, text)`` of an agent question."""
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()))
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."""
76 settings: AmbiguityReviewConfig
77 history: tuple[dict[str, Any], ...]
78 seen: frozenset[tuple[str, str]]
79 rounds: int
81 @property
82 def round(self) -> int:
83 return self.rounds + 1
85 @property
86 def exhausted(self) -> bool:
87 return self.rounds >= self.settings.rounds
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 }
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 )
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)
119def _trimmed(text: str | None) -> str | None:
120 return None if text is None else text[:_HISTORY_TEXT]
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)
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)]
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
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]