MoveMate Agent

LangGraph 기반 AI 이사 행정 · 주거 정책 멀티 에이전트.
Supervisor가 질문을 분석해 세 전문 에이전트로 라우팅하고, 복합 질문은 결과를 하나의 답변으로 합성한다.

아키텍처

사용자 질문
    │
    ▼
[supervisor_node]  ─ 키워드 매칭 → LLM 폴백으로 라우팅 결정
    │
    ├─ legal    ──▶ [legal_agent_node]     이사 행정 하위 그래프
    │                  └─ classify → direct_tool / react_agent
    │
    ├─ policy   ──▶ [policy_agent_node]    주거 정책 RAG 에이전트
    │                  └─ housing_policy_rag (9-node LangGraph)
    │
    ├─ schedule ──▶ [schedule_agent_node]  이사 일정 ReAct 에이전트
    │                  └─ Google Calendar MCP 연동
    │
    └─ both     ──▶ legal + policy 병렬 실행
    │
    ▼
[synthesize_node]  ─ 단일 답변 통과 / 복합 시 LLM 합성
    │
    ▼
  최종 답변

라우팅 규칙

route	조건	동작
`legal`	이사 행정 · 법령 키워드	이사 행정 에이전트
`policy`	청년 · 지원금 · 대출 키워드	주거 정책 RAG 에이전트
`schedule`	일정 · 체크리스트 · D-Day 키워드	이사 일정 에이전트
`both`	두 영역 키워드 혼재	legal + policy 병렬 실행 후 합성

에이전트 상세

1. legal_agent — 이사 행정 · 법령

사용자 의도를 분류한 후 ChromaDB에서 관련 문서를 검색해 LLM이 답변을 생성한다.

인텐트	설명	Tool
`legal_qa`	법령 · 개념 질문	`search_legal_info`
`admin_procedure`	행정 절차 방법	`search_admin_procedure` + `search_legal_info` (병합)
`checklist`	체크리스트 요청	`get_checklist`
`region_price`	지역 시세 조회	`get_region_price`
`complex` / `unknown`	복합 · 미분류 질문	ReAct Agent

ChromaDB 컬렉션 (moving_helper_db_v2/)

컬렉션	내용	청크 수
`legal_knowledge`	주택임대차보호법 · 법령 가이드	363
`admin_procedures`	이사 단계별 행정 절차	24
`checklist_items`	이사 체크리스트	12

임베딩 모델: jhgan/ko-sroberta-multitask

2. policy_agent — 주거 정책 RAG

housing_policy_rag/ 서브 패키지를 직접 임포트해 사용한다.
9개 노드 LangGraph 파이프라인으로 사용자 프로필을 추출하고 정책을 검색·재랭킹해 답변을 생성한다.

profile_extract → intent_classify
    → (clarify | region_resolve | follow_up)
    → rag_retrieve → rerank_filter → prepare_policies → generate_answer

ChromaDB (housing_policy_rag/vectorstore/chroma_db_new/)
임베딩 모델: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
재랭킹 모델: BAAI/bge-reranker-base
LLM: OpenAI gpt-4o-mini → 쿼터 초과 시 Groq llama-3.3-70b-versatile 자동 폴백

3. schedule_agent — 이사 일정

Google Calendar MCP를 연동해 캘린더를 조회하고 최적 일정을 제안한다.

Tool	역할
`get_schedule_tool`	이사 날짜 기반 체크리스트 마감일 계산
`get_google_calendar_events`	구글 캘린더 일정 조회
`suggest_schedule_tool`	바쁜 날 피해 최적 일정 제안
`create_calendar_event`	구글 캘린더에 일정 등록

프로젝트 구조

