기능

Richfolio는 단일 파이프라인 안에 18가지 이상의 기능을 담고 있으며 — 모두 무료 플랜 API 위에서 동작합니다.

두 단계 AI 분석 (Think/Plan 프레임워크)

Richfolio는 OpenAlice의 Think/Plan 아키텍처에서 영감을 받은 두 단계 인지 프레임워크를 사용합니다:

1단계: Observe (Think) — Gemini가 종목별로 구조화된 관찰을 추출합니다. 어떤 가격대 신호가 존재하는지(평균 P/E 이하, 52주 저점 근접, 200일선 이하), 어떤 모멘텀 신호가 작동 중인지(RSI < 35, 강세 MACD, 볼린저 %B < 0.15, 스토캐스틱 %K < 20), 리스크 플래그, 한 문장 짜리 밸류에이션 및 기술적 요약, 뉴스 감성, 배분 컨텍스트가 포함됩니다. 이 단계에서는 매매 추천이 없습니다 — 순수한 데이터 파싱입니다.

2단계: Decide (Plan) — 별도의 Gemini 호출이 구조화된 관찰(원시 숫자가 아닌)과 모든 의사결정 규칙, 과거 추론 컨텍스트를 받아 STRONG BUY 기준을 적용해 최종 추천을 만듭니다. 의사결정 단계가 이미 가공된 관찰을 다루기 때문에 엄격한 기준을 더 일관되게 적용할 수 있습니다.

각 종목은 다음 중 하나의 액션을 받습니다: STRONG BUY, BUY, HOLD, 또는 WAIT. 추천 매수 금액, 지정가 가격, (주식의 경우) 밸류 등급, 그리고 바닥 신호(과매도 감지)도 함께 제공됩니다. Gemini API를 사용할 수 없거나 할당량이 소진되면 Richfolio는 자동으로 격차 기반 추천으로 폴백합니다. 일시적인 Gemini 오류(503/429)는 백오프와 함께 최대 2회까지 자동으로 재시도됩니다.

STRONG BUY 종목에는 이메일과 Telegram 메시지에 “More Details” 링크가 함께 제공됩니다. 이 링크를 클릭하면 GitHub Pages에 호스팅된 전용 분석 페이지가 열리며, 인터랙티브 TradingView 차트, 상세 매수 논거, 리스크 분석, 핵심 지표, 펀더멘털, 액션 요약이 포함됩니다 — 모두 Gemini 2.5 Flash가 생성합니다.

Daily Brief STRONG BUY Analysis

실적 발표 캘린더 가드

Richfolio는 Yahoo Finance의 calendarEvents 모듈을 통해 다가오는 실적 발표일을 자동으로 감지하고(추가 API 호출 없음 — 기존 quoteSummary 요청에 편승), 프로그램적인 안전 상한을 적용합니다:

실적 ≤ 3일 전 → HOLD로 강제 — 실적을 끼고 보유하는 것은 매수 추천을 내기에 위험/보상이 너무 비대칭적입니다
실적 ≤ 7일 전 → BUY로 상한 — 실적이 임박한 상황에서는 절대 STRONG BUY를 내지 않습니다
실적 ≤ 14일 전 → 이메일에서는 컬러 배지로, Telegram에서는 [earnings Xd] 태그로 표시되어 인지할 수 있도록 합니다

이 가드는 AI 프롬프트(소프트 명령)에서 한 번, 그리고 가드 파이프라인에서 프로그램적인 하드 상한으로 한 번(AI가 오버라이드할 수 없음) 실행됩니다. 고위험 이벤트 기간의 포지션을 피하기 위한 OpenAlice의 실적 캘린더 인식에서 영감을 받았습니다.

AI 사후 가드 검증 파이프라인

AI가 추천을 반환하고 나면, 프로그램적인 검증 파이프라인이 6가지 순차 검사를 실행해 흔한 AI 실수를 사용자에게 전달되기 전에 잡아냅니다. 컨텍스트 격리를 적용한 OpenAlice의 가드 파이프라인 개념에서 영감을 받았습니다:

Bond ETF 상한 — 단기 듀레이션 채권 ETF (BSV, SHY 등)는 BUY로 하드 상한, 최대 신뢰도 65%
실적 임박 — 실적 캘린더 가드를 프로그램적으로 강제
STRONG BUY 기준 강제 — 배분 격차 ≥ 2%, 신뢰도 ≥ 80%, 그리고 최소 1개의 가격대 신호 존재 여부를 검증. 하나라도 실패하면 BUY로 강등
STRONG BUY 최대 2개 — 신뢰도 순으로 정렬해 상위 2개만 유지, 나머지는 강등
신뢰도 정상화 — 95%로 상한 (AI가 가끔 98~100을 출력함); HOLD/WAIT는 70%로 상한
매수 금액 정상화 — 추천 매수 금액은 격차 금액으로 상한; HOLD/WAIT는 매수 금액을 0으로

