AI Hedge Fund 딥다이브
— 13명의 전설적 투자자를 LLM 멀티에이전트로 재현하는 교육용 트레이딩 프레임워크

1프로젝트 한줄 요약

AI Hedge Fund(virattt/ai-hedge-fund)는 유명 투자자 13명의 투자 철학을 각각 하나의 LLM 에이전트로 코드화하고, 여기에 기술적·펀더멘털·밸류에이션·감성·뉴스감성·성장 분석을 맡는 6종의 정량 애널리스트를 더해, 총 19개의 분석 에이전트가 같은 종목을 동시에 평가하게 만드는 교육용 오픈소스 Python 프레임워크입니다. 각 에이전트가 낸 매수/매도/중립 신호를 리스크 매니저가 포지션 한도로 다듬고, 포트폴리오 매니저가 종합해 최종 주문을 만듭니다.

가장 먼저 못박아 둘 점: 이 시스템은 실제로 거래를 하지 않습니다. README가 굵은 글씨로 "educational purposes only(교육 목적 전용)"이라고 명시합니다. 즉 "돈 버는 봇"이 아니라, LLM 멀티에이전트 설계를 금융이라는 친숙한 소재로 배우는 교과서에 가깝습니다.

2왜 주목받는가

AI Hedge Fund는 AI 에이전트와 핀테크라는 두 인기 주제의 교차점에 있고, 만든 사람(virattt)은 AI 빌더 커뮤니티에서 유명한 개발자입니다. 하지만 단순한 화제성을 넘어, "멀티에이전트 시스템을 어떻게 깔끔하게 설계하는가"의 모범답안이라는 점에서 학습 가치가 큽니다.

경쟁 프로젝트 대비 위치

요약하면, TradingAgents가 "토론으로 편향을 줄이는" 데 집중한다면, AI Hedge Fund는 "각기 다른 투자 철학을 병렬로 돌려 비교하고, 숫자 계산과 LLM 판단을 깔끔히 분리"하는 데 집중합니다. 둘 다 LangGraph 기반이라 함께 읽으면 멀티에이전트 설계의 두 갈래를 비교 학습할 수 있습니다.

3기술 스택 전체 지도

한 문장으로: Python 3.11 + Poetry 위에서 LangChain/LangGraph가 에이전트를 엮고, Pydantic이 LLM 출력을 구조화하며, financialdatasets.ai가 재무 데이터를 공급합니다. 거기에 FastAPI + React 웹앱이 얹혀 있는 구조입니다.

백엔드 / 코어 (Python 3.11)

웹앱 (app/ 디렉토리)

4아키텍처 심화 분석

전체 흐름은 의외로 단순합니다. 시작 노드에서 선택된 애널리스트들에게 동시에(병렬) 분기(fan-out)했다가, 그 결과가 리스크 매니저 한 곳으로 모여(fan-in) 포트폴리오 매니저를 거쳐 끝납니다.

핵심 설계 패턴 1 — 단일 진실원(ANALYST_CONFIG)에서 그래프를 자동 생성

에이전트 목록은 src/utils/analysts.py의 ANALYST_CONFIG 딕셔너리 한 곳에서만 정의됩니다. 메인 코드는 이 딕셔너리를 읽어 노드와 엣지를 자동으로 만듭니다. 즉 에이전트를 추가하려면 이 딕셔너리에 한 줄 추가하면 끝 — 그래프 코드는 손대지 않습니다.

# src/main.py — create_workflow() 핵심 발췌
workflow = StateGraph(AgentState)
workflow.add_node("start_node", start)

analyst_nodes = get_analyst_nodes()          # ANALYST_CONFIG에서 파생
for analyst_key in selected_analysts:
    node_name, node_func = analyst_nodes[analyst_key]
    workflow.add_node(node_name, node_func)
    workflow.add_edge("start_node", node_name)  # 시작 → 각 애널리스트 (fan-out)

workflow.add_node("risk_management_agent", risk_management_agent)
workflow.add_node("portfolio_manager", portfolio_management_agent)
for analyst_key in selected_analysts:
    workflow.add_edge(analyst_nodes[analyst_key][0], "risk_management_agent")  # fan-in
workflow.add_edge("risk_management_agent", "portfolio_manager")
workflow.add_edge("portfolio_manager", END)

