feat: Tier 2 원인 분석 LLM+RAG 구현

agents/cause.py

@@ -1,11 +1,81 @@
-"""Tier 2 원인 분석 에이전트 (M2에서 구현)
+"""Tier 2 원인 분석 에이전트
 
-입력: 알람 컨텍스트 + Tier 1 결과
-출력: core.schema.Tier2 (추정 원인 + 기여도 % + 근거 + RAG citation)
-모델: GPT-5 mini + RAG (agents.rag.store), 과거 인시던트/FMEA 문서 검색
+알람 컨텍스트 + Tier 1 결과 + RAG 지식 문서를 근거로
+추정 원인을 기여도(%)와 근거, citation과 함께 산출
+모델: GPT-5 mini (agents.llm.SUBAGENT_MODEL)
 """
+import json
+
+from agents.llm import SUBAGENT_MODEL, client
+from agents.rag.store import load_document, search
 from core.schema import Tier1, Tier2
 
+TOP_K_DOCS = 3
+
+# structured output용 Tier2 JSON 스키마
+TIER2_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "causes": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "pct": {"type": "integer"},
+                    "evidence": {"type": "string"},
+                    "citations": {"type": "array", "items": {"type": "string"}},
+                },
+                "required": ["name", "pct", "evidence", "citations"],
+                "additionalProperties": False,
+            },
+        }
+    },
+    "required": ["causes"],
+    "additionalProperties": False,
+}
+
+SYSTEM_PROMPT = """당신은 반도체 Photo 공정의 원인 분석 전문가입니다.
+주어진 이상 알람과 탐지 결과, 사내 지식 문서를 근거로 가장 가능성 높은 원인을
+2~3개 추정합니다. 각 원인은 기여도(pct, %)를 가지며 합이 100에 가깝도록 합니다.
+근거(evidence)는 제공된 문서 내용에 기반해 구체적으로 작성하고, citations에는
+근거가 된 문서 ID만 정확히 기입합니다. 제공되지 않은 문서는 인용하지 않습니다.
+기여도가 높은 원인부터 순서대로 제시합니다."""
+
+
+def _build_query(alarm: dict, tier1: Tier1) -> str:
+    feature = alarm.get("feature") or ""
+    return f"{alarm['title']} {feature} 원인 CD 산포 렌즈 노광 진동 표면 결함"
+
 
 def run_cause(alarm: dict, tier1: Tier1) -> Tier2:
-    raise NotImplementedError("M2: Tier 2 원인 분석 에이전트 구현 예정")
+    doc_ids = search(_build_query(alarm, tier1), top_k=TOP_K_DOCS)
+    knowledge = "\n\n".join(f"[{d}]\n{load_document(d)}" for d in doc_ids)
+
+    sensors = ", ".join(f["name"] for f in tier1["features"])
+    user_prompt = f"""## 이상 알람
+- 공정: {alarm['title']}
+- lot: {alarm['lot_id']}
+- 이상 피처: {alarm.get('feature')} {alarm.get('feature_arrow') or ''}
+
+## Tier 1 이상 탐지 결과
+- 이상 점수: {tier1['score']}
+- 기여 센서(Top): {sensors}
+
+## 사내 지식 문서
+{knowledge}
+
+위 정보를 근거로 원인을 분석해 주세요."""
+
+    resp = client().chat.completions.create(
+        model=SUBAGENT_MODEL,
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": user_prompt},
+        ],
+        response_format={
+            "type": "json_schema",
+            "json_schema": {"name": "tier2", "schema": TIER2_SCHEMA, "strict": True},
+        },
+    )
+    return json.loads(resp.choices[0].message.content)

agents/llm.py

@@ -0,0 +1,21 @@
+"""OpenAI 클라이언트와 모델 설정
+
+서브에이전트(cause/impact/response) = SUBAGENT_MODEL
+오케스트레이터 = ORCHESTRATOR_MODEL
+모델명을 여기 한 곳에서 관리해 교체를 쉽게 함
+"""
+from functools import lru_cache
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+load_dotenv()
+
+SUBAGENT_MODEL = "gpt-5-mini"
+ORCHESTRATOR_MODEL = "gpt-5"
+
+
+@lru_cache(maxsize=1)
+def client() -> OpenAI:
+    """OpenAI 클라이언트, 첫 호출 시 1회만 생성"""
+    return OpenAI()

agents/rag/knowledge/FMEA-PH-007.md

@@ -0,0 +1,30 @@
+# FMEA-PH-007 — Photo 공정 실패 모드 분석
+
+## 대상
+
+Photo / Lithography 공정의 주요 실패 모드와 원인, 영향, 검출 방법을 정리합니다.
+
+## 실패 모드
+
+### 1. CD 산포 증가
+
+- 잠재 원인: 투영 렌즈 오염, 노광 에너지 드리프트, 스테이지 진동
+- 영향: 후공정 Etch 단계의 트렌치 깊이 편차 확대, 수율 손실
+- 검출: SPC 기반 CD-X 산포 모니터링, 헤이즈 센서
+
+### 2. 오버레이 오차
+
+- 잠재 원인: 스테이지 진동, 정렬 마크 손상
+- 영향: 패턴 정합 불량
+- 검출: 오버레이 계측, 진동 센서
+
+### 3. 포커스 편차
+
+- 잠재 원인: 웨이퍼 평탄도 불량, 척 오염
+- 영향: 패턴 해상도 저하
+- 검출: 포커스 계측
+
+## 우선순위
+
+CD 산포 증가는 발생 빈도와 후공정 영향이 모두 커 최우선 관리 대상입니다. 원인
+중 렌즈 오염은 PM 주기와 강한 상관이 있어 정비 이력 확인이 우선입니다.

agents/rag/knowledge/INC-2024-0289.md

@@ -0,0 +1,28 @@
+# INC-2024-0289 — 스테이지 진동에 의한 노광 위치 오차
+
+## 분류
+
+- 유형: 공정 인시던트
+- 공정: Photo / Lithography
+- 사업부: 메모리 2동
+- 발생일: 2024-02-28
+
+## 증상
+
+특정 시간대에 처리된 로트에서 오버레이와 CD 산포가 동시에 악화되었습니다.
+이상이 간헐적으로 발생하여 초기 원인 규명에 어려움이 있었습니다.
+
+## 원인
+
+웨이퍼 스테이지의 진동이 원인으로 확인되었습니다. 인접 설비의 정비 작업 중
+발생한 진동이 전달된 것으로, 진동 센서에서 동일 시간대 이상치가 검출되었습니다.
+
+## 조치
+
+- 인접 설비 정비 일정 조정
+- 진동 센서 모니터링 구간 확대
+
+## 참고
+
+렌즈 오염과 달리 진동 원인은 발생 시간대와의 상관관계가 뚜렷합니다. 원인 구분
+시 시간대 패턴을 함께 확인하는 것이 유효합니다.

agents/rag/knowledge/INC-2024-0312.md

@@ -0,0 +1,29 @@
+# INC-2024-0312 — Photo 렌즈 오염으로 인한 CD 산포 증가
+
+## 분류
+
+- 유형: 공정 인시던트
+- 공정: Photo / Lithography
+- 사업부: 메모리 1동
+- 발생일: 2024-03-12
+
+## 증상
+
+노광 공정에서 CD-X 산포가 관리 한계를 초과하였습니다. 동일 스캐너에서 처리된
+연속 로트에서 CD 균일도가 점진적으로 악화되는 양상이 관측되었습니다.
+
+## 원인
+
+투영 렌즈 표면 오염으로 확인되었습니다. 직전 PM(예방 정비) 이후 14일이 경과한
+시점이었으며, 헤이즈 센서 측정값이 평소 대비 18% 상승해 있었습니다.
+
+## 조치
+
+- 렌즈 긴급 PM 투입 (약 2시간 소요)
+- 영향 로트 후공정 진입 보류
+- PM 주기를 30일에서 21일로 단축 권고
+
+## 재발 방지
+
+헤이즈 센서 임계값을 신설하고, 임계 초과 시 자동 알람이 발생하도록 모니터링을
+강화하였습니다.

agents/rag/knowledge/SOP-PH-LENS-002.md

@@ -0,0 +1,32 @@
+# SOP-PH-LENS-002 — 렌즈 PM 표준 절차
+
+## 목적
+
+Photo 스캐너 투영 렌즈의 예방 정비(PM) 절차를 표준화합니다.
+
+## 적용 범위
+
+전 사업부 Photo / Lithography 스캐너 설비.
+
+## PM 주기
+
+- 표준 주기: 30일
+- CD 산포 악화 또는 헤이즈 센서 상승 시: 21일로 단축
+
+## 절차
+
+1. 설비 정지 및 로트 진입 차단
+2. 렌즈 표면 오염도 측정 (헤이즈 센서)
+3. 세정 작업 수행
+4. 세정 후 오염도 재측정 및 기준 충족 확인
+5. 시험 노광으로 CD 산포 정상 범위 확인
+6. 설비 재가동 및 로트 진입 재개
+
+## 소요 시간
+
+표준 약 2시간. 오염도가 높을 경우 추가 세정으로 연장될 수 있습니다.
+
+## 기록
+
+PM 수행 이력은 인시던트 DB에 기록하며, 직전 PM 경과일은 원인 분석 시 주요 참고
+지표로 활용합니다.

agents/rag/store.py

@@ -1,22 +1,41 @@
-"""RAG 도메인 지식 검색 (M2에서 구현)
+"""RAG 도메인 지식 검색
 
 knowledge/ 의 마크다운 문서(INC-*, FMEA-*, SOP-* 등)를 검색해
 원인 분석(Tier 2)·대응 권고(Tier 4) 에이전트에 근거를 제공
 
-문서가 5~6개뿐이라 벡터DB는 오버스펙
-citation ID로 직접 로드하거나 간단한 키워드 매칭이면 충분
+문서가 소수라 벡터DB는 오버스펙, 키워드 매칭으로 충분
+파일명이 곧 citation ID (예: INC-2024-0312.md -> "INC-2024-0312")
 """
