convez.ai
AgenteFinanceiroAvançado
leeje008

Stock Portfolio Agent

leeje008/stock-agent

Portfólio inteligente com otimização Black-Litterman e análise AI local

Ver no GitHub
InicialPluginScore · de 0 a 100

Agente IA baseado em Streamlit + Claude/Ollama para gestão integrada de portfólios de ações (KRX, NYSE, NASDAQ, ETFs globais). Realiza otimização média-variância, análise de sentimento de notícias, relatórios de investimento, análise técnica e debates Bull/Bear entre agentes, tudo funcionando localmente sem custos de API.

Instalação

$npx convez-ai leeje008/stock-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gestão integrada de portfólios multi-moeda (KRX/USD/globais) com conversão automática de câmbio
  • Otimização de alocação de ativos usando Mean-Variance e modelos Black-Litterman com visões geradas por IA
  • Análise de sentimento de mercado via scraping de notícias RSS + LLM local para detecção de eventos
  • Geração automática de relatórios de investimento com recomendações baseadas em fundamentais e técnica
  • Backtesting de estratégias com walk-forward e debates estruturados (Bull vs Bear vs Moderador) entre agentes

Veredito

Solução robusta e completa para análise de portfólios, destacando-se pela integração de múltiplos métodos quantitativos (otimização, backtesting) com análise qualitativa via IA local. Excelente para investidores que dominam finanças e buscam automação avançada sem dependência de APIs pagas; requer setup de Ollama local e conhecimento técnico considerável.

README

A tradução para o português deste README ainda está na fila.

Stock Portfolio Agent

한국/미국/글로벌 ETF를 통합 관리하는 AI 기반 주식 포트폴리오 에이전트입니다. 로컬 LLM(Ollama)을 활용하여 과금 없이 뉴스 감성 분석, 투자 추천 리포트, 펀더멘탈 분석, Bull/Bear 토론까지 수행합니다.


주요 기능

1. 포트폴리오 현황 (Tab 1)

  • 한국(KRX) / 미국(NYSE, NASDAQ) / 글로벌 ETF 종목 통합 관리
  • 실시간 시세 조회 (yfinance, pykrx)
  • USD/KRW 환율 자동 적용 — 다중 통화 포트폴리오도 KRW 기준으로 통일된 평가금액 표시
  • 시장별 / 섹터별 비중 파이차트
  • 포트폴리오 성과 추이 차트 — 일별 스냅샷 저장, 90일간 평가금액 vs 매입금액 추이 시각화

2. 포트폴리오 최적화 (Tab 2)

  • Mean-Variance 최적화 — 최대 샤프 비율 / 최소 변동성 전략
  • Black-Litterman 모델 — AI가 종목별 기대수익률 "뷰"를 생성하고, 이를 수학적 모델에 반영하여 최적 비중 산출
  • 이산 배분(Discrete Allocation) — 예산 내 실제 매수 주수 계산
  • 효율적 프론티어 시각화 — 위험-수익 곡선 + 최적 포트폴리오 위치 표시

3. 뉴스 & 시장 분석 (Tab 3)

  • 실제 뉴스 수집 — Google News RSS를 통한 종목별/시장별 뉴스 자동 수집 (API 키 불필요)
  • AI 감성 분석 — 경량 모델(llama3.1:8b)로 빠르게 시장 감성(bullish/neutral/bearish), 주요 이벤트 감지, 종목별 영향도 분석
  • 감성 점수 추이 차트 — 분석 이력을 DB에 저장, 30일간 감성 추이 시각화
  • 거시경제 지표 대시보드 — FRED API 연동 (미국 기준금리, CPI, 실업률, VIX, 10년물 국채금리, 달러인덱스)

4. 매수 가이드 & AI 리포트 (Tab 4)

  • 최적화 결과 기반 종목별 매수 수량 / 투자 금액 / 잔여 현금 안내
  • AI 종합 투자 리포트 — 고성능 모델(qwen3.5:27b)이 포트폴리오, 최적화 결과, 뉴스 분석, 거시경제 데이터를 종합하여 투자 추천 리포트 생성
  • 리포트 Markdown 다운로드 — 생성된 리포트를 파일로 저장
  • 리포트 히스토리 — 과거 생성된 리포트 열람 (SQLite 저장)

