Coverage for src/governed_harness/intake/depth.py: 94%

116 statements  

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

1"""Adaptive depth of the INTENT questions (``intake.ambiguityReview.depth: adaptive``). 

2 

3A poor request is never refused: the harness asks, and asks more the poorer the request is, 

4starting with the basics. This module measures, without a language model, how little a task 

5says, and turns that measure into a plan: how many rounds of questions and how many questions 

6per round INTENT may ask, and which fundamental topics the first rounds cover. 

7 

8The measure (``poverty``) adds four parts, 0 to 100 in total: 

9 

10* the words of the intent: under 25 words 35 points, under 80 words 20, under 200 words 10; 

11* the observable acceptance criteria (those rule ``C1`` does not question): none 25, one or 

12 two 15, three to five 5; 

13* the requirements: none 25, one to four 15, five to fourteen 5; 

14* the entities, distinct concrete anchors in the intent, the requirements and the criteria 

15 (numbers, quoted text, code identifiers, paths and file names): under three 15, under eight 8. 

16 

17A score of 90 or more is ``very-poor``, 75 or more ``poor``, 30 or more ``partial``, anything 

18else ``detailed``. A task with an observable criterion is at most ``partial``: it already says 

19what the work must show, so only a request without one is asked the basics deterministically. The plan starts from the configured ``maxRounds`` and ``maxQuestions`` 

20(defaults 3 and 8): ``very-poor`` adds three rounds and four questions per round, ``poor`` one 

21round and two questions, ``partial`` and ``detailed`` keep the configured values. The plan never 

22goes over ``MAX_ROUNDS`` rounds and ``MAX_QUESTIONS`` questions per round (or the configured 

23value when it is larger). 

24 

25The fundamental topics (``BASIC_TOPICS``) come first, in a fixed order: users, what they do, 

26main flows, platform and stack, data, business rules, limits and edge cases, observable 

27acceptance criteria, and priorities and scope of the first version. A ``very-poor`` request 

28covers them three per round, a ``poor`` one five per round; for these two levels the 

29deterministic intake asks one question per topic (category ``basics``, target 

30``task:<topic>``) before its other questions. A ``partial`` request passes all of them to the 

31agent review in its first round; a ``detailed`` one none. 

32 

33The level is measured on the task as the person wrote it: the first answered revision freezes 

34it in ``metadata.intakeDepth``, so the answers that enrich the task do not shrink the plan in 

35the middle of the clarification. 

36""" 

37 

38from __future__ import annotations 

39 

40import re 

41from dataclasses import dataclass 

42from typing import Any, Literal 

43 

44from governed_harness.domain.models import Task 

45 

46DepthLevel = Literal["very-poor", "poor", "partial", "detailed"] 

47 

48DEPTH_KEY = "intakeDepth" 

49"""Metadata key of the frozen measure of a task (``level`` and ``score``).""" 

50TOPICS_KEY = "intakeTopics" 

51"""Metadata key of the fundamental topics a person already answered.""" 

52BASICS_CATEGORY = "basics" 

53"""Category of a deterministic question about a fundamental topic.""" 

54TOPIC_TARGET_PREFIX = "task:" 

55 

56MAX_ROUNDS = 8 

57MAX_QUESTIONS = 16 

58 

59BASIC_TOPICS: tuple[str, ...] = ( 

60 "users", 

61 "actions", 

62 "flows", 

63 "platform", 

64 "data", 

65 "rules", 

66 "edge-cases", 

67 "acceptance", 

68 "first-version", 

69) 

70"""The fundamental topics, in the order they are asked.""" 

71 

72BASIC_TARGETS: tuple[str, ...] = tuple(TOPIC_TARGET_PREFIX + topic for topic in BASIC_TOPICS) 

73 

