---
title: FabAgent
emoji: 🟦
colorFrom: blue
colorTo: indigo
sdk: streamlit
sdk_version: 1.36.0
app_file: app.py
pinned: false
license: mit
short_description: 반도체 공정 이상의 탐지·원인·영향·대응을 잇는 멀티 에이전트 운영 플랫폼
---

# FabAgent

반도체 공정 이상의 **탐지 → 원인 분석 → 영향 평가 → 대응 권고**를 하나의 멀티 에이전트
파이프라인으로 통합하는 운영 플랫폼입니다.

각 Tier가 **자율 도구 호출(tool calling)** 과 **조건부 라우팅** 을 통해 의사결정을 진행하는
진짜 LLM agent로 구성되어, 단일 LLM 챗봇과 달리 추적 가능하고 모듈화된 의사결정 흐름과
auditable한 reasoning trace를 제공합니다.

## 핵심 특징

- **4-Tier multi-agent system** - 탐지(ML) · 원인(agentic RAG) · 영향(tool-using) · 대응(tool-using)
- **Plan-and-Execute 패턴** (기본) - Central Planner Agent가 전체 워크플로우 plan을 1회 산출, Tier executor가 plan대로 실행 → 통신 오버헤드 최소화 (LLM 호출 -60%, latency -54%)
- **Tool-using agent** (옵션) - 7개 도메인 도구를 LLM이 자율 선택·반복 호출 (`AGENT_MODE=autonomous`)
- **Supervisor agent** (autonomous 모드) - LLM이 Tier 2 결과를 보고 후속 workflow path(proceed_full / fast_track / escalate) 동적 결정
- **조건부 라우팅** - LangGraph에서 severity gate + cause confidence retry + supervisor 분기 (3단계)
- **CRAG self-correction** - retrieval grader가 검색 품질 평가, 임계치 미달 시 쿼리 자동 재작성
- **LangSmith observability** - 모든 LLM·tool·agent 호출 자동 트레이스 (production-grade)
- **Production RAG** - BM25 + FAISS + Reciprocal Rank Fusion (5단계 paradigm ablation으로 검증)
- **실데이터 기반** - UCI SECOM (590 익명 센서) + PHM 2016 CMP (25개 명명 센서, 실측)
- **자가 학습 루프** - 운영자 승인 시 분석 결과가 인시던트 DB(.md)에 자동 기록 → 다음 RAG에 즉시 반영
- **정량 근거** - 핵심 의사결정마다 ablation/벤치마크/차트 (`experiments/*/results.md`)

## 아키텍처

### 4-Tier Multi-Agent Pipeline

```
┌──────────────┐
│ 알람 인박스  │  사이드바에서 알람 선택
└──────┬───────┘
       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ agents/orchestrator.py - LangGraph StateGraph (조건부 + LLM-driven 라우팅)  │
│                                                                             │
│   START → [detect] ──── score < 0.30 ──→ [noise] → END    (severity gate)   │
│              │                                                              │
│              └── score ≥ 0.30 ──→ [cause]                                   │
│                                     │                                       │
│                  ┌──── max pct < 40% ─────→ [cause_retry] ──┐               │
│                  │ (output threshold)                       │               │
│                  └──── max pct ≥ 40% ──→ [supervisor] ←─────┘               │
│                                              │                              │
│                       ┌─── LLM 결정 ────────┤                              │
│                       │ proceed_full        │                              │
│                       │ escalate            ▼                              │
│                       │                  [impact] ──┐                       │
│                       │                              ▼                      │
│                       │ fast_track ──→ [fast_impact] → [response] → END    │
│                       │                              ▲                      │
│                       │                              │                      │
│                       └──────────────────────────────┘                      │
│                                                                             │
│   Tier 1: IsolationForest (ML) - SECOM/PHM 데이터 분기                       │
│   Tier 2: agentic RAG (tools: search_knowledge, lookup_incident, get_pm)    │
│   Supervisor (gpt-4o-mini): action·severity·reasoning을 LLM이 결정          │
│   Tier 3: tool-using (query_wip, get_downstream, get_yield_baseline, pm)    │
│   fast_impact: LLM 호출 없는 deterministic 경량 처리 (fast_track 전용)      │
│   Tier 4: tool-using (search, lookup_incident, get_pm, check_pm_schedule)   │
└─────────────────────────┬───────────────────────────────────────────────────┘
                          ▼
              ┌────────────────────────┐
              │ TierData (단일 계약)   │
              └──────────┬─────────────┘
                         ▼
              ┌────────────────────────┐
              │ Streamlit UI (cascade) │
              │ Tier 4 승인 → 작업지시 │
              │   + 자가 학습 루프     │
              └────────────────────────┘
```