movemate_agent/
├── main.py                         # CLI 진입점
├── .env                            # API 키 설정 (git 제외)
├── .env.template                   # 환경변수 예시
├── requirements.txt
│
├── config/
│   ├── llm_factory.py              # LLM 제공자 팩토리 (get_llm())
│   ├── mcp_client.py               # Google Calendar MCP 설정
│   ├── prompts.py                  # 시스템 · 라우팅 · 합성 프롬프트
│   └── settings.py / constants.py
│
├── state/
│   ├── schema.py                   # MovingAgentState (이사 행정)
│   └── supervisor_schema.py        # SupervisorState (상위 그래프)
│
├── graph/
│   ├── supervisor_graph.py         # 상위 Supervisor StateGraph
│   ├── main_graph.py               # 이사 행정 하위 그래프
│   ├── react_graph.py              # ReAct 에이전트
│   └── nodes/
│       ├── supervisor_node.py      # 라우팅
│       ├── legal_agent_node.py     # 이사 행정 에이전트 래퍼
│       ├── policy_agent_node.py    # 정책 RAG 에이전트 래퍼
│       ├── schedule_agent_node.py  # 일정 에이전트 (ReAct)
│       ├── synthesize_node.py      # 복합 답변 합성
│       ├── classify_node.py        # 인텐트 분류
│       ├── direct_tool_node.py     # Tool 검색 + LLM 합성
│       └── react_agent_node.py
│
├── tools/
│   ├── search_legal_info.py
│   ├── search_admin_procedure.py
│   ├── get_checklist.py
│   ├── get_region_price.py
│   └── schedule/
│       ├── get_calendar.py         # 구글 캘린더 조회 (MCP)
│       ├── create_calendar.py      # 일정 등록
│       ├── get_schedule.py         # 마감일 계산
│       └── suggest_schedule.py     # 최적 일정 제안
│
├── db/
│   ├── client.py                   # ChromaDB 연결
│   ├── collections/                # 컬렉션별 쿼리 함수
│   └── utils/
│
├── intent/
│   ├── rules.py                    # IntentType Enum + 키워드 규칙
│   ├── classifier.py               # 규칙 기반 분류
│   └── llm_fallback.py
│
├── housing_policy_rag/             # 주거 정책 RAG 서브 패키지
│   ├── agent/                      # LangGraph 파이프라인
│   │   ├── graph.py                # run_agent() 진입점
│   │   ├── llm_helper.py           # OpenAI → Groq 폴백 헬퍼
│   │   └── nodes/                  # 9개 파이프라인 노드
│   ├── src/                        # RAG 인프라 (벡터스토어, 임베딩)
│   └── main.py                     # 독립 실행 / 벡터스토어 빌드
│
├── moving_helper_db_v2/            # 이사 행정 ChromaDB (git 제외)
└── tests/

설치

1. 가상환경 생성

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

2. 패키지 설치

pip install -r requirements.txt

3. 환경변수 설정

.env.template을 복사해 .env를 만들고 키를 채운다.

cp .env.template .env

# ── 메인 에이전트 LLM ───────────────────────────────────────────
# 사용할 제공자: groq | openai | anthropic
LLM_PROVIDER=groq
LLM_MODEL=                      # 비워두면 제공자별 기본 모델 적용

GROQ_API_KEY=your_groq_api_key
OPENAI_API_KEY=                 # 정책 에이전트 1순위 LLM (없으면 Groq 폴백)
ANTHROPIC_API_KEY=

# ── 정책 에이전트 (housing_policy_rag) ──────────────────────────
GOOGLE_API_KEY=                 # Gemini 사용 시 (선택)
VECTORSTORE_PATH=housing_policy_rag/vectorstore/chroma_db_new
DATA_PATH=housing_policy_rag/data

# ── Google Calendar MCP ─────────────────────────────────────────
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

제공자별 기본 모델

제공자	기본 모델
`groq`	`llama-3.3-70b-versatile`
`openai`	`gpt-4o-mini`
`anthropic`	`claude-haiku-4-5-20251001`

ChromaDB 구축

이사 행정 DB (`moving_helper_db_v2/`)

이미 커밋된 DB를 그대로 사용한다. 재구축이 필요하면:

python checklist_seed.py

주거 정책 DB (`housing_policy_rag/vectorstore/`)