핵심 설계 패턴 2 — 상태(AgentState)와 리듀서(Reducer)

여러 에이전트가 동시에 상태를 건드리면 충돌이 납니다. LangGraph는 이를 리듀서로 해결합니다 — 각 필드에 "여러 결과가 들어오면 어떻게 합칠지" 규칙을 붙입니다.

# src/graph/state.py
class AgentState(TypedDict):
    messages: Annotated[Sequence[BaseMessage], operator.add]  # 리스트 이어붙이기
    data:     Annotated[dict, merge_dicts]                    # 딕셔너리 병합
    metadata: Annotated[dict, merge_dicts]

핵심 설계 패턴 3 — "숫자는 코드, 판단은 LLM" 하이브리드

이 레포에서 가장 배울 점입니다. 워런 버핏 에이전트는 LLM에게 원시 재무제표를 던지지 않습니다. 먼저 파이썬 함수로 ROE·해자·경영진 품질·오너 어닝(owner earnings)·3단계 DCF 내재가치·안전마진을 결정론적으로 계산하고, 그 결과를 짧은 facts 묶음으로 정리한 뒤, LLM에게는 "이 사실들로 버핏이라면 매수/매도/중립 중 무엇이라 할까?"만 묻습니다.

# src/agents/warren_buffett.py — LLM에 넘기는 건 "계산된 사실"뿐
facts = {
    "score": analysis_data.get("score"),
    "fundamentals": fundamental_analysis["details"],
    "moat": moat_analysis["details"],
    "intrinsic_value": intrinsic_value_analysis["intrinsic_value"],
    "margin_of_safety": margin_of_safety,   # (내재가치 - 시총)/시총
}
# system 프롬프트: "You are Warren Buffett. Decide bullish/bearish/neutral
#   using ONLY the provided facts ... Do not invent data. Return JSON only."
return call_llm(prompt=prompt, pydantic_model=WarrenBuffettSignal, ...)

핵심 설계 패턴 4 — 멀티프로바이더 LLM + 우아한 실패

src/utils/llm.py의 call_llm()은 어떤 프로바이더든 동일한 방식으로 호출합니다. JSON 모드를 지원하는 모델은 with_structured_output()로 Pydantic 스키마를 강제하고, 지원하지 않으면 응답에서 직접 JSON을 긁어냅니다(extract_json_from_response). 게다가 에이전트마다 다른 모델을 쓸 수 있고, 3회까지 재시도하며, 끝내 실패하면 default_factory로 안전한 기본 신호(중립)를 반환해 전체가 멈추지 않게 합니다.

# 호출 → 재시도 → 그래도 실패하면 안전한 기본값
for attempt in range(max_retries):          # 기본 3회
    try:
        result = llm.invoke(prompt)
        return result                        # 구조화 출력 성공
    except Exception:
        if attempt == max_retries - 1:
            return default_factory()         # 예: signal="neutral", confidence=50

5디렉토리 구조 해부

구조를 읽는 한 가지 요령: "에이전트 = 노드"라는 등식만 기억하면 됩니다. src/agents/ 안의 파일 하나가 그래프의 노드 하나이고, 각 파일은 거의 같은 골격(데이터 수집 → 정량 분석 함수들 → facts 구성 → call_llm)을 따릅니다. 그래서 한 에이전트(예: warren_buffett.py)만 정독하면 나머지 12개는 빠르게 읽힙니다.

6학습 포인트 (기술별)

A. LangGraph — 팬아웃/팬인 멀티에이전트

StateGraph로 병렬 분기와 수렴을 정의하는 법, add_node/add_edge/set_entry_point의 기본기, 그리고 리듀서(operator.add / merge_dicts)로 동시 갱신 충돌을 푸는 법을 배웁니다. TradingAgents가 "조건부 엣지로 토론 루프"를 보여준다면, 이 레포는 "정적 팬아웃의 깔끔한 정석"을 보여줍니다.

B. 설정 주도(Config-driven) 설계

ANALYST_CONFIG 딕셔너리 하나가 표시 이름·설명·투자 스타일·함수·정렬 순서를 모두 담고, 그래프·CLI·API 응답이 전부 여기서 파생됩니다. "같은 정보를 두 곳에 적지 않는다"는 단일 진실원(single source of truth) 원칙의 좋은 예시입니다.