### 7개 Agent Tools

| 도구 | 반환 | 사용 Tier |
|---|---|---|
| `search_knowledge` | INC/FMEA/SOP/FLOW 문서 hybrid 검색 결과 | 2, 4 |
| `lookup_incident_history` | 과거 incident 구조화 레코드 (원인·해결책·yield 회복률) | 2, 4 |
| `get_pm_history` | 장비 마지막 PM 일자·경과일·overdue 여부 | 2, 3, 4 |
| `check_pm_schedule` | 다음 7일 가용 PM 윈도우 | 4 |
| `query_wip_status` | 영향 받는 WIP lot/wafer 수 | 3 |
| `get_downstream_steps` | 후공정 의존성 (typical delta·severity) | 3 |
| `get_yield_baseline` | 공정 최근 30일 yield 기준선 (%) | 3 |

LLM이 어떤 도구를 언제 호출할지 자율 결정합니다. 호출 로그가 reasoning trace = production audit trail.

## 데이터 & 모델

| 알람 | 공정 step | 데이터 | 모델 / 기술 |
|---|---|---|---|
| A1 | Photo (노광) | UCI SECOM (590 익명 센서) | IsolationForest + gpt-5-mini agent + Hybrid RAG |
| A2 | Etch (식각) | UCI SECOM (다른 fail row) | IsolationForest + gpt-5-mini agent + Hybrid RAG |
| A3 | CMP (연마) | **PHM 2016 CMP** (25개 명명 센서, SLURRY_FLOW 등) | IsolationForest + gpt-5-mini agent + Hybrid RAG |

SECOM은 익명 처리된 표준 벤치마크라 공정 step 라벨이 narrative입니다 (한계 명시).
PHM 2016 CMP는 실제 CMP 공정 센서 데이터로 step-specific 추론이 가능합니다.

## 정량 평가 요약

핵심 의사결정마다 ablation 실험을 수행하고 결과·차트·시행착오를 기록했습니다.
상세는 [experiments/README.md](experiments/README.md).

| ID | 실험 | 결정 | 핵심 수치 |
|---|---|---|---|
| **D1** | Tier 1 모델 비교 | IsolationForest | PR-AUC 0.129 (LOF 0.089, OC-SVM 0.098, baseline 0.119) |
| **D2** | Retrieval 백엔드 latency | 4 backend 검증 | keyword 0.5ms / faiss 60ms / **hybrid 54ms** / +rerank 326ms |
| **D5** | Multi vs Single LLM | Multi-Agent | 비용 $0.018 vs $0.008 (2.2x), 권고 깊이 1.6~1.9배, 모듈화 결정적 |
| **D6** | RAG paradigm 5단계 ablation | **Hybrid** 채택 | faithfulness: No RAG 0.32 → Hybrid 0.82 (2.5x). Hybrid가 모든 지표 1위 |
| **D7** | Workflow vs Agentic 비교 | **Agentic** 채택 | tool 0→13, 인용 깊이 +25%, 비용 2.6x, latency 2.3x, reasoning trace 확보 |
| **D8** | CRAG (Self-correction) ON vs OFF | CRAG **활성 유지** (관측 가치) | 품질 변화 -0.1%p (동급), refinement 발동률 20%, relevance_score 노출, 비용 +31% |
| **D9** | 한국어 reranker (Dongjin-kr/ko-reranker) vs 영어(BAAI) vs hybrid (12 docs) | 둘 다 hybrid에 미달 | hybrid 0.734 / BAAI 0.714 / ko 0.703 |
| **D10** | **D9 후속**: 코퍼스 12→34 확장 후 reranker 재평가 | **가설 검증 - 효과 완전 반전** | hybrid **0.592** / BAAI **0.709 (+0.117)** / ko **0.675 (+0.083)** |
| **D11** | Conductor (Plan-and-Execute) vs Autonomous (tool-using loop) | **Conductor 채택** | LLM -60%, Latency **131→60초 (-54%)**, 비용 -58%, **인용 동등(6.0)** |

