from __future__ import annotations from collections import Counter, defaultdict from datetime import datetime, timezone from typing import Any, Iterable from zoneinfo import ZoneInfo from .catalog import Catalog, CatalogError ROME = ZoneInfo("Europe/Rome") OUTCOME_LABELS = { "first": "✓ 1° tentativo", "second": "✓ 2° tentativo", "third": "✓ 3° tentativo", "unresolved": "Da rivedere", "in_progress": "In corso", "unseen": "Non ancora incontrato", } FOCUS_OUTCOMES = {"second", "third", "unresolved"} def parse_timestamp(value: str | None) -> datetime | None: if not value: return None try: parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00")) except ValueError: return None if parsed.tzinfo is None: parsed = parsed.replace(tzinfo=timezone.utc) return parsed.astimezone(timezone.utc) def exact_timestamp(value: str | None) -> str: parsed = parse_timestamp(value) if not parsed: return "—" local = parsed.astimezone(ROME) return ( f"{local:%d/%m/%Y %H:%M:%S} {local.tzname()} " f"({parsed:%Y-%m-%d %H:%M:%S} UTC)" ) def relative_timestamp( value: str | None, *, now: datetime | None = None ) -> str: parsed = parse_timestamp(value) if not parsed: return "data non disponibile" local = parsed.astimezone(ROME) reference = (now or datetime.now(timezone.utc)).astimezone(ROME) if local > reference: return f"il {local:%d/%m/%Y}" day_delta = (reference.date() - local.date()).days elapsed_seconds = max((reference - local).total_seconds(), 0) if day_delta == 0: minutes = int(elapsed_seconds // 60) if minutes < 2: return "pochi minuti fa" if minutes < 60: return f"circa {minutes} minuti fa" hours = max(round(elapsed_seconds / 3600), 1) return f"circa {hours} {'ora' if hours == 1 else 'ore'} fa" if day_delta == 1: return "ieri" if day_delta < 30: return f"{day_delta} giorni fa" return f"il {local:%d/%m/%Y}" def outcome_key(record: dict[str, Any] | None) -> str: if not record: return "unseen" attempt = record.get("resolved_on_attempt") if attempt == 1: return "first" if attempt == 2: return "second" if attempt == 3: return "third" return "unresolved" def outcome_label(record: dict[str, Any] | None) -> str: return OUTCOME_LABELS[outcome_key(record)] def group_sessions( events: Iterable[dict[str, Any]], ) -> dict[str, list[dict[str, Any]]]: grouped: dict[str, list[dict[str, Any]]] = defaultdict(list) for event in events: if event.get("event_type") in { "consent_recorded", "participant_accessed", "questionnaire_submitted", }: continue session_id = str(event.get("session_id", "")) if session_id: grouped[session_id].append(event) for session_events in grouped.values(): session_events.sort(key=lambda item: item.get("occurred_at", "")) return dict(grouped) def descriptor_history( events: Iterable[dict[str, Any]], catalog: Catalog ) -> list[dict[str, Any]]: grouped = group_sessions(events) records: list[dict[str, Any]] = [] for session_id, session_events in grouped.items(): start = first_event(session_events, "session_started") or {} answers_by_descriptor: dict[str, list[dict[str, Any]]] = defaultdict(list) for event in session_events: if event.get("event_type") == "answer_submitted": answers_by_descriptor[str(event.get("descriptor_id", ""))].append( event ) for answers in answers_by_descriptor.values(): answers.sort(key=lambda item: int(item.get("attempt_number", 0))) for completed in ( event for event in session_events if event.get("event_type") == "descriptor_completed" ): descriptor_id = str(completed.get("descriptor_id", "")) answers = answers_by_descriptor.get(descriptor_id, []) descriptor = _catalog_item(catalog, descriptor_id) attempts = list(completed.get("attempts") or []) if not attempts: attempts = [ str(answer.get("selected_level", "")) for answer in answers ] correct_level = ( completed.get("correct_level") or descriptor.get("correct_level") or (answers[-1].get("correct_level") if answers else "") ) record = { "participant_id": completed.get("participant_id_hash", ""), "session_id": session_id, "descriptor_id": descriptor_id, "schema": start.get("schema") or descriptor.get("schema", ""), "modality": start.get("modality") or descriptor.get("modality", ""), "activity": start.get("activity") or descriptor.get("activity", ""), "scale": start.get("scale") or descriptor.get("scale", ""), "level": correct_level, "descriptor_text": descriptor.get("descriptor_text") or completed.get("descriptor_text", ""), "attempts": attempts, "attempts_text": " → ".join(attempts) if attempts else "—", "resolved": bool(completed.get("resolved")), "resolved_on_attempt": completed.get("resolved_on_attempt"), "rationale": completed.get("rationale") or descriptor.get("rationale", ""), "occurred_at": completed.get("occurred_at", ""), "outcome": outcome_key(completed), "outcome_label": outcome_label(completed), "content_revision": completed.get("content_revision") or start.get("content_revision", ""), "app_version": completed.get("app_version") or start.get("app_version", ""), "response_time_ms": sum( int(answer.get("response_time_ms") or 0) for answer in answers ) if any( answer.get("response_time_ms") is not None for answer in answers ) else None, "first_response_distance": _first_non_null( [ *[ answer.get("error_distance") for answer in answers[:1] ], completed.get("first_response_distance"), ] ), } records.append(record) records.sort(key=lambda item: item["occurred_at"]) exposures: Counter[str] = Counter() for record in records: exposures[record["descriptor_id"]] += 1 record["exposure_number"] = exposures[record["descriptor_id"]] return records def descriptor_activity( events: Iterable[dict[str, Any]], catalog: Catalog ) -> list[dict[str, Any]]: """Return completed outcomes plus descriptors left open mid-session. An open descriptor remains visible in the personal journey, but it has no outcome and therefore never changes recognition percentages. """ events_list = list(events) records = descriptor_history(events_list, catalog) for session_id, session_events in group_sessions(events_list).items(): if first_event(session_events, "session_completed"): continue start = first_event(session_events, "session_started") or {} completed_ids = { str(event.get("descriptor_id", "")) for event in session_events if event.get("event_type") == "descriptor_completed" } answers_by_descriptor: dict[str, list[dict[str, Any]]] = defaultdict(list) for event in session_events: if event.get("event_type") == "answer_submitted": answers_by_descriptor[str(event.get("descriptor_id", ""))].append( event ) for answers in answers_by_descriptor.values(): answers.sort(key=lambda item: int(item.get("attempt_number", 0))) latest_presented: dict[str, dict[str, Any]] = {} for event in session_events: if event.get("event_type") == "descriptor_presented": latest_presented[str(event.get("descriptor_id", ""))] = event for descriptor_id, presented in latest_presented.items(): if not descriptor_id or descriptor_id in completed_ids: continue descriptor = _catalog_item(catalog, descriptor_id) answers = answers_by_descriptor.get(descriptor_id, []) attempts = [str(answer.get("selected_level", "")) for answer in answers] last_event = answers[-1] if answers else presented records.append( { "participant_id": presented.get("participant_id_hash", ""), "session_id": session_id, "descriptor_id": descriptor_id, "schema": start.get("schema") or descriptor.get("schema", ""), "modality": start.get("modality") or descriptor.get("modality", ""), "activity": start.get("activity") or descriptor.get("activity", ""), "scale": start.get("scale") or descriptor.get("scale", ""), # Il livello corretto non viene esposto finché l'esercizio # resta aperto. "level": "", "descriptor_text": descriptor.get("descriptor_text") or presented.get("descriptor_text", ""), "attempts": attempts, "attempts_text": " → ".join(attempts) if attempts else "—", "resolved": False, "resolved_on_attempt": None, "rationale": "", "occurred_at": last_event.get("occurred_at", ""), "outcome": "in_progress", "outcome_label": OUTCOME_LABELS["in_progress"], "content_revision": presented.get("content_revision") or start.get("content_revision", ""), "app_version": presented.get("app_version") or start.get("app_version", ""), "response_time_ms": sum( int(answer.get("response_time_ms") or 0) for answer in answers ) if any( answer.get("response_time_ms") is not None for answer in answers ) else None, "first_response_distance": ( answers[0].get("error_distance") if answers else None ), "exposure_number": presented.get("exposure_number"), } ) return sorted(records, key=lambda item: item["occurred_at"]) def session_records( events: Iterable[dict[str, Any]], catalog: Catalog ) -> list[dict[str, Any]]: events_list = list(events) histories = descriptor_history(events_list, catalog) history_by_session: dict[str, list[dict[str, Any]]] = defaultdict(list) for record in histories: history_by_session[record["session_id"]].append(record) rows: list[dict[str, Any]] = [] for session_id, session_events in group_sessions(events_list).items(): start = first_event(session_events, "session_started") if not start: continue completed_event = first_event(session_events, "session_completed") descriptor_records = history_by_session.get(session_id, []) presented_ids = { str(event.get("descriptor_id", "")) for event in session_events if event.get("event_type") == "descriptor_presented" } completed_ids = {record["descriptor_id"] for record in descriptor_records} in_progress_ids = presented_ids - completed_ids attempts_submitted = sum( event.get("event_type") == "answer_submitted" for event in session_events if str(event.get("descriptor_id", "")) in in_progress_ids ) counts = Counter(record["outcome"] for record in descriptor_records) total = len(descriptor_records) last_timestamp = max( (event.get("occurred_at", "") for event in session_events), default=start.get("occurred_at", ""), ) rows.append( { "session_id": session_id, "schema": start.get("schema", ""), "modality": start.get("modality", ""), "activity": start.get("activity", ""), "scale": start.get("scale", ""), "progression_phase": start.get("progression_phase", ""), "descriptor_ids": list(start.get("descriptor_order", [])), "available_levels": list(start.get("answer_levels", [])), "started_at": start.get("occurred_at", ""), "completed_at": ( completed_event.get("occurred_at", "") if completed_event else "" ), "last_activity_at": last_timestamp, "status": "completed" if completed_event else "in_progress", "status_label": "Completata" if completed_event else "In corso", "descriptors_completed": total, "descriptors_planned": len(start.get("descriptor_order", [])), "descriptors_started": len(presented_ids), "descriptors_in_progress": len(in_progress_ids), "attempts_submitted_in_progress": attempts_submitted, "first": counts["first"], "second": counts["second"], "third": counts["third"], "unresolved": counts["unresolved"], "first_attempt_rate": (counts["first"] / total * 100) if total else 0.0, "duration_seconds": _duration_seconds( start.get("occurred_at"), ( completed_event.get("occurred_at") if completed_event else last_timestamp ), ), "content_revision": start.get("content_revision", ""), "app_version": start.get("app_version", ""), } ) return sorted(rows, key=lambda item: item["started_at"], reverse=True) def scale_map( catalog: Catalog, events: Iterable[dict[str, Any]], path: tuple[str, str, str, str], *, session_id: str | None = None, outcome_filter: str = "all", ) -> list[dict[str, Any]]: schema, modality, activity, scale = path descriptors = catalog.for_scale(schema, modality, activity, scale) histories = [ record for record in descriptor_activity(events, catalog) if ( record["schema"], record["modality"], record["activity"], record["scale"], ) == path and (session_id is None or record["session_id"] == session_id) ] by_descriptor: dict[str, list[dict[str, Any]]] = defaultdict(list) for record in histories: by_descriptor[record["descriptor_id"]].append(record) order = {level: index for index, level in enumerate(catalog.level_order)} rows: list[dict[str, Any]] = [] for source_order, descriptor in enumerate(descriptors): history = by_descriptor.get(descriptor["descriptor_id"], []) latest = history[-1] if history else None status = latest["outcome"] if latest else "unseen" if not _matches_filter(status, outcome_filter): continue rows.append( { "descriptor_id": descriptor["descriptor_id"], "level": ( descriptor["correct_level"] if status != "in_progress" else "?" ), "text": descriptor["descriptor_text"], "status": status, "status_label": OUTCOME_LABELS[status], "when": ( relative_timestamp(latest["occurred_at"]) if latest else "" ), "attempts": latest["attempts_text"] if latest else "—", "source_order": source_order, "level_order": order.get(descriptor["correct_level"], -1), } ) return sorted( rows, key=lambda item: (-item["level_order"], item["source_order"]), ) def descriptor_details( descriptor_id: str, events: Iterable[dict[str, Any]], catalog: Catalog, *, session_id: str | None = None, user_facing_time: bool = True, ) -> dict[str, Any]: descriptor = _catalog_item(catalog, descriptor_id) activity = [ record for record in descriptor_activity(events, catalog) if record["descriptor_id"] == descriptor_id and (session_id is None or record["session_id"] == session_id) ] history = [record for record in activity if record["outcome"] != "in_progress"] open_records = [ record for record in activity if record["outcome"] == "in_progress" ] return { "descriptor": descriptor, "history": history, "in_progress": open_records, "latest_activity": activity[-1] if activity else None, "latest": history[-1] if history else None, "time_formatter": relative_timestamp if user_facing_time else exact_timestamp, } def participant_overview( events: Iterable[dict[str, Any]], catalog: Catalog ) -> dict[str, Any]: events_list = list(events) sessions = session_records(events_list, catalog) histories = descriptor_history(events_list, catalog) activities = descriptor_activity(events_list, catalog) latest_by_descriptor: dict[str, dict[str, Any]] = {} for record in histories: latest_by_descriptor[record["descriptor_id"]] = record latest_counts = Counter( record["outcome"] for record in latest_by_descriptor.values() ) first_count = latest_counts["first"] encountered = len(latest_by_descriptor) latest_activity_by_descriptor: dict[str, dict[str, Any]] = {} for record in activities: latest_activity_by_descriptor[record["descriptor_id"]] = record in_progress = sum( record["outcome"] == "in_progress" for record in latest_activity_by_descriptor.values() ) all_descriptors = len(catalog.all()) return { "sessions_started": len(sessions), "sessions_completed": sum( session["status"] == "completed" for session in sessions ), "sessions_in_progress": sum( session["status"] == "in_progress" for session in sessions ), "descriptors_encountered": len(latest_activity_by_descriptor), "descriptors_completed": encountered, "descriptors_in_progress": in_progress, "descriptors_available": all_descriptors, "latest_first_count": first_count, "latest_first_rate": ( first_count / encountered * 100 if encountered else 0.0 ), "last_activity_at": max( (event.get("occurred_at", "") for event in events_list), default="", ), "outcome_counts": latest_counts, } def integrity_report( events: Iterable[dict[str, Any]], participants: Iterable[dict[str, Any]] = (), ) -> list[dict[str, str]]: events_list = list(events) issues: list[dict[str, str]] = [] ids: Counter[str] = Counter( str(event.get("event_id", "")) for event in events_list ) for event_id, count in ids.items(): if not event_id: issues.append( {"severity": "errore", "scope": "evento", "message": "ID mancante"} ) elif count > 1: issues.append( { "severity": "errore", "scope": event_id, "message": f"ID evento duplicato ({count} occorrenze)", } ) participant_ids = { str(participant.get("participant_id", "")) for participant in participants } for event in events_list: participant = str(event.get("participant_id_hash", "")) if not participant: issues.append( { "severity": "errore", "scope": str(event.get("event_id", "")), "message": "Identificativo partecipante mancante", } ) elif participant_ids and participant not in participant_ids: issues.append( { "severity": "avviso", "scope": str(event.get("event_id", "")), "message": "Evento senza registro partecipante corrispondente", } ) if not parse_timestamp(event.get("occurred_at")): issues.append( { "severity": "errore", "scope": str(event.get("event_id", "")), "message": "Timestamp non valido o mancante", } ) for session_id, session_events in group_sessions(events_list).items(): starts = [ event for event in session_events if event.get("event_type") == "session_started" ] completions = [ event for event in session_events if event.get("event_type") == "session_completed" ] if len(starts) != 1: issues.append( { "severity": "errore", "scope": session_id, "message": f"Eventi di avvio sessione: {len(starts)}", } ) if len(completions) > 1: issues.append( { "severity": "errore", "scope": session_id, "message": "Più eventi di completamento sessione", } ) attempt_keys: Counter[tuple[str, int]] = Counter() for event in session_events: if event.get("event_type") == "answer_submitted": key = ( str(event.get("descriptor_id", "")), int(event.get("attempt_number") or 0), ) attempt_keys[key] += 1 for (descriptor_id, attempt), count in attempt_keys.items(): if count > 1: issues.append( { "severity": "errore", "scope": session_id, "message": ( f"Tentativo duplicato: {descriptor_id}, " f"tentativo {attempt}" ), } ) return issues def first_event( events: Iterable[dict[str, Any]], event_type: str ) -> dict[str, Any] | None: return next( (event for event in events if event.get("event_type") == event_type), None, ) def _catalog_item(catalog: Catalog, descriptor_id: str) -> dict[str, Any]: try: return catalog.get(descriptor_id) except CatalogError: return {"descriptor_id": descriptor_id} def _matches_filter(status: str, outcome_filter: str) -> bool: if outcome_filter in {"", "all"}: return True if outcome_filter == "focus": return status in FOCUS_OUTCOMES return status == outcome_filter def _duration_seconds(start: str | None, end: str | None) -> int | None: parsed_start = parse_timestamp(start) parsed_end = parse_timestamp(end) if not parsed_start or not parsed_end: return None return max(round((parsed_end - parsed_start).total_seconds()), 0) def _first_non_null(values: Iterable[Any]) -> Any: return next((value for value in values if value is not None), None)