Spaces:
Running on Zero
Running on Zero
File size: 16,531 Bytes
1aa20d3 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 | """Short feedback grounded in validated or prevalidated descriptor text.
Only descriptor-level matches from the active prevalidation nuclei are included.
The other descriptors get a reflective prompt, never an invented CEFR rule.
"""
from __future__ import annotations
import hashlib
import json
import logging
import os
import re
from pathlib import Path
from typing import Any
from .guided_track import GUIDED_DESCRIPTOR_IDS, GUIDED_STAGES
FEEDBACK_VERSION = "5"
MAX_FEEDBACK_LENGTH = 180
FEEDBACK_DATA_PATH = Path(__file__).resolve().parents[1] / "data/feedback.prevalidated.json"
GUIDE_DATA_PATH = Path(__file__).resolve().parents[1] / "data/feedback.descriptor_guides.json"
LOGGER = logging.getLogger(__name__)
GUIDE_ID_PATTERN = re.compile(r"(?:SRC-\d+|QCER-GEN-(?:A1|A2|B1|B2))")
def _load_feedback_bank(path: Path) -> dict[str, tuple[str, str, str, tuple[str, ...]]]:
"""Fail closed: invalid or missing data cannot present a mismatched cue."""
try:
data = json.loads(path.read_text(encoding="utf-8"))
if not isinstance(data, dict) or (
data.get("schema_version") != 2
or data.get("review_status") != "ai_prevalidated_pending_human_review"
or not isinstance(data.get("items"), list)
):
raise ValueError("metadata non valida")
cues: dict[str, tuple[str, str, str, tuple[str, ...]]] = {}
for item in data["items"]:
descriptor_id = item["descriptor_id"]
level = item["level"]
digest = item["descriptor_sha256"]
cue = item["cue"]
evidence = item["evidence"]
if (
not isinstance(descriptor_id, str)
or not re.fullmatch(r"SRC-\d+", descriptor_id)
or descriptor_id in cues
or level not in {"A1", "A2", "A2+", "B1", "B1+", "B2"}
or not isinstance(digest, str)
or not re.fullmatch(r"[0-9a-f]{64}", digest)
or not isinstance(cue, str)
or not 10 <= len(cue) <= 140
or not cue.endswith(".")
or "<" in cue or ">" in cue
or re.search(r"(?<!\w)(?:A1|A2\+?|B1\+?|B2)(?!\w)", cue)
or not isinstance(evidence, list)
or not 1 <= len(evidence) <= 4
or any(
not isinstance(fragment, str)
or not 5 <= len(fragment) <= 100
for fragment in evidence
)
):
raise ValueError(f"indizio non valido: {descriptor_id}")
cues[descriptor_id] = (level, digest, cue, tuple(evidence))
return cues
except (OSError, ValueError, TypeError, KeyError) as exc:
LOGGER.warning("Feedback prevalidati non caricati: %s", exc)
return {}
PREVALIDATED_CUES = _load_feedback_bank(FEEDBACK_DATA_PATH)
LEVEL_ORDER = ("A1", "A2", "A2+", "B1", "B1+", "B2")
def _load_descriptor_guides(path: Path) -> dict[str, dict[str, Any]]:
"""Load editorial contrasts, bound to the exact catalog text."""
try:
data = json.loads(path.read_text(encoding="utf-8"))
if (
not isinstance(data, dict)
or data.get("schema_version") != 1
or data.get("review_status") != "mixed_validated_pending_and_draft"
or data.get("pilot_validation_status")
!= "guided_track_partial_validation"
or data.get("pilot_validation_date") != "2026-10-25"
or not isinstance(data.get("items"), list)
):
raise ValueError("metadata non valida")
guides: dict[str, dict[str, Any]] = {}
for item in data["items"]:
descriptor_id = item["descriptor_id"]
if (
not isinstance(descriptor_id, str)
or not GUIDE_ID_PATTERN.fullmatch(descriptor_id)
or descriptor_id in guides
or item["level"] not in {"A1", "A2", "A2+", "B1", "B1+", "B2"}
or not isinstance(item["descriptor_sha256"], str)
or not re.fullmatch(r"[0-9a-f]{64}", item["descriptor_sha256"])
or not isinstance(item["evidence"], list)
or not 1 <= len(item["evidence"]) <= 4
or any(not isinstance(part, str) or len(part) < 5 for part in item["evidence"])
or any(
not isinstance(item[field], str)
or not item[field]
or len(item[field]) > 155
or "<" in item[field]
or ">" in item[field]
for field in ("focus", "reason")
)
or not isinstance(item["contrasts"], dict)
or not item["contrasts"]
or not set(item["contrasts"]).issubset(set(LEVEL_ORDER) - {item["level"]})
or (
"first_hints" in item
and (
not isinstance(item["first_hints"], dict)
or not set(item["first_hints"]).issubset(
set(item["contrasts"])
)
or any(
not isinstance(hint, str)
or not 20 <= len(hint) <= 155
or "<" in hint
or ">" in hint
or re.search(r"(?<!\w)(?:A1|A2\+?|B1\+?|B2)(?!\w)", hint)
for hint in item["first_hints"].values()
)
)
)
or any(
not isinstance(contrast, dict)
or not isinstance(contrast.get("ref"), str)
or not GUIDE_ID_PATTERN.fullmatch(contrast["ref"])
or not isinstance(contrast.get("text"), str)
or not 15 <= len(contrast["text"]) <= 155
or "<" in contrast["text"]
or ">" in contrast["text"]
for contrast in item["contrasts"].values()
)
or re.search(
r"(?<!\w)(?:A1|A2\+?|B1\+?|B2)(?!\w)",
item["focus"],
)
):
raise ValueError(f"guida non valida: {descriptor_id}")
validation_status = item.get(
"validation_status", "draft_pending_human_review"
)
if validation_status not in {
"draft_pending_human_review",
"validated_for_guided_pilot",
"pending_targeted_review",
}:
raise ValueError(f"stato di validazione non valido: {descriptor_id}")
if validation_status in {
"validated_for_guided_pilot",
"pending_targeted_review",
}:
required_levels = {"A1", "A2", "B1", "B2"} - {item["level"]}
if (
descriptor_id not in GUIDED_DESCRIPTOR_IDS
or set(item.get("first_hints", {})) != required_levels
or not required_levels.issubset(item["contrasts"])
):
raise ValueError(f"guida del percorso incompleta: {descriptor_id}")
guides[descriptor_id] = item
classified_ids = {
descriptor_id
for descriptor_id, guide in guides.items()
if guide.get("validation_status")
in {"validated_for_guided_pilot", "pending_targeted_review"}
}
if classified_ids != set(GUIDED_DESCRIPTOR_IDS):
raise ValueError("insieme delle guide del percorso non valido")
return guides
except (OSError, ValueError, TypeError, KeyError) as exc:
LOGGER.warning("Guide editoriali non caricate: %s", exc)
return {}
DESCRIPTOR_GUIDES = _load_descriptor_guides(GUIDE_DATA_PATH)
# Draft editorial content outside the guided route must not silently become
# pilot feedback. Pending items remain explicitly distinguishable in events.
DRAFT_GUIDES_ENABLED = os.getenv("FAMILIARIZZAPP_DRAFT_FEEDBACK", "") == "1"
def _guide_basis(guide: dict[str, Any]) -> str:
return (
"guide_validated"
if guide.get("validation_status") == "validated_for_guided_pilot"
else "guide_draft"
)
def _matched_guide(descriptor: dict[str, Any]) -> dict[str, Any] | None:
guide = DESCRIPTOR_GUIDES.get(str(descriptor.get("descriptor_id", "")))
text = str(descriptor.get("descriptor_text", ""))
if (
guide
and guide["level"] == descriptor.get("correct_level")
and guide["descriptor_sha256"] == hashlib.sha256(text.encode("utf-8")).hexdigest()
and all(part in text for part in guide["evidence"])
):
return guide
return None
def _short_sentence(value: str, limit: int) -> str:
"""Prefer a complete short sentence to an abruptly cut explanation."""
value = re.sub(r"\s+", " ", value).strip()
if len(value) <= limit:
return value
first = re.split(r"(?<=[.!?])\s+", value, maxsplit=1)[0]
if len(first) <= limit:
return first
words = value.split()
kept: list[str] = []
for word in words:
if len(" ".join(kept + [word])) > limit - 1:
break
kept.append(word)
return " ".join(kept).rstrip(" ,;:") + "…"
def _editorial_text(descriptor: dict[str, Any], attempt: int, finished: bool) -> str:
if finished:
raw = str(descriptor.get("rationale", ""))
if (
"catalogo sorgente" in raw.casefold()
or "motivazione dettagliata sarà aggiunta" in raw.casefold()
or "soluzione corretta è il livello previsto dal catalogo" in raw.casefold()
):
return ""
raw = re.sub(r"^Il livello corretto è [^.!?]+[.!?]\s*", "", raw)
return _short_sentence(raw, MAX_FEEDBACK_LENGTH - 18) if raw else ""
raw = str(descriptor.get(f"hint_{attempt}", ""))
if not raw or any(
placeholder in raw.casefold()
for placeholder in (
"confronta il descrittore con i livelli vicini",
"feedback provvisorio",
"osserva l’ampiezza del compito, il tipo di contenuto",
)
):
return ""
# Some legacy hints contain level labels. A hint must not disclose the
# answer (or suggest a different level) while a retry is still possible.
if re.search(r"(?<!\w)(?:A1|A2\+?|B1\+?|B2)(?!\w)", raw):
return ""
return _short_sentence(raw, MAX_FEEDBACK_LENGTH - 15)
PHASE_PROMPTS = {
"orientation": "Che cosa è in grado di fare? Guarda anche le condizioni del compito.",
"canonical_variation": "Che cosa cambia rispetto agli esempi precedenti: azione, autonomia o condizioni?",
"introduce_a2_plus": "Quale dettaglio distingue questo compito dai livelli vicini?",
"introduce_b1_plus": "Quale dettaglio distingue questo compito dai livelli vicini?",
"deepening": "Rileggi l'intero compito, non una sola parola.",
"consolidation": "Quale indizio ti aveva aiutato negli incontri precedenti?",
"maintenance": "Ricontrolla il compito e le condizioni prima di scegliere.",
}
def compose_feedback(
descriptor: dict[str, Any],
*,
phase: str,
selected_level: str,
attempt_number: int,
previous_attempts: list[str],
completed_records: list[dict[str, Any]],
prior_exposure_count: int = 0,
) -> tuple[str, str]:
"""Return (message, basis) without disclosing the answer on a wrong try."""
correct = str(descriptor["correct_level"])
finished = selected_level == correct or attempt_number == 3
guided_phase = phase in {stage.phase for stage in GUIDED_STAGES}
guided_item = str(descriptor.get("descriptor_id", "")) in GUIDED_DESCRIPTOR_IDS
guide = (
_matched_guide(descriptor)
if DRAFT_GUIDES_ENABLED or (guided_phase and guided_item)
else None
)
if guide and not finished and attempt_number > 1 and selected_level not in guide["contrasts"]:
guide = None
if guide:
if not finished:
if attempt_number == 1:
lead = f"Hai scelto {selected_level}. "
if phase in {"consolidation", "maintenance"}:
lead += "Ripensa al contrasto già incontrato. "
message = lead + guide.get("first_hints", {}).get(
selected_level, guide["focus"]
)
else:
contrast = guide["contrasts"][selected_level]["text"]
lead = (
f"Hai scelto di nuovo {selected_level}. "
if selected_level in previous_attempts
else f"Confronta con {selected_level}: "
)
message = lead + (
contrast
if selected_level in previous_attempts
else contrast[0].lower() + contrast[1:]
)
return _short_sentence(message, MAX_FEEDBACK_LENGTH), _guide_basis(guide)
if selected_level == correct:
lead = f"Esatto: {correct}. "
if attempt_number == 1 and (
prior_exposure_count
or any(record.get("correct_level") == correct for record in completed_records)
):
lead = f"Esatto: {correct}, questa volta al primo tentativo. "
else:
lead = f"Il livello previsto è {correct}. "
comparison_level = None
if selected_level != correct and selected_level in guide["contrasts"]:
# The final, unsuccessful choice has not received a comparison yet.
comparison_level = selected_level
if comparison_level in guide["contrasts"]:
comparison = guide["contrasts"][comparison_level]["text"]
reason = f"Confronta con {comparison_level}: {comparison[0].lower()}{comparison[1:]}"
else:
reason = guide["reason"]
return _short_sentence(lead + reason, MAX_FEEDBACK_LENGTH), _guide_basis(guide)
prevalidated = PREVALIDATED_CUES.get(str(descriptor.get("descriptor_id", "")))
descriptor_hash = hashlib.sha256(
str(descriptor.get("descriptor_text", "")).encode("utf-8")
).hexdigest()
cue = (
prevalidated[2]
if prevalidated
and prevalidated[0] == correct
and prevalidated[1] == descriptor_hash
and all(
fragment in str(descriptor.get("descriptor_text", ""))
for fragment in prevalidated[3]
)
else ""
)
editorial = _editorial_text(descriptor, attempt_number, finished) if not cue else ""
basis = "prevalidated" if cue else "editorial" if editorial else "reflection"
detail = cue or editorial
if not finished:
if attempt_number == 1:
if detail:
message = "Rileggi la prestazione descritta: " + detail
else:
message = PHASE_PROMPTS.get(
phase, PHASE_PROMPTS["orientation"]
)
else:
lead = (
f"Hai scelto di nuovo {selected_level}. "
if selected_level in previous_attempts
else f"Hai scelto {selected_level}. "
)
message = lead + "Quale azione e quali condizioni distinguono il testo dalle opzioni rimaste?"
return _short_sentence(message, MAX_FEEDBACK_LENGTH), basis
if selected_level == correct:
if attempt_number == 1 and (prior_exposure_count or any(
record.get("correct_level") == correct for record in completed_records
)):
lead = f"Esatto: {correct}, questa volta al primo tentativo. "
else:
lead = f"Esatto: {correct}. "
else:
lead = f"Il livello previsto è {correct}. "
if detail:
message = lead + detail
else:
message = lead + "Per ragionarci: quali azioni e condizioni lo distinguono dalle altre opzioni?"
return _short_sentence(message, MAX_FEEDBACK_LENGTH), basis
|