### D6 핵심 그래프

![RAG Paradigm Evolution](experiments/rag_paradigm/charts/ragas_comparison.png)

![Quality vs Latency Trade-off](experiments/rag_paradigm/charts/tradeoff.png)

### D7 핵심 그래프

![Workflow vs Agentic - 호출 횟수](experiments/agentic_vs_workflow/charts/calls_citations.png)

![Tier별 Latency](experiments/agentic_vs_workflow/charts/latency_per_tier.png)

### D8 핵심 그래프

![CRAG 자가 정정 활동](experiments/crag_eval/charts/crag_activity.png)

![CRAG 효과 - 답변 품질](experiments/crag_eval/charts/quality.png)

### D10 핵심 그래프 (확장 코퍼스에서 reranker 효과 반전 검증)

![Reranker 비교 (34 docs)](experiments/reranker_compare/charts/reranker_comparison.png)

### D11 핵심 그래프 (Conductor vs Autonomous)

![호출 횟수 비교](experiments/conductor_vs_autonomous/charts/calls_comparison.png)

![Latency 비교](experiments/conductor_vs_autonomous/charts/latency_comparison.png)

![비용 비교](experiments/conductor_vs_autonomous/charts/cost_comparison.png)

## 시행착오

이 시스템이 처음부터 이 모양이었던 건 아닙니다. 실제로 다음 다섯 번의 큰 방향 전환을 거쳤습니다.

### 1. 더미 데이터 → 실데이터 (M1~M3)

- **시작**: `data/demo.TIER_DATA`에 하드코딩된 Tier 1~4 결과로 UI만 시연
- **문제**: 데이터 기반 의사결정이 아니라 "시나리오 영상"에 가까움. 인터뷰 부적합
- **해결**: SECOM(A1·A2) + PHM 2016 CMP(A3) 실데이터 로더 구축, Tier 1을 IsolationForest로 실제 추론

### 2. 키워드 RAG → Hybrid → +Rerank → **다시 Hybrid** (D2, D6)

- **시작**: 코퍼스가 작아서(~10문서) 단순 키워드 매칭으로 충분
- **추가**: BM25(sparse) + FAISS(dense) + Reciprocal Rank Fusion 결합. Anthropic Contextual Retrieval 패턴 적용
- **욕심**: Cross-encoder rerank(`BAAI/bge-reranker-base`)까지 추가, "production 정밀" 어필 시도
- **반전**: 5단계 paradigm ablation (D6) 결과 `Hybrid + Rerank`가 `Hybrid`보다 오히려 못함
  - `Hybrid` faithfulness 0.821, answer_relevancy 0.394
  - `Hybrid + Rerank` faithfulness 0.819, answer_relevancy **0.167** (낙폭 큼)