각 가드가 트리거될 때 디버깅을 위해 로그를 남깁니다. 가드는 독립적으로 동작합니다 — 추천 데이터를 받을 뿐, 원시 브로커/API 객체를 보지 않습니다.

기술적 모멘텀 신호

Richfolio는 Yahoo Finance를 통해 250일치 과거 가격 데이터를 가져와 포트폴리오 내 모든 종목에 대해 기술적 지표를 계산합니다:

SMA50 / SMA200 — 50일 및 200일 단순 이동평균과 현재 가격이 각각에 대해 어디에 위치하는지
RSI(14) — 14일 상대강도지수 (30 미만 = 과매도, 70 초과 = 과매수)
MACD — Moving Average Convergence Divergence (EMA12 − EMA26, 시그널 라인 = MACD의 EMA9). 골든/데드 크로스와 히스토그램 방향으로 모멘텀 전환을 감지합니다. 추세 시장에 적합
볼린저 밴드 — SMA(20) ± 2 표준편차. %B(밴드 내 위치: 0 = 하단, 1 = 상단), 밴드폭(변동성), 그리고 스퀴즈 감지(밴드폭이 120일 범위의 하위 20%에 위치하면 임박한 돌파를 시사)를 추적합니다. 박스권 시장에 적합
ATR(14) — Wilder 스무딩이 적용된 평균 진폭. 절대값과 가격 대비 % 둘 다 보고합니다. ATR% > 3% = 고변동성(AI가 지정가를 더 넓게 설정), ATR% < 1% = 저변동성(더 타이트하게). 포지션 사이징 컨텍스트로 유용
스토캐스틱 오실레이터 — %K(14)와 3일 스무딩 %D. %K < 20 = 과매도 확인 (STRONG BUY 기준의 모멘텀 신호에 포함), %K > 80 = 과매수. RSI와는 다른 계산 방식으로 상호 보완
OBV (On-Balance Volume) — 누적 OBV와 선형 회귀를 통한 10일 추세 분석. 방향만 보고합니다: 상승(매집), 하락(분산), 횡보(중립). OBV 절대값은 종목 간 비교가 의미 없으므로 — 오직 추세만 봅니다
골든 / 데드 크로스 — SMA50이 SMA200을 위로(강세) 또는 아래로(약세) 돌파
모멘텀 신호 — 가격 vs 이동평균과 RSI를 기반으로 강세, 약세, 또는 중립으로 분류
최근 저점 — 7일 및 30일 저점으로 인근 지지선 식별

AI 프롬프트에는 MACD와 볼린저 밴드가 충돌할 때를 위한 명시적인 충돌 해결 규칙이 포함되어 있습니다: 추세 시장에서는 MACD를, 박스권 시장에서는 볼린저 밴드를 신뢰합니다. 두 지표가 일치하면 신뢰도가 상향됩니다. 볼린저 스퀴즈와 동시에 발생하는 MACD 크로스는 가장 강한 진입 신호로 취급됩니다.

거래량 변화(7일 vs 30일 평균)를 포함한 모든 기술적 데이터가 더 나은 추천을 위해 AI 프롬프트에 공급됩니다. STRONG BUY 종목의 경우 모멘텀 세부 정보(MACD 크로스/히스토그램, %B, 스퀴즈 상태 포함)가 이메일과 Telegram 메시지에 직접 표시됩니다.

지정가 가격

Gemini가 STRONG BUY 또는 BUY를 추천할 때는 현재 시장가보다 약간 낮은 지정가도 함께 제안합니다. 제안 가격은 가장 가까운 지지선을 기반으로 합니다:

이동평균 지지 — 가격이 50일 또는 200일 이동평균 근처에 있을 때
최근 저점 — 7일 또는 30일 저점이 지지의 바닥 역할
라운드 넘버 — 정수 가격대의 심리적 지지

지정가 가격과 그 근거는 일일 이메일, Telegram 메시지, 장중 알림에서 STRONG BUY 종목에 한해 표시됩니다.

가치 투자 프레임워크

개별 주식(ETF나 암호화폐 제외)에 대해 AI는 구조화된 가치 투자 프레임워크를 적용하고 다섯 가지 펀더멘털 기준을 바탕으로 A–D 등급을 매깁니다:

