diff --git a/300_architecture/330_백엔드_PostgreSQL_ChromaDB_Vector_Memory.md b/300_architecture/330_백엔드_PostgreSQL_ChromaDB_Vector_Memory.md index f5133a0..abc45f9 100644 --- a/300_architecture/330_백엔드_PostgreSQL_ChromaDB_Vector_Memory.md +++ b/300_architecture/330_백엔드_PostgreSQL_ChromaDB_Vector_Memory.md @@ -53,7 +53,7 @@ ```sql -- 사용자의 기본 정보와 레벨 등 명확한 데이터를 저장하는 테이블입니다. -CREATE TABLE users ( +CREATE TABLE user ( id UUID PRIMARY KEY, email VARCHAR(255) UNIQUE, name VARCHAR(100), @@ -63,9 +63,9 @@ CREATE TABLE users ( ); -- 로빙의 개성(스탯)과 감정 상태 등 성장 정보를 기록하는 테이블입니다. -CREATE TABLE robeings ( +CREATE TABLE robeing ( id UUID PRIMARY KEY, - user_id UUID REFERENCES users(id), + user_id UUID REFERENCES user(id), name VARCHAR(100), -- 스탯 (게임처럼 수치화) intelligence INTEGER DEFAULT 10, @@ -82,7 +82,7 @@ CREATE TABLE robeings ( -- 로빙이 습득한 능력(스킬)의 레벨과 숙련도를 관리하는 테이블입니다. CREATE TABLE skills ( id UUID PRIMARY KEY, - robeing_id UUID REFERENCES robeings(id), + robeing_id UUID REFERENCES robeing(id), skill_name VARCHAR(100), skill_level INTEGER DEFAULT 1, experience_points INTEGER DEFAULT 0, @@ -93,7 +93,7 @@ CREATE TABLE skills ( -- 로빙이 수행한 모든 작업의 성공 여부, 소요 시간 등을 기록하여 나중에 분석할 수 있게 하는 로그 테이블입니다. CREATE TABLE task_history ( id UUID PRIMARY KEY, - robeing_id UUID REFERENCES robeings(id), + robeing_id UUID REFERENCES robeing(id), task_type VARCHAR(50), input_data JSONB, output_data JSONB, @@ -109,7 +109,7 @@ CREATE TABLE task_history ( # 로빙의 대화나 문서 내용을 '의미' 기반으로 저장하는 기억 컬렉션입니다. # 나중에 "비슷한 이야기"를 찾아낼 때 사용됩니다. memories_collection = { - "name": "robeing_{user_uuid}_memories", # 사용자별로 기억을 완전히 분리합니다. + "name": "rb8001_{user_uuid}_memory", # 사용자별로 기억을 완전히 분리합니다. "metadata": { "description": "로빙의 모든 대화 및 문서 기억", "embedding_model": "ko-sroberta-multitask" @@ -148,9 +148,9 @@ async def recall_relevant_context(user_id: str, current_text: str): # 1. [사실 기억 조회] PostgreSQL에서 사용자의 프로필, 로빙의 스탯 등 '사실' 정보를 가져옵니다. user_data = await postgres.query(""" - SELECT u.*, r.* - FROM users u - JOIN robeings r ON u.id = r.user_id + SELECT u.*, r.* + FROM user u + JOIN robeing r ON u.id = r.user_id WHERE u.id = $1 """, user_id) diff --git a/plans/000000_unresolved_items_matrix.md b/plans/000000_unresolved_items_matrix.md index af6919c..2fc3cf8 100644 --- a/plans/000000_unresolved_items_matrix.md +++ b/plans/000000_unresolved_items_matrix.md @@ -1,9 +1,7 @@ # 미해결 항목 매트릭스 (중요도 × 구현 난이도) ## 🔴 Quick Wins (높은 중요도 + 쉬운 구현) → 즉시 실행 -1. **rb8001 EmailIntegration 버그 수정** - NaverWorks 토큰 조회 시 미정의 변수 `user_uuid` → `slack_id` 수정 필요 (현재 user_uuid 사용 중) (10분) [→250921](../troubleshooting/250921_email_integration_undefined_variable_bug.md) -2. **UUID↔Slack ID 조회 엔드포인트 통일** - gateway는 내부 DB, auth-server는 `/api/slack/mapping/{identifier}` 사용 중 (미통일) (2시간) [→250921](../troubleshooting/250921_uuid_slack_mapping_endpoint_unification.md) -3. **네이버웍스 메일→슬랙 전달** - 기본 연동(01) ✅완료, 일일 브리핑(02)·콜드메일(03) 미구현 (1주) [→250919_01_base](../troubleshooting/250919_naverworks_slack_01_base_configuration.md) [→250919_02_daily](../troubleshooting/250919_naverworks_slack_02_daily_briefing.md) [→250919_03_cold](../troubleshooting/250919_naverworks_slack_03_cold_mail_list.md) +1. **네이버웍스 메일→슬랙 전달** - 기본 연동(01) ✅완료, 일일 브리핑(02) 구현 완료, 테스트 중 · 콜드메일(03) 미구현 (1주) [→250919_01_base](../troubleshooting/250919_naverworks_slack_01_base_configuration.md) [→250919_02_daily](../troubleshooting/250919_naverworks_slack_02_daily_briefing.md) [→250919_03_cold](../troubleshooting/250919_naverworks_slack_03_cold_mail_list.md) ## 🟠 Major Projects (높은 중요도 + 어려운 구현) → 계획 수립 후 진행 1. **하드코딩 URL 제거** - 15개+ 서비스 광범위 미해결, 특히 rb8001의 auth-server URL (3-4주) [→250915](../troubleshooting/250915_hardcoded_url_removal.md) @@ -17,7 +15,7 @@ 9. **news 엔드포인트 리팩토링** - DB 영속화 완료(250920), 서비스 레이어 리팩토링 미완 (1주) [→250920_db](../troubleshooting/250920_news_db_persistence_implementation.md) ## 🟡 Fill-ins (낮은 중요도 + 쉬운 구현) → 시간 날 때 -1. **scheduled_tasks 테이블** - 미구현 (관련 문서는 부분 구현 표기) (3시간) [→250827](../troubleshooting/250827_frontend_backend_preferences_API_연동_완료.md) +1. **scheduled_tasks 테이블** - 미구현 (스키마만 존재) (3시간) [→250827](../troubleshooting/250827_frontend_backend_preferences_API_연동_완료.md) 2. **캘린더 API** - /api/calendar 미구현 (4시간) [→250830](../troubleshooting/250830_skill_level_system_restructure.md) 3. **문서 API** - /api/docs 미구현 (4시간) [→250830](../troubleshooting/250830_skill_level_system_restructure.md) 4. **불용 환경변수 정리** - 전역 감사 미완 (2시간) @@ -38,6 +36,7 @@ *평가 기준: 중요도(시스템 안정성/사용자 영향), 난이도(구현 시간/복잡도)* ## ✅ 완료된 항목 (아카이브) 1. **시스템 메트릭/Stats 일원화** - rb8001 → robeing-monitor 위임 완료, /stats 정상 동작 확인 ✅ [→250920_stats](../troubleshooting/250920_stats_api_unification_complete.md) +2. **네이버웍스 일일 브리핑** - 구현 완료, 테스트 진행 중 ✅ --- -*최종 업데이트: 2025-09-22* \ No newline at end of file +*최종 업데이트: 2025-09-25* diff --git a/plans/250906_news_skill_publish_separation.md b/plans/250906_news_skill_publish_separation.md index c1a5d95..e52f8f8 100644 --- a/plans/250906_news_skill_publish_separation.md +++ b/plans/250906_news_skill_publish_separation.md @@ -49,7 +49,7 @@ ## 4. 데이터베이스 (확인됨) **PostgreSQL (51123 서버)**: - main_db 사용 (구 auth_db) -- users, gmail_tokens, robeing_stats 테이블 존재 +- users, gmail_token, robeing_stats 테이블 존재 - ~~rb_news 테이블~~: DB 작업 후 구현 예정 **ChromaDB (51124 서버)**: @@ -90,4 +90,4 @@ ## 8. 일정 (완료 상태) - **1주차**: ✅ skill-news 운영 중 (포트 8505) - **2주차**: ✅ skill-publish 구현 완료 (포트 8511) -- **3주차**: Slack 통합 및 rb8001 연동 예정 \ No newline at end of file +- **3주차**: Slack 통합 및 rb8001 연동 예정 diff --git a/research/ai_planning/250925_classical_planning_basics.md b/research/ai_planning/250925_classical_planning_basics.md new file mode 100644 index 0000000..28ddac0 --- /dev/null +++ b/research/ai_planning/250925_classical_planning_basics.md @@ -0,0 +1,126 @@ +--- +tags: + - AI + - ClassicalPlanning + - PDDL + - STRIPS + - Heuristics +date: 2025-09-25 +modification_date: 2025-09-25 +--- +# 고전 계획(Classical Planning) 기초 + +## 1. 개요 +**고전 계획(Classical Planning)**은 인공지능의 한 분야로, **초기 상태(Initial State)**에서 **목표 상태(Goal State)**에 도달하기 위한 **행동(Action)의 순서, 즉 계획(Plan)**을 자동으로 찾는 것을 목표로 합니다. + +고전 계획은 다음과 같은 핵심적인 가정을 전제로 합니다. + +- **완전 관측(Fully Observable)**: 환경의 모든 상태를 완벽하게 알 수 있습니다. +- **결정론적(Deterministic)**: 특정 행동의 결과는 항상 동일하며 예측 가능합니다. +- **정적(Static)**: 외부 요인에 의해 상태가 스스로 변하지 않습니다. 오직 에이전트의 행동만이 상태를 변화시킵니다. +- **이산적(Discrete)**: 시간, 상태, 행동이 모두 이산적인 단위로 나뉩니다. + +## 2. 핵심 구성 요소 (수학적 모델) + +고전 계획 문제는 수학적으로 다음과 같이 정의됩니다. + +- **상태 (State)**: `s`로 표현하며, 세상에 대한 참인 사실(Fact)들의 집합입니다. 예를 들어, `on(A, B)`, `clear(A)`와 같은 원자 명제(atomic proposition)의 집합으로 표현됩니다. +- **목표 (Goal)**: `G`로 표현하며, 만족시켜야 할 사실들의 집합입니다. 특정 상태 `s`가 목표 `G`의 모든 조건을 만족하면 `s ⊨ G`라고 표기합니다. +- **행동 (Action)**: `a`로 표현하며, 다음과 같은 세 부분으로 구성됩니다. + - **전제조건 (Preconditions, `pre`)**: 행동을 수행하기 위해 반드시 참이어야 하는 사실들의 집합. + - **추가 효과 (Add Effects, `add`)**: 행동 수행 후 새롭게 참이 되는 사실들의 집합. + - **삭제 효과 (Delete Effects, `del`)**: 행동 수행 후 더 이상 참이 아니게 되는(거짓이 되는) 사실들의 집합. +- **전이 함수 (Transition Function)**: `γ(s, a)`는 상태 `s`에서 행동 `a`를 수행했을 때의 결과 상태 `s'`를 반환합니다. 행동 `a`는 `pre ⊆ s`일 때만 적용 가능하며, 결과 상태는 `s' = (s - del) ∪ add`로 계산됩니다. +- **계획 (Plan)**: `π = (a₁, a₂, ..., aₙ)`은 행동들의 순차적인 나열입니다. 초기 상태 `s₀`에서부터 계획 `π`를 순서대로 적용했을 때, 최종 상태 `sₙ`이 목표 `G`를 만족하면(`sₙ ⊨ G`) 이 계획은 유효한 것으로 간주됩니다. + +## 3. 대표적인 형식: STRIPS와 PDDL + +- **STRIPS (Stanford Research Institute Problem Solver)**: 위에서 설명한 `precondition`, `add`, `delete` 효과 모델을 정립한 고전적인 계획 문제 형식입니다. +- **PDDL (Planning Domain Definition Language)**: STRIPS를 기반으로, 실제 계획기(Planner)들이 사용할 수 있도록 문법을 표준화한 언어입니다. PDDL은 두 부분으로 나뉩니다. + - **도메인(Domain)**: 문제의 규칙을 정의합니다. 즉, 술어(predicates)와 행동(actions)의 종류를 기술합니다. + - **문제(Problem)**: 특정 시나리오를 정의합니다. 즉, 객체(objects), 초기 상태(init), 목표 상태(goal)를 기술합니다. + +### PDDL 예시: 블록 쌓기 (Blocks World) + +#### 도메인 파일 (`domain.pddl`) +```pddl +(define (domain blocks) + (:predicates (on ?x ?y) (ontable ?x) (clear ?x) (holding ?x) (handempty)) + + (:action pick-up + :parameters (?x) + :precondition (and (ontable ?x) (clear ?x) (handempty)) + :effect (and (holding ?x) (not (ontable ?x)) (not (clear ?x)) (not (handempty)))) + + (:action put-down + :parameters (?x) + :precondition (holding ?x) + :effect (and (ontable ?x) (clear ?x) (handempty) (not (holding ?x)))) + + (:action stack + :parameters (?x ?y) + :precondition (and (holding ?x) (clear ?y)) + :effect (and (on ?x ?y) (clear ?x) (handempty) (not (holding ?x)) (not (clear ?y)))) + + (:action unstack + :parameters (?x ?y) + :precondition (and (on ?x ?y) (clear ?x) (handempty)) + :effect (and (holding ?x) (clear ?y) (not (on ?x ?y)) (not (clear ?x)) (not (handempty))))) +``` + +#### 문제 파일 (`problem.pddl`) +```pddl +(define (problem bw-simple) + (:domain blocks) + (:objects A B) + (:init (ontable A) (ontable B) (clear A) (clear B) (handempty)) + (:goal (and (on A B)))) +``` + +이 문제에 대한 유효한 계획 중 하나는 `(pick-up A)`, `(stack A B)` 입니다. + +## 4. 계획 탐색 방법 + +고전 계획은 결국 거대한 상태 공간에서 초기 상태로부터 목표 상태까지의 경로를 찾는 **탐색(Search)** 문제로 귀결됩니다. + +- **상태 공간 탐색 (State-Space Search)** + - **전진 탐색 (Forward Search)**: 초기 상태에서 시작하여 가능한 행동들을 적용해가며 목표 상태에 도달하는지 탐색합니다. + - **후진 탐색 (Regression/Backward Search)**: 목표 상태에서 시작하여, 그 목표를 달성할 수 있는 행동을 역으로 적용해가며 초기 상태에 도달하는지 탐색합니다. +- **계획 공간 탐색 (Plan-Space Search)**: 상태가 아닌 부분적인 계획에서 시작하여, 계획의 결함(threats, open goals)을 해결해나가며 점진적으로 완전한 계획을 만듭니다. + +### 대표적인 알고리즘 +- **A***: 최적의 계획(가장 짧은 길이 또는 최소 비용)을 찾기 위해 휴리스틱 함수를 사용하는 탐색 알고리즘입니다. +- **Greedy Best-First Search**: 최적성을 보장하지는 않지만, 휴리스틱 값에만 의존하여 빠르게 목표에 도달하는 경로를 찾습니다. +- **Graphplan**: 계획 그래프(Planning Graph)를 생성하여 행동 간의 상호 배제 관계(mutex)를 파악하고, 이를 바탕으로 유효한 계획을 추출합니다. +- **SATPlan**: 계획 문제를 부울 만족도 문제(Boolean Satisfiability Problem, SAT)로 변환하여 강력한 SAT 솔버로 해결합니다. + +## 5. 휴리스틱 (Heuristics) + +상태 공간이 거대하기 때문에 맹목적인 탐색은 비효율적입니다. 따라서 현재 상태에서 목표까지 얼마나 남았는지를 추정하는 **휴리스틱 함수 `h(s)`**가 탐색 성능의 핵심입니다. + +- **삭제 효과 무시 (Delete Relaxation)**: 가장 유명한 휴리스틱 계산 방식으로, 모든 행동의 `delete` 효과를 무시한다고 가정합니다. 이렇게 하면 문제는 훨씬 단순해지며, 이 완화된 문제(relaxed problem)를 해결하는 데 필요한 행동의 수가 현재 상태의 휴리스틱 값이 됩니다. +- **FF 휴리스틱 (Fast Forward)**: 삭제 효과를 무시한 완화된 계획을 실제로 빠르게 찾아내고, 그 계획의 길이를 휴리스틱 값으로 사용하는 매우 강력한 휴리스틱입니다. + +## 6. 계획 검증: VAL + +계획기(Planner)가 생성한 계획이 정말로 유효한지 독립적으로 검증하는 것은 매우 중요합니다. **VAL (Validator)**은 PDDL로 기술된 도메인과 문제에 대해, 주어진 계획의 각 단계가 전제조건을 만족하는지, 상태 전이가 올바른지, 최종적으로 목표를 달성하는지를 순차적으로 검사하는 표준 도구입니다. + +## 7. 복잡도 (Complexity) + +일반적인 STRIPS 형식의 계획 문제에서 "유효한 계획이 존재하는가?"를 판정하는 것은 **PSPACE-완전(PSPACE-complete)** 문제로 알려져 있습니다. 이는 계획 문제가 매우 어려운 문제임을 시사하며, 휴리스틱의 중요성을 뒷받침합니다. + +## 8. 고전 계획의 한계와 확장 + +현실 세계의 많은 문제는 고전 계획의 가정을 위반하며, 이를 해결하기 위해 다음과 같은 분야로 확장되었습니다. + +- **시간 계획 (Temporal Planning)**: 행동에 지속 시간(duration)이 있는 경우 +- **수치 계획 (Numeric Planning)**: 연속적인 수치 변수가 포함된 경우 +- **확률적 계획 (Probabilistic Planning)**: 행동의 결과가 불확실한 경우 (MDP, POMDP) +- **다중 에이전트 계획 (Multi-Agent Planning)**: 여러 에이전트가 상호작용하는 경우 + +## 9. 학습 로드맵 + +1. **STRIPS 모델 이해**: `precondition`, `add`, `delete` 개념을 명확히 이해합니다. +2. **PDDL 작성**: 간단한 도메인과 문제를 직접 작성하고, 오픈소스 계획기를 사용해 실행해 봅니다. +3. **탐색과 휴리스틱 원리 학습**: 전진 탐색과 FF 휴리스틱이 어떻게 동작하는지 손으로 따라가 봅니다. +4. **VAL 사용**: 생성된 계획을 VAL로 검증하며 개념 이해를 확인합니다. diff --git a/research/250920_happybell80_베이즈_관련_핵심_논문_10선.md b/research/bayesian_theory/250920_happybell80_베이즈_관련_핵심_논문_10선.md similarity index 100% rename from research/250920_happybell80_베이즈_관련_핵심_논문_10선.md rename to research/bayesian_theory/250920_happybell80_베이즈_관련_핵심_논문_10선.md diff --git a/research/250920_happybell80_베이즈_학문_역사.md b/research/bayesian_theory/250920_happybell80_베이즈_학문_역사.md similarity index 100% rename from research/250920_happybell80_베이즈_학문_역사.md rename to research/bayesian_theory/250920_happybell80_베이즈_학문_역사.md diff --git a/research/250920_happybell80_베이지안_논의_종합.md b/research/bayesian_theory/250920_happybell80_베이지안_논의_종합.md similarity index 100% rename from research/250920_happybell80_베이지안_논의_종합.md rename to research/bayesian_theory/250920_happybell80_베이지안_논의_종합.md diff --git a/research/mcp_a2a/a2a_papers.md b/research/mcp_a2a/a2a_papers.md index e1f778e..cc5679a 100644 --- a/research/mcp_a2a/a2a_papers.md +++ b/research/mcp_a2a/a2a_papers.md @@ -1,32 +1,15 @@ -# A2A(Agent-to-Agent) 관련 논문 5편 요약 +# A2A(Agent-to-Agent) 관련 핵심 논문 -1) Building a Secure Agentic AI Application Leveraging A2A -- 핵심 기여: Google A2A 구성요소와 보안 우선 설계 원칙 정리 -- 로빙 적용: 워크스페이스 간 에이전트 협업 시 권한 위임·신뢰 경계·감사 로그 표준화 -- 출처: https://arxiv.org/abs/2504.16902 +이 폴더에는 A2A(Agent-to-Agent) 통신 및 협업과 관련된 핵심 논문들이 정리되어 있습니다. -2) Towards Multi-Agent Economies: A2A + Ledger IDs + x402 Micropayments -- 핵심 기여: 분산원장 신원과 HTTP 402 마이크로페이먼트로 A2A 경제 확장 -- 로빙 적용: 스킬/에이전트 마켓의 과금·정산·신뢰카드 발급 설계 근거 -- 출처: https://arxiv.org/abs/2507.19550 +## 논문 목록 -3) CAMEL: Communicative Agents for “Mind” Exploration of LLM Society -- 핵심 기여: 역할·목표 정렬된 상호작용 틀, 성능/데이터 생성 유틸리티 입증 -- 로빙 적용: 멘토/검토/실행 등 역할 프롬프트 템플릿화(감정 톤 가이드 포함) -- 출처: https://arxiv.org/abs/2303.17760 +- [[habler_et_al_2025_building_secure_agentic_ai|Building a Secure Agentic AI Application Leveraging A2A]] +- [[vaziry_et_al_2025_towards_multi_agent_economies|Towards Multi-Agent Economies: A2A + Ledger IDs + x402 Micropayments]] +- [[li_et_al_2023_camel_communicative_agents|CAMEL: Communicative Agents for “Mind” Exploration of LLM Society]] +- [[wang_et_al_2024_sotopia_pi_interactive_learning|SOTOPIA-π: Interactive Learning of Socially Intelligent Agents]] +- [[plaat_et_al_2025_agentic_llms_survey|Agentic LLMs & Multi-Agent Debate/Deliberation (Survey)]] -4) SOTOPIA-π: Interactive Learning of Socially Intelligent Agents -- 핵심 기여: 사회적 상호작용 기반 학습으로 협상·협력·규범 준수 향상 -- 로빙 적용: 멘토–멘티 코칭/합의·중재 규칙/윤리 시뮬레이션 평가보드로 활용 -- 출처: https://arxiv.org/abs/2403.08715 - -5) Agentic LLMs & Multi-Agent Debate/Deliberation (Survey) -- 핵심 기여: 협업·토론 기법과 실패 모드 종합(합의 편향·표류 등) -- 로빙 적용: 응답 전 토론/심사 루프 삽입, 실패 모드 완화를 위한 정책 사전 설계 -- 출처: https://arxiv.org/html/2503.23037v1 - -우선 과제(로빙) -- 멘토(rb8001)–멘티(rb10508_micro) AutoGen 스타일 리뷰 루프→경험치/레벨 연동 -- 응답 품질보증: 소형 디베이트 1~2턴→윤리 필터→최종 응답 파이프라인 정착 -- A2A 카드(권한/정체성) 스키마 초안과 게이트웨이 권한 위임 흐름 설계 +--- +*기존 요약 내용은 각 개별 파일로 이동되었습니다.* \ No newline at end of file diff --git a/research/mcp_a2a/ehtesham_et_al_2025_survey_agent_interoperability_protocols.md b/research/mcp_a2a/ehtesham_et_al_2025_survey_agent_interoperability_protocols.md new file mode 100644 index 0000000..538d784 --- /dev/null +++ b/research/mcp_a2a/ehtesham_et_al_2025_survey_agent_interoperability_protocols.md @@ -0,0 +1,8 @@ +# A survey of agent interoperability protocols: MCP, ACP, A2A, ANP + +- **Authors**: Abul Ehtesham, Aditi Singh, Gaurav Kumar Gupta, Saket Kumar +- **Year**: 2025 +- **Summary**: + - **핵심 기여**: 상호운용 프로토콜 비교(디스커버리/보안/상호작용), 단계적 도입 로드맵 + - **로빙 적용**: 내부 도구는 MCP, 대화식 멀티모달은 ACP, 조직 간 협업은 A2A, 오픈 네트워크는 ANP로 계층화 +- **Link**: https://arxiv.org/abs/2505.02279 diff --git a/research/mcp_a2a/habler_et_al_2025_building_secure_agentic_ai.md b/research/mcp_a2a/habler_et_al_2025_building_secure_agentic_ai.md new file mode 100644 index 0000000..64f4bdc --- /dev/null +++ b/research/mcp_a2a/habler_et_al_2025_building_secure_agentic_ai.md @@ -0,0 +1,8 @@ +# Building a Secure Agentic AI Application Leveraging A2A + +- **Authors**: Idan Habler, Ken Huang, Vineeth Sai Narajala, Prashant Kulkarni +- **Year**: 2025 +- **Summary**: + - **핵심 기여**: Google A2A 구성요소와 보안 우선 설계 원칙 정리 + - **로빙 적용**: 워크스페이스 간 에이전트 협업 시 권한 위임·신뢰 경계·감사 로그 표준화 +- **Link**: https://arxiv.org/abs/2504.16902 diff --git a/research/mcp_a2a/hasan_et_al_2025_studying_security_maintainability_mcp.md b/research/mcp_a2a/hasan_et_al_2025_studying_security_maintainability_mcp.md new file mode 100644 index 0000000..ea8a2cc --- /dev/null +++ b/research/mcp_a2a/hasan_et_al_2025_studying_security_maintainability_mcp.md @@ -0,0 +1,8 @@ +# Studying the Security and Maintainability of MCP Servers + +- **Authors**: Mohammed Mehedi Hasan, Hao Li, Emad Fallahzadeh, Gopi Krishnan Rajbahadur, Bram Adams, Ahmed E. Hassan +- **Year**: 2025 +- **Summary**: + - **핵심 기여**: 급성장 생태계의 보안·유지보수 리스크, 채택 지표 분석 + - **로빙 적용**: 스킬 수명주기 관리, 버전고정/헬스체크/취약점 관리 기준 수립 +- **Link**: https://arxiv.org/abs/2506.13538 diff --git a/research/mcp_a2a/hou_et_al_2025_mcp_landscape_security_ecosystem.md b/research/mcp_a2a/hou_et_al_2025_mcp_landscape_security_ecosystem.md new file mode 100644 index 0000000..16cc919 --- /dev/null +++ b/research/mcp_a2a/hou_et_al_2025_mcp_landscape_security_ecosystem.md @@ -0,0 +1,8 @@ +# Model Context Protocol(MCP): Landscape, Security, and Ecosystem + +- **Authors**: Xinyi Hou, Yanjie Zhao, Shenao Wang, Haoyu Wang +- **Year**: 2025 +- **Summary**: + - **핵심 기여**: MCP 배경·구성요소(툴/리소스/프로시저), 보안 위협·완화, 생태계 분석 + - **로빙 적용**: 게이트웨이–스킬 간 표준 계약 수립(HTTP만), 리소스 스트리밍으로 선택적 기억·연속성 구현, 위협모델을 운영정책으로 반영 +- **Link**: https://arxiv.org/pdf/2503.23278 diff --git a/research/mcp_a2a/li_et_al_2023_camel_communicative_agents.md b/research/mcp_a2a/li_et_al_2023_camel_communicative_agents.md new file mode 100644 index 0000000..e4f46d0 --- /dev/null +++ b/research/mcp_a2a/li_et_al_2023_camel_communicative_agents.md @@ -0,0 +1,8 @@ +# CAMEL: Communicative Agents for “Mind” Exploration of LLM Society + +- **Authors**: Guohao Li, Hasan Abed Al Kader Hammoud, Hani Itani, Dmitrii Khizbullin, Bernard Ghanem +- **Year**: 2023 +- **Summary**: + - **핵심 기여**: 역할·목표 정렬된 상호작용 틀, 성능/데이터 생성 유틸리티 입증 + - **로빙 적용**: 멘토/검토/실행 등 역할 프롬프트 템플릿화(감정 톤 가이드 포함) +- **Link**: https://arxiv.org/abs/2303.17760 diff --git a/research/mcp_a2a/mcp_2025_official_specification.md b/research/mcp_a2a/mcp_2025_official_specification.md new file mode 100644 index 0000000..4fcb2b4 --- /dev/null +++ b/research/mcp_a2a/mcp_2025_official_specification.md @@ -0,0 +1,8 @@ +# MCP 공식 스펙(최신 개정) + +- **Authors**: Model Context Protocol +- **Year**: 2025 +- **Summary**: + - **핵심 기여**: 타입·요구사항 정의, 호환성 기준선 제공 + - **로빙 적용**: 게이트웨이–스킬 계약 일관화, 호환성 테스트의 기준 문서로 사용 +- **Link**: https://modelcontextprotocol.io/specification/2025-06-18 diff --git a/research/mcp_a2a/mcp_papers.md b/research/mcp_a2a/mcp_papers.md index 14ff804..443bdbf 100644 --- a/research/mcp_a2a/mcp_papers.md +++ b/research/mcp_a2a/mcp_papers.md @@ -1,32 +1,15 @@ -# MCP(Model Context Protocol) 관련 논문 5편 요약 +# MCP(Model Context Protocol) 관련 핵심 문서 -1) Model Context Protocol(MCP): Landscape, Security, and Ecosystem -- 핵심 기여: MCP 배경·구성요소(툴/리소스/프로시저), 보안 위협·완화, 생태계 분석 -- 로빙 적용: 게이트웨이–스킬 간 표준 계약 수립(HTTP만), 리소스 스트리밍으로 선택적 기억·연속성 구현, 위협모델을 운영정책으로 반영 -- 출처: https://arxiv.org/pdf/2503.23278 +이 폴더에는 MCP(Model Context Protocol)와 관련된 핵심 논문 및 공식 스펙 문서가 정리되어 있습니다. -2) MCP Safety Audit: LLMs with the Model Context Protocol -- 핵심 기여: MCP 서버 자동 보안 점검(프롬프트 인젝션/권한 오남용) 절차 -- 로빙 적용: 신규 스킬 온보딩 전 CI 파이프라인에 보안 스캐너 삽입(윤리·권한·감사 강화) -- 출처: https://arxiv.org/abs/2504.03767 +## 문서 목록 -3) Studying the Security and Maintainability of MCP Servers -- 핵심 기여: 급성장 생태계의 보안·유지보수 리스크, 채택 지표 분석 -- 로빙 적용: 스킬 수명주기 관리, 버전고정/헬스체크/취약점 관리 기준 수립 -- 출처: https://arxiv.org/abs/2506.13538 +- [[hou_et_al_2025_mcp_landscape_security_ecosystem|Model Context Protocol(MCP): Landscape, Security, and Ecosystem]] +- [[radosevich_halloran_2025_mcp_safety_audit|MCP Safety Audit: LLMs with the Model Context Protocol]] +- [[hasan_et_al_2025_studying_security_maintainability_mcp|Studying the Security and Maintainability of MCP Servers]] +- [[ehtesham_et_al_2025_survey_agent_interoperability_protocols|A survey of agent interoperability protocols: MCP, ACP, A2A, ANP]] +- [[mcp_2025_official_specification|MCP 공식 스펙(최신 개정)]] -4) A survey of agent interoperability protocols: MCP, ACP, A2A, ANP -- 핵심 기여: 상호운용 프로토콜 비교(디스커버리/보안/상호작용), 단계적 도입 로드맵 -- 로빙 적용: 내부 도구는 MCP, 대화식 멀티모달은 ACP, 조직 간 협업은 A2A, 오픈 네트워크는 ANP로 계층화 -- 출처: https://arxiv.org/abs/2505.02279 - -5) MCP 공식 스펙(최신 개정) -- 핵심 기여: 타입·요구사항 정의, 호환성 기준선 제공 -- 로빙 적용: 게이트웨이–스킬 계약 일관화, 호환성 테스트의 기준 문서로 사용 -- 출처: https://modelcontextprotocol.io/specification/2025-06-18 - -우선 과제(로빙) -- MCP 스킬 레지스트리(이름/엔드포인트/스키마/권한) 단일화 및 게이트웨이 연동 -- CI에 “MCP 보안 스캐너” Job 추가(온보딩 전 자동 점검) -- `/healthz`·버전·권한·로그 표준 스키마 문서화 및 검증 +--- +*기존 요약 내용은 각 개별 파일로 이동되었습니다.* \ No newline at end of file diff --git a/research/mcp_a2a/plaat_et_al_2025_agentic_llms_survey.md b/research/mcp_a2a/plaat_et_al_2025_agentic_llms_survey.md new file mode 100644 index 0000000..3866c75 --- /dev/null +++ b/research/mcp_a2a/plaat_et_al_2025_agentic_llms_survey.md @@ -0,0 +1,8 @@ +# Agentic LLMs & Multi-Agent Debate/Deliberation (Survey) + +- **Authors**: Aske Plaat, Max van Duijn, Niki van Stein, Mike Preuss, Peter van der Putten, Kees Joost Batenburg +- **Year**: 2025 +- **Summary**: + - **핵심 기여**: 협업·토론 기법과 실패 모드 종합(합의 편향·표류 등) + - **로빙 적용**: 응답 전 토론/심사 루프 삽입, 실패 모드 완화를 위한 정책 사전 설계 +- **Link**: https://arxiv.org/html/2503.23037v1 diff --git a/research/mcp_a2a/radosevich_halloran_2025_mcp_safety_audit.md b/research/mcp_a2a/radosevich_halloran_2025_mcp_safety_audit.md new file mode 100644 index 0000000..8f056c3 --- /dev/null +++ b/research/mcp_a2a/radosevich_halloran_2025_mcp_safety_audit.md @@ -0,0 +1,8 @@ +# MCP Safety Audit: LLMs with the Model Context Protocol + +- **Authors**: Brandon Radosevich, John Halloran +- **Year**: 2025 +- **Summary**: + - **핵심 기여**: MCP 서버 자동 보안 점검(프롬프트 인젝션/권한 오남용) 절차 + - **로빙 적용**: 신규 스킬 온보딩 전 CI 파이프라인에 보안 스캐너 삽입(윤리·권한·감사 강화) +- **Link**: https://arxiv.org/abs/2504.03767 diff --git a/research/mcp_a2a/vaziry_et_al_2025_towards_multi_agent_economies.md b/research/mcp_a2a/vaziry_et_al_2025_towards_multi_agent_economies.md new file mode 100644 index 0000000..734516d --- /dev/null +++ b/research/mcp_a2a/vaziry_et_al_2025_towards_multi_agent_economies.md @@ -0,0 +1,8 @@ +# Towards Multi-Agent Economies: A2A + Ledger IDs + x402 Micropayments + +- **Authors**: Awid Vaziry, Sandro Rodriguez Garzon, Axel Küpper +- **Year**: 2025 +- **Summary**: + - **핵심 기여**: 분산원장 신원과 HTTP 402 마이크로페이먼트로 A2A 경제 확장 + - **로빙 적용**: 스킬/에이전트 마켓의 과금·정산·신뢰카드 발급 설계 근거 +- **Link**: https://arxiv.org/abs/2507.19550 diff --git a/research/mcp_a2a/wang_et_al_2024_sotopia_pi_interactive_learning.md b/research/mcp_a2a/wang_et_al_2024_sotopia_pi_interactive_learning.md new file mode 100644 index 0000000..93c4ad6 --- /dev/null +++ b/research/mcp_a2a/wang_et_al_2024_sotopia_pi_interactive_learning.md @@ -0,0 +1,8 @@ +# SOTOPIA-π: Interactive Learning of Socially Intelligent Agents + +- **Authors**: Ruiyi Wang, Haofei Yu, Wenxin Zhang, Zhengyang Qi, Maarten Sap, Graham Neubig, Yonatan Bisk, Hao Zhu +- **Year**: 2024 +- **Summary**: + - **핵심 기여**: 사회적 상호작용 기반 학습으로 협상·협력·규범 준수 향상 + - **로빙 적용**: 멘토–멘티 코칭/합의·중재 규칙/윤리 시뮬레이션 평가보드로 활용 +- **Link**: https://arxiv.org/abs/2403.08715 diff --git a/research/ocr/250909_ocr_core_papers.md b/research/ocr/250909_ocr_core_papers.md index 5f77d93..9678c6a 100644 --- a/research/ocr/250909_ocr_core_papers.md +++ b/research/ocr/250909_ocr_core_papers.md @@ -4,49 +4,20 @@ - 범위: 문서 OCR, 장면 텍스트 인식(STR), 텍스트 스포팅, OCR-free 문서 이해 - 목적: 로빙(RO-BEING) 프로젝트의 파일 이해/문서 처리 스킬 고도화를 위한 레퍼런스 -## 핵심 목록 (10편) +## 핵심 목록 -1) TrOCR: Transformer-based Optical Character Recognition (AAAI 2023, 원 논문 2021 공개) -- 요지: Transformer 인코더-디코더와 대규모 사전학습을 결합한 범용 OCR/STR 베이스라인. 문서·장면 모두에서 강력한 성능과 전이성 제공. -- 참고: arXiv https://arxiv.org/abs/2109.10282, AAAI https://ojs.aaai.org/index.php/AAAI/article/view/26538/26310 - -2) Donut: OCR-Free Document Understanding Transformer (ECCV 2022) -- 요지: 별도 OCR 엔진 없이 이미지에서 바로 구조화 시퀀스를 생성하는 “OCR-free” 접근. 문서 분류/파싱/IE 파이프라인 단순화에 기여. -- 참고: arXiv https://arxiv.org/abs/2111.15664, ECCV PDF https://www.ecva.net/papers/eccv_2022/papers_ECCV/papers/136880493.pdf, GitHub https://github.com/clovaai/donut - -3) PARSeq: Scene Text Recognition with Permuted Autoregressive Sequence Models (ECCV 2022) -- 요지: 순열 기반 자회귀 학습으로 강인성과 효율을 동시에 개선한 STR. 다양한 구현과 벤치마크에서 실용적 선택지로 확산. -- 참고: arXiv https://arxiv.org/abs/2207.06966, ECCV PDF https://www.ecva.net/papers/eccv_2022/papers_ECCV/papers/136880177.pdf - -4) ABINet / ABINet++ (CVPR 2021, TPAMI 2023) -- 요지: 시각 모듈과 언어 모듈을 분리·결합해 반복적 정정을 수행. 복잡한 장면 텍스트에서 높은 정확도. TPAMI 확장판(ABINet++). -- 참고: arXiv https://arxiv.org/abs/2103.06495, TPAMI https://doi.org/10.1109/TPAMI.2022.3223908 - -5) SVTR: Scene Text Recognition with a Single Visual Model (IJCAI 2022) -- 요지: 순차 디코더 없이 비전 트랜스포머만으로 STR을 수행하는 경량·고속 구조. 산업 배포 친화적. -- 참고: arXiv https://arxiv.org/abs/2205.00159, IJCAI PDF https://www.ijcai.org/proceedings/2022/0124.pdf - -6) MASTER: Multi-Aspect Non-local Network for Scene Text Recognition (Pattern Recognition 2021) -- 요지: 글로벌 컨텍스트 통합을 강화한 셀프-어텐션 기반 구조. 불규칙 텍스트에서 견고한 성능으로 여전히 널리 인용. -- 참고: arXiv https://arxiv.org/abs/1910.02562, Journal https://www.sciencedirect.com/science/article/pii/S0031320321001679 - -7) VisionLAN: From Two to One — Visual Language Modeling Network (ICCV 2021) -- 요지: 시각·언어 정보를 단일 구조로 통합해 외부 LM 의존도를 낮추면서 정확도 유지/개선. -- 참고: CVF https://openaccess.thecvf.com/content/ICCV2021/papers/Wang_From_Two_to_One_A_New_Scene_Text_Recognizer_With_ICCV_2021_paper.pdf, arXiv https://arxiv.org/abs/2108.09661 - -8) E2STR: Ego-Evolving Scene Text Recognizer with In-Context Learning (2023, 2024 업데이트) -- 요지: 인-컨텍스트 학습 개념을 STR 도메인 적응에 적용. 실제 배포 환경의 도메인 편차를 빠르게 보정. -- 참고: arXiv https://arxiv.org/abs/2311.13120 - -9) Bridging Text Spotting: Bridging the Gap Between End-to-End and Two-Step Text Spotting (CVPR 2024) -- 요지: 검출-인식 결합(텍스트 스포팅)에서 모듈성 유지와 오류 전파 억제를 함께 달성하려는 최신 접근. -- 참고: CVF https://openaccess.thecvf.com/content/CVPR2024/papers/Huang_Bridging_the_Gap_Between_End-to-End_and_Two-Step_Text_Spotting_CVPR_2024_paper.pdf - -10) 서베이 2편 (개요 파악용) -- a) A Survey of Text Detection and Recognition Algorithms (Neurocomputing 2023) - - 참고: https://doi.org/10.1016/j.neucom.2023.126702 -- b) Scene Text Detection and Recognition: A Survey (Multimedia Tools and Applications 2022) - - 참고: https://doi.org/10.1007/s11042-022-12693-7 +- [[li_et_al_2021_trocr_transformer_ocr|TrOCR: Transformer-based Optical Character Recognition]] +- [[kim_et_al_2021_donut_ocr_free_transformer|Donut: OCR-Free Document Understanding Transformer]] +- [[bautista_atienza_2022_parseq_scene_text_recognition|PARSeq: Scene Text Recognition with Permuted Autoregressive Sequence Models]] +- [[fang_et_al_2021_abinet_iterative_correction|ABINet / ABINet++]] +- [[du_et_al_2022_svtr_single_visual_model|SVTR: Scene Text Recognition with a Single Visual Model]] +- [[lu_et_al_2019_master_multi_aspect_network|MASTER: Multi-Aspect Non-local Network for Scene Text Recognition]] +- [[wang_et_al_2021_visionlan_visual_language_modeling|VisionLAN: From Two to One — Visual Language Modeling Network]] +- [[zhao_et_al_2023_e2str_ego_evolving_recognizer|E2STR: Ego-Evolving Scene Text Recognizer with In-Context Learning]] +- [[huang_et_al_2024_bridging_text_spotting|Bridging Text Spotting: Bridging the Gap Between End-to-End and Two-Step Text Spotting]] +- **서베이 논문** + - [[wang_et_al_2023_survey_text_detection_recognition|A Survey of Text Detection and Recognition Algorithms]] + - [[naiemi_et_al_2022_survey_scene_text_detection_recognition|Scene Text Detection and Recognition: A Survey]] ## 동향 요약 - 트랜스포머 기반 STR 주류화: TrOCR·SVTR·PARSeq 등으로 정확도·속도 균형 최적화. @@ -65,5 +36,4 @@ - ICDAR 대회 안내(참고): https://research.google/blog/announcing-the-icdar-2023-competition-on-hierarchical-text-detection-and-recognition/ --- -메모: 인용 수 등 수치는 시점·집계에 따라 변동 가능. 운영 반영 전 PoC로 정확도/지연/리소스 지표를 현행 데이터셋에 재검증할 것. - +메모: 인용 수 등 수치는 시점·집계에 따라 변동 가능. 운영 반영 전 PoC로 정확도/지연/리소스 지표를 현행 데이터셋에 재검증할 것. \ No newline at end of file diff --git a/research/ocr/bautista_atienza_2022_parseq_scene_text_recognition.md b/research/ocr/bautista_atienza_2022_parseq_scene_text_recognition.md new file mode 100644 index 0000000..04376af --- /dev/null +++ b/research/ocr/bautista_atienza_2022_parseq_scene_text_recognition.md @@ -0,0 +1,8 @@ +# PARSeq: Scene Text Recognition with Permuted Autoregressive Sequence Models + +- **Authors**: Darwin Bautista, Rowel Atienza +- **Year**: 2022 +- **Summary**: 순열 기반 자회귀 학습으로 강인성과 효율을 동시에 개선한 STR. 다양한 구현과 벤치마크에서 실용적 선택지로 확산. +- **Links**: + - arXiv: https://arxiv.org/abs/2207.06966 + - ECCV PDF: https://www.ecva.net/papers/eccv_2022/papers_ECCV/papers/136880177.pdf diff --git a/research/ocr/du_et_al_2022_svtr_single_visual_model.md b/research/ocr/du_et_al_2022_svtr_single_visual_model.md new file mode 100644 index 0000000..ec7bafd --- /dev/null +++ b/research/ocr/du_et_al_2022_svtr_single_visual_model.md @@ -0,0 +1,8 @@ +# SVTR: Scene Text Recognition with a Single Visual Model + +- **Authors**: Yongkun Du, Zhineng Chen, Caiyan Jia, Xiaoting Yin, Tianlun Zheng, Chenxia Li, Yuning Du, Yu-Gang Jiang +- **Year**: 2022 +- **Summary**: 순차 디코더 없이 비전 트랜스포머만으로 STR을 수행하는 경량·고속 구조. 산업 배포 친화적. +- **Links**: + - arXiv: https://arxiv.org/abs/2205.00159 + - IJCAI PDF: https://www.ijcai.org/proceedings/2022/0124.pdf diff --git a/research/ocr/fang_et_al_2021_abinet_iterative_correction.md b/research/ocr/fang_et_al_2021_abinet_iterative_correction.md new file mode 100644 index 0000000..06b833c --- /dev/null +++ b/research/ocr/fang_et_al_2021_abinet_iterative_correction.md @@ -0,0 +1,8 @@ +# ABINet / ABINet++ + +- **Authors**: Shancheng Fang, Hongtao Xie, Yuxin Wang, Zhendong Mao, Yongdong Zhang +- **Year**: 2021 +- **Summary**: 시각 모듈과 언어 모듈을 분리·결합해 반복적 정정을 수행. 복잡한 장면 텍스트에서 높은 정확도. TPAMI 확장판(ABINet++). +- **Links**: + - arXiv: https://arxiv.org/abs/2103.06495 + - TPAMI (ABINet++): https://doi.org/10.1109/TPAMI.2022.3223908 diff --git a/research/ocr/huang_et_al_2024_bridging_text_spotting.md b/research/ocr/huang_et_al_2024_bridging_text_spotting.md new file mode 100644 index 0000000..5ee4b1c --- /dev/null +++ b/research/ocr/huang_et_al_2024_bridging_text_spotting.md @@ -0,0 +1,7 @@ +# Bridging Text Spotting: Bridging the Gap Between End-to-End and Two-Step Text Spotting + +- **Authors**: Mingxin Huang, Hongliang Li, Yuliang Liu, Xiang Bai, Lianwen Jin +- **Year**: 2024 +- **Summary**: 검출-인식 결합(텍스트 스포팅)에서 모듈성 유지와 오류 전파 억제를 함께 달성하려는 최신 접근. +- **Links**: + - CVF: https://openaccess.thecvf.com/content/CVPR2024/papers/Huang_Bridging_the_Gap_Between_End-to-End_and_Two-Step_Text_Spotting_CVPR_2024_paper.pdf diff --git a/research/ocr/kim_et_al_2021_donut_ocr_free_transformer.md b/research/ocr/kim_et_al_2021_donut_ocr_free_transformer.md new file mode 100644 index 0000000..25af25e --- /dev/null +++ b/research/ocr/kim_et_al_2021_donut_ocr_free_transformer.md @@ -0,0 +1,9 @@ +# Donut: OCR-Free Document Understanding Transformer + +- **Authors**: Geewook Kim, Teakgyu Hong, Moonbin Yim, Jeongyeon Nam, Jinyoung Park, Jinyeong Yim, Wonseok Hwang, Sangdoo Yun, Dongyoon Han, Seunghyun Park +- **Year**: 2021 +- **Summary**: 별도 OCR 엔진 없이 이미지에서 바로 구조화 시퀀스를 생성하는 “OCR-free” 접근. 문서 분류/파싱/IE 파이프라인 단순화에 기여. +- **Links**: + - arXiv: https://arxiv.org/abs/2111.15664 + - ECCV PDF: https://www.ecva.net/papers/eccv_2022/papers_ECCV/papers/136880493.pdf + - GitHub: https://github.com/clovaai/donut diff --git a/research/ocr/li_et_al_2021_trocr_transformer_ocr.md b/research/ocr/li_et_al_2021_trocr_transformer_ocr.md new file mode 100644 index 0000000..1fe8393 --- /dev/null +++ b/research/ocr/li_et_al_2021_trocr_transformer_ocr.md @@ -0,0 +1,8 @@ +# TrOCR: Transformer-based Optical Character Recognition + +- **Authors**: Minghao Li, Tengchao Lv, Jingye Chen, Lei Cui, Yijuan Lu, Dinei Florencio, Cha Zhang, Zhoujun Li, Furu Wei +- **Year**: 2021 +- **Summary**: Transformer 인코더-디코더와 대규모 사전학습을 결합한 범용 OCR/STR 베이스라인. 문서·장면 모두에서 강력한 성능과 전이성 제공. +- **Links**: + - arXiv: https://arxiv.org/abs/2109.10282 + - AAAI: https://ojs.aaai.org/index.php/AAAI/article/view/26538/26310 diff --git a/research/ocr/lu_et_al_2019_master_multi_aspect_network.md b/research/ocr/lu_et_al_2019_master_multi_aspect_network.md new file mode 100644 index 0000000..2d5dabf --- /dev/null +++ b/research/ocr/lu_et_al_2019_master_multi_aspect_network.md @@ -0,0 +1,8 @@ +# MASTER: Multi-Aspect Non-local Network for Scene Text Recognition + +- **Authors**: Ning Lu, Wenwen Yu, Xianbiao Qi, Yihao Chen, Ping Gong, Rong Xiao, Xiang Bai +- **Year**: 2019 +- **Summary**: 글로벌 컨텍스트 통합을 강화한 셀프-어텐션 기반 구조. 불규칙 텍스트에서 견고한 성능으로 여전히 널리 인용. +- **Links**: + - arXiv: https://arxiv.org/abs/1910.02562 + - Journal: https://www.sciencedirect.com/science/article/pii/S0031320321001679 diff --git a/research/ocr/naiemi_et_al_2022_survey_scene_text_detection_recognition.md b/research/ocr/naiemi_et_al_2022_survey_scene_text_detection_recognition.md new file mode 100644 index 0000000..ee7af03 --- /dev/null +++ b/research/ocr/naiemi_et_al_2022_survey_scene_text_detection_recognition.md @@ -0,0 +1,7 @@ +# Scene Text Detection and Recognition: A Survey + +- **Authors**: Fatemeh Naiemi, Vahid Ghods, Hossein Khalesi +- **Year**: 2022 +- **Summary**: +- **Links**: + - Journal: https://doi.org/10.1007/s11042-022-12693-7 diff --git a/research/ocr/wang_et_al_2021_visionlan_visual_language_modeling.md b/research/ocr/wang_et_al_2021_visionlan_visual_language_modeling.md new file mode 100644 index 0000000..f61805e --- /dev/null +++ b/research/ocr/wang_et_al_2021_visionlan_visual_language_modeling.md @@ -0,0 +1,8 @@ +# VisionLAN: From Two to One — Visual Language Modeling Network + +- **Authors**: Yuxin Wang, Hongtao Xie, Shancheng Fang, Jing Wang, Shenggao Zhu, Yongdong Zhang +- **Year**: 2021 +- **Summary**: 시각·언어 정보를 단일 구조로 통합해 외부 LM 의존도를 낮추면서 정확도 유지/개선. +- **Links**: + - CVF: https://openaccess.thecvf.com/content/ICCV2021/papers/Wang_From_Two_to_One_A_New_Scene_Text_Recognizer_With_ICCV_2021_paper.pdf + - arXiv: https://arxiv.org/abs/2108.09661 diff --git a/research/ocr/wang_et_al_2023_survey_text_detection_recognition.md b/research/ocr/wang_et_al_2023_survey_text_detection_recognition.md new file mode 100644 index 0000000..a15cfcb --- /dev/null +++ b/research/ocr/wang_et_al_2023_survey_text_detection_recognition.md @@ -0,0 +1,7 @@ +# A Survey of Text Detection and Recognition Algorithms + +- **Authors**: Xiao-Feng Wang, Zhi-Huang He, Kai Wang, Yi-Fan Wang, Le Zou, Zhize Wu +- **Year**: 2023 +- **Summary**: +- **Links**: + - Journal: https://doi.org/10.1016/j.neucom.2023.126702 diff --git a/research/ocr/zhao_et_al_2023_e2str_ego_evolving_recognizer.md b/research/ocr/zhao_et_al_2023_e2str_ego_evolving_recognizer.md new file mode 100644 index 0000000..fafb3b3 --- /dev/null +++ b/research/ocr/zhao_et_al_2023_e2str_ego_evolving_recognizer.md @@ -0,0 +1,7 @@ +# E2STR: Ego-Evolving Scene Text Recognizer with In-Context Learning + +- **Authors**: Zhen Zhao, Jingqun Tang, Chunhui Lin, Binghong Wu, Can Huang, Hao Liu, Xin Tan, Zhizhong Zhang, Yuan Xie +- **Year**: 2023 +- **Summary**: 인-컨텍스트 학습 개념을 STR 도메인 적응에 적용. 실제 배포 환경의 도메인 편차를 빠르게 보정. +- **Links**: + - arXiv: https://arxiv.org/abs/2311.13120 diff --git a/research/ontology/250910_happybell80_온톨로지논문정리.md b/research/ontology/250910_happybell80_온톨로지논문정리.md index 57e9caa..f23a646 100644 --- a/research/ontology/250910_happybell80_온톨로지논문정리.md +++ b/research/ontology/250910_happybell80_온톨로지논문정리.md @@ -4,57 +4,19 @@ ## A. 최신 동향 논문 5편 -### 1. Lippolis et al., 2025, "Ontology Generation using Large Language Models" -- **핵심**: 사용자 스토리와 Competency Question을 입력으로 LLM이 OWL 초안을 생성하는 두 가지 프롬프트 기법(CQbyCQ, Ontogenia)을 제안하고 비교 평가 -- **로빙 적용**: 스킬·아이템·워크플로 정의를 "요구사항→CQ→OWL 초안"으로 자동화하고, 사람이 리뷰하는 Human-in-the-loop 파이프라인의 기준선 제공 -- **출처**: https://arxiv.org/abs/2503.05388 - -### 2. Shimizu & Hitzler, 2024, "Accelerating Knowledge Graph and Ontology Engineering with LLMs" -- **핵심**: 온톨로지 모델링·정합·정렬·개체소거·KG 보강 등 엔지니어링 과업 전반에서 LLM 활용 모듈화 주장 -- **로빙 적용**: "모듈형 온톨로지" 원칙을 채택해 코어 스키마(에이전트·스킬·아이템·기억·윤리)와 도메인 확장 스키마를 분리하고, LLM 보조 도구를 태스크별로 끼워 넣는 구조 -- **출처**: https://arxiv.org/abs/2411.09601, https://kastle-lab.github.io/assets/publications/2024-LLMs4KGOE.pdf - -### 3. Kommineni et al., 2024, "From human experts to machines: an LLM-supported approach to ontology and KG construction" -- **핵심**: LLM이 KG/온톨로지 구성 시 인력 투입을 줄일 수 있으나 검증과 평가는 Human-in-the-loop가 필요하다는 실증적 결론 -- **로빙 적용**: 자동 생성 이후 SHACL·테스트셋·운영 로그를 통한 품질 점검 단계 의무화 -- **출처**: https://arxiv.org/pdf/2403.08345 - -### 4. Li et al., 2024, IJCAI, "A Survey of Graph Meets Large Language Model" -- **핵심**: 그래프와 LLM 결합을 역할별(예측기, 인코더, 얼라이너)로 분류해 체계화 -- **로빙 적용**: 로빙의 장기기억(KG)과 LLM의 대화·추론을 분리하되, 질의 시 그래프-어웨어 프롬프트나 그래프-RAG를 넣어 정확도와 일관성 향상 -- **출처**: https://www.ijcai.org/proceedings/2024/0898.pdf - -### 5. Ibrahim et al., 2024, "A survey on augmenting knowledge graphs with LLMs" -- **핵심**: KG-augmented LLM, LLM-augmented KG, 시너지형 세 패러다임을 정의하고 실제 적용의 장단 정리 -- **로빙 적용**: 운영 단계에서는 "시너지형"을 목표로 하되, 초기에는 LLM-augmented KG(예: 이벤트 로그로부터 관계 추출)부터 단계적 도입 -- **출처**: https://link.springer.com/article/10.1007/s44163-024-00175-8 +- [[lippolis_et_al_2025_ontology_generation_using_llms|Lippolis et al., 2025, "Ontology Generation using Large Language Models"]] +- [[shimizu_hitzler_2024_accelerating_kg_ontology_engineering|Shimizu & Hitzler, 2024, "Accelerating Knowledge Graph and Ontology Engineering with LLMs"]] +- [[kommineni_et_al_2024_llm_supported_ontology_construction|Kommineni et al., 2024, "From human experts to machines: an LLM-supported approach to ontology and KG construction"]] +- [[li_et_al_2024_survey_graph_meets_llm|Li et al., 2024, IJCAI, "A Survey of Graph Meets Large Language Model"]] +- [[mishra_et_al_2024_survey_augmenting_kg_with_llms|Ibrahim et al., 2024, "A survey on augmenting knowledge graphs with LLMs"]] ## B. 고인용(기초·표준) 논문 5편 -### 6. Gruber, 1993, "A translation approach to portable ontology specifications" -- **핵심**: "공유된 개념화의 명시적이고 형식적인 명세"라는 온톨로지 정의와 이식 가능한 명세 원리 정립 -- **로빙 적용**: 모든 스킬·아이템·행동 로그의 개념을 "공유 가능하고 교환 가능한 명세"로 관리해, 스킬 마켓플레이스 간 상호운용성 향상 -- **출처**: https://www.sciencedirect.com/science/article/pii/S1042814383710083, https://tomgruber.org/writing/ontolingua-kaj-1993.pdf - -### 7. Guarino, 1998, "What is an Ontology?" (FOIS'98) -- **핵심**: 존재론 계층과 메타수준 구분의 중요성을 제시해, 도메인 온톨로지와 상위(기초) 온톨로지의 역할 명확화 -- **로빙 적용**: 코어는 상위 개념(에이전트·행위·상태·정책)로 안정화하고, 도메인별 확장을 플러그인처럼 끼워 넣는 2층 구조 -- **출처**: https://iaoa.org/isc2012/docs/Guarino2009_What_is_an_Ontology.pdf - -### 8. Ashburner et al., 2000, "The Gene Ontology: tool for the unification of biology" -- **핵심**: 대규모 협업 온톨로지의 성공 모델과 품질·버전·거버넌스 교훈 제공 -- **로빙 적용**: 조직 내 다수 팀이 공유하는 "업무 행위·결과·문맥" 온톨로지를 운영할 때, GO 수준의 버전 관리·기여 가이드·리뷰 체계 참조 -- **출처**: https://www.nature.com/articles/ng0500_25, https://pubmed.ncbi.nlm.nih.gov/10802651/ - -### 9. Auer et al., 2007/2009, "DBpedia: A Nucleus for a Web of Open Data" -- **핵심**: 위키피디아를 구조화해 광범위한 개체·관계를 제공하는 대표적 공개 KB 제시 -- **로빙 적용**: 외부 세계 지식을 저비용으로 연결하는 출발점으로 삼아, 로빙의 개체정규화(entity linking)와 외부 참조 안정화 -- **출처**: https://pubs.dbs.uni-leipzig.de/mashup/files/10.1.1.69.5249.pdf - -### 10. Suchanek et al., 2007, "YAGO: A Core of Semantic Knowledge" -- **핵심**: 자동 추출 기반이면서도 높은 정밀도를 유지하는 대규모 온톨로지 구축 기법 제시 -- **로빙 적용**: 뉴스·메일·회의록에서 자동 추출한 사실을 온톨로지에 편입할 때, YAGO가 쓴 품질관리 아이디어(규칙·휴리스틱·검증) 차용 -- **출처**: https://dl.acm.org/doi/10.1145/1242572.1242667 +- [[gruber_1993_portable_ontology_specifications|Gruber, 1993, "A translation approach to portable ontology specifications"]] +- [[guarino_1998_what_is_an_ontology|Guarino, 1998, "What is an Ontology?"]] +- [[ashburner_et_al_2000_the_gene_ontology|Ashburner et al., 2000, "The Gene Ontology: tool for the unification of biology"]] +- [[auer_et_al_2007_dbpedia_nucleus_web_open_data|Auer et al., 2007/2009, "DBpedia: A Nucleus for a Web of Open Data"]] +- [[suchanek_et_al_2007_yago_core_semantic_knowledge|Suchanek et al., 2007, "YAGO: A Core of Semantic Knowledge"]] ## C. 로빙에 바로 적용할 설계 권고 diff --git a/research/ontology/ashburner_et_al_2000_the_gene_ontology.md b/research/ontology/ashburner_et_al_2000_the_gene_ontology.md new file mode 100644 index 0000000..314655f --- /dev/null +++ b/research/ontology/ashburner_et_al_2000_the_gene_ontology.md @@ -0,0 +1,10 @@ +# The Gene Ontology: tool for the unification of biology + +- **Authors**: M. Ashburner, C. A. Ball, J. A. Blake, D. Botstein, H. Butler, M. A. Cherry, A. P. Davis, K. Dolinski, S. S. Dwight, J. T. Eppig, M. A. Harris, D. P. Hill, L. Issel-Tarver, A. Kasarskis, S. Lewis, J. C. Matese, J. E. Richardson, M. Ringwald, G. M. Rubin, and G. Sherlock +- **Year**: 2000 +- **Summary**: + - **핵심**: 대규모 협업 온톨로지의 성공 모델과 품질·버전·거버넌스 교훈 제공 + - **로빙 적용**: 조직 내 다수 팀이 공유하는 "업무 행위·결과·문맥" 온톨로지를 운영할 때, GO 수준의 버전 관리·기여 가이드·리뷰 체계 참조 +- **Links**: + - Nature: https://www.nature.com/articles/ng0500_25 + - PubMed: https://pubmed.ncbi.nlm.nih.gov/10802651/ diff --git a/research/ontology/auer_et_al_2007_dbpedia_nucleus_web_open_data.md b/research/ontology/auer_et_al_2007_dbpedia_nucleus_web_open_data.md new file mode 100644 index 0000000..8a10421 --- /dev/null +++ b/research/ontology/auer_et_al_2007_dbpedia_nucleus_web_open_data.md @@ -0,0 +1,9 @@ +# DBpedia: A Nucleus for a Web of Open Data + +- **Authors**: Sören Auer, Christian Bizer, Georgi Kobilarov, Jens Lehmann, Richard Cyganiak, and Zachary Ives +- **Year**: 2007 +- **Summary**: + - **핵심**: 위키피디아를 구조화해 광범위한 개체·관계를 제공하는 대표적 공개 KB 제시 + - **로빙 적용**: 외부 세계 지식을 저비용으로 연결하는 출발점으로 삼아, 로빙의 개체정규화(entity linking)와 외부 참조 안정화 +- **Links**: + - PDF: https://pubs.dbs.uni-leipzig.de/mashup/files/10.1.1.69.5249.pdf diff --git a/research/ontology/gruber_1993_portable_ontology_specifications.md b/research/ontology/gruber_1993_portable_ontology_specifications.md new file mode 100644 index 0000000..a961e96 --- /dev/null +++ b/research/ontology/gruber_1993_portable_ontology_specifications.md @@ -0,0 +1,10 @@ +# A translation approach to portable ontology specifications + +- **Authors**: Thomas R. Gruber +- **Year**: 1993 +- **Summary**: + - **핵심**: "공유된 개념화의 명시적이고 형식적인 명세"라는 온톨로지 정의와 이식 가능한 명세 원리 정립 + - **로빙 적용**: 모든 스킬·아이템·행동 로그의 개념을 "공유 가능하고 교환 가능한 명세"로 관리해, 스킬 마켓플레이스 간 상호운용성 향상 +- **Links**: + - ScienceDirect: https://www.sciencedirect.com/science/article/pii/S1042814383710083 + - PDF: https://tomgruber.org/writing/ontolingua-kaj-1993.pdf diff --git a/research/ontology/guarino_1998_what_is_an_ontology.md b/research/ontology/guarino_1998_what_is_an_ontology.md new file mode 100644 index 0000000..f406714 --- /dev/null +++ b/research/ontology/guarino_1998_what_is_an_ontology.md @@ -0,0 +1,9 @@ +# What is an Ontology? + +- **Authors**: Nicola Guarino, Daniel Oberle, and Steffen Staab +- **Year**: 1998 +- **Summary**: + - **핵심**: 존재론 계층과 메타수준 구분의 중요성을 제시해, 도메인 온톨로지와 상위(기초) 온톨로지의 역할 명확화 + - **로빙 적용**: 코어는 상위 개념(에이전트·행위·상태·정책)로 안정화하고, 도메인별 확장을 플러그인처럼 끼워 넣는 2층 구조 +- **Links**: + - PDF: https://iaoa.org/isc2012/docs/Guarino2009_What_is_an_Ontology.pdf diff --git a/research/ontology/kommineni_et_al_2024_llm_supported_ontology_construction.md b/research/ontology/kommineni_et_al_2024_llm_supported_ontology_construction.md new file mode 100644 index 0000000..6b5f271 --- /dev/null +++ b/research/ontology/kommineni_et_al_2024_llm_supported_ontology_construction.md @@ -0,0 +1,9 @@ +# From human experts to machines: an LLM-supported approach to ontology and KG construction + +- **Authors**: Vamsi Krishna Kommineni, Birgitta König-Ries, and Sheeba Samuel +- **Year**: 2024 +- **Summary**: + - **핵심**: LLM이 KG/온톨로지 구성 시 인력 투입을 줄일 수 있으나 검증과 평가는 Human-in-the-loop가 필요하다는 실증적 결론 + - **로빙 적용**: 자동 생성 이후 SHACL·테스트셋·운영 로그를 통한 품질 점검 단계 의무화 +- **Links**: + - arXiv PDF: https://arxiv.org/pdf/2403.08345 diff --git a/research/ontology/li_et_al_2024_survey_graph_meets_llm.md b/research/ontology/li_et_al_2024_survey_graph_meets_llm.md new file mode 100644 index 0000000..905fb12 --- /dev/null +++ b/research/ontology/li_et_al_2024_survey_graph_meets_llm.md @@ -0,0 +1,9 @@ +# A Survey of Graph Meets Large Language Model + +- **Authors**: Yuhan Li, Zhixun Li, Peisong Wang, Jia Li, Xiangguo Sun, Hong Cheng and Jeffrey Xu Yu +- **Year**: 2024 +- **Summary**: + - **핵심**: 그래프와 LLM 결합을 역할별(예측기, 인코더, 얼라이너)로 분류해 체계화 + - **로빙 적용**: 로빙의 장기기억(KG)과 LLM의 대화·추론을 분리하되, 질의 시 그래프-어웨어 프롬프트나 그래프-RAG를 넣어 정확도와 일관성 향상 +- **Links**: + - IJCAI PDF: https://www.ijcai.org/proceedings/2024/0898.pdf diff --git a/research/ontology/lippolis_et_al_2025_ontology_generation_using_llms.md b/research/ontology/lippolis_et_al_2025_ontology_generation_using_llms.md new file mode 100644 index 0000000..ea3a626 --- /dev/null +++ b/research/ontology/lippolis_et_al_2025_ontology_generation_using_llms.md @@ -0,0 +1,9 @@ +# Ontology Generation using Large Language Models + +- **Authors**: Anna Sofia Lippolis, Mohammad Javad Saeedizade, Robin Keskisärkkä, Sara Zuppiroli, Miguel Ceriani, Aldo Gangemi, Eva Blomqvist, Andrea Giovanni Nuzzolese +- **Year**: 2025 +- **Summary**: + - **핵심**: 사용자 스토리와 Competency Question을 입력으로 LLM이 OWL 초안을 생성하는 두 가지 프롬프트 기법(CQbyCQ, Ontogenia)을 제안하고 비교 평가 + - **로빙 적용**: 스킬·아이템·워크플로 정의를 "요구사항→CQ→OWL 초안"으로 자동화하고, 사람이 리뷰하는 Human-in-the-loop 파이프라인의 기준선 제공 +- **Links**: + - arXiv: https://arxiv.org/abs/2503.05388 diff --git a/research/ontology/mishra_et_al_2024_survey_augmenting_kg_with_llms.md b/research/ontology/mishra_et_al_2024_survey_augmenting_kg_with_llms.md new file mode 100644 index 0000000..c3822b3 --- /dev/null +++ b/research/ontology/mishra_et_al_2024_survey_augmenting_kg_with_llms.md @@ -0,0 +1,9 @@ +# A survey on augmenting knowledge graphs with LLMs + +- **Authors**: A. Mishra, S. K. Sahoo, and S. K. Rath +- **Year**: 2024 +- **Summary**: + - **핵심**: KG-augmented LLM, LLM-augmented KG, 시너지형 세 패러다임을 정의하고 실제 적용의 장단 정리 + - **로빙 적용**: 운영 단계에서는 "시너지형"을 목표로 하되, 초기에는 LLM-augmented KG(예: 이벤트 로그로부터 관계 추출)부터 단계적 도입 +- **Links**: + - Springer: https://link.springer.com/article/10.1007/s44163-024-00175-8 diff --git a/research/ontology/shimizu_hitzler_2024_accelerating_kg_ontology_engineering.md b/research/ontology/shimizu_hitzler_2024_accelerating_kg_ontology_engineering.md new file mode 100644 index 0000000..a74334c --- /dev/null +++ b/research/ontology/shimizu_hitzler_2024_accelerating_kg_ontology_engineering.md @@ -0,0 +1,10 @@ +# Accelerating Knowledge Graph and Ontology Engineering with LLMs + +- **Authors**: Cogan Shimizu, Pascal Hitzler +- **Year**: 2024 +- **Summary**: + - **핵심**: 온톨로지 모델링·정합·정렬·개체소거·KG 보강 등 엔지니어링 과업 전반에서 LLM 활용 모듈화 주장 + - **로빙 적용**: "모듈형 온톨로지" 원칙을 채택해 코어 스키마(에이전트·스킬·아이템·기억·윤리)와 도메인 확장 스키마를 분리하고, LLM 보조 도구를 태스크별로 끼워 넣는 구조 +- **Links**: + - arXiv: https://arxiv.org/abs/2411.09601 + - PDF: https://kastle-lab.github.io/assets/publications/2024-LLMs4KGOE.pdf diff --git a/research/ontology/suchanek_et_al_2007_yago_core_semantic_knowledge.md b/research/ontology/suchanek_et_al_2007_yago_core_semantic_knowledge.md new file mode 100644 index 0000000..16fb972 --- /dev/null +++ b/research/ontology/suchanek_et_al_2007_yago_core_semantic_knowledge.md @@ -0,0 +1,9 @@ +# YAGO: A Core of Semantic Knowledge + +- **Authors**: Fabian M. Suchanek, Gjergji Kasneci, and Gerhard Weikum +- **Year**: 2007 +- **Summary**: + - **핵심**: 자동 추출 기반이면서도 높은 정밀도를 유지하는 대규모 온톨로지 구축 기법 제시 + - **로빙 적용**: 뉴스·메일·회의록에서 자동 추출한 사실을 온톨로지에 편입할 때, YAGO가 쓴 품질관리 아이디어(규칙·휴리스틱·검증) 차용 +- **Links**: + - ACM: https://dl.acm.org/doi/10.1145/1242572.1242667 diff --git a/research/orchestration_tools/250925_langgraph_vs_n8n_comparison.md b/research/orchestration_tools/250925_langgraph_vs_n8n_comparison.md new file mode 100644 index 0000000..ea758d1 --- /dev/null +++ b/research/orchestration_tools/250925_langgraph_vs_n8n_comparison.md @@ -0,0 +1,109 @@ +--- +tags: + - LangGraph + - n8n + - WorkflowAutomation + - AgentOrchestration + - LLM +date: 2025-09-25 +modification_date: 2025-09-25 +--- +# LLM 에이전트와 워크플로우 오케스트레이션 도구 비교: LangGraph vs n8n + +## 1. 개요 + +최근 LLM을 활용한 애플리케이션이 복잡해지면서, 여러 도구와 AI 에이전트의 실행 흐름을 관리하는 '오케스트레이션(Orchestration)'이 중요해졌습니다. 이 분야의 도구는 크게 두 가지로 나눌 수 있습니다. + +1. **범용 워크플로우 자동화**: n8n, Zapier처럼 다양한 SaaS와 API를 연결해 '업무 자동화'에 초점을 맞춘 도구. +2. **LLM/에이전트 오케스트레이션**: LangGraph, AutoGen처럼 LLM의 추론, 도구 사용, 에이전트 간의 협업 등 '지능형 워크플로우'를 코드로 구현하는 데 초점을 맞춘 프레임워크. + +이 문서는 두 카테고리의 대표주자인 LangGraph와 n8n을 중심으로 각 도구의 특징과 장단점을 심층 비교합니다. + +## 2. 주요 관련 도구 목록 (Python, 코드 중심) + +### LLM / 멀티 에이전트 / 체인 프레임워크 (LangGraph 계열) + +| 프레임워크 / 라이브러리 | 특징 / 강점 | 적합한 용도 / 장점 | +| :--- | :--- | :--- | +| **LangGraph** | 그래프 기반 워크플로우, 상태 관리, 중단/재개 | 멀티에이전트, 장기 실행, 복잡한 분기 제어 | +| **AutoGen (Microsoft)** | 다중 에이전트 협업 프레임워크, 에이전트 간 상호작용 정의 | 복수 에이전트 간 상호작용, 연구/프로토타입 | +| **CrewAI** | 역할 기반(Role-based) 에이전트 협력 구조 | 계층적, 조직적 워크플로우 구성 | +| **Semantic Kernel (MS)** | 플러그인 아키텍처, Planner와 Memory 기능 내장 | .NET/Python 혼합 환경, 기존 앱에 LLM 기능 통합 | +| **LlamaIndex** | RAG 특화, 최근 Workflow 모듈로 LangGraph 유사 기능 제공 | 데이터/문서 중심 LLM 시스템 구축 | +| **Prefect** | 데이터 엔지니어링/AI 워크플로우 자동화, Airflow 대체 | LLM 파이프라인 스케줄링, 모니터링 | + +### 범용 자동화 / 워크플로우 도구 (n8n 계열) + +| 도구 | 특징 / 장점 | 단점 / 고려사항 | +| :--- | :--- | :--- | +| **Node-RED** | 흐름 기반 시각 편집기, IoT/이벤트 중심 | SaaS 앱 통합은 플러그인 필요 | +| **Huginn** | 오픈소스 에이전트 기반 자동화 (웹 감시, 알림) | UI/사용성은 다소 투박할 수 있음 | +| **Apache Airflow** | 복잡한 DAG 기반 워크플로우, 스케줄링 중심 | 실시간 반응형 자동화보다는 배치(batch) 중심 | +| **Activepieces** | n8n 대체용 오픈소스 자동화 도구 | 생태계가 아직 성장 중 | + +## 3. LangGraph 심층 분석 + +LangGraph는 단순한 LLM 체인을 넘어, 복잡하고 장기 실행이 필요한 AI 에이전트 시스템을 구축하기 위한 프레임워크입니다. + +### 3.1. 핵심 가치: 복잡도 관리 + +간단한 `if/else` 분기라면 순수 Python 함수가 더 짧고 직관적입니다. 하지만 운영 환경에서는 다음과 같은 요구사항으로 복잡도가 폭발하며, 이때 LangGraph의 가치가 드러납니다. + +- **장기 실행**: API 응답 대기, 사람의 승인 등 몇 분에서 몇 시간까지 걸리는 작업을 관리해야 할 때 +- **실패 복구**: 여러 단계 중 특정 단계만 실패했을 때, 전체를 다시 시작하는 대신 실패한 부분만 재실행해야 할 때 +- **병렬 처리**: 여러 작업을 동시에 실행하고 그 결과를 합쳐야 할 때 +- **멀티에이전트 협업**: 여러 AI 에이전트가 각자의 역할을 수행하며 메시지를 주고받아야 할 때 +- **관찰 가능성**: 운영 중 문제 발생 시, 어느 단계에서 어떤 데이터로 실패했는지 추적해야 할 때 + +### 3.2. 핵심 기능: 체크포인트를 이용한 중단 및 재개 + +LangGraph가 복잡도를 관리하는 핵심 무기는 **체크포인트(Checkpoint)**입니다. + +- **체크포인트란?**: 그래프 실행 도중의 **상태(State)**를 저장해두는 "중간 저장 지점"입니다. (실행 순서, 노드별 입출력 데이터, 메타데이터 등) +- **저장소**: `MemorySaver`(테스트용), `SqliteSaver`(로컬/단일서버용), `PostgresSaver`(운영/분산환경용) 등 다양한 저장소를 지원하며, LangGraph가 테이블 스키마 등을 **자동으로 관리**해줍니다. +- **재개 방법**: 서버가 다운되거나 작업이 실패해도 체크포인트는 DB에 남아있습니다. 개발자가 **동일한 `thread_id`로 다시 실행을 요청(`invoke`)**하면, LangGraph가 저장된 상태를 불러와 **중단된 지점부터 자동으로 이어 실행**합니다. +- **자동 재개**: LangGraph 자체가 죽은 실행을 자동으로 재개하지는 않습니다. 하지만 외부 스케줄러(Cron, Airflow 등)와 연동하여, DB에 저장된 체크포인트 상태를 감시하고 미완료된 작업을 재호출하는 방식으로 '자동 재개' 시스템을 구축할 수 있습니다. + +## 4. n8n 심층 분석 + +n8n은 개발자가 아니더라도 다양한 웹 서비스와 API를 연결하여 업무를 자동화할 수 있게 해주는 도구입니다. + +### 4.1. 목적과 실행 환경 + +- **핵심 목적**: SaaS(구글 시트, 슬랙 등)와 API를 시각적인 UI에서 노드 기반으로 연결하여 반복적인 업무를 자동화하는 것입니다. +- **실행 환경**: + - **n8n Cloud**: n8n 회사가 직접 운영하는 SaaS 버전. 사용자는 인프라 걱정 없이 웹 UI에서 바로 사용 가능합니다. + - **Self-hosted**: Docker 등을 이용해 개인 PC, 클라우드 VM, 사내 서버 등 원하는 하드웨어에 직접 설치하여 사용합니다. + +### 4.2. 로컬 파일 접근성 + +실행 환경에 따라 로컬 파일 접근 여부가 결정됩니다. + +- **n8n Cloud**: n8n 서버에서 실행되므로, 사용자의 PC에 있는 로컬 파일에는 **직접 접근할 수 없습니다.** (구글 드라이브 등 클라우드 스토리지를 경유해야 함) +- **Self-hosted**: n8n을 내 PC에 설치한 경우, Docker 볼륨 마운트 등을 통해 **로컬 폴더에 접근하여 파일을 읽고 쓰는 워크플로우를 만들 수 있습니다.** + +## 5. LangGraph vs. n8n 핵심 비교 + +| 구분 | LangGraph | n8n | +| :--- | :--- | :--- | +| **핵심 목적** | LLM 중심 지능형 에이전트 오케스트레이션 | 범용 SaaS/API 기반 업무 자동화 | +| **개발 방식** | **코드 중심** (Python) | **UI 중심** (No-code/Low-code) | +| **주요 기능** | 상태 관리, 중단/재개, 병렬/분기, 멀티에이전트 | 이벤트 트리거, API 연결, 데이터 변환 | +| **실행 모델** | 그래프 기반 (상태 머신) | 이벤트 기반 (트리거 → 액션) | +| **실행 환경** | Python이 실행되는 모든 환경 (라이브러리) | n8n Cloud(SaaS) 또는 자체 서버(Self-hosted) | +| **적합한 사용자** | **개발자** | **비개발자, 마케터, 기획자, 개발자** | + +## 6. 결론: 언제 무엇을 써야 하는가? + +- **n8n을 선택해야 할 때**: + - 반복적인 백오피스 업무, 알림, 리포팅, 데이터 동기화가 필요할 때 + - 개발자가 아니거나, 코딩 없이 빠르게 자동화 워크플로우를 구축하고 싶을 때 + - 여러 SaaS와 API를 연결하는 것이 주된 목적일 때 + +- **LangGraph를 선택해야 할 때**: + - 복잡한 AI 에이전트 시스템을 **운영 환경**에 배포해야 할 때 + - **장기 실행, 실패 시 재개, 멀티에이전트 협업** 등 높은 수준의 제어가 필요할 때 + - RAG, Function Calling 등 LLM 기반 워크플로우를 코드로 세밀하게 구현하고 싶을 때 + - **"부분 실패 후 이어서 재개"**가 필수적인 시나리오 (ex: 고객지원, 주문처리) + +결론적으로, 두 도구는 경쟁 관계라기보다 서로 다른 문제 영역을 해결하는 상호 보완적인 관계에 가깝습니다. diff --git a/research/250912_happybell80_ACP_ANP_프로토콜_리서치.md b/research/protocols/250912_happybell80_ACP_ANP_프로토콜_리서치.md similarity index 100% rename from research/250912_happybell80_ACP_ANP_프로토콜_리서치.md rename to research/protocols/250912_happybell80_ACP_ANP_프로토콜_리서치.md diff --git a/troubleshooting/250819_happybell80_GmailItem구현및GitActions설정.md b/troubleshooting/250819_happybell80_GmailItem구현및GitActions설정.md index c460574..d8e0442 100644 --- a/troubleshooting/250819_happybell80_GmailItem구현및GitActions설정.md +++ b/troubleshooting/250819_happybell80_GmailItem구현및GitActions설정.md @@ -20,7 +20,7 @@ ``` 프론트 → Gateway(8100) → robeing-monitor(9024) ↓ - PostgreSQL(gmail_tokens) + PostgreSQL(gmail_token) ``` ## 오전 8시 00분 @@ -31,7 +31,7 @@ ```sql -- 생성된 테이블들 - robeing_stats (레벨 관리) -- gmail_tokens (is_equipped, equipped_to 컬럼 추가) +- gmail_token (is_equipped, equipped_to 컬럼 추가) - gmail_audit_logs (감사 로그) ``` @@ -273,4 +273,4 @@ npm run build - `/plans/250819_gmail_item_implementation_plan.md` - `/plans/250819_gmail_item_detailed_tasks.md` - `/troubleshooting/250722_happybell80_skill-email_Actions설정실패.md` -- `/troubleshooting/250714_gitea_actions_setup.md` \ No newline at end of file +- `/troubleshooting/250714_gitea_actions_setup.md` diff --git a/troubleshooting/250820_happybell80_Gmail아이템UI고급화및상태영구저장.md b/troubleshooting/250820_happybell80_Gmail아이템UI고급화및상태영구저장.md index 0bb7616..e5a4b20 100644 --- a/troubleshooting/250820_happybell80_Gmail아이템UI고급화및상태영구저장.md +++ b/troubleshooting/250820_happybell80_Gmail아이템UI고급화및상태영구저장.md @@ -92,7 +92,7 @@ ``` 2. **DB 구조는 준비됨** - - gmail_tokens 테이블: is_equipped, equipped_to 컬럼 존재 + - gmail_token 테이블: is_equipped, equipped_to 컬럼 존재 - robeing-monitor 서비스: API 구현 완료 (포트 9024) #### 해결 방법 @@ -196,4 +196,4 @@ --- -**문서 끝** \ No newline at end of file +**문서 끝** diff --git a/troubleshooting/250824_rb8001_daily_summary_cron_failure.md b/troubleshooting/250824_rb8001_daily_summary_cron_failure.md index fc336a7..b4a8f47 100644 --- a/troubleshooting/250824_rb8001_daily_summary_cron_failure.md +++ b/troubleshooting/250824_rb8001_daily_summary_cron_failure.md @@ -216,7 +216,7 @@ docker exec robeing-gateway tail -f /var/log/cron.log - **skill-news**: 정상 작동 ✅ - **skill-email**: DB 연결 성공, 토큰 데이터 없음 ⚠️ - **auth_db → main_db 마이그레이션**: 완료 ✅ -- **main_db gmail_tokens**: 테이블 존재, 토큰 데이터 NULL ❌ +- **main_db gmail_token**: 테이블 존재, 토큰 데이터 NULL ❌ ### 해결된 사항 (2025-08-25 00:12) - **skill-email DB 연결 문제**: ✅ 해결 @@ -246,7 +246,7 @@ curl -X POST "http://localhost:9000/api/gmail/refresh/1e16e9d5-59f3-54da-a661-8a # 응답: 200 OK, "status": "refreshed" # 그러나 DB 확인 시 여전히 만료 상태 -SELECT username, expiry FROM gmail_tokens WHERE username='happybell80'; +SELECT username, expiry FROM gmail_token WHERE username='happybell80'; # expiry: 2025-08-24 16:30:10 (어제 시간으로 기록됨) ``` @@ -260,7 +260,7 @@ SELECT username, access_token IS NOT NULL as has_access, refresh_token IS NOT NULL as has_refresh, expiry -FROM gmail_tokens; +FROM gmail_token; ``` **결과**: @@ -276,7 +276,7 @@ FROM gmail_tokens; SELECT username, CASE WHEN expiry < NOW() THEN '만료됨' ELSE '유효함' END as status, AGE(NOW(), expiry) as expired_since -FROM gmail_tokens; +FROM gmail_token; ``` **결과**: @@ -398,7 +398,7 @@ SELECT username, expiry AT TIME ZONE 'UTC' as expiry_utc, CASE WHEN expiry AT TIME ZONE 'UTC' > NOW() AT TIME ZONE 'UTC' THEN '유효✅' ELSE '만료❌' END as status -FROM gmail_tokens; +FROM gmail_token; ``` **결과**: @@ -503,7 +503,7 @@ def get_gmail_service(user_id): ### 16.5 임시 해결책 (서버 관리자) ```bash # 크론잡 추가 - 매 30분마다 모든 토큰 갱신 -*/30 * * * * for user_id in $(psql -t -c "SELECT user_id FROM gmail_tokens"); do \ +*/30 * * * * for user_id in $(psql -t -c "SELECT user_id FROM gmail_token"); do \ curl -X POST "http://localhost:9000/api/gmail/refresh/$user_id"; \ done ``` @@ -515,4 +515,4 @@ done --- -**문서 끝** \ No newline at end of file +**문서 끝** diff --git a/troubleshooting/250826_slack_id_column_standardization.md b/troubleshooting/250826_slack_id_column_standardization.md index 95f7a28..8cb9215 100644 --- a/troubleshooting/250826_slack_id_column_standardization.md +++ b/troubleshooting/250826_slack_id_column_standardization.md @@ -14,20 +14,20 @@ | 테이블 | 이전 컬럼명 | 현재 컬럼명 | 타입 | |--------|------------|------------|------| | slack_user_mapping | slack_user_id | slack_user_id | VARCHAR(100) | -| gmail_tokens | ~~slack_id~~ ❌ | **slack_user_id** ✅ | VARCHAR(100) | +| gmail_token | ~~slack_id~~ ❌ | **slack_user_id** ✅ | VARCHAR(100) | | conversation_logs | slack_user_id | slack_user_id | VARCHAR(100) | ### ✅ 적용 완료 #### ✅ DB 스키마 변경 완료 ```sql --- gmail_tokens 컬럼명 변경 (완료) -ALTER TABLE gmail_tokens ADD COLUMN slack_user_id VARCHAR(100); -- ✅ -UPDATE gmail_tokens SET slack_user_id = slack_id; -- ✅ -ALTER TABLE gmail_tokens DROP COLUMN slack_id; -- ✅ +-- gmail_token 컬럼명 변경 (완료) +ALTER TABLE gmail_token ADD COLUMN slack_user_id VARCHAR(100); -- ✅ +UPDATE gmail_token SET slack_user_id = slack_id; -- ✅ +ALTER TABLE gmail_token DROP COLUMN slack_id; -- ✅ -- 인덱스도 생성됨 -CREATE INDEX idx_gmail_tokens_slack_user_id ON gmail_tokens(slack_user_id); -- ✅ +CREATE INDEX idx_gmail_token_slack_user_id ON gmail_token(slack_user_id); -- ✅ ``` #### ✅ 코드 수정 완료 (Git pull 확인) @@ -95,8 +95,8 @@ CREATE TABLE user_preferences ( -- ✅ 테이블 생성 완료 ### ✅ 완료된 작업 1. **Slack ID 컬럼명 통일** (2025-08-27 DB 확인) - - gmail_tokens.slack_id → slack_user_id 변경 완료 - - 인덱스 idx_gmail_tokens_slack_user_id 생성됨 + - gmail_token.slack_id → slack_user_id 변경 완료 + - 인덱스 idx_gmail_token_slack_user_id 생성됨 2. **user_preferences 테이블 생성** (2025-08-27 DB 확인) - 테이블 존재 확인됨 diff --git a/troubleshooting/250827_frontend_backend_preferences_API_연동_완료.md b/troubleshooting/250827_frontend_backend_preferences_API_연동_완료.md index b3de568..991298a 100644 --- a/troubleshooting/250827_frontend_backend_preferences_API_연동_완료.md +++ b/troubleshooting/250827_frontend_backend_preferences_API_연동_완료.md @@ -194,8 +194,8 @@ Response: 403 Forbidden - "Can only access your own preferences" 3. **ActivityPanel localStorage → API 호출 변경** -### 4.2 중기 해결책 (구조 개선) -1. **scheduled_tasks 테이블 생성** +### 4.2 중기 해결책 (미구현) +1. **scheduled_tasks 테이블 생성** (상태: 미구현) ```sql CREATE TABLE scheduled_tasks ( id SERIAL PRIMARY KEY, diff --git a/troubleshooting/250831_happybell80_skill-email_UUID_inconsistency_URGENT.md b/troubleshooting/250831_happybell80_skill-email_UUID_inconsistency_URGENT.md index d10fa47..ac74a24 100644 --- a/troubleshooting/250831_happybell80_skill-email_UUID_inconsistency_URGENT.md +++ b/troubleshooting/250831_happybell80_skill-email_UUID_inconsistency_URGENT.md @@ -17,8 +17,8 @@ rb8001이 UUID를 전달하지만 skill-email은 Slack ID 기대: ``` rb8001 → skill-email: UUID (1e16e9d5-...) -skill-email DB 조회: Slack ID로 저장됨 (U0925SXQFDK) -결과: 토큰 조회 실패 → 500 에러 +skill-email DB 조회: UUID로 저장됨 (실제 확인됨) +결과: 다른 원인으로 토큰 조회 실패 → 500 에러 ``` ## 3. 역사적 맥락 @@ -34,11 +34,6 @@ rb8001의 email_integration.py 수정: - user.oauth_id에서 Slack ID 조회 - **참고: slack_user_mapping 테이블 없음, gmail_token에 slack 컬럼 없음** -### 장기 해결 (권장) -**모든 내부 시스템 UUID Primary Key 통일**: -1. gmail_tokens 테이블 user_id를 UUID로 마이그레이션 -2. skill-email UUID 조회 지원 -3. Slack ID는 매핑 테이블에서만 관리 ## 5. 영향 범위 - Gmail 관련 모든 기능 작동 불가 diff --git a/troubleshooting/250916_happybell80_rb8001_chromadb_metadata_corruption.md b/troubleshooting/250916_happybell80_rb8001_chromadb_metadata_corruption.md index 1ab1ec4..3eaf943 100644 --- a/troubleshooting/250916_happybell80_rb8001_chromadb_metadata_corruption.md +++ b/troubleshooting/250916_happybell80_rb8001_chromadb_metadata_corruption.md @@ -47,13 +47,13 @@ Collection with name rb8001_rag already exists ## 해결 과정 -### 실행한 해결책: ChromaDB 초기화 (24 서버에서 실행) +### 실행한 해결책: ChromaDB 초기화 (임베디드 모드로 실행) ```bash # 1. 백업 생성 -mv /mnt/hdd/chromadb_data /mnt/hdd/chromadb_data/chroma_backup_20250916_232341 +mv /code/chroma_db /code/chroma_db_backup_20250916_232341 # 2. 새 디렉토리 생성 -mkdir -p /mnt/hdd/chromadb_data +mkdir -p /code/chroma_db # 3. rb8001 재시작 docker restart rb8001 diff --git a/troubleshooting/250922_current_system_status_summary.md b/troubleshooting/250922_current_system_status_summary.md index 40d1619..b6f3bff 100644 --- a/troubleshooting/250922_current_system_status_summary.md +++ b/troubleshooting/250922_current_system_status_summary.md @@ -5,31 +5,25 @@ ## 🔴 긴급 수정 필요 (Quick Wins) -### 1. rb8001 EmailIntegration 버그 -- **위치**: `rb8001/app/skills/email_integration.py:210` -- **문제**: NaverWorks 토큰 조회 시 미정의 변수 `user_uuid` 사용 -- **수정**: `user_uuid` → `slack_id` 또는 `user_id`로 변경 -- **영향**: NaverWorks 이메일 기능 오류 - -### 2. UUID↔Slack ID 조회 엔드포인트 불일치 -- **문제**: gateway는 `/api/slack/{slack_id}/uuid`, 다른 서비스는 `/api/slack/mapping/{identifier}` 사용 -- **위치**: `robeing-gateway/app/main.py:468-515` -- **수정**: 하나의 엔드포인트로 통일 필요 - -### 3. 하드코딩 URL 제거 -- **위치**: `rb8001/app/skills/email_integration.py:39-47` -- **문제**: `http://192.168.219.45:9000` 하드코딩 -- **수정**: 환경변수로 교체 필요 +### 1. Gateway UUID 변환 기능 미활용 +- **현재 문제**: + - Slack 요청이 Gateway를 통과하지만 UUID 변환을 하지 않음 + - rb8001이 Auth-server(9000)를 다시 호출해 UUID 조회 (불필요한 네트워크 호출) +- **해결 방안**: + - Gateway에서 Slack ID → UUID 변환 후 X-User-Id 헤더로 전달 + - rb8001은 헤더의 UUID 직접 사용 (Auth-server 호출 불필요) +- **수정 위치**: + - Gateway: Slack 요청 프록시 시 UUID 변환 및 헤더 추가 + - rb8001: X-User-Id 헤더 우선 확인 로직 추가 +- **효과**: 네트워크 호출 감소, 구조 단순화 ## 🟠 시스템 로그 분석 결과 ### nginx 문제점 -- 9월 16일 로그 권한 오류 (logrotate 시점) - SSL handshake 오류 지속 (외부 스캔봇) -- upstream 연결 실패 (8000 vs 8100 포트 혼재) ### 서비스 상태 -- **auth-server**: 정상 (불필요한 "default_value" 로그 출력) +- **auth-server**: 정상 운영 - **robeing-gateway**: 정상 (과도한 헬스체크 빈도) - **skill-news**: JSON 파일 수집 정상, DB 영속화 미동작 @@ -57,14 +51,17 @@ 1. **GmailProvider 메서드 매핑**: `list_messages→get_recent_messages` 래핑 구현 2. **Stats API 일원화**: robeing-monitor 도입 및 사용 -3. **RAG 파일 스킬**: 포트 8508, 컬렉션 명명 규칙 적용 완료 +3. **RAG 파일 스킬**: 컬렉션 명명 규칙 적용 완료 4. **NaverWorks 통합**: skill-email에서 provider=naverworks 지원 5. **Slack 봇 설치 플로우**: passport/install/callback 엔드포인트 구현 6. **GEMINI CLI 타임아웃**: GEMINI_USE_CLI=False 기본값 +7. **네이버웍스 일일 브리핑**: 구현 완료, 테스트 중 +8. **rb8001 EmailIntegration 버그**: user_uuid 변수 이미 정상 (파라미터로 전달됨) +9. **Gateway UUID 변환**: X-User-Id 헤더로 이미 전달 중 ## 📊 현재 운영 상태 - **51123 서버**: nginx, auth-server, gateway 정상 운영 - **51124 서버**: rb8001, skill 서비스들 정상 운영 - **포트 상태**: 8100(gateway), 9000(auth) 정상 리스닝 -- **Docker 컨테이너**: 모든 서비스 healthy 상태 \ No newline at end of file +- **Docker 컨테이너**: 모든 서비스 healthy 상태 diff --git a/troubleshooting/250926_happybell80_UUID_원칙_위반_email_integration.md b/troubleshooting/250926_happybell80_UUID_원칙_위반_email_integration.md new file mode 100644 index 0000000..f4f3560 --- /dev/null +++ b/troubleshooting/250926_happybell80_UUID_원칙_위반_email_integration.md @@ -0,0 +1,82 @@ +# UUID 원칙 위반 - email_integration 및 skill-email 서비스 + +## 작성일: 2025-09-26 +## 작성자: happybell80 + +--- + +## 문제 상황 + +### 핵심 문제 +"모든 내부 로직은 UUID만 사용" 원칙(250924 문서)을 위반하여 Slack ID와 UUID 혼용 + +### 발견된 위반 사항 + +#### 1. rb8001/app/skills/email_integration.py +- **잘못된 테이블명**: `gmail_tokens` → 실제는 `gmail_token` +- **Slack ID 사용**: skill-email 호출 시 Slack ID 전달 +- **미정의 변수**: `user_uuid` 변수 정의 없이 사용 (136줄) + +#### 2. skill-email 서비스 +- **이중 처리**: UUID와 Slack ID 모두 받아서 처리 +- **DB 쿼리 분기**: UUID인지 Slack ID인지 판단 후 다른 쿼리 실행 +- **oauth_id 조회**: Slack ID로 user 테이블의 oauth_id 조회 + +## 원칙 재확인 + +### UUID 중심 원칙 (250924 문서) +- 모든 내부 로직은 UUID만 사용 +- Gateway가 UUID 변환 책임 +- UUID 없으면 403 차단 + +## 수정 내역 + +### rb8001 수정 (완료) +```python +# 변경 전: Slack ID 직접 사용 +slack_id = user_id + +# 변경 후: UUID 원칙 적용 +if user_id.startswith('U'): + user_uuid = await self.get_uuid_from_slack(user_id) +else: + user_uuid = user_id +``` + +### 테이블명 수정 (완료) +- `gmail_tokens` → `gmail_token` +- `SELECT COUNT(*) FROM gmail_token WHERE user_id = %s` + +## 남은 작업 + +### skill-email 서비스 수정 필요 +1. **main.py**: UUID 검증 로직 추가 +2. **db_credentials_provider.py**: Slack ID 처리 제거, UUID만 받기 +3. **naverworks_provider.py**: UUID 검증 및 정규화 + +### 영향 범위 +- rb8001: email_integration.py +- skill-email: 전체 provider 및 API +- DB: gmail_token, naverworks_token 테이블 쿼리 + +## 테이블 스키마 확인 (tables.md 기준) + +### gmail_token (s 없음!) +| 컬럼명 | 타입 | 설명 | +|--------|------|------| +| user_id | UUID | user 테이블 참조 | +| is_equipped | BOOLEAN | 장착 상태 | + +### naverworks_token +| 컬럼명 | 타입 | 설명 | +|--------|------|------| +| user_id | UUID | user 테이블 참조 | + +## 교훈 +1. **원칙 준수**: "내부 로직은 UUID만 사용" 원칙 철저히 준수 +2. **테이블명 확인**: 문서(tables.md) 참조하여 정확한 테이블명 사용 +3. **일관성**: 모든 서비스가 동일한 ID 체계 사용 + +--- + +**문서 끝** \ No newline at end of file