From d03f46edbf396431000670dd70f4d1587a079586 Mon Sep 17 00:00:00 2001 From: I Luk Kim Date: Wed, 18 Mar 2026 11:08:24 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20README/CHANGELOG=20=EC=97=85=EB=8D=B0?= =?UTF-8?q?=EC=9D=B4=ED=8A=B8=20=E2=80=94=20Attention=20=EC=84=9C=EB=B8=8C?= =?UTF-8?q?=EC=8B=9C=EC=8A=A4=ED=85=9C=20=EB=B0=8F=20ETF=20=EB=82=A0?= =?UTF-8?q?=EC=A7=9C=20=EC=88=98=EC=A0=95=20=EB=B0=98=EC=98=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CHANGELOG.md | 21 +++++++++++++++++++++ README.md | 27 +++++++++++++++++++++++---- 2 files changed, 44 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 92a1504..0cb35d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,27 @@ All notable changes to Stock Oracle API will be documented in this file. +## [3.0.3] - 2026-03-18 + +### Fixed +- **ETF Holdings `as_of_date` 정확도**: 요청 날짜에 가장 가까운 파일링을 반환하도록 수정 + - `_load_snapshot_holdings()`: DB 캐시 스냅샷과 `as_of_date` 간격이 120일 초과 시 stale 판단, SEC 신규 fetch 트리거 + - `_find_best_filing_and_xml()`: eligible 후보 필터에 365일 하한 추가 — target_date 기준 1년 이내 파일링 우선 탐색 + - 수정 전: `SPY?as_of_date=2021-06-30` → 2019-11-18 (19개월 stale) + - 수정 후: `SPY?as_of_date=2021-06-30` → 2021-05-28 (정상) + +## [3.0.2] - 2026-03-17 + +### Added +- **Attention 서브시스템**: 이벤트 중심 Wikipedia/GDELT 관심도 피처 (백테스팅용) + - `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}` — Wikipedia 페이지뷰 수집 + - `POST /api/v1/attention/admin/collect/gdelt/{ticker}` — GDELT 뉴스 아티클 수집 + - Wikipedia 일별 페이지뷰 스파이크 / z-score 계산 + - GDELT GKG 아티클 수 기반 언론 노출 지표 + ## [3.0.1] - 2026-03-14 ### Added diff --git a/README.md b/README.md index d3e6c09..4bd31f9 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,13 @@ Stock Oracle is a comprehensive investment analysis API that leverages SEC EDGAR - **Error Handling**: Detailed error categorization and reporting - **Migration Support**: Database transfer capabilities +### Attention Subsystem (NEW! 🆕) +- **Event-Centric Features**: Wikipedia pageviews + GDELT news coverage for backtesting +- **Spike Detection**: Daily pageview spike ratio and z-score vs. rolling baseline +- **GDELT Integration**: News article count from GDELT GKG (global knowledge graph) +- **Entity Resolution**: Ticker → canonical Wikipedia entity mapping +- **On-Demand Collection**: Collect data per event date without full precomputation + ### Alpaca Market Data (NEW! 🆕) - **Official REST API**: Alpaca Market Data v2 with proper authentication - **OHLCV + VWAP**: Daily/intraday bars with volume-weighted average price @@ -580,19 +587,24 @@ curl "http://localhost:18001/api/v1/fred/stats/usage" # Monitor API usage ( # Get latest holdings for QQQ curl "http://localhost:18001/api/v1/etf/holdings/QQQ" -# Get holdings for specific date -curl "http://localhost:18001/api/v1/etf/holdings/QQQM?as_of_date=2024-01-01" +# Get holdings for specific date (returns closest prior NPORT-P filing) +curl "http://localhost:18001/api/v1/etf/holdings/SPY?as_of_date=2021-06-30" # Without detailed holdings (metadata only) curl "http://localhost:18001/api/v1/etf/holdings/SPY?include_holdings=false" + +# Bypass Redis cache to force fresh fetch +curl "http://localhost:18001/api/v1/etf/holdings/SPY?as_of_date=2021-06-30&force_refresh=true" ``` #### Key Features - **Automatic CIK Lookup**: No need to know CIK numbers - just use ticker symbols - **Historical Data Support**: Access NPORT filings from 2019 onwards +- **Accurate Date Matching**: Returns the closest NPORT-P filing ≤ `as_of_date` within 365-day window +- **Stale Cache Prevention**: DB snapshots >120 days from requested date trigger fresh SEC fetch - **Date Validation**: Automatically checks if ETF existed on requested date - **Availability Info**: Returns available date ranges when data not found -- **Fast Performance**: <0.1s response time with launch date caching +- **Fast Performance**: <0.1s response time for cached results; Redis-backed 1-hour cache #### Response with Availability Information ```json @@ -758,9 +770,16 @@ curl "http://localhost:18001/api/v1/news/NVDA/social-only?days_back=3&max_social - `GET /api/v1/fred/stats/usage` - API usage statistics and daily limit monitoring #### ETF Holdings -- `GET /api/v1/etf/holdings/{ticker}` - Get ETF holdings with date support +- `GET /api/v1/etf/holdings/{ticker}` - Get ETF holdings with date support (closest NPORT-P filing) - `POST /api/v1/etf/admin/refresh-maps` - Refresh ETF CIK mappings +#### Attention (Backtesting Features) +- `GET /api/v1/attention/event/{ticker}` - Event-date attention features (Wikipedia pageviews + GDELT coverage) +- `GET /api/v1/attention/entity/{ticker}` - Canonical entity info for ticker +- `POST /api/v1/attention/admin/resolve/{ticker}` - Resolve ticker → canonical entity +- `POST /api/v1/attention/admin/collect/wiki/{ticker}` - Collect Wikipedia pageview data +- `POST /api/v1/attention/admin/collect/gdelt/{ticker}` - Collect GDELT news article data + #### Financial Data - `GET /api/v1/financial/data/{ticker}` - Simple financial data with query parameters - `POST /api/v1/financial/data` - Detailed financial data request