AI Engineering · LLM Boundary Design

LLM을 어디에 둘지 설계한 멀티에이전트 자산관리 백엔드

이 백엔드를 관통하는 한 가지 원칙은 "의도 파악·답변 생성만 LLM, 금융 계산·룰·절대값은 결정론 코드"입니다. 노후 자금 시뮬레이션을 대화형(CHAT)으로 저지연 응답하되 환각이 숫자에 끼어들지 못하게 LLM 권한을 좁히고, 재무 건강도를 결정론 코어로 진단해 그 신뢰 가능한 결과 위에서 답하며, 모든 위험 판단을 추적 가능한 근거 그래프(Evidence Graph)로 적재하고, 이 모듈들을 Supervisor 그래프로 하나의 워크플로우로 엮었습니다. "근거 없는 위험 주장 금지", "결과는 절대 유실하지 않는다", "LLM은 꼭 필요한 자리에만"을 시스템 불변식으로 강제하는 데 집중했습니다.

Python 3.11 LangGraph StateGraph FastAPI SQLAlchemy · MySQL Neo4j (옵션) LLM structured output 담당 모듈 4종

At a glance

한눈에 보기

결정론적 재무 룰 — ① Financial Health

3-way

LLM 의도 분류 + fast-path — ② CHAT

2-tier

그래프 백엔드 (MySQL/Neo4j) — ③ Evidence

9-node

오케스트레이션 그래프 — ④ Supervisor

네 모듈을 관통하는 설계 판단은 "LLM을 어디에 두고 어디에 두지 않을지"입니다 — 금융 계산·룰·절대값은 결정론 코드가 쥐고, LLM은 의도 분류·답변 생성에만 둡니다. 구현상으로는 SharedState(LangGraph TypedDict + reducer)라는 공통 계약 위에서 맞물립니다. 재무건강도가 근거 조각을 생산하면, 노후 CHAT 모드가 그 위에서 대화형 답변을 만들고, Evidence Graph가 모든 위험 판단을 탐색 가능한 그래프로 영속화하며, Supervisor가 여러 에이전트의 기여를 하나의 run으로 통합합니다.

재무건강도 ──▶ 노후 CHAT ── evidence_refs / rule_checks ──▶ Evidence Graph ── 통합 적재 ──▶ Supervisor

System architecture

시스템 아키텍처

HTTP 요청 → Supervisor 그래프가 라우팅·디스패치 → 각 분석 에이전트가 SharedState에 기여 → 종단에서 근거 그래프를 단일 writer로 적재 → 결과·감사기록을 MySQL에 영속화하는 구조입니다.

# 전체 워크플로우 진입점: POST /agents/supervisor/run
HTTP ─▶ build_supervisor_graph(container)
          │
          ├─ route            # event → routing.{workflow_type, selected_agents, mode}
          ├─ prepare_parent   # 다중이면 parent run 1개 발급 → meta.run_id 고정
          ├─ financial_health # ★ 담당: 결정론적 진단 + 근거 생산
          ├─ orchestrator ─┬─ retirement_chat   # mode=CHAT  (경량 시뮬)
          │                └─ retirement_report # mode=REPORT (LLM 딥다이브)
          ├─ persist_graph    # ★ 담당: Evidence Graph 통합 적재 (단일 writer)
          └─ finalize_parent  # child run 상태로 parent status 산정·마감

저장소: MySQL (SSOT · 결과/감사/그래프 기본)  ·  Neo4j (옵션 그래프 백엔드)

설계 원칙 graph_builder는 변환(오케스트레이션)만 담당하고 실제 적재는 GraphRepository 구현체에 위임 — 동일 빌더 로직으로 MySQL/Neo4j 백엔드를 교체할 수 있게 Repository 패턴으로 분리했습니다.

Scope of ownership

담당 범위

① 재무건강도 결정론 코어

LLM을 의도적으로 배제하고 자산·현금흐름·부채·유동성·보험 5개 영역을 결정론적으로 채점, 16개 룰을 평가해 등급(A~D)·위험플래그·근거를 산출하는 분석 에이전트. 환각이 금융 결론에 끼어들 여지를 구조적으로 제거.

