busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

semantics

Browse Source
This commit is contained in:
busya
2026-05-12 20:06:16 +03:00
parent 0d56842ac6
commit 13f40048c1
459 changed files with 13698 additions and 13915 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
backend/src/services/reports/normalizer.py
View File

@@ -1,16 +1,14 @@
# [DEF:normalizer:Module]
# @COMPLEXITY: 5
# @SEMANTICS: reports, normalization, tasks, fallback
# @PURPOSE: Convert task manager task objects into canonical unified TaskReport entities with deterministic fallback behavior.
# @LAYER: Domain
# @RELATION: DEPENDS_ON ->[backend.src.core.task_manager.models.Task:Function]
# @RELATION: DEPENDS_ON ->[backend.src.models.report:Function]
# @RELATION: DEPENDS_ON ->[backend.src.services.reports.type_profiles:Function]
# @INVARIANT: Normalizer instance maintains consistent field order
# @DATA_CONTRACT: ReportRow -> NormalizerInput; session_id -> valid UUID
# @PRE: session is active and valid
# @POST: Returns Normalizer output with normalized fields
# @SIDE_EFFECT: Read-only database operations
# #region normalizer [C:5] [TYPE Module] [SEMANTICS reports, normalization, tasks, fallback]
# @BRIEF Convert task manager task objects into canonical unified TaskReport entities with deterministic fallback behavior.
# @LAYER Domain
# @PRE session is active and valid
# @POST Returns Normalizer output with normalized fields
# @SIDE_EFFECT Read-only database operations
# @DATA_CONTRACT ReportRow -> NormalizerInput; session_id -> valid UUID
# @INVARIANT Normalizer instance maintains consistent field order
# @RELATION DEPENDS_ON -> [backend.src.core.task_manager.models.Task:Function]
# @RELATION DEPENDS_ON -> [backend.src.models.report:Function]
# @RELATION DEPENDS_ON -> [backend.src.services.reports.type_profiles:Function]
# [SECTION: IMPORTS]
from datetime import datetime
@@ -23,10 +21,10 @@ from .type_profiles import get_type_profile, resolve_task_type
# [/SECTION]
# [DEF:status_to_report_status:Function]
# @PURPOSE: Normalize internal task status to canonical report status.
# @PRE: status may be known or unknown string/enum value.
# @POST: Always returns one of canonical ReportStatus values.
# #region status_to_report_status [TYPE Function]
# @BRIEF Normalize internal task status to canonical report status.
# @PRE status may be known or unknown string/enum value.
# @POST Always returns one of canonical ReportStatus values.
# @PARAM: status (Any) - Internal task status value.
# @RETURN: ReportStatus - Canonical report status.
def status_to_report_status(status: Any) -> ReportStatus:
@@ -39,13 +37,13 @@ def status_to_report_status(status: Any) -> ReportStatus:
if raw in {TaskStatus.PENDING.value, TaskStatus.RUNNING.value, TaskStatus.AWAITING_INPUT.value, TaskStatus.AWAITING_MAPPING.value}:
return ReportStatus.IN_PROGRESS
return ReportStatus.PARTIAL
# [/DEF:status_to_report_status:Function]
# #endregion status_to_report_status
# [DEF:build_summary:Function]
# @PURPOSE: Build deterministic user-facing summary from task payload and status.
# @PRE: report_status is canonical; plugin_id may be unknown.
# @POST: Returns non-empty summary text.
# #region build_summary [TYPE Function]
# @BRIEF Build deterministic user-facing summary from task payload and status.
# @PRE report_status is canonical; plugin_id may be unknown.
# @POST Returns non-empty summary text.
# @PARAM: task (Task) - Source task object.
# @PARAM: report_status (ReportStatus) - Canonical status.
# @RETURN: str - Normalized summary.
@@ -64,13 +62,13 @@ def build_summary(task: Task, report_status: ReportStatus) -> str:
if report_status == ReportStatus.IN_PROGRESS:
return "Task is in progress"
return "Task completed with partial data"
# [/DEF:build_summary:Function]
# #endregion build_summary
# [DEF:extract_error_context:Function]
# @PURPOSE: Extract normalized error context and next actions for failed/partial reports.
# @PRE: task is a valid Task object.
# @POST: Returns ErrorContext for failed/partial when context exists; otherwise None.
# #region extract_error_context [TYPE Function]
# @BRIEF Extract normalized error context and next actions for failed/partial reports.
# @PRE task is a valid Task object.
# @POST Returns ErrorContext for failed/partial when context exists; otherwise None.
# @PARAM: task (Task) - Source task.
# @PARAM: report_status (ReportStatus) - Canonical status.
# @RETURN: Optional[ErrorContext] - Error context block.
@@ -108,13 +106,13 @@ def extract_error_context(task: Task, report_status: ReportStatus) -> Optional[E
next_actions = ["Review task diagnostics", "Retry the operation"]
return ErrorContext(code=code, message=message, next_actions=next_actions)
# [/DEF:extract_error_context:Function]
# #endregion extract_error_context
# [DEF:normalize_task_report:Function]
# @PURPOSE: Convert one Task to canonical TaskReport envelope.
# @PRE: task has valid id and plugin_id fields.
# @POST: Returns TaskReport with required fields and deterministic fallback behavior.
# #region normalize_task_report [TYPE Function]
# @BRIEF Convert one Task to canonical TaskReport envelope.
# @PRE task has valid id and plugin_id fields.
# @POST Returns TaskReport with required fields and deterministic fallback behavior.
# @PARAM: task (Task) - Source task.
# @RETURN: TaskReport - Canonical normalized report.
#
@@ -170,6 +168,6 @@ def normalize_task_report(task: Task) -> TaskReport:
error_context=extract_error_context(task, report_status),
source_ref=source_ref or None,
)
# [/DEF:normalize_task_report:Function]
# #endregion normalize_task_report
# [/DEF:normalizer:Module]
# #endregion normalizer