ROE > 15% — 강한 수익성
부채/자본 < 50% — 보수적인 레버리지
FCF/영업현금흐름 > 80% — 강한 현금 전환력
이익 성장률 플러스 — 성장하는 사업
주가가 애널리스트 목표가 이하 — 시장 저평가

등급	충족 기준 수	의미
A	4–5	우수한 가치
B	3	양호한 가치
C	1–2	보통의 가치
D	0	고평가

가치 등급은 AI의 신뢰도 점수 계산에 반영되며 (A는 약 10점 가산, D는 약 10점 차감) 이메일과 Telegram 출력에서 컬러 배지로 표시됩니다.

모든 펀더멘털 데이터는 Yahoo Finance의 financialData 모듈에서 가져오며 기존 quoteSummary 호출에 추가되어 — 추가 API 부담은 0입니다.

바닥 신호 모델

모든 종목(주식, ETF, 암호화폐)에 대해 AI는 잠재적인 매집 구간을 감지하기 위해 4가지 바닥 지표를 평가합니다:

RSI < 30 — 과매도 영역
거래량 위축 > 20% — 매도세 소진 (7일 평균 vs 직전 30일 평균)
가격이 200일선 이하 — 깊은 가치 영역
데드 크로스 존재 — 이미 가격에 반영되었을 가능성 (RSI가 매우 낮을 때는 역추세 신호)

오탐을 줄이기 위해 자산 유형별로 임계값을 다르게 둡니다:

암호화폐 (BTC, ETH): 지표 2개 이상이면 바닥 신호 표시. 3개 이상이면 STRONG BUY 격상 고려.
주식 및 ETF: 지표 3개 이상이어야 바닥 신호 표시(더 엄격). 4가지 모두 정렬되어야 STRONG BUY 격상 고려.

바닥 신호는 일일 이메일, 장중 알림, Telegram 메시지에서 표시됩니다. 거래량 변화 데이터는 기존 차트 데이터에서 계산되므로 — 추가 API 호출이 없습니다.

배분 격차 분석

현재 보유 종목을 목표 배분 비중과 비교합니다. 각 종목은 목표에서 얼마나 떨어져 있는지 점수가 매겨지며, 달러 금액과 주식 수로 매수 추천이 제공됩니다.

분석은 실제 포트폴리오 가치와 설정된 추정치 중 더 큰 값을 사용하므로, 현재 보유 자산이 목표 포트폴리오 규모보다 작더라도 격차 계산이 의미 있게 유지됩니다.

동적 P/E 신호

후행 P/E는 Yahoo Finance의 실적 이력 데이터에서 도출한 과거 평균 P/E와 비교됩니다. 수동으로 기준을 설정할 필요가 없습니다 — 시스템이 분기별 EPS 데이터를 가져와 자동으로 평균을 계산합니다.

과거 평균 P/E보다 낮게 거래되는 종목은 below avg(잠재 가치)로 표시되고, 그보다 높으면 above avg(잠재적 고평가)로 표시됩니다. ETF와 암호화폐는 실적 데이터가 없으므로 이 신호를 자연스럽게 건너뜁니다.

ETF 중첩 감지

목표 포트폴리오의 ETF에서 상위 보유 종목인 개별 주식을 본인이 직접 보유하고 있다면, Richfolio는 중첩을 감지하고 해당 ETF의 매수 우선순위를 그만큼 낮춥니다.

예시: AAPL 30주를 보유하고 있고 VOO가 약 7%의 AAPL을 포함한다면, 직접 보유한 AAPL이 VOO의 배분 격차 일부를 이미 메우고 있습니다. VOO에 대한 추천 매수 금액은 중첩 가치만큼 줄어듭니다.

이는 ETF를 통해 본인이 이미 보유 중인 종목에 본의 아니게 과도하게 집중되는 것을 방지해 줍니다.

52주 범위 신호

각 종목의 현재 가격은 52주 범위 내에서 위치가 산정됩니다 (0% = 저점, 100% = 고점):

저점 근접 (20% 미만) — 잠재적인 매수 기회
고점 근접 (80% 초과) — 주의 필요
중간 영역 — 중립

AI 분석은 이 신호를 P/E 및 배분 데이터와 함께 추천에 반영합니다.

감성 점수가 포함된 뉴스 다이제스트

NewsAPI에서 종목별 톱 헤드라인을 무료 플랜 1일 100건 한도 내에 머물도록 배치 요청으로 가져옵니다. 최근 24시간 헤드라인을 회사명 매핑을 이용해 종목과 매칭합니다.

Gemini는 관련 헤드라인 각각에 다음을 점수화합니다:

감성: 강세, 약세, 또는 중립
영향도: 높음, 중간, 또는 낮음 (주가를 얼마나 움직일 수 있는지)
전체 감성: 종목별 집계 (강세, 약세, 중립, 또는 혼합)