C. 결정론 + LLM 하이브리드 추론

LLM에 raw 데이터를 던지지 않고 "계산된 사실(facts)"만 넘기는 패턴, "데이터를 지어내지 말라"는 프롬프트 가드, 점수화(scoring) 로직과 판단(LLM)의 책임 분리를 배웁니다. 이건 금융을 넘어 모든 LLM 앱에 일반화되는 안티-환각 설계입니다.

D. Pydantic 구조화 출력 + 우아한 실패

with_structured_output(method="json_mode")로 JSON 스키마 강제, JSON 미지원 모델을 위한 수동 파싱(extract_json_from_response), 재시도 후 default_factory로 안전한 기본값을 반환하는 실패해도 멈추지 않는(graceful degradation) 설계를 배웁니다.

E. 펀더멘털 밸류에이션을 코드로

버핏 에이전트 안에는 진짜 투자 이론이 코드로 들어 있습니다 — analyze_moat(ROE 일관성·마진 안정성으로 해자 추정), calculate_owner_earnings(순이익+감가상각−유지보수 CapEx−운전자본 변화), 3단계 DCF 내재가치, 안전마진. "가치투자가 실제로 어떻게 숫자가 되는가"를 코드로 배울 수 있습니다.

F. 백테스팅 사고방식

src/backtester.py와 backtesting/로 과거 기간을 재생하며 의사결정을 시뮬레이션합니다. 포트폴리오 상태(현금·롱/숏 포지션·마진·실현손익)를 어떻게 표현하는지, 룩어헤드 편향 없이 날짜를 전진시키는지를 배웁니다.

G. 풀스택 패키징 (FastAPI + React)

같은 코어 로직을 CLI와 웹앱이 공유하는 모노레포 구조, FastAPI로 코어를 REST API로 감싸기, SQLAlchemy/Alembic로 실행 이력 저장, run.sh로 비개발자도 원클릭 실행하게 만드는 배포 경험을 배웁니다.

7하드웨어 / 시스템 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

1주차: LangGraph 기초

공식 문서로 StateGraph·노드·엣지·entry point 이해. 2~3개 노드의 간단한 워크플로우를 직접 만들어 보고, operator.add 리듀서로 메시지가 어떻게 쌓이는지 관찰합니다. 참고: langchain-ai.github.io/langgraph/

2주차: 팬아웃/팬인 멀티에이전트

이 레포의 src/main.py create_workflow를 정독하며 병렬 분기→수렴 패턴을 따라 구현합니다. 동시 갱신 충돌을 리듀서로 푸는 연습을 합니다.

3주차: 구조화 출력과 안티-환각

Pydantic 모델 + with_structured_output으로 LLM에 JSON 스키마를 강제하는 법, 재시도·기본값으로 실패를 흡수하는 법을 익힙니다. "raw 데이터 대신 facts만 넘기기" 패턴을 자신의 프로젝트에 적용해 봅니다.

4주차: 멀티프로바이더 LLM 추상화

src/llm/models.py와 call_llm 구조를 분석해, OpenAI·Anthropic·Ollama를 한 인터페이스로 다루는 래퍼를 직접 만들어 봅니다. JSON 모드 지원 여부 분기 처리도 구현합니다.

5주차: 금융 밸류에이션 기초

ROE·영업이익률·부채비율 같은 재무지표의 의미, 오너 어닝과 DCF로 내재가치를 추정하는 법, 안전마진 개념을 warren_buffett.py의 함수들과 함께 이해합니다. (투자 조언이 아니라 "이론이 코드가 되는 과정"을 보는 학습입니다.)

6주차: 통합 — 미니 헤지펀드

2개 페르소나 + 리스크/포트폴리오 노드로 축소판을 직접 구현합니다. financialdatasets.ai(또는 무료 데이터)로 한 종목을 분석하고 백테스트까지 돌려 봅니다.

10핵심 키워드 사전

11참고 링크

• GitHub — virattt/ai-hedge-fund
• 웹앱(app/) 설치·실행 안내
• LangGraph 공식 문서
• LangChain 공식 문서
• Pydantic 문서 (구조화 출력)
• Financial Datasets API
• FastAPI 문서
• Poetry 문서
• Ollama (로컬 LLM 실행)
• 제작자 virattt (X/Twitter)