74TOPIC_LABELS: dict[str, dict[str, str]] = { 

75 "en": { 

76 "users": "Users and roles", 

77 "actions": "What each user does", 

78 "flows": "Main flows", 

79 "platform": "Platform and stack", 

80 "data": "Data", 

81 "rules": "Business rules", 

82 "edge-cases": "Limits and edge cases", 

83 "acceptance": "Observable acceptance criteria", 

84 "first-version": "Priorities and scope of the first version", 

85 }, 

86 "es": { 

87 "users": "Usuarios y roles", 

88 "actions": "Qué hace cada usuario", 

89 "flows": "Flujos principales", 

90 "platform": "Plataforma y stack", 

91 "data": "Datos", 

92 "rules": "Reglas de negocio", 

93 "edge-cases": "Límites y casos borde", 

94 "acceptance": "Criterios de aceptación observables", 

95 "first-version": "Prioridades y alcance de la primera versión", 

96 }, 

97} 

98"""Labels of the topics; an answer becomes a requirement prefixed with its topic's label.""" 

99 

100TOPIC_QUESTIONS: dict[str, dict[str, str]] = { 

101 "en": { 

102 "users": ( 

103 "Who uses '{title}'? List each kind of user or role and what distinguishes them." 

104 ), 

105 "actions": ( 

106 "What does each kind of user do with '{title}'? One action per line, with the user " 

107 "who does it." 

108 ), 

109 "flows": ( 

110 "Which are the main flows of '{title}', step by step from start to end (for example " 

111 "sign up, order, pay, deliver)?" 

112 ), 

113 "platform": ( 

114 "On which platform and stack must '{title}' run (language, framework, interface such " 

115 "as a library, a CLI, a web API or an app, storage)?" 

116 ), 

117 "data": ( 

118 "Which data does '{title}' keep, with which fields, and which states does each " 

119 "record go through?" 

120 ), 

121 "rules": ( 

122 "Which business rules apply in '{title}' (prices, fees, permissions, assignments, " 

123 "cancellations), with their exact numbers?" 

124 ), 

125 "edge-cases": ( 

126 "Which limits and edge cases must '{title}' handle, and what happens exactly in each " 

127 "one (empty input, nothing available, a value at the limit, a repeated action)?" 

128 ), 

129 "acceptance": ( 

130 "How will you check that '{title}' is done? Give observable results, one per line " 

131 "(input or action -> exact expected result)." 

132 ), 

133 "first-version": ( 

134 "What must the first version of '{title}' include, in order of priority, and what is " 

135 "left for later?" 

136 ), 

137 }, 

138 "es": { 

139 "users": ( 

140 "¿Quiénes usan '{title}'? Enumera cada tipo de usuario o rol y qué lo distingue." 

141 ), 

142 "actions": ( 

143 "¿Qué hace cada tipo de usuario con '{title}'? Una acción por línea, con el usuario " 

144 "que la hace." 

145 ), 

146 "flows": ( 

147 "¿Cuáles son los flujos principales de '{title}', paso a paso de principio a fin " 

148 "(por ejemplo registrarse, pedir, pagar, entregar)?" 

149 ), 

150 "platform": ( 

151 "¿En qué plataforma y stack debe funcionar '{title}' (lenguaje, framework, interfaz " 

152 "como biblioteca, CLI, API web o app, almacenamiento)?" 

153 ), 

154 "data": ( 

155 "¿Qué datos guarda '{title}', con qué campos, y por qué estados pasa cada registro?" 

156 ), 

157 "rules": ( 

158 "¿Qué reglas de negocio aplican en '{title}' (precios, comisiones, permisos, " 

159 "asignaciones, cancelaciones), con sus números exactos?" 

160 ), 

161 "edge-cases": ( 

162 "¿Qué límites y casos borde debe manejar '{title}' y qué pasa exactamente en cada uno " 

163 "(entrada vacía, nada disponible, un valor en el límite, una acción repetida)?" 

164 ), 

165 "acceptance": ( 

166 "¿Cómo vas a comprobar que '{title}' está terminado? Da resultados observables, uno " 

167 "por línea (entrada o acción -> resultado exacto esperado)." 

168 ), 

169 "first-version": ( 

170 "¿Qué debe incluir la primera versión de '{title}', en orden de prioridad, y qué " 

171 "queda para después?" 

172 ), 

173 }, 

174} 

