quant.ai

미국 주식에 대한 퀀트 리서치, AI 어시스턴트 안에서 바로 작동하도록 설계되었습니다. Claude 또는 Codex에 MCP를 통해 연결하고 원하는 티커에 대해 물어보세요 — 설명 가능한 등급, 주요 지지/저항 레벨, 그리고 그 근거를 얻은 후, 같은 채팅에서 논의할 수 있습니다. 또한 한 줄 명령어로 실행되는 CLI로도 사용 가능합니다.

English | 中文

quant.ai는 미국 주식을 위한 명령줄 기반 퀀트 리서치 도구로, 일반 투자자를 위해 만들어졌습니다. 하나의 명령어를 입력하면 설명 가능한 등급, 주요 지지/저항 레벨, 그리고 그 근거를 얻을 수 있습니다 — 모두 과거 가격 데이터에서 도출되며, 완전히 오프라인에서 작동하고, 증권사와 연결되지 않습니다.

⚠️ 리서치 전용 — 투자 조언이 아닙니다. 실제 주문을 제안하거나 실행하지 않습니다. 출력은 기본적으로 영어입니다. --lang zh를 추가하거나 (quant-ai init에서 선택) 중국어(中文)로 설정할 수 있습니다.

빠른 시작

pip install -e .          # or: pip install -r requirements.txt
quant-ai doctor           # environment self-check (deps + data connectivity)
quant-ai analyze AAPL     # rate one stock in seconds

진입점이 없나요? python -m quant_agent analyze AAPL도 동일하게 작동합니다.

Related MCP server: mcp-financex

제공되는 기능

quant-ai analyze AAPL의 실제 출력 — 기본적으로 영어, --lang zh는 중국어. 등급은 Strong Buy부터 Neutral, Strong Sell까지 있습니다. --output-dir을 추가하면 Markdown + JSON으로 내보내거나, --chart를 추가하면 PNG 차트를 얻을 수 있습니다.

Claude 또는 Codex 내에서 사용하기

핵심 기능 — quant.ai를 MCP 서버로 노출하여 AI 어시스턴트가 호출할 수 있게 합니다:

claude mcp add quant-research -- python -m quant_agent.mcp_server

그러면 작업 중인 동일한 채팅에서 다음과 같이 물어보기만 하면 됩니다:

"NVDA에 대한 평가는?" · "TSLA 좀 봐줘." · "AAPL 15주를 182.5에 샀어 — 추적해줘." · "내 포지션은 어때?" · "오늘 시장 보고서 생성해줘."

Claude(또는 Codex)가 실제 프로젝트 데이터를 호출하여 퀀트 분석 결과를 보여주고, 인라인으로 논의할 수 있습니다 — 별도의 웹사이트나 복사-붙여넣기가 필요 없습니다. 일일 보고서는 보유 종목 손익으로 시작하며 정교한 HTML 아티팩트로 렌더링됩니다. Claude Desktop / Codex 설정에 대한 자세한 내용은 매뉴얼(중국어)을 참조하세요.

AI 어시스턴트가 직접 설치하도록 하세요 — 이 내용을 Claude Code(또는 모든 AI CLI)에 붙여넣으면 모든 설정을 자동으로 처리합니다:

Install https://github.com/TingdeLiu/quant.ai as an MCP server:
1. git clone https://github.com/TingdeLiu/quant.ai && cd quant.ai
2. pip install -e .
3. claude mcp add quant-research -- python -m quant_agent.mcp_server
4. Verify: `claude mcp list` should show quant-research ✓ connected

주요 특징

• 🤖 AI 어시스턴트 내에서 작동 — 핵심 기능입니다. 내장된 MCP 서버를 Claude 또는 Codex에 연결하고 *"NVDA에 대한 평가는?"*이라고 물어보세요. 이 프로젝트에서 실제 퀀트 분석 결과를 가져와서 분석 결과를 보고 한 번의 대화로 논의할 수 있습니다. 대부분의 주식 분석 도구는 독립형 웹사이트이지만, 이 도구는 이미 대화 중인 AI에 내장되어 있습니다.