5. 기술적 분석 (Tab 5)

  • RSI (14) — 과매수/과매도 구간 판단
  • MACD — 추세 전환 신호
  • 볼린저 밴드 — 가격 변동성 범위
  • 이동평균선 (5, 20, 60, 120일) — 추세 방향
  • 종합 기술적 신호 — 모든 지표를 종합한 매수/매도/중립 판정
  • 인터랙티브 Plotly 차트 (3단 서브플롯: 가격+BB, RSI, MACD)
  • AI 펀더멘탈 분석 — US/ETF 종목의 재무제표(손익, 재무상태표, 현금흐름)를 AI가 분석하여 밸류에이션/수익성/건전성/성장성 평가

6. 백테스팅 (Tab 6)

  • 3가지 전략 비교 백테스트 — 최대 샤프, 최소 변동성, 동일 비중
  • Walk-forward 방식 — 과거 데이터로 최적화, 미래 성과 측정
  • 성과 지표: 총 수익률, 연환산 수익률, 변동성, 샤프 비율, 최대 낙폭(MDD)
  • 자산 곡선 차트 — 전략별 성과 비교 시각화
  • 룩백 기간, 리밸런싱 주기 커스터마이징 가능

7. AI 토론 (Tab 7)

  • Bull vs Bear 멀티 에이전트 토론 — 강세론자와 약세론자 AI가 3라운드에 걸쳐 토론
    • Round 1: Bull 분석가가 낙관적 시나리오 제시
    • Round 2: Bear 분석가가 비관적 시나리오 제시 + Bull 반박
    • Round 3: 중립 Moderator가 양측 의견 종합, 최종 판정
  • 최종 판정: bullish / neutral / bearish + 확신도

아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                     Streamlit 대시보드 (7탭)                       │
│  포트폴리오 │ 최적화 │ 뉴스분석 │ 매수가이드 │ 기술분석 │ 백테스팅 │ AI토론 │
└──────────────────────────┬──────────────────────────────────────┘
                            │
┌──────────────────────────▼──────────────────────────────────────┐
│                      Core Engine (Python)                        │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │ Data Layer   │  │ Optimizer    │  │ AI Agent Module       │  │
│  │              │  │              │  │                       │  │
│  │ • fetcher    │  │ • Max Sharpe │  │ • News Analyzer       │  │
│  │ • news RSS   │  │ • Min Vol    │  │ • Market Analyst      │  │
│  │ • FRED API   │  │ • Black-     │  │ • Fundamental Analyst │  │
│  │ • market_data│  │   Litterman  │  │ • Views Generator     │  │
│  │ • FX rate    │  │ • Backtest   │  │ • Debate (Bull/Bear)  │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬────────────┘  │
│         │                  │                      │              │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌───────────▼───────────┐  │
│  │ yfinance     │  │ PyPortfolio  │  │ Ollama (로컬 LLM)     │  │
│  │ pykrx        │  │ Opt          │  │ • llama3.1:8b (Light) │  │
│  │ FRED API     │  │              │  │ • qwen3.5:27b (Heavy) │  │
│  │ Google RSS   │  │              │  │                       │  │
│  └──────────────┘  └──────────────┘  └───────────────────────┘  │
└──────────────────────────┬──────────────────────────────────────┘
                            │
┌──────────────────────────▼──────────────────────────────────────┐
│                      Data Storage                                │
│  ┌───────────────────────────────────────────────────────────┐   │
│  │ SQLite (stock_agent.db)                                   │   │
│  │ • portfolio_holdings — 보유 종목                            │   │
│  │ • transactions — 거래 내역                                  │   │
│  │ • optimization_history — 최적화 결과                        │   │
│  │ • analysis_reports — AI 리포트                              │   │
│  │ • portfolio_snapshots — 일별 성과 스냅샷                     │   │
│  │ • sentiment_history — 감성 분석 이력                         │   │
│  └───────────────────────────────────────────────────────────┘   │
│  ┌───────────────┐                                               │
│  │ JSON Cache    │ — 시세/뉴스/환율 캐시 (6시간 만료)              │
│  └───────────────┘                                               │
└──────────────────────────────────────────────────────────────────┘

스마트 모델 라우팅

모든 LLM 호출은 100% 로컬(Ollama)로 처리되며, 태스크 복잡도에 따라 자동으로 모델이 선택됩니다.

태스크모델크기응답 속도선택 이유
뉴스 감성 분석 (JSON)llama3.1:8b4.9GB~2초정형 JSON 출력, 단순 분류
BL 뷰 생성 (JSON)llama3.1:8b4.9GB~2초숫자 기대수익률 추정
종합 투자 리포트qwen3.5:27b17GB~15초다중 데이터 종합, 한국어 서술
펀더멘탈 분석qwen3.5:27b17GB~15초재무제표 해석, 밸류에이션 판단
Bull/Bear 토론 (3라운드)qwen3.5:27b17GB~45초복합 추론, 논증

