chore: FabAgent 골격 구성

.env.example

@@ -0,0 +1,3 @@
+# OpenAI API — 백엔드 멀티에이전트(agents/)용
+# 서브에이전트 = GPT-5 mini, 오케스트레이터 = GPT-5
+OPENAI_API_KEY=sk-...

.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.env
+.venv/
+venv/
+.streamlit/secrets.toml
+.DS_Store
+.idea/
+.vscode/
+CLAUDE.md
+.claude/
+.mcp.json
+data/secom/raw/*.data

README.md

@@ -0,0 +1,74 @@
+# FabAgent
+
+반도체 공정 이상의 **탐지 → 원인 분석 → 영향 평가 → 대응 권고**를 하나의
+멀티 에이전트 파이프라인으로 통합하는 운영 플랫폼 MVP입니다.
+
+## 아키텍처
+
+```
+알람 클릭 → core/pipeline.get_tier_data(alarm_id)
+              ├─ A1 (Photo): agents/ 실제 LLM 멀티에이전트 + RAG
+              │              └ Tier 1은 SECOM 센서 데이터로 이상 탐지
+              └─ A2·A3:      data/demo.py 하드코딩
+           → core/schema.TierData (단일 계약면)
+           → components/ 가 Streamlit으로 렌더
+```
+
+프론트엔드는 데이터가 실제 에이전트에서 오는지 하드코딩인지 알지 못합니다.
+실제 에이전트로 돌릴 알람을 늘리려면 `core/pipeline.REAL_AGENT_ALARMS`에
+ID만 추가하면 됩니다.
+
+## 파일 구조
+
+```
+fabagent/
+├── app.py                  # 엔트리포인트
+├── components/             # Streamlit UI (프론트 담당)
+├── core/
+│   ├── schema.py           # Tier1~4 데이터 계약 ★ 양쪽 공유
+│   └── pipeline.py         # 알람 → Tier 데이터 라우터
+├── data/
+│   ├── demo.py             # A2·A3 하드코딩 데이터
+│   └── secom/              # UCI SECOM 데이터셋 + 로더 (Tier 1 이상 탐지용)
+├── agents/                 # A1 실제 멀티에이전트 (백엔드 담당)
+│   ├── orchestrator.py
+│   ├── detection.py / cause.py / impact.py / response.py
+│   └── rag/                # 도메인 지식 검색
+├── styles/main.css         # 디자인 시안 CSS
+└── assets/
+```
+
+## 기술 스택
+
+- **프론트**: Streamlit 1.36+ (의존성 최소화 — `streamlit-extras` 등 미사용)
+- **백엔드**: OpenAI SDK — 서브에이전트 `GPT-5 mini`, 오케스트레이터 `GPT-5`
+- **데이터**: UCI SECOM 공개 데이터셋 (Tier 1 이상 탐지), pandas
+- **Python**: 3.11+
+
+데이터셋 준비 방법은 `data/README.md`를 참고하세요.
+
+## 실행
+
+```bash
+pip install -r requirements.txt
+cp .env.example .env        # OPENAI_API_KEY 입력
+streamlit run app.py --server.port 8501
+```
+
+## 개발 마일스톤
+
+| 단계 | 내용 | 담당 |
+|---|---|---|
+| M0 | 레포 골격 · `schema.py` 합의 · 설정 파일 | 같이 |
+| M1 | Streamlit UI 전체 (`demo.py` 데이터로) | 프론트 |
+| M2 | `agents/` — A1 4단계 오케스트레이션 + RAG | 백엔드 |
+| M3 | A1을 실제 에이전트로 스위치 · 통합 테스트 | 같이 |
+| M4 | 시연 리허설 (개발 가이드 15장 체크리스트) | 같이 |
+
+M1·M2는 `core/schema.py`만 고정되면 완전히 병렬로 작업할 수 있습니다.
+
+## 브랜치 전략
+
+- 기본 브랜치는 `develop`이며, 직접 푸시하지 않고 PR로만 머지합니다.
+- `feat/streamlit-ui` · `feat/agents-a1` · `feat/css-port` 로 작업을 분담합니다.
+- `core/schema.py`를 가장 먼저 작은 PR로 머지한 뒤 병렬 작업을 시작합니다.

agents/cause.py

@@ -0,0 +1,11 @@
+"""Tier 2 원인 분석 에이전트 (M2에서 구현)
+
+입력: 알람 컨텍스트 + Tier 1 결과
+출력: core.schema.Tier2 (추정 원인 + 기여도 % + 근거 + RAG citation)
+모델: GPT-5 mini + RAG (agents.rag.store), 과거 인시던트/FMEA 문서 검색
+"""
+from core.schema import Tier1, Tier2
+
+
+def run_cause(alarm: dict, tier1: Tier1) -> Tier2:
+    raise NotImplementedError("M2: Tier 2 원인 분석 에이전트 구현 예정")

agents/detection.py

@@ -0,0 +1,11 @@
+"""Tier 1 이상 탐지 에이전트 (M2에서 구현)
+
+입력: 알람 컨텍스트 + SECOM 센서 데이터 (data.secom.loader.load_secom)
+출력: core.schema.Tier1 (이상 점수 + 기여 피처 Top-N + 영향 lot)
+모델: GPT-5 mini + tool use, IsolationForest 등으로 이상 점수 계산
+"""
+from core.schema import Tier1
+
+
+def run_detection(alarm: dict) -> Tier1:
+    raise NotImplementedError("M2: Tier 1 이상 탐지 에이전트 구현 예정")

agents/impact.py

@@ -0,0 +1,11 @@
+"""Tier 3 공정 간 영향 평가 에이전트 (M2에서 구현)
+
+입력: 알람 컨텍스트 + Tier 1·2 결과
+출력: core.schema.Tier3 (예상 수율 손실 + 공정 의존성 + 영향 lot)
+모델: GPT-5 mini + tool use (후공정 의존성 그래프 조회 툴)
+"""
+from core.schema import Tier1, Tier2, Tier3
+
+
+def run_impact(alarm: dict, tier1: Tier1, tier2: Tier2) -> Tier3:
+    raise NotImplementedError("M2: Tier 3 영향 평가 에이전트 구현 예정")

agents/orchestrator.py

@@ -0,0 +1,20 @@
+"""4-Tier 멀티에이전트 오케스트레이터 (M2에서 구현)
+
+run_orchestrator()가 detection -> cause -> impact -> response 순으로
+서브에이전트를 호출하고 각 결과를 core.schema.TierData로 합쳐 반환
+
+설계 원칙: 특정 알람(A1)에 하드코딩하지 말 것
+알람의 공정 타입(Photo/Etch/CMP)을 받아 처리하는 일반 함수로 만들면
+core.pipeline.REAL_AGENT_ALARMS에 ID만 추가해 다른 알람도 확장 가능
+
+모델: 서브에이전트 = GPT-5 mini, 오케스트레이터 = GPT-5 (OpenAI SDK)
+
+현재는 스텁, demo.py 데이터를 그대로 반환해 프론트가 M1부터 동작하게 함
+"""
+from core.schema import TierData
+from data import demo
+
+
+def run_orchestrator(alarm_id: str) -> TierData:
+    # TODO(M2/M3) detection->cause->impact->response 서브에이전트 호출로 교체
+    return demo.TIER_DATA[alarm_id]

agents/rag/knowledge/README.md

@@ -0,0 +1,15 @@
+# RAG 지식 베이스
+
+원인 분석(Tier 2)·대응 권고(Tier 4) 에이전트가 검색하는 도메인 문서.
+파일명 = citation ID. 예: `INC-2024-0312.md` → 코드에서 `load_document("INC-2024-0312")`.
+
+## M2에서 작성할 문서 (A1 Photo 시나리오 기준)
+
+| 파일 | 유형 | 내용 |
+|---|---|---|
+| `INC-2024-0312.md` | 과거 인시던트 | 메모리 1동 렌즈 오염 유사 사례 |
+| `INC-2024-0289.md` | 과거 인시던트 | 스테이지 진동 이상 사례 |
+| `FMEA-PH-007.md` | 실패 모드 분석 | Photo 공정 FMEA |
+| `SOP-PH-LENS-002.md` | 표준 절차 | 렌즈 PM 표준 절차 |
+
+A2·A3까지 실제 에이전트로 확장할 경우 Etch/CMP 관련 문서도 같은 형식으로 추가.

agents/rag/store.py

@@ -0,0 +1,22 @@
+"""RAG 도메인 지식 검색 (M2에서 구현)
+
+knowledge/ 의 마크다운 문서(INC-*, FMEA-*, SOP-* 등)를 검색해
+원인 분석(Tier 2)·대응 권고(Tier 4) 에이전트에 근거를 제공
+
+문서가 5~6개뿐이라 벡터DB는 오버스펙
+citation ID로 직접 로드하거나 간단한 키워드 매칭이면 충분
+"""
+from pathlib import Path
+
+KNOWLEDGE_DIR = Path(__file__).parent / "knowledge"
+
+
+def load_document(doc_id: str) -> str:
+    """citation ID(예: 'INC-2024-0312')로 knowledge 문서 본문을 로드, 없으면 빈 문자열"""
+    path = KNOWLEDGE_DIR / f"{doc_id}.md"
+    return path.read_text(encoding="utf-8") if path.exists() else ""
+
+
+def search(query: str, top_k: int = 3) -> list[str]:
+    """쿼리와 관련된 문서 ID를 반환 (M2: 키워드 매칭 기반)"""
+    raise NotImplementedError("M2: RAG 검색 구현 예정")

agents/response.py

@@ -0,0 +1,11 @@
+"""Tier 4 대응 권고 에이전트 (M2에서 구현)
+
+입력: 알람 컨텍스트 + Tier 1·2·3 결과
+출력: core.schema.Tier4 (즉시 조치 + 중장기 조치 + 근거 자료)
+모델: GPT-5 (오케스트레이터급) + RAG, SOP/표준 절차 문서 검색
+"""
+from core.schema import Tier1, Tier2, Tier3, Tier4
+
+
+def run_response(alarm: dict, tier1: Tier1, tier2: Tier2, tier3: Tier3) -> Tier4:
+    raise NotImplementedError("M2: Tier 4 대응 권고 에이전트 구현 예정")

app.py

@@ -0,0 +1,68 @@
+"""FabAgent 운영자 대시보드 엔트리포인트
+
+실행: streamlit run app.py --server.port 8501
+"""
+from pathlib import Path
+
+import streamlit as st
+
+from components.alarm_inbox import render_alarm_inbox
+from components.header import render_header
+from components.progress import render_progress_strip
+from components.tiers import render_tier_cascade
+from data.demo import DEFAULT_ALARMS
+
+st.set_page_config(
+    page_title="FabAgent — 운영자 대시보드",
+    page_icon="🟦",
+    layout="wide",
+    initial_sidebar_state="expanded",
+)
+
+
+def inject_css():
+    css_path = Path("styles/main.css")
+    if css_path.exists():
+        st.markdown(
+            f"<style>{css_path.read_text(encoding='utf-8')}</style>",
+            unsafe_allow_html=True,
+        )
+    st.markdown(
+        '<link rel="stylesheet" '
+        'href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/variable/pretendardvariable.min.css">',
+        unsafe_allow_html=True,
+    )
+
+
+def init_state():
+    ss = st.session_state
+    ss.setdefault("selected_alarm_id", "A1")
+    ss.setdefault("stage", 0)  # 0=idle, 1..4=loading, 5=done
+    ss.setdefault("completed_tiers", set())
+    ss.setdefault("approved", False)
+    ss.setdefault("alarms", [a.copy() for a in DEFAULT_ALARMS])
+    ss.setdefault("animation_pending", False)
+    ss.setdefault("speed", "normal")  # "fast" | "normal" | "real"
+
+
+def render_main():
+    render_header()
+
+    col_title, col_progress = st.columns([5, 4])
+    with col_title:
+        # TODO(M1) 메인 타이틀 + 4-Tier 워크플로우 서브텍스트
+        st.markdown("<!-- TODO(M1): 메인 타이틀 -->", unsafe_allow_html=True)
+    with col_progress:
+        render_progress_strip()
+
+    st.markdown(
+        '<hr style="border-color: var(--border); margin: 16px 0 22px;"/>',
+        unsafe_allow_html=True,
+    )
+    render_tier_cascade()
+
+
+inject_css()
+init_state()
+render_alarm_inbox()
+render_main()

components/alarm_inbox.py

@@ -0,0 +1,13 @@
+"""사이드바 알람 인박스 (개발 가이드 6장)
+
+TODO(M1): 가이드 6장 '권장 대안', HTML 카드 + 바로 아래 st.button 분리 방식
+on_alarm_click()에서 stage / completed_tiers / approved 리셋 후
+animation_pending=True 로 두고 st.rerun()
+"""
+import streamlit as st
+
+
+def render_alarm_inbox():
+    with st.sidebar:
+        # TODO(M1) st.session_state.alarms 순회하며 알람 카드 + 선택 버튼 렌더
+        st.markdown("<!-- TODO(M1): 알람 인박스 -->", unsafe_allow_html=True)

components/header.py

@@ -0,0 +1,11 @@
+"""상단 헤더 (개발 가이드 부록 A)
+
+TODO(M1): 가이드 부록 A의 render_header() 구현, 디자인 시안 헤더와 1:1
+헤더는 st.columns 밖, .block-container 최상단에 둠
+"""
+import streamlit as st
+
+
+def render_header():
+    # TODO(M1) 로고 + 공정/라인 컨텍스트 + LIVE 시계 + 사용자 영역
+    st.markdown("<!-- TODO(M1): FabAgent 헤더 -->", unsafe_allow_html=True)

components/progress.py

@@ -0,0 +1,11 @@
+"""4단계 진행 스트립 (개발 가이드 부록 C)
+
+TODO(M1): 가이드 부록 C의 render_progress_strip() 구현
+st.session_state.stage 기준으로 각 단계를 idle / active / done 으로 렌더
+"""
+import streamlit as st
+
+
+def render_progress_strip():
+    # TODO(M1) 이상 탐지 -> 원인 분석 -> 영향 평가 -> 권고서 진행 표시
+    st.markdown("<!-- TODO(M1): 진행 스트립 -->", unsafe_allow_html=True)

components/skeleton.py

@@ -0,0 +1,12 @@
+"""로딩 스켈레톤 (개발 가이드 12장)
+
+TODO(M1): 가이드 12장 render_skeleton() 구현
+스켈레톤 CSS(.skel, .skel-row, .skel-block, @keyframes shimmer)는
+디자인 프로토타입에서 styles/main.css로 복사
+"""
+import streamlit as st
+
+
+def render_skeleton(tier_num: int):
+    # TODO(M1) tier_num별 스켈레톤 레이아웃
+    st.markdown("<!-- TODO(M1): 스켈레톤 -->", unsafe_allow_html=True)

components/tiers.py

@@ -0,0 +1,28 @@
+"""Tier 1~4 순차 등장 렌더러 (개발 가이드 8·9장)
+
+TODO(M1): 가이드 8장 '접근법 A', st.empty() placeholder 4개 + time.sleep으로
+스켈레톤 -> 콘텐츠 순차 교체, stage>=5면 즉시 정적 렌더(새로고침 대응)
+
+중요: Tier 데이터는 반드시 core.pipeline.get_tier_data() 한 함수로만 받음
+data.demo.TIER_DATA 를 직접 import 하지 말 것, 실제 에이전트 교체가 막힘
+"""
+import streamlit as st
+
+from core.pipeline import get_tier_data
+
+
+def render_tier_cascade():
+    data = get_tier_data(st.session_state.selected_alarm_id)
+    if data is None:
+        st.markdown(
+            '<div class="fab-empty">선택한 알람의 분석 데이터가 없습니다.</div>',
+            unsafe_allow_html=True,
+        )
+        return
+    # TODO(M1) 가이드 8장 run_sequence(), 스켈레톤 -> 콘텐츠 순차 등장
+    st.markdown("<!-- TODO(M1): Tier 1~4 cascade -->", unsafe_allow_html=True)
+
+
+def render_tier(tier_num: int, data, loading: bool, with_actions: bool = False):
+    # TODO(M1) 가이드 9장 render_tier(), Tier 프레임 + 본문/스켈레톤 분기
+    raise NotImplementedError("M1: Tier 프레임 렌더러 구현 예정")

components/tiers_body.py

@@ -0,0 +1,25 @@
+"""Tier 1~4 본문 렌더러 (개발 가이드 9·10장)
+
+TODO(M1): 상호작용 없는 본문은 f-string HTML + st.markdown 한 번에 렌더
+Streamlit 위젯을 본문에 쓰지 말 것(레이아웃 깨짐), Tier 4 액션 바만 st.button
+디자인 프로토타입의 tiers.jsx 구조를 1:1로 옮길 것
+"""
+from core.schema import Tier1, Tier2, Tier3, Tier4
+
+
+def render_tier_1_body(data: Tier1):
+    raise NotImplementedError("M1: Tier 1 본문 구현 예정 (가이드 9장 참고)")
+
+
+def render_tier_2_body(data: Tier2):
+    raise NotImplementedError("M1: Tier 2 본문 구현 예정")
+
+
+def render_tier_3_body(data: Tier3):
+    raise NotImplementedError("M1: Tier 3 본문 구현 예정")
+
+
+def render_tier_4_body(data: Tier4, with_actions: bool):
+    # TODO(M1) 본문 HTML + with_actions면 거절/보류/승인 액션 바
+    # 승인 시 on_approve, approved=True, 알람 status="done", st.toast, st.rerun
+    raise NotImplementedError("M1: Tier 4 본문 + 액션 바 구현 예정 (가이드 10장)")

core/pipeline.py

@@ -0,0 +1,22 @@
+"""알람 -> Tier 데이터 라우터
+
+components/는 이 함수 하나만 호출함
+데이터가 하드코딩(demo.py)에서 오는지 실제 멀티에이전트(agents/)에서
+오는지 프론트는 알 필요가 없음
+
+실제 LLM 에이전트로 돌릴 알람을 늘리려면 REAL_AGENT_ALARMS에 ID만 추가하면 됨
+"""
+from core.schema import TierData
+from data import demo
+
+# LLM 멀티에이전트로 처리할 알람
+REAL_AGENT_ALARMS = {"A1"}
+
+
+def get_tier_data(alarm_id: str) -> TierData | None:
+    """알람 ID로 4-Tier 분석 결과를 반환, 데이터가 없으면 None"""
+    if alarm_id in REAL_AGENT_ALARMS:
+        from agents.orchestrator import run_orchestrator
+
+        return run_orchestrator(alarm_id)
+    return demo.TIER_DATA.get(alarm_id)

core/schema.py

@@ -0,0 +1,83 @@
+"""FabAgent Tier 데이터 계약
+
+프론트엔드(components/)와 백엔드(agents/)가 공유하는 단일 계약면
+이 구조를 바꾸면 양쪽 다 영향받으므로, 변경은 작은 PR로 먼저 합의 예정
+
+모든 Tier 데이터는 plain dict로 다룸 - components/가 HTML f-string에서
+dict 키로 직접 접근하기 때문, TypedDict는 타입 힌트/문서 용도
+"""
+from typing import Optional, TypedDict
+
+
+# Tier 1 이상 탐지
+class Feature(TypedDict):
+    name: str
+    value: float
+
+
+class LotRef(TypedDict):
+    id: str
+    wafers: int
+
+
+class Tier1(TypedDict):
+    score: float             # 이상 점수 (0~1)
+    features: list[Feature]  # 기여 피처 Top-N (value 내림차순)
+    lot: LotRef
+
+
+# Tier 2 원인 분석
+class Cause(TypedDict):
+    name: str
+    pct: int                # 추정 기여도 (%)
+    evidence: str
+    citations: list[str]    # RAG 근거 문서 ID
+
+
+class Tier2(TypedDict):
+    causes: list[Cause]
+
+
+# Tier 3 공정 간 영향 평가
+class Dependency(TypedDict):
+    stage: str
+    delta: str
+    tag: str
+    kind: str               # "current" | "impacted" | "minor"
+
+
+class ImpactLot(TypedDict):
+    label: str
+    lots: int
+    wafers: int
+
+
+class Tier3(TypedDict):
+    yield_loss: float       # 예상 수율 손실 (%p)
+    dependencies: list[Dependency]
+    impact_lots: list[ImpactLot]
+
+
+# Tier 4 대응 권고
+class Action(TypedDict):
+    text: str
+    meta: Optional[str]
+
+
+class Reference(TypedDict):
+    id: str
+    desc: str
+
+
+class Tier4(TypedDict):
+    immediate: list[Action]
+    longterm: list[Action]
+    refs: list[Reference]
+
+
+# 전체
+class TierData(TypedDict):
+    tier1: Tier1
+    tier2: Tier2
+    tier3: Tier3
+    tier4: Tier4

data/README.md

@@ -0,0 +1,25 @@
+# 데이터
+
+## SECOM (Tier 1 이상 탐지용)
+
+UCI SECOM 반도체 제조 공정 센서 데이터셋을 사용합니다.
+
+- 규모: 1,567 row × 590 sensor feature, pass/fail 라벨
+- 출처: https://archive.ics.uci.edu/dataset/179/secom
+- Tier 1 이상 탐지 에이전트가 이 데이터로 이상 점수와 기여 피처를 계산합니다.
+
+### 준비 방법
+
+`secom.data`, `secom_labels.data` 두 파일을 `data/secom/raw/` 에 둡니다.
+raw 데이터는 git에 포함하지 않으므로(`.gitignore`) 각자 내려받아야 합니다.
+
+로드는 `data/secom/loader.py`의 `load_secom()`을 사용합니다.
+
+### 알람 매핑
+
+SECOM은 익명화된 데이터라 lot ID·공정 step 정보가 없습니다. MVP에서는 fail 라벨이
+붙은 특정 row 하나를 알람 A1(Photo Step 이상)의 대상 웨이퍼로 지정해 사용합니다.
+
+## demo.py (A2·A3용)
+
+A2·A3는 실제 데이터 대신 시연용 하드코딩 데이터를 사용합니다 (`data/demo.py`).

data/demo.py

@@ -0,0 +1,106 @@
+"""데모 데이터 - 알람 인박스 + 하드코딩 Tier 데이터
+
+A1(Photo)은 M3에서 agents/ 실제 에이전트로 교체됨, A2·A3는 시연용 하드코딩
+TIER_DATA에 없는 알람을 클릭하면 pipeline이 None을 반환하고
+프론트가 "데이터 없음"을 안내함
+"""
+from core.schema import TierData
+
+DEFAULT_ALARMS = [
+    {
+        "id": "A1",
+        "status": "critical",
+        "title": "Photo Step 이상",
+        "lot_id": "L20240511-N-03",
+        "feature": "CD-X 산포",
+        "feature_arrow": "↑",
+        "time": "3분 전",
+    },
+    {
+        "id": "A2",
+        "status": "warn",
+        "title": "Etch Step 이상",
+        "lot_id": "L20240511-N-02",
+        "feature": "Trench Depth",
+        "feature_arrow": "↓",
+        "time": "15분 전",
+    },
+    {
+        "id": "A3",
+        "status": "done",
+        "title": "CMP Step 이상",
+        "lot_id": "L20240510-N-08",
+        "feature": None,
+        "time": "2시간 전",
+    },
+]
+
+STATUS_LABELS = {"critical": "긴급", "warn": "주의", "done": "완료"}
+
+# alarm_id -> TierData
+# A1은 개발 가이드 11장 데이터, A2·A3은 M1에서 채움
+TIER_DATA: dict[str, TierData] = {
+    "A1": {
+        "tier1": {
+            "score": 0.87,
+            "features": [
+                {"name": "CD-X 산포", "value": 0.42},
+                {"name": "노광 에너지", "value": 0.31},
+                {"name": "Focus 편차", "value": 0.14},
+            ],
+            "lot": {"id": "L20240511-N-03", "wafers": 25},
+        },
+        "tier2": {
+            "causes": [
+                {
+                    "name": "렌즈 오염",
+                    "pct": 62,
+                    "evidence": "직전 PM 후 14일 경과 · 유사 사례 4건 · 헤이즈 센서 +18%",
+                    "citations": ["INC-2024-0312", "FMEA-PH-007"],
+                },
+                {
+                    "name": "스테이지 진동",
+                    "pct": 23,
+                    "evidence": "동일 시간대 진동 센서 이상치 검출",
+                    "citations": ["INC-2024-0289"],
+                },
+                {
+                    "name": "웨이퍼 표면 결함",
+                    "pct": 15,
+                    "evidence": "직전 공정 입고 검사 패스",
+                    "citations": [],
+                },
+            ],
+        },
+        "tier3": {
+            "yield_loss": 2.3,
+            "dependencies": [
+                {"stage": "Photo", "delta": "+0.87", "tag": "현재", "kind": "current"},
+                {"stage": "Etch", "delta": "+18%", "tag": "영향", "kind": "impacted"},
+                {"stage": "CMP", "delta": "+5%", "tag": "경미", "kind": "minor"},
+            ],
+            "impact_lots": [
+                {"label": "가공 중", "lots": 3, "wafers": 75},
+                {"label": "대기 중", "lots": 5, "wafers": 125},
+            ],
+        },
+        "tier4": {
+            "immediate": [
+                {"text": "렌즈 PM 긴급 투입", "meta": "예상 2시간"},
+                {"text": "후공정 진입 보류 — 영향 lot 3건 (75장)", "meta": "Etch hold"},
+                {"text": "양산 일정 재조정 — 영향 범위 격리", "meta": "PPC 협조"},
+            ],
+            "longterm": [
+                {"text": "PM 주기 단축 권고: 30일 → 21일", "meta": None},
+                {"text": "동일 패턴 발생 lot 추적 모니터링 강화", "meta": None},
+            ],
+            "refs": [
+                {"id": "SOP-PH-LENS-002", "desc": "렌즈 PM 표준 절차"},
+                {"id": "INC-2024-0312", "desc": "과거 유사 사례 (메모리 1동)"},
+                {"id": "FMEA-PH-007", "desc": "Photo 공정 실패 모드 분석"},
+            ],
+        },
+    },
+    # TODO(M1) A2(Etch) 시연 데이터 추가
+    # TODO(M1) A3(CMP) 시연 데이터 추가, 비워두면 "데이터 없음" 경로가 시연됨
+}

data/secom/loader.py

@@ -0,0 +1,33 @@
+"""UCI SECOM 데이터셋 로더
+
+반도체 제조 공정 센서 데이터 (1567 row x 590 feature, pass/fail 라벨)
+출처: https://archive.ics.uci.edu/dataset/179/secom
+raw/ 에 secom.data, secom_labels.data 를 두면 로드됨 (data/README.md 참고)
+
+Tier 1 이상 탐지 에이전트가 이 데이터로 이상 점수와 기여 피처를 계산
+"""
+from pathlib import Path
+
+import pandas as pd
+
+RAW_DIR = Path(__file__).parent / "raw"
+
+
+def load_secom() -> tuple[pd.DataFrame, pd.Series]:
+    """SECOM 센서 피처와 pass/fail 라벨을 반환
+
+    features: 1567 x 590 (결측치 포함), 컬럼명 sensor_000 ~ sensor_589
+    labels: 1=fail(이상), -1=pass(정상)
+    """
+    data_path = RAW_DIR / "secom.data"
+    label_path = RAW_DIR / "secom_labels.data"
+    if not data_path.exists() or not label_path.exists():
+        raise FileNotFoundError(
+            f"SECOM 데이터가 없음, {RAW_DIR}에 secom.data / secom_labels.data 를 두세요 "
+            "(data/README.md 참고)"
+        )
+
+    features = pd.read_csv(data_path, sep=r"\s+", header=None)
+    features.columns = [f"sensor_{i:03d}" for i in range(features.shape[1])]
+    labels = pd.read_csv(label_path, sep=r"\s+", header=None, usecols=[0])[0]
+    return features, labels

requirements.txt

@@ -0,0 +1,4 @@
+streamlit>=1.36.0
+openai>=1.0.0
+python-dotenv>=1.0.0
+pandas>=2.0.0

styles/main.css

@@ -0,0 +1,42 @@
+/* FabAgent 전체 스타일
+   TODO(M1 / feat/css-port): 디자인 프로토타입의 styles.css 전체를 여기에 그대로 복사
+   토큰/간격/애니메이션이 모두 그 안에 검증돼 있으므로 다시 작성하지 말 것
+   아래는 디자인 토큰 :root + Streamlit 기본 요소 숨김만 미리 둔 시작점 */
+
+:root {
+  --text-primary: #1F2A3A;
+  --text-secondary: #6B7788;
+  --text-tertiary: #9AA3B2;
+  --bg-page: #FAFBFC;
+  --bg-card: #FFFFFF;
+  --bg-subtle: #F4F6F9;
+  --border: #E3E6EC;
+  --brand: #2C5AB8;     /* Tier 1 파랑 */
+  --t2-text: #6E46A8;   /* Tier 2 보라 */
+  --t3-text: #2A8A55;   /* Tier 3 초록 */
+  --t4-text: #B07718;   /* Tier 4 앰버 */
+  --crit-text: #C04A6E; /* 긴급 핑크 */
+}
+
+/* Streamlit 기본 요소 숨기기 */
+#MainMenu { visibility: hidden; }
+footer { visibility: hidden; }
+header[data-testid="stHeader"] { display: none; }
+
+/* 상단 여백 제거 + 폭 제한 해제 */
+.block-container {
+  padding-top: 1rem;
+  padding-bottom: 4rem;
+  max-width: none;
+}
+
+/* 사이드바 너비 320px 고정 */
+section[data-testid="stSidebar"] {
+  width: 320px !important;
+  min-width: 320px !important;
+  background: var(--bg-card);
+  border-right: 1px solid var(--border);
+}
+section[data-testid="stSidebar"] > div {
+  padding-top: 0;
+}