16-rule engine100점 스코어링 KLoSA 동연령 보정commit-first 감사

② 노후 시뮬레이션 CHAT 모드

사용자 발화를 3-way LLM 의도 분류로 가르고, 시나리오는 delta-only로만 받아 코드가 절대값을 계산. 경량 시뮬 1회 + LLM 응답 1콜로 대화형 답변을 만드는 저지연 경로.

3-way intentdelta-only override 그래프 적재 이연준법 rewrite 루프

③ Graph Evidence Layer

SharedState 기여분을 노드/엣지/경로로 변환해 단일 트랜잭션으로 적재하는 cross-agent 공용 근거 레이어. MySQL 기본 + Neo4j 옵션, 멱등·검증·조회 포함.

Repository 패턴단일 트랜잭션 멱등 가드근거 무결성 검증

④ Supervisor 워크플로우 연결

라우팅 → 디스패치 → 종단 통합 적재까지 LangGraph로 엮은 오케스트레이터. FH 전제 순차 실행, 모드 분기, parent/child run 생명주기, 부분실패 격리.

9-node graphrun_id 이원화 부분실패 격리SharedState reducer

공통 계약 (SharedState)

세 모듈이 합의한 인터페이스. 리스트 키는 append reducer, analysis_results는 키별 병합 reducer로 병렬 fan-in 시 유실을 방지합니다.

TypedDictAnnotated reducerby_alias 직렬화

Module 1 · Financial Health

재무건강도 분석 — LLM을 의도적으로 배제한 결정론 코어

customer_id 하나만 받아 데이터 수집 → 결정론적 채점 → 룰 평가 → 등급·근거 산출 → 영속화까지 끝내는 분석 에이전트입니다. 금융 판단의 본체는 LLM이 아니라 검증 가능한 코드여야 한다고 보고 이 모듈에는 LLM 추론을 전혀 두지 않았습니다. 핵심은 "같은 입력이면 항상 같은 결과"인 결정론적 코어와, 그 결과를 감사 가능하게 저장하는 run 생명주기 분리이며 — 이것이 뒤이어 나오는 노후 CHAT 모드가 신뢰하고 소비하는 숫자 기반이 됩니다.

채점 영역 (asset/cashflow/debt/liquidity/insurance)

25·25·20·15·15

영역별 배점 = 100점

A~D

등급 (80/65/50 임계)

Decimal

금전 계산 정밀도 보장

결정론적 룰·스코어링 엔진

분석 코어(agent.py)는 DB와 완전히 분리된 순수 함수입니다. FinancialMetrics → compute_scores() + evaluate() → FinancialHealthResult. 각 영역 점수는 구간별 대표 점수를 결정론적으로 부여한 뒤 KLoSA(고령화연구패널) 동연령 보정을 적용하고 [0, max]로 클램프합니다.

# scoring/scorer.py — 현금흐름 영역(25점) 채점 발췌
def _cashflow_score(m: FinancialMetrics) -> Decimal:
    rate = m.net_cashflow_amt / m.monthly_income_amt
    if   rate >= D("0.20"): score = D("24")
    elif rate >= D("0.10"): score = D("18")
    elif rate >= D("0"):    score = D("11")
    else:                   score = D("4")
    # 2개월 연속 적자 → 추가 감점 (지속 위험 신호)
    if len(m.cashflow_history[-2:]) >= 2 and all(c < 0 for c in recent):
        score -= D("5")
    return _clamp(score, D("0"), D("25"))

룰 엔진(rules/)은 16개 룰을 SSOT 상수로 정의하고, 발동된 룰만 RuleCheck로 반환합니다. 각 RuleCheck에는 evidence_id(ev-<slug>-<cid> 규약)를 부여해 — 뒤의 Validator가 "근거 없는 위험"을 차단할 수 있게 합니다.