175"""Question texts of the topics, by language.""" 

176 

177_EXTRA: dict[DepthLevel, tuple[int, int, int]] = { 

178 "very-poor": (3, 4, 3), 

179 "poor": (1, 2, 5), 

180 "partial": (0, 0, len(BASIC_TOPICS)), 

181 "detailed": (0, 0, 0), 

182} 

183"""Rounds added, questions per round added and topics per round, by level.""" 

184 

185_ANCHORS = ( 

186 re.compile(r"\d+(?:[.,]\d+)?"), 

187 re.compile(r"`[^`]+`|\"[^\"]+\"|“[^”]+”"), 

188 re.compile(r"[A-Za-z_][\w.]*\("), 

189 re.compile(r"\b[A-Za-z][A-Za-z0-9]*_[A-Za-z0-9_]+\b"), # NOSONAR(S6353) 

190 re.compile(r"\b[\w-]+\.[a-z]{1,5}\b"), 

191 re.compile(r"\b[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]*)+\b"), 

192) 

193 

194 

195@dataclass(frozen=True) 

196class Poverty: 

197 """How little a task says (see the module).""" 

198 

199 words: int 

200 criteria: int 

201 requirements: int 

202 entities: int 

203 score: int 

204 level: DepthLevel 

205 

206 def as_dict(self) -> dict[str, Any]: 

207 return { 

208 "words": self.words, 

209 "criteria": self.criteria, 

210 "requirements": self.requirements, 

211 "entities": self.entities, 

212 "score": self.score, 

213 "level": self.level, 

214 } 

215 

216 

217@dataclass(frozen=True) 

218class DepthPlan: 

219 """The rounds and questions INTENT may ask about a task, and its topics per round.""" 

220 

221 level: DepthLevel 

222 score: int 

223 rounds: int 

224 questions: int 

225 topics_per_round: int 

226 

227 @property 

228 def deterministic_basics(self) -> bool: 

229 """Whether the deterministic intake asks the topics (``very-poor`` and ``poor``).""" 

230 return self.level in ("very-poor", "poor") 

231 

232 def round_topics(self, round_number: int) -> tuple[str, ...]: 

233 """The topics the agent review covers in round ``round_number`` (1-based).""" 

234 size = self.topics_per_round 

235 if size <= 0 or round_number < 1: 235 ↛ 236line 235 didn't jump to line 236 because the condition on line 235 was never true

236 return () 

237 start = (round_number - 1) * size 

238 return BASIC_TOPICS[start : start + size] 

239 

240 def next_topics(self, covered: tuple[str, ...]) -> tuple[str, ...]: 

241 """The first topics nobody answered yet, as many as one round asks.""" 

242 if not self.deterministic_basics: 

243 return () 

244 return tuple(topic for topic in BASIC_TOPICS if topic not in covered)[ 

245 : self.topics_per_round 

246 ] 

247 

248 def as_dict(self) -> dict[str, Any]: 

249 return { 

250 "level": self.level, 

251 "score": self.score, 

252 "rounds": self.rounds, 

253 "questions": self.questions, 

254 "topicsPerRound": self.topics_per_round, 

255 } 

256 

257 

258def _entities(task: Task) -> int: 

259 text = "\n".join( 

260 [ 

261 task.intent, 

262 *(item.text for item in task.requirements), 

263 *(item.text for item in task.acceptance_criteria), 

264 ] 

265 ) 

266 found: set[str] = set() 

267 for pattern in _ANCHORS: 

268 found.update(match.group().lower() for match in pattern.finditer(text)) 

269 return len(found) 

270 

271 

272def _points(value: int, steps: tuple[tuple[int, int], ...]) -> int: 

273 for limit, points in steps: 

274 if value < limit: 

275 return points 

276 return 0 

277 

278 

279def _level(score: int) -> DepthLevel: 

280 if score >= 90: 

281 return "very-poor" 

282 if score >= 75: 

283 return "poor" 

284 if score >= 30: 284 ↛ 286line 284 didn't jump to line 286 because the condition on line 284 was always true