• 💼 채팅으로 관리하는 관심목록 및 보유 종목. Claude에게 "NVDA 관심 등록" 또는 *"AAPL 15주를 182.5에 샀어"*라고 말하면 — 로컬 data/portfolio.json에 저장되며, 모든 분석에 자동으로 포함되고, 일일 보고서는 보유 종목과 미실현 손익으로 시작합니다(최선의 실시간 시세, 실패 시 마지막 종가 사용).

• 🖼️ 아티팩트 지원 일일 보고서 — 시장 브리핑은 Claude가 인라인 아티팩트로 렌더링하는 독립형 라이트/다크 HTML 파일로 제공됩니다. Markdown과 JSON도 함께 기록됩니다.

• 🎯 설정 불필요 단일 주식 분석 — analyze AAPL은 등급, 수익률, RSI, 변동성, 이동평균 위치, 지지/저항 레벨, 사람이 읽을 수 있는 이유를 반환합니다.

• 🧩 개인화된 관심목록 — quant-ai init은 2/3는 사용자 직접 선택(관심 있는 회사 + 섹터)과 1/3은 엔진이 광범위한 시장에서 발견한 종목으로 구성된 유니버스를 구축합니다.

• 🔬 리서치 백테스트 — 횡단면 신호(12-1 모멘텀, 20/50 추세, 1개월 반전, 저변동성), 신호 가중치 검색, 워크포워드 안정성 분석, SPY 및 동일가중 벤치마크를 포함하여 알파와 베타를 분리합니다.

• 📊 로컬 콘솔 — 한 페이지에 4개의 탭(보고서 / 시장 / 백테스트 진단 / 운영)으로 구성되며, 스택 전체에 API 키 없이 로컬에서 제공됩니다.

• 🛡️ 안전한 설계 — 결정론적 신호 + 위험 계층, 네트워크/데이터 오류에 대한 우아한 성능 저하, 페이퍼 트레이딩 전용 — 실제 주문을 제출하지 않습니다.

일일 시장 보고서 및 로컬 콘솔

quant-ai market-report는 Anthropic 스타일 디자인의 일일 미국 주식 리서치 브리핑을 생성하며, 네 가지 형식으로 제공됩니다: 전체 HTML 페이지, 독립형 아티팩트 조각, Markdown 및 JSON. 한 페이지에 4개의 탭 — 보유 종목, 시장, 아이디어, 뉴스 — 이 순수 CSS로 전환되므로 AI 클라이언트의 샌드박스 아티팩트 뷰 내에서도 작동합니다.

보유 종목 — 포지션이 먼저

브리핑은 손익으로 시작합니다: 시장 가치, 미실현 손익, 일일 손익, 포지션별 스파크라인(최선의 실시간 시세, 실패 시 마지막 종가 사용). 바로 아래 보유 종목 한눈에 보기에서 각 포지션에 대한 카드를 제공합니다 — 포트폴리오 비중, 추세 상태, 5일/1개월/3개월 수익률, 연간 변동성, 1년 최대 낙폭, 52주 최고가 대비 거리, 벤치마크 대비 강도, 매도 측 애널리스트 범위, 퀀트 리스트 내 위치, 최근 헤드라인, 그리고 클릭하여 확장 가능한 1주~5년 종가 차트.

이 섹션은 의도적으로 사실만 제시합니다. 매수/매도 추천이나 가격 예측이 포함되지 않습니다 — 테스트에서 문구가 벗어나지 않는지 확인합니다. 이는 리서치 도구이지 면허를 받은 조언자가 아닙니다: 증거를 제시하고 결정은 사용자에게 맡깁니다.