설계 원칙: JSON 분류/추출 → 경량 모델 (빠름) / 서술형 분석·종합 추론 → 고성능 모델 (정확함)


프로젝트 구조

stock-agent/
├── app.py                          # Streamlit 메인 앱 (7탭 대시보드)
├── config.py                       # 환경변수, LLM 설정, DB 경로
├── main.py                         # 엔트리포인트 (stub)
├── pyproject.toml                  # 의존성 관리 (uv)
├── .env.example                    # 환경변수 템플릿
│
├── agent/                          # AI 에이전트 모듈
│   ├── llm_client.py              # Ollama LLM 클라이언트 (듀얼 모델 라우팅)
│   ├── news_analyzer.py           # 뉴스 감성 분석 (light 모델)
│   ├── market_analyst.py          # 종합 투자 리포트 생성 (heavy 모델)
│   ├── fundamental_analyst.py     # 재무제표 펀더멘탈 분석 (heavy 모델)
│   ├── views_generator.py         # Black-Litterman 뷰 생성 (light 모델)
│   ├── debate.py                  # Bull vs Bear 멀티에이전트 토론 (heavy 모델)
│   └── report_generator.py        # 리포트 저장/조회 (SQLite)
│
├── analysis/                       # 분석 엔진
│   ├── technical.py               # 기술적 분석 (RSI, MACD, BB, MA)
│   └── backtest.py                # 전략 백테스팅 (Walk-forward)
│
├── portfolio/                      # 포트폴리오 관리
│   ├── manager.py                 # CRUD (종목 추가/삭제/조회)
│   ├── optimizer.py               # 최적화 엔진 (Max Sharpe, Min Vol, BL)
│   ├── allocator.py               # 예산 배분 & 매수 가이드
│   └── tracker.py                 # 성과 추적 (일별 스냅샷)
│
├── data/                           # 데이터 수집
│   ├── fetcher.py                 # 주가 데이터 (yfinance, pykrx)
│   ├── news_fetcher.py            # 뉴스 수집 (Google News RSS)
│   ├── economic_data.py           # 거시경제 지표 (FRED API)
│   └── market_data.py             # 시세 가공 (수익률, 변동성, 상관관계)
│
├── db/                             # 데이터베이스
│   ├── database.py                # SQLite 초기화 & 연결 (6개 테이블)
│   └── models.py                  # 데이터 모델 (dataclass)
│
├── utils/                          # 유틸리티
│   ├── fx.py                      # USD/KRW 환율 변환
│   ├── helpers.py                 # 캐시 관리, 포매팅
│   └── constants.py               # 상수 (리스크 레벨, FRED 지표 ID)
│
└── data/                           # 데이터 저장 (자동 생성)
    ├── stock_agent.db             # SQLite 데이터베이스
    └── cache/                     # JSON 캐시 파일

기술 스택

구분기술용도
UIStreamlit대시보드, 사용자 입력, 차트 시각화
언어Python 3.11+전체 백엔드
LLMOllama (로컬)뉴스 분석, 리포트 생성, 토론 — 과금 없음
LLM SDKOpenAI Python SDKOllama OpenAI 호환 API 연동
최적화PyPortfolioOptMean-Variance, Black-Litterman, 이산 배분
차트Plotly인터랙티브 차트 (서브플롯, 파이차트, 라인차트)
주가 (미국)yfinanceNYSE/NASDAQ/ETF 시세, 재무제표
주가 (한국)pykrx코스피/코스닥 시세
뉴스feedparserGoogle News RSS 파싱
경제지표fredapiFRED 거시경제 데이터
DBSQLite포트폴리오, 리포트, 스냅샷, 감성 이력
패키지 관리uv의존성 관리 & 가상환경

설치 및 실행

사전 요구사항

  • Python 3.11+
  • Ollama — https://ollama.com 에서 설치
  • uv — pip install uv 또는 curl -LsSf https://astral.sh/uv/install.sh | sh

1. Ollama 모델 준비

ollama pull llama3.1:8b      # Light 모델 (뉴스 분석, JSON 추출)
ollama pull qwen3.5:27b      # Heavy 모델 (종합 리포트, 토론)

2. 프로젝트 설치

git clone https://github.com/leeje008/stock-agent.git
cd stock-agent
uv sync

3. 환경 변수 설정 (선택)

