Add Phase Z runtime foundation
- add visual fit classifier, router, retry, and failure routing modules - add composition planner and catalog-driven mapper - add Phase Z pipeline orchestration and architecture docs
This commit is contained in:
181
src/phase_z2_router.py
Normal file
181
src/phase_z2_router.py
Normal file
@@ -0,0 +1,181 @@
|
||||
"""Phase Z-2 overflow_router v0 (A2 — 정책 매핑 layer 만).
|
||||
|
||||
fit_classifier 의 출력 (category) 를 spec §4 의 *proposed_action* 으로 매핑하는 layer.
|
||||
|
||||
본 module 은 ***매핑까지만***. 실제 action 실행은 별도 step (A3+).
|
||||
출력 = 각 classification 에 proposed_action 추가 + router 전체 summary.
|
||||
|
||||
원칙 :
|
||||
- classifier = 사실 분류 (category 결정)
|
||||
- router = 정책 결정 (그 category 면 무엇을 *제안* 할 것인가)
|
||||
- 본 단계는 *제안 trace* 만. pipeline behavior / abort 정책 / rerender 변경 X
|
||||
- 실행 안 됨 → 현재 코드는 여전히 visual_check_passed=False 시 sys.exit(1)
|
||||
그러나 debug.json 에 *어떤 action 이 제안됐는지* 가 기록됨
|
||||
|
||||
다음 step (별도 — A3) :
|
||||
zone_ratio_retry action 의 *실제 구현* — 지금 spec §4 mapping 의 가장 자주
|
||||
트리거되는 action.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Optional
|
||||
|
||||
|
||||
# ─── §4 mapping table (spec PHASE-Z-FIT-CLASSIFIER-ROUTER-SPEC §4) ──
|
||||
|
||||
# category → proposed_action (primary)
|
||||
ACTION_BY_CATEGORY: dict[str, str] = {
|
||||
"minor_overflow": "zone_ratio_retry",
|
||||
"moderate_overflow": "layout_adjust",
|
||||
"structural_minor_overflow": "zone_ratio_retry",
|
||||
"structural_major_overflow": "details_popup_escalation",
|
||||
"tabular_overflow": "details_popup_escalation",
|
||||
"frame_capacity_mismatch": "frame_reselect",
|
||||
"layout_zone_mismatch": "layout_adjust",
|
||||
"hard_visual_fail": "abort",
|
||||
}
|
||||
|
||||
# 매핑 근거 — *왜 이 category 면 이 action 인가* trace 용
|
||||
ACTION_RATIONALE: dict[str, str] = {
|
||||
"minor_overflow":
|
||||
"1.5 줄 미만 text/label flow → zone 양보 / spacing 재계산으로 fit 가능",
|
||||
"moderate_overflow":
|
||||
"1.5~4 줄 text/label → layout/zone ratio 재분배 필요",
|
||||
"structural_minor_overflow":
|
||||
"structural unit boundary spill (<1 unit drop) → zone 양보로 fit, 단위 자르기 X",
|
||||
"structural_major_overflow":
|
||||
"1+ structural unit 완전 잘림 → 의미 손실, popup 으로 escalate",
|
||||
"tabular_overflow":
|
||||
"표는 행 단위로 잘리면 의미 손실 → popup escalate (또는 table-friendly frame reselect)",
|
||||
"frame_capacity_mismatch":
|
||||
"composition capacity_fit 가 이미 mismatch 신호 → V4 top-k 의 다른 frame 평가",
|
||||
"layout_zone_mismatch":
|
||||
"frame root 자체 overflow → layout preset 변경 또는 zone 키움",
|
||||
"hard_visual_fail":
|
||||
"위 매핑 모두 미적용 — 마지막 fallback (현재 코드는 sys.exit 으로 abort)",
|
||||
}
|
||||
|
||||
# 각 action 의 *현재 코드* 구현 상태 (2026-04-29 기준)
|
||||
# A2 단계에서 이 매핑이 *어디까지 자동 처리되고 어디서 막히는지* trace 확보용
|
||||
ACTION_IMPLEMENTATION_STATUS: dict[str, str] = {
|
||||
"zone_ratio_retry": "IMPLEMENTED", # A3 (2026-04-29) phase_z2_retry.plan_zone_ratio_retry + pipeline orchestration
|
||||
"layout_adjust": "MISSING",
|
||||
"details_popup_escalation": "MISSING", # CLAUDE.md 의 <details> 원칙은 있음, runtime 미구현
|
||||
"frame_reselect": "MISSING", # V4 top-k 자료는 있음, planner 가 rank-1 만
|
||||
"adapter_needed": "PARTIAL", # composition v0.1.1 의 mapper FitError catch
|
||||
"abort": "IMPLEMENTED", # sys.exit(1) — pipeline 의 현재 default
|
||||
}
|
||||
|
||||
|
||||
# ─── 단일 분류 → routing 결과 ─────────────────────────────────────
|
||||
|
||||
|
||||
def route_action(category: str) -> dict:
|
||||
"""category → proposed_action mapping 결과 (단일).
|
||||
|
||||
Returns:
|
||||
dict :
|
||||
proposed_action : action 이름 (또는 None)
|
||||
rationale : *왜* 이 action 인가
|
||||
implementation_status : implemented / partial / missing / unknown
|
||||
mapping_source : "spec §4 ACTION_BY_CATEGORY" 또는 "no mapping"
|
||||
"""
|
||||
action = ACTION_BY_CATEGORY.get(category)
|
||||
if action is None:
|
||||
return {
|
||||
"proposed_action": None,
|
||||
"rationale": f"category '{category}' has no mapping in ACTION_BY_CATEGORY",
|
||||
"implementation_status": "unknown",
|
||||
"mapping_source": "no mapping (unknown category)",
|
||||
}
|
||||
return {
|
||||
"proposed_action": action,
|
||||
"rationale": ACTION_RATIONALE.get(category, ""),
|
||||
"implementation_status": ACTION_IMPLEMENTATION_STATUS.get(action, "unknown"),
|
||||
"mapping_source": "spec §4 ACTION_BY_CATEGORY",
|
||||
}
|
||||
|
||||
|
||||
# ─── fit_classification 전체 → router decision ──────────────────
|
||||
|
||||
|
||||
def route_fit_classification(fit_classification: dict) -> dict:
|
||||
"""fit_classification 의 모든 classifications 에 proposed_action 추가 + summary.
|
||||
|
||||
각 classification 에 다음 필드를 *추가* (기존 필드 보존) :
|
||||
- proposed_action
|
||||
- proposed_action_rationale
|
||||
- proposed_action_implementation_status
|
||||
- proposed_action_mapping_source
|
||||
|
||||
Returns:
|
||||
router decision summary dict :
|
||||
router_active : True/False (visual_check_passed=False 일 때만 True)
|
||||
proposed_actions_summary : unique action 들 sorted list
|
||||
implementation_status_summary : {status: count} dict
|
||||
routed_count : 처리된 classification 수
|
||||
routed_details : per-classification routing trace
|
||||
missing_actions_pending_impl : 본 routing 에서 *현재 미구현* 인 action 모음
|
||||
note : 사용자 안내 텍스트
|
||||
"""
|
||||
if fit_classification.get("visual_check_passed", True):
|
||||
return {
|
||||
"router_active": False,
|
||||
"proposed_actions_summary": [],
|
||||
"implementation_status_summary": {},
|
||||
"routed_count": 0,
|
||||
"routed_details": [],
|
||||
"missing_actions_pending_impl": [],
|
||||
"note": "visual check passed — no overflow to route",
|
||||
}
|
||||
|
||||
classifications = fit_classification.get("classifications", []) or []
|
||||
routed_details = []
|
||||
|
||||
for cls in classifications:
|
||||
category = cls.get("category", "hard_visual_fail")
|
||||
routing = route_action(category)
|
||||
|
||||
# classification entry 에 proposed_action 정보 *추가* (기존 필드 보존)
|
||||
cls["proposed_action"] = routing["proposed_action"]
|
||||
cls["proposed_action_rationale"] = routing["rationale"]
|
||||
cls["proposed_action_implementation_status"] = routing["implementation_status"]
|
||||
cls["proposed_action_mapping_source"] = routing["mapping_source"]
|
||||
|
||||
routed_details.append({
|
||||
"source": cls.get("source"),
|
||||
"zone_position": cls.get("zone_position"),
|
||||
"category": category,
|
||||
"proposed_action": routing["proposed_action"],
|
||||
"implementation_status": routing["implementation_status"],
|
||||
})
|
||||
|
||||
# summary
|
||||
actions_seen = sorted({
|
||||
r["proposed_action"] for r in routed_details
|
||||
if r["proposed_action"] is not None
|
||||
})
|
||||
status_breakdown: dict[str, int] = {}
|
||||
missing_actions: list[str] = []
|
||||
for r in routed_details:
|
||||
s = r["implementation_status"]
|
||||
status_breakdown[s] = status_breakdown.get(s, 0) + 1
|
||||
if s == "MISSING" and r["proposed_action"] not in missing_actions:
|
||||
missing_actions.append(r["proposed_action"])
|
||||
|
||||
return {
|
||||
"router_active": True,
|
||||
"proposed_actions_summary": actions_seen,
|
||||
"implementation_status_summary": status_breakdown,
|
||||
"routed_count": len(routed_details),
|
||||
"routed_details": routed_details,
|
||||
"missing_actions_pending_impl": sorted(missing_actions),
|
||||
"note": (
|
||||
"router 는 category → proposed_action 매핑까지 담당. 실제 action 실행은 "
|
||||
"pipeline 의 별도 orchestrator 가 처리 (예: zone_ratio_retry 는 "
|
||||
"_attempt_zone_ratio_retry 에서 실행). proposed_action 의 implementation_status "
|
||||
"가 IMPLEMENTED 이면 pipeline 이 시도하고 결과는 retry_trace 에 기록, "
|
||||
"MISSING 이면 그 action 은 실행 X 이고 기존 abort/status 흐름 (sys.exit(1)) 으로 종료."
|
||||
),
|
||||
}
|
||||
Reference in New Issue
Block a user