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
« 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``).
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.
8The measure (``poverty``) adds four parts, 0 to 100 in total:
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.
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).
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.
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"""
38from __future__ import annotations
40import re
41from dataclasses import dataclass
42from typing import Any, Literal
44from governed_harness.domain.models import Task
46DepthLevel = Literal["very-poor", "poor", "partial", "detailed"]
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:"
56MAX_ROUNDS = 8
57MAX_QUESTIONS = 16
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."""
72BASIC_TARGETS: tuple[str, ...] = tuple(TOPIC_TARGET_PREFIX + topic for topic in BASIC_TOPICS)
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."""
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."""
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."""
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)
195@dataclass(frozen=True)
196class Poverty:
197 """How little a task says (see the module)."""
199 words: int
200 criteria: int
201 requirements: int
202 entities: int
203 score: int
204 level: DepthLevel
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 }
217@dataclass(frozen=True)
218class DepthPlan:
219 """The rounds and questions INTENT may ask about a task, and its topics per round."""
221 level: DepthLevel
222 score: int
223 rounds: int
224 questions: int
225 topics_per_round: int
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")
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]
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 ]
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 }
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)
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
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"
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
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)
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
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)
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)
350def topic_language(language: str | None) -> str:
351 return "es" if language == "es" else "en"
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
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]