cp .env.example .env
# 필요시 .env 파일을 열어 API 키 입력

참고: .env 파일 없이도 앱의 모든 핵심 기능이 동작합니다. FRED API 키가 있으면 거시경제 지표 기능이 추가로 활성화됩니다.

4. 실행

ollama serve          # Ollama 서버 시작 (이미 실행 중이면 생략)
uv run streamlit run app.py

브라우저에서 http://localhost:8501 접속


환경 변수

변수기본값설명필수
LLM_BASE_URLhttp://localhost:11434/v1Ollama API 주소아니오 (기본값 사용)
LLM_API_KEYollamaOllama는 인증 불필요아니오
LLM_MODEL_LIGHTllama3.1:8b경량 태스크용 모델아니오
LLM_MODEL_HEAVYqwen3.5:27b고성능 태스크용 모델아니오
FRED_API_KEY—FRED 거시경제 지표아니오 (없으면 경제지표 기능 비활성)
DART_API_KEY—DART 기업 공시아니오 (향후 사용 예정)
BOK_API_KEY—한국은행 경제지표아니오 (향후 사용 예정)

데이터베이스 스키마

앱 최초 실행 시 data/stock_agent.db에 SQLite 데이터베이스가 자동 생성됩니다.

테이블용도주요 컬럼
portfolio_holdings보유 종목ticker, market, name, quantity, avg_price, currency, sector
transactions거래 내역ticker, action(BUY/SELL), quantity, price
optimization_history최적화 이력strategy, weights_json, expected_return, volatility, sharpe_ratio
analysis_reportsAI 리포트report_type, content, metadata_json
portfolio_snapshots성과 스냅샷date(UNIQUE), total_value, total_cost, holdings_json
sentiment_history감성 분석 이력date, market_sentiment, sentiment_score, summary

사용 예시

기본 워크플로우

  1. 사이드바에서 종목 추가 — 티커, 시장(US/KR/ETF), 수량, 매입가 입력
  2. Tab 1: 포트폴리오 확인 — 환율 적용된 평가금액, 손익 확인
  3. Tab 2: 최적화 실행 — 전략 선택 후 최적 비중 및 효율적 프론티어 확인
  4. Tab 3: 뉴스 분석 — 실제 뉴스 수집 + AI 감성 분석 실행
  5. Tab 4: AI 리포트 — 모든 분석 결과를 종합한 투자 추천 리포트 생성
  6. Tab 5: 기술적 분석 — 개별 종목의 RSI, MACD, BB 차트 확인
  7. Tab 6: 백테스팅 — 최적화 전략의 과거 성과 검증
  8. Tab 7: AI 토론 — Bull/Bear 관점의 균형 잡힌 투자 의견 확인

예시 포트폴리오

티커시장종목명섹터
AAPLUSApple Inc.Technology
MSFTUSMicrosoftTechnology
005930KR삼성전자Semiconductor
QQQETFInvesco QQQETF

비용 정책

모든 기능 100% 무료로 운영됩니다.

항목비용방식
LLM (AI 분석)무료Ollama 로컬 실행
주가 데이터무료yfinance, pykrx
뉴스 수집무료Google News RSS
경제 지표무료FRED API (무료 키 발급)
데이터 저장무료SQLite 로컬 파일

면책 조항

본 앱은 개인 참고용 도구로만 사용해야 합니다.

  • AI가 생성한 투자 추천은 금융 자문(financial advice)이 아닙니다
  • 최종 투자 결정의 책임은 사용자에게 있습니다
  • 투자에는 원금 손실 위험이 있습니다
  • 이 앱을 타인에게 유료로 제공하면 자본시장법상 투자자문업 등록 의무가 발생할 수 있습니다

향후 개발 계획

  • RAG 기반 심층 분석 — ChromaDB + 임베딩 모델(nomic-embed-text)로 과거 뉴스 검색 기반 분석
  • 섹터 로테이션 전략 — 경기순환 분석 + 섹터별 투자 강도 히트맵
  • PDF 리포트 내보내기 — Markdown → PDF 변환
  • 증권사 API 연동 — 한국투자증권 OpenAPI를 통한 실계좌 조회/주문
  • Telegram/이메일 알림 — 리밸런싱 시점 자동 알림
  • 한국 기업 공시 연동 — DART API를 통한 한국 기업 재무제표/공시 분석

라이선스

이 프로젝트는 개인 학습 및 투자 참고 목적으로 개발되었습니다.

Ver o original no GitHub

Bom para

Relacionados