# Value-Chain Public Source Catalog

This catalog maps the Korean stock-price-factor taxonomy in `inputs/taxonomy_headings.txt` to practical collection targets for the value-chain dashboard. It favors sources that are public, documented, and suitable for repeatable batch collection without scraping private pages or bypassing rate limits.

## Public / No Key

| Taxonomy area | Collectable source | Fields / artifacts | Notes |
| --- | --- | --- | --- |
| 1.1-1.7 revenue, margin, earnings, cash flow, balance sheet, growth | SEC EDGAR submissions and companyfacts | 10-K/10-Q/8-K metadata, XBRL facts, frames, fiscal periods, units | US issuers only. Use SEC `company_tickers.json`, submissions, and companyfacts APIs with a respectful User-Agent. |
| 1.11-1.14 governance, buybacks, dilution, accounting, events | SEC EDGAR submissions | Filing forms, accession numbers, report dates, primary documents | Public metadata is collectable; detailed event interpretation is downstream NLP/rules work. |
| 2.1-2.5 macro, rates, inflation, FX, commodities | FRED graph CSV, U.S. Treasury yield-curve XML, Yahoo chart proxies | Treasury rates, Fed funds, CPI/PCE, unemployment, USD/KRW, major FX pairs, crude, gold, copper | FRED graph CSV endpoints can be fetched without an API key for many series. U.S. Treasury XML is an official fallback for yield-curve tenors. Yahoo chart is an availability/proxy source, not an official reference feed. |
| 3.5 index / ETF / passive context | Yahoo chart proxies | Index and ETF proxy prices/volumes | Public proxy only; holdings and flows are incomplete without issuer/paid data. |
| 4.2 information flow, 4.4 themes / stories | GDELT 2.1 Doc API, Google News RSS URL plans | Query URLs, article metadata from GDELT, RSS item metadata where allowed | The scaffold plans URLs and can sample metadata. It does not aggressively scrape article bodies. |
| 5.1-5.5 relative value, factors, alternative assets | Yahoo chart proxies, SEC companyfacts | Market prices, basic valuation inputs derived from fundamentals | Full factor history and consensus valuation require licensed data for production-grade backtests. |
| 6.1-6.7 industry-specific context | SEC filings, macro proxies, commodity proxies, news plans | Industry tags from filings where available, sector-sensitive macro/commodity series | Industry semantics should be layered on top of raw source collection. |

## Requires Key

| Taxonomy area | Source | Required secret | Fields / artifacts | Notes |
| --- | --- | --- | --- | --- |
| 1.1-1.14 Korean company fundamentals, filings, governance, events | OpenDART | `OPENDART_API_KEY` | company list, filings, financial statements, major events | Marked `needs_key` when the environment variable is absent. Do not print the key. |
| 2.x macro extensions | FRED API | `FRED_API_KEY` optional | richer metadata, realtime periods, release tables | The first pass uses no-key graph CSV where possible. |
| 4.2 information flow extensions | News APIs | provider-specific key | normalized article metadata, source quality signals | Optional enrichment beyond GDELT/RSS planning. |

## Paid / Proprietary / Limited

| Taxonomy area | Source class | Fields / artifacts | Why limited |
| --- | --- | --- | --- |
| 3.1 investor-by-investor flows, 3.3 short selling / stock lending, 3.4 margin credit | Exchange terminals, broker feeds, KRX data vendors | investor net buys, lending balances, borrow fees, short interest, margin balances | Public KR data exists in fragments, but complete clean point-in-time coverage is vendor-grade. |
| 3.5 ETF flows / ownership, 3.6 derivatives positioning | ETF issuer files, options/futures feeds, data vendors | creations/redemptions, holdings, options greeks, open interest history | Public files are incomplete, delayed, or hard to normalize globally. |
| 4.1 market expectations, analyst revisions | FactSet, LSEG, Bloomberg, S&P Capital IQ, Visible Alpha, broker feeds | consensus EPS/revenue, target prices, estimate revisions, recommendation changes | Redistribution and systematic use normally require paid licenses. |
| 5.3 style/factor analytics | MSCI, Barra, Axioma, Bloomberg, academic/vendor factor files | exposures, risk model returns, factor covariance | Public proxies are possible, but production-quality risk models are proprietary. |

## Not Collectable As Raw Public Data

| Taxonomy area | Examples | Treatment |
| --- | --- | --- |
| 4.3 behavioral finance / sentiment, 4.5 market regime | fear, greed, crowding, narrative exhaustion | Derive from public proxies, news volume, volatility, flows, and price behavior; do not treat as directly observed truth. |
| 7.x time-horizon checklists and event interpretation | short/medium/long-term impact paths | Analysis framework, not a source. |
| 8.x scoring framework and scenarios | factor score, good/base/bad scenarios | Dashboard modeling layer, not source collection. |
| 9.x industry-opposite effects | same factor affecting industries differently | Rule/model layer using collected source facts. |
| 10.x references | bibliography | Documentation only. |

## Production Caveats

Public data is often revised, delayed, or lacks point-in-time semantics. The first production pass should store raw responses, fetch timestamps, URLs, request parameters, source status, and downstream normalization version. Paid datasets are required for analyst revisions, clean global ownership/flows, and complete short-lending coverage.