영역	대표 룰	심각도
순자산	`FH_NET_WORTH_NEGATIVE` · `..._BELOW_PEER_P25`	WARN / INFO
현금흐름	`FH_CASHFLOW_NEGATIVE` · `..._RISK_SUSTAINED`	WARN / DANGER
부채	`FH_DSR_HIGH` · `FH_DSR_CRITICAL` · `FH_HIGH_RATE_LOAN`	WARN / DANGER
유동성	`FH_LIQUIDITY_SHORTAGE` · `FH_DEPOSIT_EXPIRING_SOON`	DANGER / INFO
보험·의료	`FH_MEDICAL_BURDEN_HIGH` · `FH_COVERAGE_GAP_CANCER`	WARN
KLoSA 비교	`FH_PENSION_INCOME_BELOW_PEER_P25` 외 3종	WARN / INFO

엔지니어링 디테일 — 책임 경계 원래 18룰 중 방치자금(idle fund) 2룰은 retirement 모듈 소유로 이관하고, 유동성 부족은 재무건강도 고유 책임으로 유지했습니다. assert len(RULES) == 16으로 룰 개수 회귀를 코드 레벨에서 박제합니다.

collect → calc → rules → score 서브그래프

결정론적 코어를 LangGraph StateGraph로 감싸 선형 파이프라인으로 컴파일합니다. collect 노드는 두 경로를 지원합니다 — 호출부가 fh_metrics를 주입하면 순수 계산만, container가 배선돼 있으면 customer_repository(SSOT)에서 직접 수집.

START▶ collect▶ calc▶ rules▶ score▶ END

식별자 정합성 (A-5) — event.customer_id가 정본. 주입 메트릭과 어긋나면 collect에서 즉시 차단해 조용한 오동작을 막습니다.
엔트리포인트 안전성 — make_graph()는 Container를 배선한 팩토리로 노출. 모듈레벨에서 container 없이 빌드하면 DB 수집 경로가 영구히 죽는 함정을 회피합니다.
지연 초기화 — Container provider가 lazy라 그래프 빌드 시점엔 DB 연결을 열지 않고, collect 실행 시 비로소 세션을 엽니다 (context manager로 수명 관리).

Run 생명주기 서비스 — commit-first 감사 펜싱

순수 계산과 영속화·감사기록을 명확히 분리한 것이 이 모듈에서 가장 공들인 부분입니다. run을 RUNNING으로 먼저 선커밋한 뒤 결과를 적재 — 중간에 어디서 실패해도 FAILED 감사기록이 남고, 결과는 COMPLETED 커밋이 성공해야만 영구 보존됩니다.

# run_service.py — A-3 커밋-퍼스트 펜싱
run_id = run_repo.create_run(..., status="RUNNING")
session.commit()                # ① 선커밋 — 이후 rollback 에도 감사기록 보존
try:
    refs = fh_repo.persist_results(run_id, metrics, result)
    run_repo.finish_run(run_id, output, status="COMPLETED")
    session.commit()            # ② 결과+완료를 단일 트랜잭션으로 확정
except Exception as exc:
    session.rollback()
    run_repo.finish_run(run_id, {"error": ...}, status="FAILED")
    session.commit()            # ③ 실패도 박제 후 재발생
    raise

