Add free source configuration pack

Author: Pigbibi

README.md

@@ -99,6 +99,9 @@ python scripts/import_truthsocial_export.py \
 uploads `source_events.csv` plus `source_tracker.csv` as a GitHub Actions
 artifact. It is intentionally artifact-only and does not publish recommendations.
 
+Free-source setup notes are in
+[`docs/free_source_setup.zh-CN.md`](docs/free_source_setup.zh-CN.md).
+
 Run the synthetic event study:
 
 ```bash

README.zh-CN.md

@@ -121,3 +121,5 @@ python -m pytest -q
 3. **点名后是否有可交易的统计优势**：需要事件研究和样本外验证，不能只看少数轶事案例。
 
 本仓库先解决前两步的数据结构和复盘框架；第三步需要更多点位和真实行情输入。后续如果需要 LLM 处理长文本，只能作为可替换的抽取工具，不能把模型判断结果写成核心信号合同。
+
+免费数据源配置见 [docs/free_source_setup.zh-CN.md](docs/free_source_setup.zh-CN.md)。

config/core_us_equity_aliases.csv

@@ -0,0 +1,40 @@
+symbol,name,aliases
+AAPL,Apple,Apple|AAPL|iPhone|iPad|Mac|Tim Cook
+AMD,Advanced Micro Devices,AMD|Advanced Micro Devices|Radeon|EPYC|Instinct
+AMZN,Amazon,Amazon|AMZN|AWS|Amazon Web Services|Project Kuiper
+AVGO,Broadcom,Broadcom|AVGO|VMware
+BA,Boeing,Boeing|BA|737 MAX|Starliner
+COIN,Coinbase,Coinbase|COIN|crypto exchange
+CRWD,CrowdStrike,CrowdStrike|CRWD|Falcon cybersecurity
+CVX,Chevron,Chevron|CVX
+ENPH,Enphase Energy,Enphase|ENPH|solar inverter
+F,Ford,Ford|F|F-150|Mustang Mach-E
+GE,GE Aerospace,GE Aerospace|General Electric|GE|jet engine
+GME,GameStop,GameStop|GME
+GOOGL,Alphabet,Alphabet|Google|GOOGL|GOOG|Gemini|Waymo
+INTC,Intel,Intel|INTC|foundry|CHIPS Act
+IONQ,IonQ,IonQ|IONQ|quantum computing
+JPM,JPMorgan Chase,JPMorgan|JPMorgan Chase|JPM|Jamie Dimon
+LMT,Lockheed Martin,Lockheed Martin|LMT|F-35|missile defense
+META,Meta Platforms,Meta|META|Facebook|Instagram|WhatsApp|Llama
+MSFT,Microsoft,Microsoft|MSFT|Azure|OpenAI|Copilot
+MSTR,Strategy,Strategy|MicroStrategy|MSTR|Michael Saylor|Bitcoin treasury
+MU,Micron Technology,Micron|MU|HBM|DRAM|NAND
+NEE,NextEra Energy,NextEra|NEE|renewable energy
+NOC,Northrop Grumman,Northrop Grumman|NOC|B-21
+NVDA,NVIDIA,NVIDIA|Nvidia|NVDA|Blackwell|CUDA|GPU
+OKLO,Oklo,Oklo|OKLO|nuclear reactor|advanced nuclear
+ORCL,Oracle,Oracle|ORCL|cloud infrastructure
+PANW,Palo Alto Networks,Palo Alto Networks|PANW|cybersecurity
+PLTR,Palantir,Palantir|PLTR|Gotham|Foundry|AIP
+QCOM,Qualcomm,Qualcomm|QCOM|Snapdragon
+RBLX,Roblox,Roblox|RBLX
+RTX,RTX,RTX|Raytheon|Pratt Whitney|missile
+SMCI,Super Micro Computer,Supermicro|Super Micro|SMCI|AI server
+SMR,NuScale Power,NuScale|SMR|small modular reactor
+SOFI,SoFi Technologies,SoFi|SOFI
+TSLA,Tesla,Tesla|TSLA|Elon Musk|Cybertruck|FSD|Optimus|xAI
+TSM,Taiwan Semiconductor,TSMC|Taiwan Semiconductor|TSM|foundry
+UNH,UnitedHealth Group,UnitedHealth|UNH|UnitedHealthcare
+VRT,Vertiv,Vertiv|VRT|data center power|liquid cooling
+XOM,Exxon Mobil,Exxon|ExxonMobil|XOM

config/free_rss_feeds.csv

@@ -0,0 +1,4 @@
+feed_id,feed_url,source_type,author
+whitehouse-presidential-actions,https://www.whitehouse.gov/presidential-actions/feed/,official_remarks,White House
+sec-press-releases,https://www.sec.gov/news/pressreleases.rss,regulatory_action,SEC
+sec-speeches-statements,https://www.sec.gov/news/speeches-statements.rss,regulatory_action,SEC

config/free_x_queries.csv

@@ -0,0 +1,3 @@
+query_id,query,source_type,author_label
+trump-ai-defense-energy,from:realDonaldTrump (NVIDIA OR NVDA OR Tesla OR TSLA OR Intel OR INTC OR Boeing OR Lockheed OR nuclear OR energy OR chip OR tariff OR defense) -is:retweet,verified_social_post,Donald Trump
+official-sec-company,from:SECGov (NVIDIA OR Tesla OR Intel OR Microsoft OR Amazon OR Coinbase OR crypto OR AI) -is:retweet,verified_social_post,SEC

data/live/political_events.csv

@@ -0,0 +1 @@
+event_id,event_date,symbol,event_type,direction,confidence,source_url,notes

data/live/political_watchlist.csv

@@ -0,0 +1,39 @@
+symbol,name,bucket,research_status,thesis,source_url
+AAPL,Apple,named_mentioned,watchlist,"AI devices, supply-chain, tariff, antitrust, and platform-policy watch.",https://www.apple.com/investor-relations/
+AMD,Advanced Micro Devices,named_mentioned,watchlist,"AI accelerator and semiconductor export-control watch.",https://ir.amd.com/
+AMZN,Amazon,named_mentioned,watchlist,"Cloud AI, government procurement, logistics, and antitrust watch.",https://ir.aboutamazon.com/
+AVGO,Broadcom,named_mentioned,watchlist,"AI networking, VMware, and semiconductor policy watch.",https://investors.broadcom.com/
+BA,Boeing,policy_capital,watchlist,"Aerospace, defense procurement, export, and safety-regulatory watch.",https://investors.boeing.com/
+COIN,Coinbase,named_mentioned,watchlist,"Crypto policy, SEC enforcement, and market-structure watch.",https://investor.coinbase.com/
+CRWD,CrowdStrike,policy_capital,watchlist,"Cybersecurity and government security-spend watch.",https://ir.crowdstrike.com/
+CVX,Chevron,policy_capital,watchlist,"Energy policy, permitting, oil/gas, and geopolitical-risk watch.",https://chevroncorp.gcs-web.com/
+ENPH,Enphase Energy,policy_capital,watchlist,"Solar, tariff, tax-credit, and grid policy watch.",https://investor.enphase.com/
+F,Ford,policy_capital,watchlist,"EV subsidy, tariff, labor, and industrial-policy watch.",https://shareholder.ford.com/
+GE,GE Aerospace,policy_capital,watchlist,"Aerospace procurement and export-control watch.",https://www.geaerospace.com/investor-relations
+GOOGL,Alphabet,named_mentioned,watchlist,"AI, antitrust, cloud, search, and autonomous-driving policy watch.",https://abc.xyz/investor/
+INTC,Intel,policy_capital,watchlist,"CHIPS Act, foundry, export-control, and domestic semiconductor policy watch.",https://www.intc.com/
+IONQ,IonQ,named_mentioned,watchlist,"Quantum computing and government research funding watch.",https://investors.ionq.com/
+JPM,JPMorgan Chase,named_mentioned,watchlist,"Bank regulation, rates, credit, and market-structure watch.",https://www.jpmorganchase.com/ir
+LMT,Lockheed Martin,policy_capital,watchlist,"Defense procurement, missile defense, and geopolitics watch.",https://investors.lockheedmartin.com/
+META,Meta Platforms,named_mentioned,watchlist,"AI, social regulation, privacy, antitrust, and metaverse watch.",https://investor.fb.com/
+MSFT,Microsoft,named_mentioned,watchlist,"AI, cloud procurement, antitrust, and cybersecurity watch.",https://www.microsoft.com/en-us/Investor
+MSTR,Strategy,named_mentioned,watchlist,"Bitcoin treasury, crypto regulation, and capital-market sentiment watch.",https://www.strategy.com/investor-relations
+MU,Micron Technology,policy_capital,watchlist,"Memory, HBM, export-control, and domestic semiconductor policy watch.",https://investors.micron.com/
+NEE,NextEra Energy,policy_capital,watchlist,"Power demand, renewable policy, grid, and data-center energy watch.",https://www.investor.nexteraenergy.com/
+NOC,Northrop Grumman,policy_capital,watchlist,"Defense procurement, drone/space, and geopolitical-risk watch.",https://investor.northropgrumman.com/
+NVDA,NVIDIA,policy_capital,watchlist,"AI accelerator, export-control, data-center, and sovereign AI policy watch.",https://investor.nvidia.com/
+OKLO,Oklo,policy_capital,watchlist,"Advanced nuclear, data-center power, and DOE/NRC policy watch.",https://oklo.com/investors/
+ORCL,Oracle,named_mentioned,watchlist,"Cloud infrastructure, sovereign cloud, and AI data-center watch.",https://investor.oracle.com/
+PANW,Palo Alto Networks,policy_capital,watchlist,"Cybersecurity, federal spend, and breach-response watch.",https://investors.paloaltonetworks.com/
+PLTR,Palantir,policy_capital,watchlist,"Defense AI, government procurement, and public-sector software watch.",https://investors.palantir.com/
+QCOM,Qualcomm,named_mentioned,watchlist,"Mobile AI, China exposure, export-control, and auto-chip watch.",https://investor.qualcomm.com/
+RBLX,Roblox,named_mentioned,watchlist,"Youth safety, platform policy, and gaming/metaverse watch.",https://ir.roblox.com/
+RTX,RTX,policy_capital,watchlist,"Defense procurement, aerospace supply chain, and missile-demand watch.",https://investors.rtx.com/
+SMCI,Super Micro Computer,named_mentioned,watchlist,"AI server, data-center supply chain, and governance watch.",https://ir.supermicro.com/
+SMR,NuScale Power,policy_capital,watchlist,"Small modular reactor, nuclear policy, and DOE/NRC watch.",https://www.nuscalepower.com/en/investors
+SOFI,SoFi Technologies,named_mentioned,watchlist,"Fintech, bank regulation, student-loan policy, and consumer-credit watch.",https://investors.sofi.com/
+TSLA,Tesla,named_mentioned,watchlist,"EV, autonomy, energy storage, tariff, safety, and Elon Musk social signal watch.",https://ir.tesla.com/
+TSM,Taiwan Semiconductor,policy_capital,watchlist,"Semiconductor foundry, export-control, Taiwan risk, and CHIPS policy watch.",https://investor.tsmc.com/
+UNH,UnitedHealth Group,named_mentioned,watchlist,"Healthcare policy, Medicare, antitrust, and regulatory watch.",https://www.unitedhealthgroup.com/investors.html
+VRT,Vertiv,policy_capital,watchlist,"Data-center power, cooling, AI infrastructure, and grid constraints watch.",https://investors.vertiv.com/
+XOM,Exxon Mobil,policy_capital,watchlist,"Energy policy, drilling, LNG, and geopolitical-risk watch.",https://corporate.exxonmobil.com/investors

docs/free_source_setup.zh-CN.md

@@ -0,0 +1,83 @@
+# 免费数据源配置
+
+## 已落地文件
+
+- `config/free_rss_feeds.csv`：无需账号的官方 RSS 源。
+- `config/core_us_equity_aliases.csv`：核心美股观察池别名。
+- `config/free_x_queries.csv`：X recent-search 查询模板，需要 `X_BEARER_TOKEN` 后才能运行。
+- `data/live/political_watchlist.csv`：真实发布链路的初始观察池。
+- `data/live/political_events.csv`：人工核验后的真实事件输入，初始为空表头。
+
+## 免费且无需注册
+
+当前可直接跑：
+
+- White House presidential actions RSS。
+- SEC press releases RSS。
+- SEC speeches/statements RSS。
+- Federal Register API：无需 API key，适合作为下一步 API adapter。
+- USAspending API：公开 endpoints 当前不需要 authorization，适合做政府合同/资金流 adapter。
+
+运行 RSS：
+
+```bash
+gh workflow run "RSS Source Pipeline" \
+  --repo QuantStrategyLab/PoliticalEventTrackingResearch \
+  -f feeds_path=config/free_rss_feeds.csv \
+  -f aliases_path=config/core_us_equity_aliases.csv \
+  -f max_items_per_feed=25
+```
+
+## 免费但需要注册 key
+
+- X API Recent Search：需要 X Developer / App Bearer Token。免费层是否够用取决于 X 当前政策和额度。
+- Congress.gov API：需要 api.data.gov key，通常可免费申请。
+
+配置 X：
+
+```bash
+gh secret set X_BEARER_TOKEN \
+  --repo QuantStrategyLab/PoliticalEventTrackingResearch
+```
+
+运行 X：
+
+```bash
+gh workflow run "X Recent Search Pipeline" \
+  --repo QuantStrategyLab/PoliticalEventTrackingResearch \
+  -f queries_path=config/free_x_queries.csv \
+  -f aliases_path=config/core_us_equity_aliases.csv \
+  -f max_results=10
+```
+
+## 免费但建议谨慎
+
+- Truth Social 没有稳定官方公开开发者接口。当前建议先用导出 JSON 或经确认合规的第三方工具，再导入 `source_items.csv`。
+- 开源 `truthbrush` 可作为候选工具，但应先做合规和稳定性验证，不能直接作为高置信来源。
+
+## 开源项目候选
+
+- Federal Register 官方 API core：`usnationalarchives/federalregister-api-core`
+- USAspending 官方 API：`fedspendingtransparency/usaspending-api`
+- SEC EDGAR downloader：`jadchaar/sec-edgar-downloader`
+- SEC EDGAR package：`sec-edgar/sec-edgar`
+- Truth Social candidate：`w2rc/truthbrush`
+
+这些项目只作为 adapter 参考，不直接引入依赖。当前仓库优先用标准库和 CSV artifact，降低 VPS 与供应链风险。
+
+## 推荐运营流程
+
+1. RSS/X/Truth Social 先生成 `source_items.csv` 和 `source_events.csv`。
+2. 人工核验后，把确认事件写入 `data/live/political_events.csv`。
+3. 发布 Advisor 时使用：
+
+```bash
+gh workflow run "Publish Model Recommendations Site" \
+  --repo QuantStrategyLab/QuantAdvisorResearch \
+  -f as_of=2026-05-30 \
+  -f political_events_path=data/live/political_events.csv \
+  -f political_watchlist_path=data/live/political_watchlist.csv \
+  -f ai_signal_path=data/output/latest_signal.json
+```
+
+如果 `political_events_path` / `political_watchlist_path` 不在 `examples/` 下，Advisor 输出会标记为 `source_mode=operator_supplied`。

src/political_event_tracking_research/source_mention_extract.py

@@ -60,6 +60,8 @@ def load_aliases(path: str | Path) -> list[MentionAlias]:
 
 def alias_pattern(alias: str) -> re.Pattern[str]:
     escaped = re.escape(alias)
+    if re.fullmatch(r"[A-Za-z]", alias):
+        return re.compile(rf"(?<![A-Za-z0-9])\${escaped}(?![A-Za-z0-9])", re.IGNORECASE)
     if re.fullmatch(r"[A-Za-z][A-Za-z0-9.\-]{0,9}", alias):
         return re.compile(rf"(?<![A-Za-z0-9$])\$?{escaped}(?![A-Za-z0-9])", re.IGNORECASE)
     return re.compile(escaped, re.IGNORECASE)
@@ -145,4 +147,3 @@ def main(argv: list[str] | None = None) -> None:
 
 if __name__ == "__main__":
     main()
-

tests/test_source_mention_extract.py

@@ -17,6 +17,15 @@ def test_match_symbols_supports_ticker_and_name_aliases() -> None:
     assert match_symbols("PREVT1 should not match.", aliases) == []
 
 
+def test_single_letter_ticker_requires_cash_tag_or_name_alias() -> None:
+    aliases = [MentionAlias(symbol="F", aliases=("F", "Ford", "F-150"))]
+
+    assert match_symbols("5 C.F.R. mentions investment workforce.", aliases) == []
+    assert match_symbols("$F is mentioned.", aliases) == ["F"]
+    assert match_symbols("Ford is mentioned.", aliases) == ["F"]
+    assert match_symbols("F-150 policy is mentioned.", aliases) == ["F"]
+
+
 def test_extract_source_records_outputs_confidence_by_source_type(tmp_path: Path) -> None:
     output = tmp_path / "source_events.csv"
 
@@ -32,4 +41,3 @@ def test_extract_source_records_outputs_confidence_by_source_type(tmp_path: Path
     assert by_symbol["EVT3"]["confidence"] == "low"
     assert by_symbol["EVT4"]["event_type"] == "procurement"
     assert output.exists()
-