285 return "partial" 

286 return "detailed" 

287 

288 

289def poverty(task: Task) -> Poverty: 

290 """The measure of a task as it stands (see the module). Criteria are read with the Spanish 

291 vocabularies, which include the English ones, so the measure does not depend on 

292 ``intake.language``.""" 

293 from .clarification import no_observable_result 

294 

295 words = len(task.intent.split()) 

296 criteria = sum( 

297 1 

298 for criterion in task.acceptance_criteria 

299 if not no_observable_result(criterion, language="es") 

300 ) 

301 requirements = len(task.requirements) 

302 entities = _entities(task) 

303 score = ( 

304 _points(words, ((25, 35), (80, 20), (200, 10))) 

305 + _points(criteria, ((1, 25), (3, 15), (6, 5))) 

306 + _points(requirements, ((1, 25), (5, 15), (15, 5))) 

307 + _points(entities, ((3, 15), (8, 8))) 

308 ) 

309 level = _level(score) 

310 if level in ("very-poor", "poor") and criteria: 

311 # An observable criterion already says what the task must show: the person wrote more 

312 # than a wish, so the basics are left to the agent review. 

313 level = "partial" 

314 return Poverty(words, criteria, requirements, entities, score, level) 

315 

316 

317def frozen_level(task: Task) -> tuple[DepthLevel, int] | None: 

318 """The level and score ``metadata.intakeDepth`` froze, if any.""" 

319 value = task.metadata.get(DEPTH_KEY) 

320 if not isinstance(value, dict): 

321 return None 

322 level, score = value.get("level"), value.get("score") 

323 if level in _EXTRA and isinstance(score, int): 323 ↛ 325line 323 didn't jump to line 325 because the condition on line 323 was always true

324 return level, score 

325 return None 

326 

327 

328def covered_topics(task: Task) -> tuple[str, ...]: 

329 """The fundamental topics a person answered (``metadata.intakeTopics``).""" 

330 value = task.metadata.get(TOPICS_KEY) 

331 if not isinstance(value, list): 331 ↛ 333line 331 didn't jump to line 333 because the condition on line 331 was always true

332 return () 

333 return tuple(item for item in value if item in BASIC_TOPICS) 

334 

335 

336def depth_plan(task: Task, base_rounds: int, base_questions: int) -> DepthPlan: 

337 """The plan of a task from its frozen level, or from its measure when nothing froze it.""" 

338 frozen = frozen_level(task) 

339 if frozen is None: 

340 measured = poverty(task) 

341 level, score = measured.level, measured.score 

342 else: 

343 level, score = frozen 

344 rounds_added, questions_added, per_round = _EXTRA[level] 

345 rounds = min(base_rounds + rounds_added, max(base_rounds, MAX_ROUNDS)) 

346 questions = min(base_questions + questions_added, max(base_questions, MAX_QUESTIONS)) 

347 return DepthPlan(level, score, rounds, questions, per_round) 

348 

349 

350def topic_language(language: str | None) -> str: 

351 return "es" if language == "es" else "en" 

352 

353 

354def topic_of(target: str) -> str | None: 

355 """The topic of a ``task:<topic>`` target, or ``None``.""" 

356 topic = target.removeprefix(TOPIC_TARGET_PREFIX) 

357 return topic if target.startswith(TOPIC_TARGET_PREFIX) and topic in BASIC_TOPICS else None 

358 

359 

360__all__ = [ 

361 "BASICS_CATEGORY", 

362 "BASIC_TARGETS", 

363 "BASIC_TOPICS", 

364 "DEPTH_KEY", 

365 "MAX_QUESTIONS", 

366 "MAX_ROUNDS", 

367 "TOPICS_KEY", 

368 "TOPIC_LABELS", 

369 "TOPIC_QUESTIONS", 

370 "DepthLevel", 

371 "DepthPlan", 

372 "Poverty", 

373 "covered_topics", 

374 "depth_plan", 

375 "frozen_level", 

376 "poverty", 

377 "topic_language", 

378 "topic_of", 

379]