semantics
This commit is contained in:
@@ -1,21 +1,19 @@
|
||||
# [DEF:ClarificationEngine:Module]
|
||||
# @COMPLEXITY: 4
|
||||
# @SEMANTICS: dataset_review, clarification, question_payload, answer_persistence, readiness, findings
|
||||
# @PURPOSE: Manage one-question-at-a-time clarification state, deterministic answer persistence, and readiness/finding updates.
|
||||
# @LAYER: Domain
|
||||
# @RELATION: DEPENDS_ON -> [DatasetReviewSessionRepository]
|
||||
# @RELATION: DEPENDS_ON -> [ClarificationSession]
|
||||
# @RELATION: DEPENDS_ON -> [ClarificationQuestion]
|
||||
# @RELATION: DEPENDS_ON -> [ClarificationAnswer]
|
||||
# @RELATION: DEPENDS_ON -> [ValidationFinding]
|
||||
# @RELATION: DISPATCHES -> [ClarificationHelpers:Module]
|
||||
# @PRE: Target session contains a persisted clarification aggregate in the current ownership scope.
|
||||
# @POST: Active clarification payload exposes one highest-priority unresolved question, and each recorded answer is persisted before pointer/readiness mutation.
|
||||
# @SIDE_EFFECT: Persists clarification answers, question/session states, and related readiness/finding changes.
|
||||
# @DATA_CONTRACT: Input[DatasetReviewSession|ClarificationAnswerCommand] -> Output[ClarificationStateResult]
|
||||
# @INVARIANT: Only one active clarification question may exist at a time; skipped and expert-review items remain unresolved and visible.
|
||||
# @RATIONALE: Original 635-line file exceeded INV_7 (400-line module limit). Extracted pure helpers into _helpers sub-module.
|
||||
# @REJECTED: Keeping all clarification logic in one file because it exceeded the fractal limit.
|
||||
# #region ClarificationEngine [C:4] [TYPE Module] [SEMANTICS dataset_review, clarification, question_payload, answer_persistence, readiness, findings]
|
||||
# @BRIEF Manage one-question-at-a-time clarification state, deterministic answer persistence, and readiness/finding updates.
|
||||
# @LAYER Domain
|
||||
# @PRE Target session contains a persisted clarification aggregate in the current ownership scope.
|
||||
# @POST Active clarification payload exposes one highest-priority unresolved question, and each recorded answer is persisted before pointer/readiness mutation.
|
||||
# @SIDE_EFFECT Persists clarification answers, question/session states, and related readiness/finding changes.
|
||||
# @DATA_CONTRACT Input[DatasetReviewSession|ClarificationAnswerCommand] -> Output[ClarificationStateResult]
|
||||
# @INVARIANT Only one active clarification question may exist at a time; skipped and expert-review items remain unresolved and visible.
|
||||
# @RELATION DEPENDS_ON -> [DatasetReviewSessionRepository]
|
||||
# @RELATION DEPENDS_ON -> [ClarificationSession]
|
||||
# @RELATION DEPENDS_ON -> [ClarificationQuestion]
|
||||
# @RELATION DEPENDS_ON -> [ClarificationAnswer]
|
||||
# @RELATION DEPENDS_ON -> [ValidationFinding]
|
||||
# @RELATION DISPATCHES -> [ClarificationHelpers:Module]
|
||||
# @RATIONALE Original 635-line file exceeded INV_7 (400-line module limit). Extracted pure helpers into _helpers sub-module.
|
||||
# @REJECTED Keeping all clarification logic in one file because it exceeded the fractal limit.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -56,9 +54,8 @@ from src.services.dataset_review.clarification_pkg._helpers import (
|
||||
log = MarkerLogger("ClarificationEngine")
|
||||
|
||||
|
||||
# [DEF:ClarificationQuestionPayload:Class]
|
||||
# @COMPLEXITY: 2
|
||||
# @PURPOSE: Typed active-question payload returned to the API layer.
|
||||
# #region ClarificationQuestionPayload [C:2] [TYPE Class]
|
||||
# @BRIEF Typed active-question payload returned to the API layer.
|
||||
@dataclass
|
||||
class ClarificationQuestionPayload:
|
||||
question_id: str
|
||||
@@ -72,12 +69,11 @@ class ClarificationQuestionPayload:
|
||||
options: list[dict[str, object]] = field(default_factory=list)
|
||||
|
||||
|
||||
# [/DEF:ClarificationQuestionPayload:Class]
|
||||
# #endregion ClarificationQuestionPayload
|
||||
|
||||
|
||||
# [DEF:ClarificationStateResult:Class]
|
||||
# @COMPLEXITY: 2
|
||||
# @PURPOSE: Clarification state result carrying the current session, active payload, and changed findings.
|
||||
# #region ClarificationStateResult [C:2] [TYPE Class]
|
||||
# @BRIEF Clarification state result carrying the current session, active payload, and changed findings.
|
||||
@dataclass
|
||||
class ClarificationStateResult:
|
||||
clarification_session: ClarificationSession
|
||||
@@ -86,12 +82,11 @@ class ClarificationStateResult:
|
||||
changed_findings: List[ValidationFinding] = field(default_factory=list)
|
||||
|
||||
|
||||
# [/DEF:ClarificationStateResult:Class]
|
||||
# #endregion ClarificationStateResult
|
||||
|
||||
|
||||
# [DEF:ClarificationAnswerCommand:Class]
|
||||
# @COMPLEXITY: 2
|
||||
# @PURPOSE: Typed answer command for clarification state mutation.
|
||||
# #region ClarificationAnswerCommand [C:2] [TYPE Class]
|
||||
# @BRIEF Typed answer command for clarification state mutation.
|
||||
@dataclass
|
||||
class ClarificationAnswerCommand:
|
||||
session: DatasetReviewSession
|
||||
@@ -101,32 +96,29 @@ class ClarificationAnswerCommand:
|
||||
user: User
|
||||
|
||||
|
||||
# [/DEF:ClarificationAnswerCommand:Class]
|
||||
# #endregion ClarificationAnswerCommand
|
||||
|
||||
|
||||
# [DEF:ClarificationEngine:Class]
|
||||
# @COMPLEXITY: 4
|
||||
# @PURPOSE: Provide deterministic one-question-at-a-time clarification selection and answer persistence.
|
||||
# @RELATION: DEPENDS_ON -> [DatasetReviewSessionRepository]
|
||||
# @RELATION: CALLS -> [ClarificationHelpers:Module]
|
||||
# @PRE: Repository is bound to the current request transaction scope.
|
||||
# @POST: Returned clarification state is persistence-backed and aligned with session readiness/recommended action.
|
||||
# @SIDE_EFFECT: Mutates clarification answers, session flags, and related clarification findings.
|
||||
# #region ClarificationEngine [C:4] [TYPE Class]
|
||||
# @BRIEF Provide deterministic one-question-at-a-time clarification selection and answer persistence.
|
||||
# @PRE Repository is bound to the current request transaction scope.
|
||||
# @POST Returned clarification state is persistence-backed and aligned with session readiness/recommended action.
|
||||
# @SIDE_EFFECT Mutates clarification answers, session flags, and related clarification findings.
|
||||
# @RELATION DEPENDS_ON -> [DatasetReviewSessionRepository]
|
||||
# @RELATION CALLS -> [ClarificationHelpers:Module]
|
||||
class ClarificationEngine:
|
||||
# [DEF:ClarificationEngine_init:Function]
|
||||
# @COMPLEXITY: 2
|
||||
# @PURPOSE: Bind repository dependency for clarification persistence operations.
|
||||
# #region ClarificationEngine_init [C:2] [TYPE Function]
|
||||
# @BRIEF Bind repository dependency for clarification persistence operations.
|
||||
def __init__(self, repository: DatasetReviewSessionRepository) -> None:
|
||||
self.repository = repository
|
||||
|
||||
# [/DEF:ClarificationEngine_init:Function]
|
||||
# #endregion ClarificationEngine_init
|
||||
|
||||
# [DEF:build_question_payload:Function]
|
||||
# @COMPLEXITY: 4
|
||||
# @PURPOSE: Return the one active highest-priority clarification question payload.
|
||||
# @PRE: Session contains unresolved clarification state or a resumable clarification session.
|
||||
# @POST: Returns exactly one active/open question payload or None when no unresolved question remains.
|
||||
# @SIDE_EFFECT: Normalizes the active-question pointer and clarification status in persistence.
|
||||
# #region build_question_payload [C:4] [TYPE Function]
|
||||
# @BRIEF Return the one active highest-priority clarification question payload.
|
||||
# @PRE Session contains unresolved clarification state or a resumable clarification session.
|
||||
# @POST Returns exactly one active/open question payload or None when no unresolved question remains.
|
||||
# @SIDE_EFFECT Normalizes the active-question pointer and clarification status in persistence.
|
||||
def build_question_payload(
|
||||
self, session: DatasetReviewSession,
|
||||
) -> Optional[ClarificationQuestionPayload]:
|
||||
@@ -179,14 +171,13 @@ class ClarificationEngine:
|
||||
log.reflect("Clarification payload built", payload={"session_id": session.session_id, "question_id": payload.question_id, "option_count": len(payload.options)})
|
||||
return payload
|
||||
|
||||
# [/DEF:build_question_payload:Function]
|
||||
# #endregion build_question_payload
|
||||
|
||||
# [DEF:record_answer:Function]
|
||||
# @COMPLEXITY: 4
|
||||
# @PURPOSE: Persist one clarification answer before any pointer/readiness mutation.
|
||||
# @PRE: Target question belongs to the session's active clarification session and is still open.
|
||||
# @POST: Answer row is persisted before current-question pointer advances.
|
||||
# @SIDE_EFFECT: Inserts answer row, mutates question/session states, updates clarification findings, and commits.
|
||||
# #region record_answer [C:4] [TYPE Function]
|
||||
# @BRIEF Persist one clarification answer before any pointer/readiness mutation.
|
||||
# @PRE Target question belongs to the session's active clarification session and is still open.
|
||||
# @POST Answer row is persisted before current-question pointer advances.
|
||||
# @SIDE_EFFECT Inserts answer row, mutates question/session states, updates clarification findings, and commits.
|
||||
def record_answer(self, command: ClarificationAnswerCommand) -> ClarificationStateResult:
|
||||
with belief_scope("ClarificationEngine.record_answer"):
|
||||
session = command.session
|
||||
@@ -266,41 +257,36 @@ class ClarificationEngine:
|
||||
changed_findings=[changed_finding] if changed_finding else [],
|
||||
)
|
||||
|
||||
# [/DEF:record_answer:Function]
|
||||
# #endregion record_answer
|
||||
|
||||
# [DEF:summarize_progress:Function]
|
||||
# @COMPLEXITY: 1
|
||||
# @PURPOSE: Produce a compact progress summary for pause/resume and completion UX.
|
||||
# #region summarize_progress [C:1] [TYPE Function]
|
||||
# @BRIEF Produce a compact progress summary for pause/resume and completion UX.
|
||||
def summarize_progress(self, clarification_session: ClarificationSession) -> str:
|
||||
resolved = count_resolved_questions(clarification_session)
|
||||
remaining = count_remaining_questions(clarification_session)
|
||||
return f"{resolved} resolved, {remaining} unresolved"
|
||||
|
||||
# [/DEF:summarize_progress:Function]
|
||||
# #endregion summarize_progress
|
||||
|
||||
# [DEF:_get_latest_clarification_session:Function]
|
||||
# @COMPLEXITY: 2
|
||||
# @PURPOSE: Select the latest clarification session for the current dataset review aggregate.
|
||||
# #region _get_latest_clarification_session [C:2] [TYPE Function]
|
||||
# @BRIEF Select the latest clarification session for the current dataset review aggregate.
|
||||
def _get_latest_clarification_session(self, session: DatasetReviewSession) -> Optional[ClarificationSession]:
|
||||
if not session.clarification_sessions:
|
||||
return None
|
||||
ordered = sorted(session.clarification_sessions, key=lambda item: (item.started_at, item.clarification_session_id), reverse=True)
|
||||
return ordered[0]
|
||||
|
||||
# [/DEF:_get_latest_clarification_session:Function]
|
||||
# #endregion _get_latest_clarification_session
|
||||
|
||||
# [DEF:_find_question:Function]
|
||||
# @COMPLEXITY: 1
|
||||
# @PURPOSE: Resolve a clarification question from the active clarification aggregate.
|
||||
# #region _find_question [C:1] [TYPE Function]
|
||||
# @BRIEF Resolve a clarification question from the active clarification aggregate.
|
||||
def _find_question(self, clarification_session: ClarificationSession, question_id: str) -> Optional[ClarificationQuestion]:
|
||||
for q in clarification_session.questions:
|
||||
if q.question_id == question_id:
|
||||
return q
|
||||
return None
|
||||
|
||||
# [/DEF:_find_question:Function]
|
||||
# #endregion _find_question
|
||||
|
||||
|
||||
# [/DEF:ClarificationEngine:Class]
|
||||
|
||||
# [/DEF:ClarificationEngine:Module]
|
||||
# #endregion ClarificationEngine
|
||||
|
||||
Reference in New Issue
Block a user