🚀 Financial AI Agent Starter Kit

금융 도메인 특화 실전 AI 에이전트 개발 실습 키트

본 프로젝트는 LangChain과 LangGraph 기반의 **AI 에이전트 핵심 아키텍처(ReAct, Dynamic Tooling, Checkpointer, Long-term Profile Memory, Progressive Skill Execution)**를 학습하고, FastAPI 백엔드 및 Chainlit 웹 UI를 통해 실시간 금융 데이터 분석과 인터랙티브 대시보드 시각화 서비스를 직접 조립·구동하는 종합 실습 스타터 킷입니다.

---

✨ 핵심 기능 및 아키텍처

• ⚡ GitHub Codespaces 초고속 기동: 사전 빌드된 Docker 이미지(hukimartia/agent-starter:latest) 기반으로 30초 내에 완벽한 개발 환경 준비
• 🧩 Dynamic Agent Loader (FastAPI): 에이전트 모듈을 런타임에 지연 로딩(Lazy Loading)하고 파일 수정 시 무중단 자동 리로드 지원
• 💬 인터랙티브 Chat UI (Chainlit):
  • 실시간 토큰 스트리밍 및 도구 호출 접기/펼치기 그룹화
  • Chart.js 기반 인터랙티브 HTML 대시보드 인라인 렌더링 (접기/펼치기 토글 및 ↗ 새 탭 전체화면 열기)
• 🧠 양방향 자가 갱신형 장기 기억 (Consolidation & Update): 대화를 통해 사용자 프로필(USER.md)을 스스로 통합·갱신
• 🛠️ Progressive Skill Disclosure: 13종의 국내/해외 주식, 공시, 거시경제, 퀀트 스킬(pykrx, yfinance, opendart, fred, quant 등) 자동 스캔 및 점진적 코드 실행

---

📂 프로젝트 구조

agent_starter/
├── .devcontainer/          # GitHub Codespaces 컨테이너 환경 설정
├── app/
│   ├── agents/             # 에이전트 팩토리 (chatbot.py, finance_analyst.py)
│   ├── prompts/            # 시스템 프롬프트 및 SkillPromptBuilder
│   ├── tools/              # 기본 8대 도구 및 커스텀 기억 도구 (custom_tools.py)
│   ├── database/           # SQLite 세션 DB 및 사용자 프로필 (USER.md)
│   ├── server.py           # FastAPI 백엔드 서버 (:8000)
│   ├── chainlit_ui.py      # Chainlit 웹 채팅 프론트엔드 (:8080)
│   └── client.py           # 비동기 SSE 클라이언트
├── configs/                # 모델 및 로깅 설정 파일
├── install/                # 환경 의존성 (requirements.txt, install_all.sh)
├── missions/               # 🎯 단계별 실습 가이드 문서
│   ├── 01_missions.md      # Mission 1: 챗봇 장기 기억 도구 연결
│   └── 02_missions.md      # Mission 2: 금융 분석 에이전트 구축 및 시각화
├── notebooks/              # 📚 핵심 원리 학습용 주피터 노트북
│   ├── 1_Create_agent.ipynb# 1편: 에이전트 기초 & ReAct & 체크포인터
│   └── 2_Skills_and_MCP.ipynb # 2편: Progressive Skills & MCP 연동
├── public/                 # Chainlit 커스텀 React 컴포넌트 (HtmlDashboard.jsx)
└── skills/                 # 13종 전문 금융 스킬 라이브러리

---

🚀 빠른 시작 가이드 (Quick Start)

1. 환경 변수 설정 (.env)

프로젝트 루트에 .env 파일을 생성하고 사용할 LLM API 키를 설정합니다:

cp .env.example .env

.env 파일에 API 키를 입력하세요:

GOOGLE_API_KEY="your-gemini-api-key"
# 또는 OPENAI_API_KEY="your-openai-api-key"

---

2. 서비스 실행 (터미널 2개 구동)

🖥️ 터미널 1: FastAPI 백엔드 서버 가동

python app/server.py --port 8000

정상 실행 시 Uvicorn running on http://0.0.0.0:8000 출력

🌐 터미널 2: Chainlit 웹 채팅 UI 가동

chainlit run app/chainlit_ui.py --port 8080

정상 실행 시 Your app is available at http://localhost:8080 출력 (Codespaces에서는 브라우저 자동 오픈)

• 웹 접속 URL: http://localhost:8080
• 로그인 계정: 아이디 user / 비밀번호 1234
• 에이전트 선택: 좌측 상단 프로필에서 원하는 에이전트(chatbot 또는 finance_analyst) 선택

---

📚 학습 로드맵 & 미션 안내

  [1단계: 노트북 개념 학습]
     ├─ 1_Create_agent.ipynb ──> [Mission 01] Chatbot에 자가 갱신형 장기 기억 도구 탑재
     │
     └─ 2_Skills_and_MCP.ipynb ──> [Mission 02] 13개 스킬 기반 전문 금융 분석 에이전트 구축

🎯 [Mission 01] Chatbot에 장기 기억 도구 탑재

👉 missions/01_missions.md 가이드를 열고 단계별로 따라하세요.

• app/tools/custom_tools.py에 read_user_memory, update_user_memory 도구 2종 구현
• 고양이 챗봇(chatbot)에 도구를 바인딩하여 세션이 바뀌어도 프로필(USER.md)을 기억하고 대화를 통해 스스로 갱신하는 기능 검증

🎯 [Mission 02] Progressive Skills 기반 금융 분석 에이전트 구축

👉 missions/02_missions.md 가이드를 열고 단계별로 따라하세요.

• SkillPromptBuilder를 통해 skills/ 폴더 내 13종 금융 스킬 카탈로그를 시스템 프롬프트에 동적으로 주입
• app/agents/finance_analyst.py 팩토리 함수를 조립하여 국내/해외 주식, 거시경제, 퀀트 리스크 분석 및 인터랙티브 HTML 대시보드 시각화 검증

---

🌿 브랜치 가이드

• main: 교육생 실습용 스타터 브랜치 (핵심 실습 파일들이 TODO 스켈레톤 코드로 제공됨)
• instructor: 강사용 완성 정답본 브랜치 (모든 미션 코드가 완성되어 있어 즉시 시연 가능)