- **원인 분석**: ① 코퍼스가 ~10문서로 작아 Hybrid top-3이 이미 정답에 근접 ② `bge-reranker-base`가 영어 학습 모델이라 한국어 도메인 텍스트에서 점수 신호가 잡음
- **교훈**: production 패턴을 블라인드 적용하면 역효과. **정량 평가(RAGAS) 없이 'rerank가 좋다'는 통념을 그대로 끌고 갈 뻔함**
- **결정**: 기본 backend를 `hybrid_rerank` → `hybrid`로 변경. `Hybrid + Rerank`는 환경변수 옵션으로 유지 (코퍼스 100+ 확장 시 재평가 권장)

### 3. "이게 진짜 agent인가?" 자기 검증 (M5)

- **상황**: 4-Tier가 LLM 호출하니 multi-agent라고 주장하고 있었음
- **냉정한 점검**: Anthropic의 ["Building Effective Agents"](https://www.anthropic.com/engineering/building-effective-agents) 정의 기준으로 보면 현재는 **workflow** (각 Tier가 사전 정의된 RAG 한 번 + LLM 한 번)
- **agent의 정의**: LLM이 도구를 자율 선택·반복 호출, 조건부 분기, reasoning loop
- **갭**: 도구 호출 없음 / 루프 없음 / 조건부 라우팅 없음

### 4. Workflow → Agentic 전환 (현재)

- **구현**: 7개 도메인 도구 정의 (`agents/tools/`), Tier 2/3/4를 tool-calling loop + synthesis 호출 패턴으로 재작성
- **conditional routing**: LangGraph에 severity gate (Tier 1 score < 0.3 → noise) + cause confidence retry (max pct < 40 → 한 번 재시도) 분기 추가
- **정량 검증 (D7)**: workflow vs agentic 3 알람 비교
  - LLM 호출: 3 → 9 (x3.0)
  - Tool 호출: 0 → 13 (agentic의 reasoning trace)
  - 유니크 인용: 4 → 5 (+25%, 솔직히 적당한 수준)
  - 비용: $0.012 → $0.030 / 알람 (x2.6)
  - Latency: 83s → 194s (x2.3)
- **솔직한 trade-off**: 비용 2.6배가 정당화되는 이유는 인용 +25%가 아니라 **tool 호출 로그 자체가 production audit trail**. fab 환경에서 "이 권고가 왜 나왔는가"의 감사 추적이 결정적

### 5. LangGraph 도입 (M4)

- **이전**: orchestrator가 결정론적 함수 호출 시퀀스
- **현재**: LangGraph StateGraph + `lru_cache`로 컴파일된 그래프
- **이득**: ① mermaid 다이어그램 자동 추출 → 분기 시각화 ② 향후 동적 라우팅·재시도·인터럽트 확장 시 동일 구조 위에서 점진 가능

### 6. CRAG (Self-correction) 도입 - 두 번째 "정량으로 통념 반박" 사례 (D8)

- **시작**: Anthropic·LangChain이 자주 언급하는 CRAG (Corrective RAG) 패턴 도입. retrieval grader가 검색 결과를 자체 평가하고, 임계치 미달 시 쿼리를 재작성해 재검색
- **구현**: `agents/rag/crag.py` - gpt-4o-mini 기반 grader/refiner, `search_knowledge` 도구에 transparent 통합 (환경변수 `CRAG_ENABLED` 토글)
- **smoke test 결과 인상적**: gibberish 쿼리(`알수없음 xyzzy foobar`)에 대해 grader가 avg score 0.0 부여 → LLM이 `CMP 공정 실패 모드 분석 및 슬러리 관리 절차 관련 정보` 로 자동 재작성 → avg score 0.68 회복. 진짜 자가 정정 메커니즘 작동
- **반전**: 3 알람 정량 비교(D8)에서 품질 차이 사실상 없음 (faithfulness -0.1%p, relevancy -3.3%p)
- **원인 분석**:
  1. 코퍼스가 ~10문서로 작아 hybrid 검색이 이미 잘 작동
  2. agentic loop 자체가 이미 self-correction 일부 수행 (LLM이 첫 검색 결과가 부족하면 다른 쿼리로 다시 호출). CRAG와 부분 중복
  3. Refinement 발동률 20% (5번 중 1번) - 정상 쿼리에선 무발동
- **교훈**: **D6 (Rerank) 시행착오와 같은 패턴** - production 패턴을 작은 도메인 코퍼스에 블라인드 적용하면 ROI 낮음. 정량 평가 없이는 "CRAG 도입했음" 마케팅으로 끝났을 것
- **결정**: CRAG **활성 유지** (`CRAG_ENABLED=true`).
  - 품질 향상 미미하지만 인용 신뢰도(0~1 relevance_score) 가시화가 production observability에 가치
  - 비용 +31% 절대값 미미 (1000 알람당 +$2.90)
  - 코퍼스 100+ 확장 또는 한국어 reranker 도입 시 재평가 권장

### 7. 한국어 reranker 후속 평가 - D6 가설 검증 (D9)

- **시작**: D6에서 "영어 학습 reranker가 한국어 코퍼스에서 효과 없음" 가설 제시. `Dongjin-kr/ko-reranker`로 검증
- **방법**: `rerank.py`에 `RERANK_MODEL` 환경변수 추가, 6개 대표 쿼리 × 3 모드(hybrid / BAAI / ko-reranker)로 CRAG grader 채점
- **결과**: hybrid 0.734 (baseline), BAAI 0.714 (-0.020), **ko-reranker 0.703 (-0.031)**
- **반전 안에 반전**: 쿼리별로 보면 ko-reranker가 CMP(+0.10), 의미 우회 1(+0.083)에선 우위. Etch(-0.18), 의미 우회 2(-0.20)에선 손실. 전체 평균은 무승부
- **해석**: 한국어 reranker가 영어보단 도메인 적합성 약간 우위지만, **본 코퍼스 규모(~10문서)에선 hybrid top-3이 이미 충분히 정밀해 어떤 reranker도 의미 있는 이득 없음**
- **결론(잠정)**: D6 가설 부분적 재확인 - 코퍼스 규모가 진짜 원인이라는 더 큰 가설을 제시

### 8. Supervisor agent - LLM-driven 동적 workflow routing

- **시작**: 기존 conditional edge는 threshold 기반(`score < 0.3` → skip, `max pct < 40` → retry). "진짜 agent라면 LLM이 맥락을 보고 결정해야 한다"
- **구현**: `agents/supervisor.py` - Tier 2 결과를 받아 3가지 action 결정
  - `proceed_full` (표준): Tier 3 → Tier 4
  - `fast_track` (단일 원인 우세): Tier 3 LLM skip, deterministic 경량 처리로 비용 절감
  - `escalate` (고위험): 정상 진행 + human review 플래그 (Tier 4 immediate 첫 항목에 🚨 prepend)
- **모델**: gpt-4o-mini (의사결정 소작업, 비용 절감)
- **LangGraph 시각화**: 3개 분기 노드 (detect, cause, supervisor) - 정적 + LLM-driven 라우팅의 조합
- **smoke test**: A1 (medium severity, 3 causes) → proceed_full, A2/A3 (high severity) → proceed_full. 현 데이터에선 모두 표준 경로 선택 (안전한 기본)

### 9. LangSmith observability 통합

- **목적**: production-grade 트레이스 대시보드. 알람별 LLM 호출 트리, tool 호출 시퀀스, latency·token 분석
- **구현**: `wrap_openai`로 모든 chat.completions.create 자동 트레이스, `@traceable` 데코레이터로 4-Tier agent + Supervisor + tool dispatcher를 nested run으로 시각화
- **토글**: 환경변수 `LANGSMITH_TRACING=true/false`로 on/off, 비활성 시 no-op (성능·기능 영향 없음)
- **포트폴리오 가치**: 인터뷰에서 "각 LLM 호출·tool 호출·token·latency 다 보입니다" 한 줄로 production-grade 인상

### 10. 코퍼스 12 → 34 확장 + D10으로 가설 검증

- **시작**: D9까지 누적된 가설 "코퍼스 규모가 reranker 효용의 선결조건". 이를 정량 검증하려면 코퍼스 확장 필수
- **방법**: 합법적 공개 자료로 12개 → 34개 확장
  - 한국어 위키백과 12개 (반도체 공정 전반: Photo/Etch/CMP/이온주입/박막/포토레지스트/EUV 등)
  - SK하이닉스 뉴스룸 6개 (실제 산업 운영 관점: 식각·포토·CMP·세정)
  - 삼성반도체 공식 3개 (8대 공정·용어집·EUV)
  - SKC 소재 1개, PHM Society 2016 챌린지 1개
  - 모든 출처는 CC BY-SA 또는 공개 자료, 파일별 attribution 명시
- **D10 결과 (re-run D9 with 34 docs)**:
  - hybrid: 0.734 → **0.592** (-0.142, noise 증가)
  - BAAI: -0.020 → **+0.117** (반전!)
  - ko-reranker: -0.031 → **+0.083** (반전!)
- **검증 완료**: 가설 정확히 입증. 확장 코퍼스에서는 BM25/FAISS가 일반 자료 noise를 흡수하지만 cross-encoder가 그중에서 정답을 골라냄
- **결정**: 코퍼스 30+ 환경에서는 `RAG_BACKEND=hybrid_rerank` 권장. 데모용 12개에선 hybrid 유지
- **시리즈 의의**: D6 → D9 → D10이 portfolio narrative로 완성. "통념 → 정량 반박 → 가설 → 정량 검증"의 사이클이 정량 평가의 가치 자체를 증명

### 11. Conductor 패턴 (Plan-and-Execute) 도입 - "agentic → conductor" 전환

- **상황**: 4-tier agentic 시스템(D7) 도입 후 알람당 약 3분(194초)·LLM 10~13회로 데모 UX 저하. 코퍼스 확장(D10)으로 컨텍스트 더 무거워짐
- **진단**: Anthropic의 [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)가 명시하듯 "autonomous" 패턴은 적응성이 강점이지만 통신 오버헤드(iteration 누적·재귀 호출 위험) 큼
- **전환**: Plan-and-Execute 패턴 - Central Planner Agent가 알람+Tier 1을 보고 전체 워크플로우(Tier 2/3/4 각 tool 호출 plan)를 1회 산출, 각 Tier executor는 plan대로 tool 직접 실행 + LLM 1회 synthesis
- **구현**: `agents/planner.py` 신규 + `cause/impact/response.py`에 conductor 경로 추가 (autonomous는 옵션 유지). 환경변수 `AGENT_MODE=conductor` (기본) / `autonomous`로 토글
- **D11 정량 결과 (3 알람, CRAG OFF 동일 조건)**:
  - LLM 호출: 10.0 → 4.0 (**-60%**, Planner 1 + Tier×3 synthesis)
  - Latency: 131초 → **60초** (**-54%**)
  - 비용: $33.23 → $13.80 / 1000알람 (**-58%**)
  - 인용 깊이: 6.0 → 6.0 (**동등**, 품질 손실 없음)
- **핵심 narrative**: D7(workflow → agentic으로 자율성 확보) → D11(agentic → conductor로 효율 회복). 두 단계 모두 정량 데이터 기반 의사결정. **autonomous의 자율성 vs conductor의 효율성을 trade-off로 명시 채택**
- **재귀 위험 원천 차단**: 기존 `MAX_TOOL_ITERATIONS=4` 캡에 의존하던 무한루프 방지가 plan 고정 실행으로 본질적으로 해결

## 실행

### 로컬

```bash
pip install -r requirements.txt
cp .env.example .env           # OPENAI_API_KEY 입력
streamlit run app.py --server.port 8501
```

PHM 2016 CMP 캐시(`data/phm2016/phm_cmp_features.csv`)는 저장소에 포함되어 별도 다운로드가 필요 없습니다.
raw trajectory 데이터를 직접 다루려면 `data/phm2016/README.md` 참고.

### RAG 백엔드 전환

```bash
RAG_BACKEND=hybrid streamlit run app.py        # 기본값 (실측 데이터 근거 채택)
RAG_BACKEND=hybrid_rerank streamlit run app.py # 옵션: 코퍼스 확장 시
RAG_BACKEND=faiss streamlit run app.py         # 옵션: 의미 위주
RAG_BACKEND=keyword streamlit run app.py       # 옵션: 의존성 최소
```

### Agent 모드 토글 (D11)

```bash
AGENT_MODE=conductor streamlit run app.py    # 기본 - Plan-and-Execute (빠르고 저렴, 통신 최소)
AGENT_MODE=autonomous streamlit run app.py   # 옵션 - tool-using agent loop (적응성 우위)
```

### CRAG (Self-correction) 토글

```bash
CRAG_ENABLED=true streamlit run app.py    # 기본값 - retrieval grader + 자동 refinement
CRAG_ENABLED=false streamlit run app.py   # 비활성 - latency critical 시나리오
```

### LangSmith Observability (선택)

모든 LLM·tool·agent 호출이 [LangSmith](https://smith.langchain.com) 대시보드로 자동 전송됩니다.

```bash
# .env 에 추가 (https://smith.langchain.com 에서 API 키 발급)
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_pt_...
LANGSMITH_PROJECT=fabagent
```

활성 시:
- `wrap_openai`가 모든 `chat.completions.create` 호출을 자동 트레이스 (Tier 2/3/4 agent, CRAG grader, RAGAS 평가 등)
- `@traceable` 데코레이터로 4-Tier orchestrator·각 agent·tool dispatcher를 nested run으로 시각화
- production observability: 알람별 latency / 비용 / tool 호출 트리 / error 추적

### Hugging Face Spaces 배포

1. HF Space 생성 (SDK: Streamlit)
2. 본 저장소 연결 (또는 push)
3. Space settings → Variables and secrets → `OPENAI_API_KEY` 추가
4. 자동 빌드·배포

상단 frontmatter가 HF Space 설정으로 자동 인식됩니다.

## 파일 구조

```
fabagent/
├── app.py                       # Streamlit 엔트리포인트
├── components/                  # UI 컴포넌트 (사이드바·헤더·Tier 카드·cascade)
├── core/
│   ├── schema.py                # Tier1~4 TypedDict 계약
│   └── pipeline.py              # 알람 → Tier 데이터 라우터
├── agents/
│   ├── orchestrator.py          # LangGraph StateGraph + 조건부 라우팅
│   ├── detection.py             # Tier 1 IsolationForest (SECOM/PHM 디스패치)
│   ├── planner.py               # Central Planner Agent (Plan-and-Execute, conductor 모드)
│   ├── cause.py                 # Tier 2 (conductor: plan 받음 / autonomous: tool loop)
│   ├── impact.py                # Tier 3 (conductor / autonomous 양 모드)
│   ├── response.py              # Tier 4 (conductor / autonomous 양 모드)
│   ├── supervisor.py            # autonomous 모드 전용 LLM-driven router
│   ├── llm.py                   # OpenAI 클라이언트 + LangSmith wrap_openai 통합
│   ├── tools/                   # 7개 agent 도구
│   │   ├── knowledge.py         #   search_knowledge (RAG 검색)
│   │   ├── incident.py          #   lookup_incident_history
│   │   ├── equipment.py         #   get_pm_history, check_pm_schedule
│   │   └── process.py           #   query_wip_status, get_downstream_steps, get_yield_baseline
│   └── rag/
│       ├── store.py             # 백엔드 dispatch (keyword/faiss/hybrid/hybrid_rerank)
│       ├── faiss_store.py       # FAISS 벡터 검색
│       ├── hybrid_store.py      # BM25 + FAISS + Reciprocal Rank Fusion
│       ├── rerank.py            # Cross-encoder 재정렬 (BAAI/bge-reranker-base)
│       ├── crag.py              # CRAG self-correction (grader + query refiner)
│       ├── learn.py             # 자가 학습 루프 (INC-AUTO-*.md 자동 기록)
│       └── knowledge/           # 도메인 문서 (INC/FMEA/SOP/FLOW)
├── data/
│   ├── demo.py                  # 알람 정의
│   ├── wip.py                   # 영향 WIP 결정론 데이터
│   ├── secom/                   # SECOM 로더 + 전처리 + raw .data
│   └── phm2016/                 # PHM 2016 CMP 로더 + 사전 집계 CSV
├── experiments/                 # 정량 비교 실험 + 차트
│   ├── tier1_detection/         # D1: IsoForest / LOF / OC-SVM
│   ├── retrieval_compare/       # D2: keyword / FAISS / hybrid / +rerank
│   ├── multi_vs_single/         # D5: multi-agent vs single LLM
│   ├── rag_eval/                # RAGAS 평가 (hybrid vs hybrid_rerank)
│   ├── rag_paradigm/            # D6: 5단계 paradigm ablation
│   ├── agentic_vs_workflow/     # D7: workflow vs agentic 비교
│   ├── crag_eval/               # D8: CRAG self-correction 효과 평가
│   ├── reranker_compare/        # D9·D10: 한국어 reranker + 확장 코퍼스 가설 검증
│   └── conductor_vs_autonomous/ # D11: Conductor vs Autonomous (latency -54%, 인용 동등)
├── docs/orchestrator_graph.mmd  # LangGraph 자동 추출 mermaid
├── styles/main.css              # 디자인 시스템
└── tests/
```

## 기술 스택

- **프론트**: Streamlit 1.36+
- **백엔드**: OpenAI SDK (`gpt-5-mini`, structured output + function calling)
- **Orchestration**: LangGraph StateGraph (조건부 + LLM-driven 라우팅, mermaid 추출)
- **Observability**: LangSmith (`wrap_openai` + `@traceable`, 옵션)
- **ML**: scikit-learn (IsolationForest, LOF, OC-SVM)
- **RAG**: rank-bm25 + sentence-transformers + FAISS + RRF (옵션: cross-encoder rerank)
- **평가**: RAGAS (faithfulness, answer_relevancy, context_precision) with gpt-4o-mini
- **데이터**: pandas, UCI SECOM, PHM 2016 CMP Data Challenge
- **Python**: 3.11+

## 한계와 향후 확장

- **SECOM의 익명성**: 590개 센서가 어느 공정·물리량인지 비공개라 A1/A2의 step 라벨은 시연용 narrative
- **knowledge 문서**: 합성 12개 + 공개 자료(위키/SK하이닉스/삼성/SKC/PHM) 22개 = **총 34개**. 실 fab 수천 문서 대비 여전히 작지만, D10에서 코퍼스 규모와 reranker 효용의 관계는 정량 검증됨
- **도구 mock data**: PM 이력·yield baseline·downstream 의존성은 in-memory mock (실 fab은 MES/EAP/YMS 어댑터로 교체)
- **한국어 reranker 검증 완료(D9)**: hybrid 단독에 미달, 코퍼스 확장이 reranker 효용의 선결조건임을 확인
- **Supervisor fast_track 시연 부재**: 현 3개 데모 알람은 모두 proceed_full 선택 - fast_track/escalate 시연을 위해선 더 다양한 알람 시나리오 필요
- **고도화 방향**: GraphRAG(공정 의존성 노드 그래프) · 실 MES/EAP/YMS 어댑터 · 한국어 reranker 전용 fine-tuning · 멀티 에이전트 negotiation (현재는 supervisor가 일방향 라우팅)