## 새 기능
- GET /universe/screen — 과거 날짜 기준 시총/섹터/거래소 필터링
- GET /universe/registry — 추적 종목 목록 조회
- POST /universe/admin/discover — yfinance screener로 US 주식 자동 등록
- POST /universe/admin/build-snapshots — SEC EDGAR × yfinance 월별 시총 스냅샷 생성
## 데이터 모델
- universe_ticker_registry: 종목 마스터 (ticker, name, cik, sector, industry, exchange)
- universe_snapshot: 월별 스냅샷 (ticker, snapshot_date, market_cap, close_price, shares_outstanding)
- 인덱스: (snapshot_date, market_cap) — 핵심 스크리닝 쿼리 최적화
- ~4000종목 × 120개월 ≈ 480K 행 예상
## 데이터 흐름
1. SEC EDGAR companyfacts → shares_outstanding (최신, 주가분할 반영)
2. yfinance bulk download 1mo interval → 월별 종가
3. market_cap = latest_shares × close_price (yfinance 분할조정 가격과 일관성)
## 제한사항
- Survivorship bias: 현재 상장 종목만 (상폐 종목 미포함)
- 자사주 매입으로 과거 시총 ~20% 오차 가능 (분할 오차 방지가 주목적)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1. Earnings Surprise: Alpha Vantage → SEC EDGAR XBRL 전환
- companyfacts API에서 EarningsPerShareDiluted/Basic 추출
- QoQ surprise 계산 (현재 EPS - 이전 분기 EPS)
- 15일 이내 중복 분기 제거 (10-Q 우선)
- force_refresh 시 기존 데이터 삭제 후 재인덱싱
- API 키 불필요, 2009년~ 커버리지
2. Insider transactions: days max 1095→3650, older pages 3→10
3. FINRA: 이전 커밋에서 이미 days=3650, limit=10000 적용됨
F1: SEC Form 4 내부자 거래 (insider transactions)
- GET /insider/transactions/{symbol} — Form 4 거래 내역 조회
- GET /insider/summary/{symbol} — 3/6/12개월 매수/매도 집계
- SEC EDGAR submissions JSON → Form 4 XML 파싱 → DB 저장
- 자동 인덱싱 (첫 조회 시 SEC에서 페치)
- joint filing, derivative/non-derivative 거래 모두 지원
F2: Earnings Surprise (Alpha Vantage)
- GET /earnings/surprise/{symbol} — 분기별 EPS surprise
- reported EPS vs estimated EPS, beat/miss streak 계산
- ALPHA_VANTAGE_API_KEY 환경변수 필요 (무료 tier: 25 req/day)
- DB 캐싱으로 반복 호출 시 API 절약
F3: FINRA Short Volume 확장
- days 파라미터: max 365 → 3650 (10년)
- limit 파라미터: max 1000 → 10000
- 5년치 백필 완료 반영
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- docs/DATA_COVERAGE.md 신규 생성: 엔드포인트별 실제 DB 보유 범위,
이론적 최대 범위, 백필 방법, SQL 확인 쿼리 포함
- FINRA/Alpaca/stocks/filings 엔드포인트 description에 데이터 범위 및
백필 방법 안내 추가 (Swagger UI에 표시됨)
현재 백필 필요 항목:
- FINRA: 2026-02-10~ 28거래일만 존재 → 2025년치 백필 권장
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- CHANGELOG: v3.0.2 (Attention 서브시스템), v3.0.3 (ETF as_of_date 버그 수정) 항목 추가
- README: ETF Holdings 섹션에 정확한 날짜 매칭 / stale 방지 설명 추가
- README: Attention 서브시스템 Features 및 Available Endpoints 섹션 추가
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- _load_snapshot_holdings(): DB 캐시 스냅샷이 as_of_date와 120일 초과
차이나면 stale로 판단하고 None 반환 → SEC 신규 fetch 트리거
- _find_best_filing_and_xml(): eligible 필터에 365일 하한 추가,
target_date 기준 1년 이내 파일링만 우선 후보로 사용
(하한 내 후보 없으면 기존 전체 검색 fallback 유지)
수정 전: SPY?as_of_date=2021-06-30 → 2019-11-18 (19개월 stale)
수정 후: SPY?as_of_date=2021-06-30 → 2021-05-28 (정상)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
period=None으로 history() 호출 시 발생하던
AttributeError: 'NoneType' object has no attribute 'lower' 수정.
upstream 변경사항:
- HistoricalDataCache.get/store/normalize에 period=None 가드 추가
- start/end 날짜 범위 요청 시 불필요한 pickle 캐시 시도 제거
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
## Overlay 버그 수정
- **collect_all 동시성 오류**: asyncio.gather로 공유 DB 세션에 동시 접근 → SQLAlchemy 오류
발생. 어댑터를 순차 실행으로 변경
- **feedparser/apscheduler/pytrends 미설치**: Docker 이미지 재빌드로 패키지 영구 포함
- **중복 job log 항목**: _log_job이 매번 새 행 삽입 → running+completed 중복 생성.
기존 running 행을 업데이트하도록 수정
- **admin/health 잘못된 job_type**: yahoo_rss/wikimedia 등 존재하지 않는 타입 조회.
실제 로깅되는 collect_all/feature_build만 조회하도록 수정
- **source_presence 항상 false**: z-score가 계산 불가능하면(2일 미만 데이터) source가
false로 표시됨. 실제 데이터 존재 여부(headline_count_24h > 0 등)로 판단하도록 수정
- **top-movers 심볼 중복**: 파이프라인 실행 횟수만큼 같은 심볼 반복 출력.
심볼별 최신 레코드만 조회하는 서브쿼리로 수정
- **YouTube None 곱셈 오류**: view_count * channel_weight에서 None이면 TypeError.
(or 0) / (or 0.5) 가드 추가
## Trends 기능 수정
- **ThemeTopicMap 자동 시딩**: 파이프라인 최초 실행 시 TOP_50_SYMBOLS에 대한
기본 topic 매핑 자동 생성
- **GOOGLE_TRENDS_ENABLED=true**: docker-compose.yml에 환경변수 추가
- **theme_heat_z 항상 null**: feature_builder에 build_trends_features() 메서드
누락 → OverlayTrendObservation 데이터가 점수에 반영 안 됨. 메서드 추가 및 연결
- **POST /admin/seed-topics**: ThemeTopicMap 수동 시딩용 admin 엔드포인트 추가
## OpenAPI 문서 개선
- 모든 엔드포인트에 summary/description 추가 (filings, news, database, etf, stocks,
screener, fred, attention, overlay)
- Pydantic 스키마에 json_schema_extra example 추가 (attention, filing)
- 누락된 태그 6개 추가 (attention, attention-admin, database, fred, error-logs,
request-logs)
- 루트(/) 랜딩 페이지를 Swagger UI로 리다이렉트로 교체
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
하드코딩된 330줄 HTML을 제거하고 request.app.openapi()에서
동적으로 엔드포인트 목록을 렌더링하도록 변경.
새 라우터 추가 시 / 페이지를 별도로 수정할 필요 없음.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
## 주요 기능
- Entity resolver: ticker → canonical name → Wikipedia 매칭
- SEC company_tickers.json fallback으로 placeholder name 자동 수정
- all-caps SEC 이름 title-case 변환, "Com" suffix 처리
- Wikipedia 페이지뷰 수집 + spike_10d / zscore_20d 피처 계산
- GDELT V2 DOC API 뉴스 기사 수집 (2017-01-01 이후)
## GDELT rate limit 제약 강제
- /event/{ticker} 온디맨드 GDELT 수집 제거 (IP ban 방지)
- 프로세스 전역 asyncio.Lock + 10초 최소 간격 강제
- 429 시 exponential backoff (30→60→120s)
- news.gdelt_status 필드로 클라이언트에 수집 상태 명시
('collected' | 'not_collected' | 'not_available')
## API
- GET /api/v1/attention/event/{ticker}?event_date=YYYY-MM-DD
- GET /api/v1/attention/entity/{ticker}
- POST /api/v1/attention/admin/resolve/{ticker}
- POST /api/v1/attention/admin/collect/wiki/{ticker}
- POST /api/v1/attention/admin/collect/gdelt/{ticker} ← scheduler 전용
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
content.read()로 body를 읽은 후 resp.get_encoding() 호출 시
aiohttp 내부 self._body(None) 접근으로 예외 발생.
이 예외가 except Exception에 잡혀 6번 retry + 지수 backoff(최대 ~22초)
→ asyncio.wait_for 캔슬 → TimeoutError → 504.
Content-Type 헤더에서 charset 직접 파싱으로 교체.
기본값 utf-8, SEC는 대부분 charset 미지정이므로 실질적으로 항상 utf-8 사용.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
index 페이지 + exhibit 두 단계를 15초에 커버하기엔 너무 빡빡함.
미캐시 시 index fetch 최대 8초 + exhibit fetch 최대 12초 = 최악 20초.
max_bytes 수정으로 메모리 고갈은 이미 해결되었으므로
deadline은 25초로 조정 (원래 30초보다 5초 단축).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- fetch_text에 max_bytes 파라미터 추가: Content-Length 헤더로 다운로드 전 사전 reject,
헤더 없으면 content.read(max_bytes+1)로 제한적 읽기
- ValueError는 즉시 raise (retry 없음 — 크기는 재시도해도 안 줄어듦)
- in-memory 캐시(_text_cache) 1MB 가드: 대형 응답은 디스크 캐시에만 저장
- MAX_EXHIBIT_SIZE 1MB → 5MB, fetch_text(max_bytes=...) 호출로 다운로드 전 체크
- exhibit deadline 30초 → 15초 (서비스 + 엔드포인트 + bulk)
- 신규 테스트 5개: Content-Length 사전 거부, body 제한 읽기, 메모리 캐시 가드,
소형 캐시 유지, ValueError no-retry
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- SECHttpClient._deadline(인스턴스 변수) → contextvars.ContextVar로 교체
asyncio task별 독립 데드라인으로 싱글턴 공유로 인한 레이스 컨디션 해결
- bulk exhibit에 Semaphore(4) + 전체 300s 타임아웃 추가
동시 50개 코루틴이 Semaphore(2)를 무제한 점유하던 문제 해결
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- sec_filings_service: 루프 전 accession_number 일괄 pre-fetch로 N+1 제거
- sec_filings_service: 500건 단위 청크 커밋으로 all-or-nothing 트랜잭션 방지
- sec_filings_service: bulk 인덱싱 시 코루틴별 독립 세션 생성으로 동시 세션 충돌 해결
- sec_filings_service: index_filings 데드라인 60s → 120s, bulk timeout 동일 적용
- sec_http_client: _TokenBucket(10 req/sec) 추가로 SEC EDGAR 과부하 방지
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- README/API_DOCUMENTATION에 `just run dev` 개발 서버 실행 방법 추가
- `GET /stocks/index/{index_name}` 엔드포인트 문서화 (sp500/nasdaq100)
- justfile을 프로젝트 파일로 문서에 포함
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
GET /stocks/index/{index_name} 엔드포인트 추가.
sp500/nasdaq100 구성 종목을 Wikipedia에서 실시간 파싱하여 반환.
24시간 Redis 캐시 및 30초 타임아웃 적용.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
asyncio.gather로 동시에 실행되는 exhibit 항목들이 단일 DB 세션을
공유하면서 "concurrent operations are not permitted" 에러 발생.
각 _fetch_one 태스크가 AsyncSessionLocal()로 독립 세션 사용하도록 수정.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
PostgreSQL is the actual DB; create_all handles schema creation.
The SQLite workaround added in the previous commit is not needed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Expose SEC ACCEPTANCE-DATETIME so downstream consumers (filing_poller)
can populate Document.accepted_at_utc and Event.filed_at_utc.
- SECFiling model: add nullable accepted_at TIMESTAMP column
- main.py startup: ALTER TABLE migration for existing SQLite DBs
- sec_filings_service: extract acceptanceDateTime from SEC JSON, store on
INSERT and force_refresh UPDATE
- FilingSummary schema: add Optional[str] accepted_at field
- filings endpoint: map accepted_at as ISO 8601 string in response
- CHANGELOG: v3.0.1 entry
Existing rows have accepted_at=NULL; backfill with force_refresh=true.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Separate Alpaca price data into dedicated AlpacaPriceData table to avoid
UniqueConstraint('ticker', 'date') conflicts with Yahoo Finance PriceData.
Add Redis caching (build_cache_key/get_cached_response/set_cached_response)
to 3 Alpaca endpoints and 2 FINRA query endpoints with appropriate TTLs.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add SEC Filings section to root HTML docs, example requests, key features,
and OpenAPI tags for Swagger UI / ReDoc visibility.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Extract shared SECHttpClient from ETF fetcher (retry, backoff, cache, throttle)
and apply it to both ETF and core SEC services, fixing missing rate limiting.
Add SECFiling DB model, Pydantic schemas, SECFilingsService with auto-indexing,
and REST endpoints at /filings/search, /filings/documents, /filings/exhibit.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Upgrade Node base image from 18-alpine to 20-alpine (npm compatibility)
- Use npm ci instead of npm install for reliable dependency extraction
- Use named volumes for node_modules and .next to avoid anonymous volume issues
- Upgrade React/ReactDOM to ^19.0.0 for Next.js 15.4.6 compatibility
- Change Dockerfile to use --legacy-peer-deps for peer dep conflicts
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
I Luk Kim