+import re
 from pathlib import Path
 
 KNOWLEDGE_DIR = Path(__file__).parent / "knowledge"
 
 
 def load_document(doc_id: str) -> str:
-    """citation ID(예: 'INC-2024-0312')로 knowledge 문서 본문을 로드, 없으면 빈 문자열"""
+    """citation ID로 knowledge 문서 본문을 로드, 없으면 빈 문자열"""
     path = KNOWLEDGE_DIR / f"{doc_id}.md"
     return path.read_text(encoding="utf-8") if path.exists() else ""
 
 
+def _knowledge_docs() -> dict[str, str]:
+    """knowledge/ 의 모든 문서를 {doc_id: 본문}으로 로드, README는 제외"""
+    docs = {}
+    for path in KNOWLEDGE_DIR.glob("*.md"):
+        if path.stem == "README":
+            continue
+        docs[path.stem] = path.read_text(encoding="utf-8")
+    return docs
+
+
 def search(query: str, top_k: int = 3) -> list[str]:
-    """쿼리와 관련된 문서 ID를 반환 (M2: 키워드 매칭 기반)"""
-    raise NotImplementedError("M2: RAG 검색 구현 예정")
+    """쿼리와 관련된 문서 ID를 키워드 매칭으로 반환, 관련도 내림차순"""
+    keywords = [w for w in re.split(r"\W+", query.lower()) if len(w) >= 2]
+    scored = []
+    for doc_id, text in _knowledge_docs().items():
+        low = text.lower()
+        hits = sum(low.count(kw) for kw in keywords)
+        if hits > 0:
+            scored.append((doc_id, hits))
+    scored.sort(key=lambda x: -x[1])
+    return [doc_id for doc_id, _ in scored[:top_k]]