customer_id 단일 진입점 — 스케줄러·수동·API·Supervisor가 공유하는 run_financial_health_check(). 수집→계산→저장→그래프까지 한 함수로 끝냅니다.
멱등 가드 (#74) — 오늘자 동일 workflow의 COMPLETED run이 있으면 재실행 없이 재사용해 배치 중복을 방지. 단 RUNNING 좀비 행은 재사용하지 않습니다.
입력 경계 방어 (#77) — customer_id <= 0이면 Supervisor의 무검증 전달을 가정해 즉시 ValueError. 데이터 부족은 InsufficientDataError로 422 매핑.
그래프 적재 분리 (#83) — persist_graph=False 플래그로 단독 run(자체 적재) vs Supervisor 통합 적재(이중 적재 방지)를 전환합니다.

Module 2 · Retirement CHAT Mode

노후 시뮬레이션 CHAT 모드

기존 노후 시뮬레이션에는 여러 가설을 LLM으로 비교·분석하는 무거운 REPORT 모드(10~15초)가 있었습니다. 그 옆에 단발 대화형 질의응답을 위한 CHAT 모드를 설계했습니다. 예: "은퇴를 5년 늦추면 자금이 충분할까?" → "○○ 조건으로 계산하면 73세에 자금이 바닥날 것 같습니다…"

핵심 목표는 지연(latency)이었습니다. 채팅에서 10초대 응답은 부적합하므로, 꼭 필요한 LLM 호출만 남기고 무거운 연산을 잘라낸 별도 경로를 만들었습니다. 설계 전반을 관통하는 원칙은 "계산·룰·절대값은 결정론, 의도 파악·답변 생성만 LLM"입니다.

3-way

의도 분류 (SIMULATE / CHITCHAT / UNRELATED)

delta

LLM은 변화량만, 절대값은 코드가 계산

1-call

응답 생성 LLM 호출 (REPORT는 가설 N개)

~5.5s

그래프 적재 이연 후 warm 응답(개발 실측 참고치)

3-way LLM 의도 분류 + 결정론 fast-path

CHAT 모드의 첫 관문은 사용자 발화의 의도를 3가지로 분류하는 것입니다(nodes/chat_intent_classifier.py). 여기서 비용·지연을 의식한 하이브리드 분류기를 설계했습니다.

# core/constants.py
class ChatIntent(str, Enum):
    SIMULATE  = "SIMULATE"   # 시뮬레이션 실행 후 질문 맞춤 답변
    CHITCHAT  = "CHITCHAT"   # 인사/감사 → 템플릿 응답 (LLM·시뮬 불필요)
    UNRELATED = "UNRELATED"  # 범위 밖 발화 → 안내 템플릿

① 결정론 fast-path 먼저 — 은퇴 도메인 키워드(노후/은퇴/연금/자금/소진…)·인사 키워드로 확신이 서면 LLM 없이 즉시 분류.
② 불확실할 때만 LLM — fast-path가 애매하면 그제서야 LLM을 structured output으로 1회 호출.
③ 실패 시 graceful fallback — LLM 호출이 실패하면 결정론 분류로 강등(서비스는 죽지 않음).

효과 인사·확실한 시나리오 질의 등 상당수 요청이 fast-path에서 끝나 불필요한 LLM 1콜(~1초)을 절약합니다. 의도가 SIMULATE가 아니면 시뮬레이션·응답 생성 자체를 건너뜁니다.

LLM은 "델타"만 — 절대값은 코드가 계산

가장 공들인 설계 결정입니다. 시나리오 파라미터를 LLM이 절대값으로 뱉지 않게 했습니다. LLM은 변화량(delta)만 출력하고, 실제 절대값은 data_snapshot의 기준값에 코드가 적용합니다(nodes/scenario_overrides.py).

# LLM 출력 스키마 — delta only
retirement_age_delta_years : +5     # 5년 늦게
monthly_expense_delta_pct  : -0.1   # 지출 10% 감소
return_rate_delta_pctp     : +0.02  # 수익률 +2%p

# 변환: "늦게 은퇴" → delta +5
snapshot: current_age=58, retirement_age=65 → years_to_retirement=7
        → 7 + 5 = 12  → overrides["years_to_retirement"] = 12  # 절대값
        → 적용 라벨: "은퇴를 5년 늦추는"

왜 delta-only인가 LLM이 "73세 은퇴", "월 320만원" 같은 절대값을 환각하면 시뮬레이션이 통째로 틀어집니다. 기준값의 진실(truth)은 항상 DB 스냅샷이 쥐고, LLM에는 "어느 방향으로 얼마나"만 맡겨 환각 표면적을 최소화했습니다. 변환된 override는 화이트리스트 + Pydantic 재검증을 거쳐야 시뮬레이터에 들어갑니다.

경량 응답 서브그래프

CHAT 분기는 build_retirement_context(의도 분류·override 조립) → retirement_chat(경량 서브그래프 invoke) 순으로 흐릅니다. 서브그래프(chat_response_graph.py)는 의도에 따라 갈라집니다.

route_intent (3-way)
  ├─ CHITCHAT  ─▶ chat_chitchat ─▶ END           # 템플릿, 시뮬레이션 없음
  ├─ UNRELATED ─▶ chat_redirect ─▶ END           # 안내 템플릿
  └─ SIMULATE  ─▶ chat_sim ─▶ build_chat_response ─▶ persist_draft ─▶ call_compliance
                                  │  (route_after_chat_compliance)
                                  ├─ NOT_PASS & retry<2 ─▶ rewrite ─▶ persist_draft ↻
                                  └─ PASS / BLOCKED       ─▶ persist ─▶ END

chat_sim — 결정론 시뮬레이션 1회만 실행(LLM 없음, <100ms). 자식 run을 만들어 simulations 테이블에 저장.
build_chat_response — REPORT 경로의 응답 생성 서브에이전트(build_generate_response)를 재사용해 LLM 1콜로 자연어 답변 생성. 질문 + 시나리오 조건("은퇴를 5년 늦추는")을 함께 넘겨 조건 맞춤 답변을 만듭니다.
persist_draft → call_compliance — 답변을 DRAFT 상태로 먼저 적재한 뒤 준법 검증. NOT_PASS면 최대 2회 rewrite 루프.

지연 최적화 — 그래프 적재 백그라운드 이연

CHAT 응답에서 Evidence Graph 적재는 latency-critical 하지 않다는 점에 착안해, 채팅일 때만 그래프 적재를 응답 이후 백그라운드 태스크로 이연했습니다(api/routers/supervisor.py).

is_chat = req.mode and str(req.mode).upper() == RetirementMode.CHAT.value
if is_chat:
    event["defer_graph_persist"] = True      # persist_graph 노드는 동기 적재 skip
# ... 그래프 invoke / 응답 조립 ...
if (meta.get("graph_status") or {}).get("deferred"):
    background_tasks.add_task(persist_graph_deferred, container, final)  # 응답 후 적재

대신 응답 본문에는 그래프 재조회 없이도 근거를 보여줄 수 있도록 evidence_refs를 직접 동봉했습니다. 시뮬레이션 결과는 이미 simulations 테이블에 커밋돼 있어 데이터 유실 위험도 없습니다.

개발환경 실측(참고치) warm 상태에서 그래프 동기 적재 제거로 응답이 약 7.9초 → 5.5초 수준으로 단축. 잔여 지연의 지배 요인은 순차로 일어나는 4~6회의 LLM 호출(의도분류·FH·응답생성·준법)이며, fast-path·이연·서브에이전트 재사용은 모두 이 호출 수를 줄이거나 응답 경로 밖으로 빼는 방향으로 설계했습니다.

Module 3 · Evidence Graph Layer

Graph Evidence Layer

모든 위험 판단을 "고객 → 위험룰 → 근거 행"으로 잇는 탐색 가능한 근거 그래프로 만드는 cross-agent 공용 레이어입니다. 취합된 SharedState를 입력으로 evidence_nodes → evidence_edges → evidence_paths를 단일 트랜잭션으로 적재합니다 (FK 제약상 노드가 먼저 존재해야 엣지가 들어가므로 순서를 강제).

Repository 패턴 · 2-tier 백엔드 전략

적재 로직(오케스트레이션)과 저장 메커니즘을 GraphRepository Protocol로 분리해, 같은 빌더로 MySQL(기본·CI·오프라인)과 Neo4j(옵션)를 교체합니다. 백엔드 선택은 환경·연결성·정책을 종합한 resolve_graph_backend()가 결정합니다.

# graph_builder.py — 백엔드 결정: graceful degrade vs fail-fast
def resolve_graph_backend(db) -> ResolvedBackend:
    if backend != "neo4j":        return MySQL          # 기본
    if can_connect():            return Neo4j          # 연결되면 Neo4j
    if settings.graph_fallback_to_mysql:                    # dev:
        return MySQL  (fell_back=True)   #   조용히 MySQL 로 강등(가시성 기록)
    raise RuntimeError(...)      # demo/prod: 저장소가 몰래 바뀌는 것을 fail-fast

MySQL Repository

팀 BaseRepository 상속 — insert()가 생성 PK(lastrowid)를 반환. MySQL(운영)·sqlite(오프라인 테스트) 양쪽에서 도는 파라미터 바인딩만 사용.

기본 백엔드CI 친화

Neo4j Repository

명시적 트랜잭션으로 원자성 보장. 합성 핸들(n1, n2…)을 node_key로 부여하고, MERGE 키 {run_id, node_key}로 서로 다른 run을 완전 격리(Aura Free 단일 DB 대응).

옵션 백엔드Cypher allowlist

보안 — Cypher 인젝션 방어 Cypher 관계 타입은 파라미터화가 불가능하므로 문자열 보간 전 ^[A-Z][A-Z0-9_]*$ 정규식 + Validator의 edge_type allowlist로 이중 게이트합니다 (우리 코드가 생성하는 값만 허용).

단일 트랜잭션 빌더 · 멱등 · 중복 제거

원자성 (D5) — 노드·엣지·경로 적재 중 어디서든 실패하면 rollback으로 전체 무효화. rollback 자체가 실패해도 원본 적재 예외를 보존해 전파합니다 (#84 B3: 정리 실패가 진짜 원인을 가리지 않게).
멱등 가드 (#51) — 같은 run_id 그래프가 이미 적재돼 있으면 exists_for_run()으로 감지해 재적재를 skip(first-writer-wins). FH 단독 run 적재 후 Supervisor 재적재·재시도에도 중복 INSERT를 막습니다.
물리 근거 중복 제거 (#94) — 여러 룰이 같은 DB 행을 근거로 삼을 때(예: cashflow 두 룰이 같은 월 행 참조), (source_type, ref_table, ref_id) 기준으로 노드를 1회만 INSERT하고 여러 evidence_id가 같은 node_id를 공유하게 합니다.
경로 생성 — TRIGGERED 엣지가 RISK_RULE을 가리킬 때 "고객 → 위험룰 → 근거" 경로를 evidence_paths로 적재. 룰 카테고리를 path_type으로 매핑(debt→DEBT_BURDEN_RISK 등).

Supervisor 파이프라인용으로는 persist_graph_best_effort()를 제공합니다. 결과(MySQL)는 이미 커밋됐고 그래프는 부가 산출물이므로, 적재 실패는 예외 대신 GraphStatus(ok=False)로 흡수합니다. 단 백엔드 결정은 try 밖에 둬 demo/prod의 Neo4j 불가 fail-fast가 살아있게 하고, meta.run_id 누락은 best-effort로 삼키지 않고 hard-fail합니다(중앙 fan-in 계약 위반=배선 버그).

Validator — 근거 무결성 게이트

빌더 실행 전, 취합된 SharedState가 근거 그래프를 만들 수 있는지 검증합니다. "근거 없는 위험 금지"를 시스템 불변식으로 강제하는 핵심 컴포넌트입니다.

검증 항목	차단하는 오류
`meta.run_id` 존재	그래프가 analysis_runs에 연결 안 되는 고아 적재
발동 룰의 `evidence_id` 필수	근거 없이 위험을 주장하는 룰
관계의 evidence_id ∈ evidence_refs	존재하지 않는 근거 참조
`edge_type` allowlist (B2)	정의되지 않은 관계 타입 (Cypher 보간 전 방어)
`TRIGGERED` 근거 교차검증	발동하지 않은 룰의 근거로 위험을 주장하는 배선 오류
evidence_id 형식 `ev-<slug>-<id>` (B5)	꼬리표 규약 위반

팀 계약 재작성 — 개인 레포 → 팀 레포 팀 SharedState는 TypedDict이고 기여분은 model_dump된 dict 리스트라(개인 레포의 pydantic 속성 접근과 다름), by_alias=True 직렬화로 관계 양끝 키가 from/to입니다. Validator·Builder 전체를 dict 접근으로 재작성하고 식별자 위치(run_id→meta, customer_id→event)를 팀 계약에 맞춰 정렬했습니다.

조회 경로 — N+1 회피

적재(write)와 분리된 읽기 전용 경로(graph/read.py). run_id로 evidence_paths를 읽고 node_ids_json/edge_ids_json을 노드·엣지와 결합해 펼칩니다. 경로들의 모든 id를 모아 IN 쿼리 2번으로 일괄 조회 후 메모리에서 결합 — N+1을 회피합니다. GET /api/analysis-runs/{run_id}/evidence-paths로 노출.

Module 4 · Supervisor

Supervisor 워크플로우 연결

앞의 세 모듈과 은퇴 시뮬레이션·준법(compliance) 검증 에이전트를 하나의 LangGraph 워크플로우로 엮은 오케스트레이터입니다. 라우터가 workflow_type · 사용자 발화 · customer_id를 받아 디스패치하고, 답변 생성 직후 검증 에이전트까지 연결하는 것, 그리고 다중 에이전트의 부분 실패를 어떻게 다룰지가 설계의 핵심이었습니다.

검증 에이전트 연결 준법 검증은 별도 서브그래프(compliance/graph.py)이고, retirement 경로(CHAT·REPORT) 양쪽에서 답변 생성 직후 call_compliance 노드로 주입됩니다. 결과(PASS/NOT_PASS/BLOCKED)는 compliance_result로 state에 surface되어 최종 응답에 포함되고, NOT_PASS면 최대 2회 rewrite 루프를 돕니다. 미배선/예외 시에는 mock PASS로 graceful fallback해 오케스트레이터가 죽지 않게 했습니다.

토폴로지 — FH 전제 순차 + 모드 분기

은퇴 계열 워크플로우는 재무건강도 결과를 입력으로 소비하므로(재계산 금지), 과거의 병렬 fan-out(#88)을 FH 전제 순차로 교정했습니다(#83 후속). routing.mode로 경량 시뮬(CHAT)과 LLM 딥다이브(REPORT)를 분기합니다.

route ─▶ prepare_parent ─▶ financial_health ─▶ build_orchestrator_input
                                                       │
                                            ┌── mode 분기 ──┐
            chat:  build_retirement_context ─▶ retirement_chat
            report: retirement_report ─────────────────────┤
                                                       ▼
                            persist_graph(parent) ─▶ finalize_parent ─▶ END

route — 결정론 라우터. event → routing.{workflow_type, selected_agents, mode}.
prepare_parent — 다중이면 parent run 1개를 발급해 meta.run_id로 고정. FH-only(단일)이면 no-op.
financial_health — 단일=자체 그래프 적재+adopt / 다중=child(force + persist_graph=False + parent 연결). 두 경우 모두 1회만 계산.
build_orchestrator_input — 상위 FH 결과를 소비(recompute_fh=False)해 retirement 입력을 조립. "FH 1회 계산" 불변식을 명시 차단으로 강제.
persist_graph — parent run_id로 FH+retirement 기여를 통합 1개 그래프로 기록(단일 writer).
finalize_parent — DB child run을 권위 소스로 parent status를 산정해 마감.

빌드 타임 정합성 가드 분기 라우터의 가능한 반환값이 conditional-edge 목적지 맵과 일치하는지 build_supervisor_graph에서 명시적 raise로 검증합니다(assert가 아니라 — python -O에서 stripped 되지 않게). 배선 버그를 런타임이 아닌 빌드 시점에 잡습니다.

run_id 이원화 · 부분실패 격리

run_id 이원화 (Option A) — meta.run_id=parent(통합 graph 파티션), retirement의 retirement_run_id=child. simulations·evidence_refs의 source_id는 child로 분리해 추적성을 확보합니다.
부분실패 격리 — 다중 모드에서 한 에이전트가 예외를 던져도 agent_errors + child FAILED 기록 후 분기를 정상 종료. 다른 분기와 통합 그래프를 보존합니다.
좀비 run 방지 — child run 마감 실패를 exc_info와 함께 best-effort로 흡수하되, create_run/commit 실패는 격리해 finalize_parent가 반드시 실행되도록(parent가 RUNNING으로 남지 않게) 처리.
권위 소스 분리 — parent status는 SharedState 관측치(child_runs)가 아니라 DB child run을 권위 소스로 산정. run 생성 전 크래시한 에이전트는 expected 기준 FAILED 패딩으로 오판을 방지.
SharedState reducer — 리스트 키는 operator.add, analysis_results는 키별 병합 reducer로 병렬 기여 시 덮어쓰기 대신 병합. compliance_result(#90)를 최종 state로 surface.

Engineering decisions

핵심 설계 결정

⚡ LLM을 어디에 둘지 — 경계 설계

계산·룰·시나리오 절대값은 결정론으로 고정하고, 의도 분류·답변 생성에만 LLM을 둡니다. 이 경계 하나가 정확성·지연·비용을 동시에 좌우했습니다. fast-path·그래프 적재 이연·서브에이전트 재사용으로 CHAT의 LLM 콜 수와 체감 지연을 줄였습니다.

🧮 결정론적 코어 + delta-only 제약

채점·룰 평가는 DB와 분리된 순수 함수 + Decimal 정밀도. LLM 시나리오는 변화량(delta)만 출력하고 절대값은 코드가 계산·재검증해, 환각이 금융 숫자에 끼어들 여지를 구조로 제거했습니다.

🔒 근거 없는 위험 금지

모든 발동 룰은 evidence_id를 가져야 하고, Validator가 적재 전에 이를 강제합니다. "왜 이 고객이 위험한가"를 항상 그래프로 역추적할 수 있습니다.

💾 결과는 절대 유실하지 않는다

commit-first 펜싱으로 RUNNING/COMPLETED/FAILED를 항상 감사기록으로 남기고, 그래프 적재 실패는 best-effort로 흡수해 이미 커밋된 결과를 깨지 않습니다.

🔁 멱등성을 모든 층에

run 재사용(#74), 그래프 run_id 가드(#51), 물리 근거 중복 제거(#94) — 재시도·중복 디스패치가 데이터를 오염시키지 않게 3중으로 막았습니다.

🔌 교체 가능한 백엔드

Repository 패턴으로 MySQL/Neo4j를 동일 빌더로 교체. 환경별 fail-fast vs graceful degrade 정책으로 "저장소가 몰래 바뀌는" 사고를 차단합니다.

🛡️ 빌드 타임 계약 검증

conditional-edge 정합성, 룰 개수 assert, 식별자 정합성 등 배선 버그를 런타임 이전에 명시적으로 잡도록 가드를 심었습니다.

Stack & contribution

기술 스택 · 기여

기술 스택

Python 3.11LangGraph FastAPISQLAlchemy MySQLNeo4j PydanticDecimal pytestruff

설계 패턴

RepositoryDependency Injection (Container) StateGraph 오케스트레이션Reducer 기반 fan-in commit-first 감사 펜싱

담당 산출물

재무건강도 분석 — 16룰 엔진, 5영역 스코어러, KLoSA 보정, 서브그래프, run 생명주기 서비스, 조회 API #7 #34
노후 CHAT 모드 — 3-way 의도 분류기(fast-path+LLM), delta-only 시나리오 override, 경량 응답 서브그래프, 그래프 적재 이연, 준법 rewrite 루프 #26 #167 #169 #171
Evidence Graph — Repository 추상화, MySQL/Neo4j 구현, Validator, 단일 트랜잭션 빌더, 멱등·중복제거, 조회 #40 #51 #57 #84 #94
Supervisor — 9-node 그래프, 라우팅 디스패치, FH 전제 순차, 검증 에이전트 연결, run_id 이원화, 부분실패 격리 #70 #83 #90

AI Lifelong Wealth Management — 개인 담당 영역 포트폴리오 (4개 모듈) · 기준 코드: dev 브랜치 · 갱신일 2026-06-13 · 본 문서는 dev 코드(src/app/agents/financial_health, src/app/agents/retirement, src/app/graph, src/app/graphs/supervisor.py, src/app/agents/compliance)를 근거로 작성되었습니다. 일부 지연(latency) 수치는 개발 환경 실측 참고치입니다.