감성 태그는 AI 프롬프트의 헤드라인 옆에 표시되며 (예: "Apple beats estimates" [bullish, high impact]) 전체 뉴스 감성 평가에 반영됩니다. 이는 기존의 이분법적인 관련/비관련 필터를 더 풍부한 신호 추출로 대체합니다 — 추가 API 비용 없이(같은 Gemini 호출, 더 풍부한 출력 스키마).

추론 이력 영속화

매일 실행 이후 Richfolio는 모든 AI 추천의 스냅샷(액션, 신뢰도, 가격, 근거)을 7일치 롤링 이력 파일(state/reasoning-history.json)에 저장합니다. 다음 실행에서 AI는 자신의 확신이 어떻게 변화해 왔는지를 보여주는 “HISTORICAL CONTEXT” 섹션을 받습니다:

AAPL: BUY 72% ($185) → BUY 68% ($187) → HOLD 55% ($192) — weakening
SMH: HOLD 45% ($220) → BUY 70% ($210) → STRONG BUY 85% ($205) — strengthening

이를 통해 AI는 확신 모멘텀을 식별할 수 있습니다 — 어떤 종목이 3일 이상 연속으로 강해지고 있다면 추세를 확인할 수 있고, 약해지고 있다면 더 신중해집니다. 이는 인지 상태를 감사 가능한 커밋으로 추적하는 OpenAlice의 brain/memory 영속화 개념에서 영감을 받았습니다.

GitHub Actions에서는 state/ 디렉토리에 actions/cache를 사용하면 워크플로우 실행 간 추론 이력을 영속화할 수 있습니다.

포트폴리오 헬스

현재 보유 종목으로부터 두 가지 포트폴리오 단위 지표를 계산합니다:

가중 베타 — 포지션 크기로 가중된 포트폴리오 단위 시장 리스크
예상 연간 배당 수익 — 현재 배당 수익률과 포지션 크기를 기반으로 한 연간 배당 추정치

장중 알림

오늘의 매수 타이밍을 놓치지 마세요. 아침 브리핑이 실행된 후 Richfolio는 AI 추천을 기준선으로 저장합니다. 장중 체크(npm run intraday)는 장중 시간대에 2시간마다 실행되며, 가격과 기술적 지표를 다시 가져오고, Gemini 분석을 재실행(API 할당량 절약을 위해 뉴스는 건너뜀)한 뒤 아침 기준선과 비교합니다.

알림은 다음 경우에만 발동합니다:

신뢰도가 최소 5%p 이상 상승 (설정 가능)하고 동시에 80%를 초과할 때 (설정 가능)
액션 격상 — 예를 들어 아침의 BUY가 오후에 STRONG BUY가 될 때
새로운 신호 — 아침에 추천되지 않았던 종목이 이제 강한 매수 신호를 보일 때

알림은 이메일과 Telegram으로 전달되며, 아침 vs 현재 비교, 가격 변동, AI 근거, STRONG BUY 신호의 지정가 가격을 보여주는 집중된 포맷을 사용합니다. 알림이 없으면 메시지도 없습니다 — 중요한 순간에만 Richfolio가 연락합니다.

모든 임계값은 CONFIG_JSON 변수의 intradayAlerts 섹션을 통해 설정할 수 있습니다. 자세한 내용은 설정을 참고하세요.

Intraday Alert

주간 리밸런싱 리포트

별도의 주간 리포트(npm run weekly)는 오로지 포트폴리오 드리프트와 리밸런싱 액션에만 집중합니다. 뉴스도, AI도 없습니다 — 깔끔한 표 하나만 보여줍니다:

BUY — 비중 부족 포지션 (격차 > 1%)
TRIM — 비중 과다 포지션 (격차 < -1%)
OK — 목표 범위 내 포지션

비중 과다 경고를 포함하고, 목표 포트폴리오에 없는 보유 종목도 표시합니다.

Weekly Rebalance

듀얼 전달

모든 리포트는 두 채널을 통해 전달됩니다:

이메일 — Resend를 통한 다크 테마 HTML 이메일로 모든 세부 정보 포함 (배분 표, P/E 신호, AI 추천, 기술적 모멘텀, 지정가, 뉴스)
Telegram — Telegram Bot API를 통한 압축된 일반 텍스트 요약, 모바일 읽기에 최적화 (STRONG BUY의 기술적 지표와 지정가 포함)

두 채널은 독립적으로 동작합니다 — 한쪽이 설정되어 있지 않아도 다른 쪽은 정상적으로 전달됩니다.