포지션별 뉴스 요약은 **직접 작성되었으며 data/news_digest.json**에서 읽어옵니다({as_of, digests: {SYMBOL: "한 줄"}} 형식) — 프로젝트는 이를 위해 LLM API를 호출하지 않습니다. 해당 파일의 as_of가 보고서 데이터 날짜보다 오래된 경우 각 카드에 "digest as of …" 스탬프가 찍히므로, 오래된 요약이 오늘의 것으로 오인되지 않습니다.

시장 — 실제 시장 상황

단순히 지수 수치를 인용하는 대신: 벤치마크의 일일/5일/1개월/3개월 수익률과 52주 최고가 대비 거리, 낙폭 및 변동성; VIX 위험 게이지와 지난 1년 백분위수; 시장 폭 측정기 — 5일/1개월 동안 상승한 종목 비율과 20일/50일 이동평균선 위에 있는 종목 비율(단일 주식만 집계하므로 수십 개의 지수 ETF가 수치를 부풀리지 않음); 섹터 로테이션 — 11개 SPDR 섹터 ETF를 1개월 움직임 순으로 정렬하고 벤치마크 대비 초과 수익률 표시; 펀드 추적기 — 광범위 지수, 테마(반도체, AI) 및 교차 자산(VIX, 장기 국채, 금, 달러, 원유)으로 그룹화하여 주식 외 자금 흐름을 보여줍니다.

아이디어 — 퀀트 추천, 잠재력 및 고위험

보유 기간(장기 / 중기 / 단기)별로 분류된 리서치 추천, 각각 애널리스트 밸류에이션 범위 막대, 일일 변동, 위험 및 신뢰도 태그 포함 — 이미 보유 중인 포지션은 상단에 고정되어 강조 표시됩니다. 그 아래 잠재력 추천 및 고위험 표는 각 종목이 선정된 통계적 이유를 설명합니다. 지수 및 섹터 ETF는 두 목록에서 제외됩니다.

로컬 콘솔

quant-ai serve-dashboard는 4개의 탭(보고서, 시장, 백테스트 진단, 운영)이 있는 로컬 페이지를 제공하며, 별도의 디자인 대신 보고서의 스타일을 재사용합니다. write-dashboard는 백테스트 진단 페이지를 단독으로 실행 출력 옆에 기록합니다. 페이지 언어는 설정 파일의 language: 설정을 따릅니다.

일반 명령어

작동 방식

1. 데이터 — 기본적으로 Yahoo Finance(yfinance)의 일일 OHLCV, 또는 로컬 CSV/Parquet. 캐시 및 검증됨.

2. 신호 — 횡단면, 시점 지연 요인, 일별 z-점수화.

3. 포트폴리오 및 위험 — 포지션/회전율/유동성 제한 하의 결정론적 목표 비중.

4. 평가 — 훈련 / 검증 / 테스트 분할, 워크포워드 윈도우, 벤치마크 대비 지표(샤프, 소르티노, 칼마, 최대 낙폭, 알파/베타).

5. AI — 프로젝트는 자체적으로 LLM API를 호출하지 않습니다. 확인 가능한 사실(정량적 통계, 규칙 기반 등급, 제3자 컨센서스)을 제공합니다. 종합 및 논의는 MCP 서버가 마운트된 AI 클라이언트에서 이루어지므로, API 키, 추가 비용, 데이터와 사용자 사이의 두 번째 모델이 없습니다.

문서

• 전체 매뉴얼 (중국어): docs/manual_zh.md — 상세 설정, 백테스트/워크포워드, 대시보드 API, MCP 통합, 출력 파일.

• 변경 로그: CHANGELOG.md · 기여 가이드: CONTRIBUTING.md · 로드맵: roadmap.md

테스트

python -m pytest      # 106 tests, network-free
python -m ruff check quant_agent tests conftest.py

면책 조항

이 프로젝트는 퀀트 리서치 및 교육 목적으로만 제공됩니다. 과거 가격을 분석하고 리서치 신호를 생성합니다 — 투자 조언이 아니며, 거래를 승인하지 않습니다. 시장에는 위험이 따르며, 모든 결정에 대한 책임은 사용자에게 있습니다.

라이선스

MIT