팀원에게 받은 ChromaDB를 housing_policy_rag/vectorstore/chroma_db_new/에 복사하거나,
샘플 데이터로 직접 구축한다.

cd housing_policy_rag
python main.py build --use-sample

실행

python main.py

====================================
  AI 이사 행정 · 주거 정책 에이전트
====================================
질문을 입력하세요. 종료하려면 'exit'를 입력하세요.

질문: 확정일자란 뭐야?
답변: 확정일자는 주택임대차계약서가 실제로 그 날에 존재했음을 공적으로 증명하는 날짜입니다 ...

질문: 서울 청년 전세 지원 정책 알려줘
답변: 서울 청년 전세 지원 정책으로는 청년 버팀목 전세자금 대출과 ...

질문: 8월 15일 이사인데 일정 짜줘
답변: 이사 날짜 2026-08-15 기준으로 체크리스트를 정리했습니다 ...

테스트

# 통합 E2E 테스트 (세 에이전트 + 라우팅, 22개 케이스)
$env:PYTHONUTF8 = "1"
.venv\Scripts\python.exe _test_e2e.py

# 단위 테스트
pytest tests/ -v

기술 스택

구분	내용
에이전트 프레임워크	LangGraph 1.x (Supervisor + 하위 그래프)
LLM (메인)	Groq / OpenAI / Anthropic (`.env`로 전환)
LLM (정책 에이전트)	OpenAI gpt-4o-mini → Groq llama-3.3-70b 자동 폴백
벡터 DB	ChromaDB (PersistentClient)
임베딩 (이사 행정)	`jhgan/ko-sroberta-multitask`
임베딩 (정책)	`paraphrase-multilingual-MiniLM-L12-v2`
재랭킹 (정책)	`BAAI/bge-reranker-base` (CrossEncoder)
캘린더 연동	Google Calendar MCP (`@cocal/google-calendar-mcp`)
언어	Python 3.11+

유의 사항

moving_helper_db_v2/ 내부 파일은 수동으로 수정하지 않는다
housing_policy_rag/vectorstore/ 및 housing_policy_rag/data/는 .gitignore 처리됨 — 팀원에게 별도 수령
메타데이터 필드명은 반드시 move_stage를 사용한다 (moving_stage 사용 금지)
Google Calendar 연동은 gcp-oauth.keys.json OAuth 키 파일이 필요하다 (git 제외)

Navigation Menu

Uh oh!

Repository files navigation

MoveMate Agent

아키텍처

라우팅 규칙

에이전트 상세

1. legal_agent — 이사 행정 · 법령

2. policy_agent — 주거 정책 RAG

3. schedule_agent — 이사 일정

프로젝트 구조

설치

1. 가상환경 생성

2. 패키지 설치

3. 환경변수 설정

ChromaDB 구축

이사 행정 DB (`moving_helper_db_v2/`)

주거 정책 DB (`housing_policy_rag/vectorstore/`)

실행

테스트

기술 스택

유의 사항

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
api		api
config		config
db		db
graph		graph
housing_policy_rag		housing_policy_rag
ingestion		ingestion
intent		intent
state		state
tests		tests
tools		tools
.env.template		.env.template
.gitignore		.gitignore
README.md		README.md
README_schedule.md		README_schedule.md
_test_e2e.py		_test_e2e.py
checklist_seed.py		checklist_seed.py
main.py		main.py
requirements.txt		requirements.txt

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

MoveMate Agent

아키텍처

라우팅 규칙

에이전트 상세

1. legal_agent — 이사 행정 · 법령

2. policy_agent — 주거 정책 RAG

3. schedule_agent — 이사 일정

프로젝트 구조

설치

1. 가상환경 생성

2. 패키지 설치

3. 환경변수 설정

ChromaDB 구축

이사 행정 DB (moving_helper_db_v2/)

주거 정책 DB (housing_policy_rag/vectorstore/)

실행

테스트

기술 스택

유의 사항

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

이사 행정 DB (`moving_helper_db_v2/`)

주거 정책 DB (`housing_policy_rag/vectorstore/`)