File Organizer AI Agent

단순히 확장자(*.txt, *.jpg)에 의존해 폴더를 분류하는 기존의 방식을 넘어선 진정한 형태의 지능형 파일 정리 에이전트입니다.

LangGraph 기반의 AI 에이전트가 지정된 폴더 안의 파일들을 직접 열어 내용을 읽고(Reading), 그 문맥에 맞춰 목적과 카테고리를 추론한 뒤, 일관된 네이밍 규칙을 부여하여 자동으로 폴더를 정리합니다.

주요 특징 (Key Features)

• 내용 기반 분류 (Content-based Reasoning):
  • recipe_123.txt, unknown.md 같이 이름이 무작위여도 파일 내부의 텍스트가 '파이썬 코드'인지 '갈비찜 레시피'인지 스스로 읽고 파악합니다.
• Human-in-the-loop (승인 기반 실행):
  • AI가 혼자 사고 치지 않도록, 정리할 파일 목록과 이동 경로를 미리 테이블 형태로 사용자에게 제안(Proposal)하고 [y/n] 승인을 받습니다.
• 실시간 감시 (Watchdog Mode):
  • 특정 폴더(예: 다운로드 폴더)를 백그라운드에서 상시 감시하여, 새 파일이 들어오는 즉시 사용자의 개입 없이 자동으로 정리해버립니다.
• 지식 추출 (RAG Extractor):
  • 단순 이동뿐만 아니라 "문서에서 IT 기술 용점만 추출해줘"라고 명령하면 문서 내의 핵심 지식을 뽑아 메타데이터(.agent_metadata.json)로 축적합니다.
• 타임머신 복구 (Undo):
  • 정리 결과가 마음에 들지 않거나 실수가 발생하면 단축 명령어 한 번으로 완벽하게 실행 취소(Rollback) 할 수 있습니다.

---

설치 및 설정

1. 가상 환경 구축

파이썬 3.10 이상의 환경을 권장합니다.

# 가상 환경 생성 및 진입
python3 -m venv .venv
source .venv/bin/activate

2. 패키지 설치

(현재 의존성 패키지는 프로젝트 구축 시점에 맞춰 설치됩니다. langchain, langgraph, openai, rich, watchdog 등이 요구됩니다.)

3. API 키 설정 (필수)

이 프로젝트는 OpenAI의 LLM(gpt-4o)을 활용합니다. 프로젝트 루트에 .env 파일을 만들고 키를 삽입해주세요.

#.env 파일 내용
OPENAI_API_KEY="sk-여러분들의-발급받은-키"

---

사용 방법

1. 기본 대화형 모드 (수동 정리)

CLI에서 인터랙티브하게 AI와 소통하며 파일 정리를 지시합니다. 승인을 받아야만 실제로 파일이 이동됩니다.

python agent.py

실행 후 정리할 디렉토리 경로와 희망하는 정리 방식(예: "레시피랑 개발 문서로 나눠줘")을 입력합니다.

2. 실시간 자동 모드 (배치 백그라운드)

폴더를 데몬처럼 감시하며 파일이 들어올 때마다 조건에 맞게 자동 분배합니다.

python agent.py --watch

폴더 지정 후에는 프로세스가 종료(Ctrl+C)될 때까지 켜져 있습니다.

3. 복구 모드 (실행 취소)

최근 AI가 실행한 작업 이력이 마음에 안들 경우 원상태로 되돌립니다.

python agent.py --undo

직전 1건만 되돌릴 것인지, 전체 내역을 영구 복구시킬 것인지 선택할 수 있습니다.

---

기술 스택 (Architecture)

• 언어: Python 3.12+
• LLM 프레임워크: LangChain, LangGraph
• AI 모델: OpenAI gpt-4o, gpt-4o-mini
• 인터페이스 & 시스템 제어: rich (CLI UI), watchdog (파일시스템 이벤트 캐치)