tg12/congressional-filings-explorer

# 国会财务披露分析工具 [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) 一款智能模式匹配工具，用于利用AI驱动的光学字符识别技术分析公开可用的国会财务披露文件。 ## 法律免责声明 **本软件仅供信息和教育目的使用。** **本软件不构成投资建议、财务建议、法律建议或任何形式的专业建议。** 本软件生成的信息**不应**作为任何投资、财务或法律决策的唯一依据。 ### 局限性与责任 本软件的开发者、贡献者和分发者： - 不对任何分析的准确性、完整性或可靠性作任何明示或暗示的保证 - 对于因使用本软件而产生的任何损失、损害或后果不承担任何责任 - 不保证数据提取或任何AI生成分析的正确性 - 对基于此工具输出做出的投资决策不承担责任 ### 用户责任 用户必须： - 独立验证所有信息 - 在做出投资决策前咨询合格的财务、法律和税务专业人士 - 理解过往交易活动并不能预测未来表现 - 认识到AI生成的分析可能存在错误或误判 **通过使用本软件，您确认并同意这些条款，并为自己的决定承担全部责任。** ## 概述 该工具利用先进的AI视觉能力，自动处理众议院财务披露PDF文件。它提取关于国会议员披露的股票交易、资产持有和其他财务数据的结构化信息。 ### 主要功能 - **AI驱动分析**：使用具有视觉能力的模型进行模式识别 - **批量处理**：同时分析多份申报文件，以获得更广泛的洞察 - **自动刷新**：当数据过时时下载新的XML元数据 - **多线程**：并行获取PDF以提高性能 - **安全性**：无硬编码凭证——使用环境变量 - **丰富输出**：格式化的表格和全面的分析摘要 ## 安装说明 ### 前置条件 - Python 3.8 或更高版本 - `poppler-utils` 系统包（用于PDF处理） ### 系统依赖项 **macOS:** ``` brew install poppler ``` **Ubuntu/Debian:** ``` sudo apt-get install poppler-utils ``` **Windows:** 从这里下载：https://github.com/oschwartz10612/poppler-windows/releases ### Python 包 ``` pip install -r requirements.txt ``` **必需包：** - `pandas` - 数据处理 - `requests` - HTTP 请求 - `colorlog` - 彩色控制台输出 - `fake-useragent` - 用户代理轮换 - `tabulate` - 表格格式化 - `pdf2image` - PDF 转图像 ## 配置 ### OpenAI API 密钥 将你的 OpenAI API 密钥设置为环境变量： ``` export OPENAI_API_KEY='your-api-key-here' ``` 从这里获取你的 API 密钥：https://platform.openai.com/api-keys **要进行永久配置**，请添加到你的 shell 配置文件中： ``` # ~/.zshrc 或 ~/.bashrc export OPENAI_API_KEY='your-api-key-here' ``` ### 配置常量 编辑 `load_xml.py` 以自定义行为： ``` DEFAULT_DAYS = 30 # Time window for filtering (days) DEFAULT_TOP_N = None # Number of results to display (None = all) MAX_XML_AGE_DAYS = 2 # XML refresh threshold (days) OPENAI_MODEL = "gpt-4.1-mini" # AI model to use ``` ## 使用 ### 完整分析模式 处理申报文件并执行 AI 分析： ``` python3 load_xml.py ``` ### 测试模式 仅进行数据处理，不调用 API： ``` python3 load_xml.py --test ``` ## 工作原理 ### 工作流程 1. **下载/刷新 XML**：从众议院披露服务器获取最新元数据 2. **解析记录**：加载并验证申报信息 3. **按日期过滤**：应用时间过滤器（最近 N 天） 4. **构建 URL**：构造 PDF 下载链接 5. **获取 PDF**：并行下载文档（20个线程） 6. **转换为图像**：将 PDF 页面渲染为 PNG 图像 7. **AI 分析**：将图像发送到 OpenAI Vision API 进行模式识别 8. **显示结果**：显示格式化的表格和全面的摘要 ### 数据处理 ``` House Disclosure Server ↓ XML Metadata ↓ Pandas DataFrame ↓ Date Filtering ↓ PDF URLs ↓ Parallel Download (20 threads) ↓ PDF → PNG Images ↓ Base64 Encoding ↓ OpenAI Vision API ↓ Analysis Summary ``` ## 输出 ### 示例输出 ``` ================================================================================ Congressional Financial Disclosure Analysis Tool v1.0.0 ================================================================================ [1/7] Loading XML metadata... Loaded 1,234 total disclosure records [2/7] Processing filing dates... 1,234 records with valid dates [3/7] Filtering to last 30 days... 15 recent filings match filter ... ================================================================================ FILING METADATA ================================================================================ Last First DocID FilingDate Year Smith John 12345678 2025-10-20 2025 Doe Jane 12345679 2025-10-19 2025 ... ================================================================================ PDF URLS ================================================================================ 1. https://disclosures-clerk.house.gov/.../2025/12345678.pdf 2. https://disclosures-clerk.house.gov/.../2025/12345679.pdf ... ================================================================================ COMPREHENSIVE STOCK ANALYSIS SUMMARY ================================================================================ [AI-generated analysis appears here] ================================================================================ ``` ## 性能考量 ### API 成本 - 每个 PDF 页面消耗视觉模型 tokens - 批量处理限制：每 PDF 3 页，总计 20 张图像 - 估计成本：每份申报文件约 $0.01-0.05（因模型定价而异） ### 处理时间 - XML 下载：5-10 秒 - PDF 获取（并行）：10-30 秒处理 10-20 份申报文件 - AI 分析：30-60 秒，取决于图像数量 - **总计**：典型批处理约 1-2 分钟 ### 资源使用 - 内存：处理期间约 500MB-1GB - 网络：每份申报文件下载约 5-20MB - 磁盘：极小（仅 XML 缓存） ## 数据来源 **众议院财务披露** https://disclosures-clerk.house.gov/ 本工具处理的所有数据均属于根据《政府道德法》和众议院规则提交的公开信息。 ## 故障排除 ### "未找到 XML 文件" 工具会自动下载 XML。如果失败： 1. 检查网络连接 2. 验证是否能访问 https://disclosures-clerk.house.gov/ 3. 尝试先以测试模式运行：`python3 load_xml.py --test` ### "pdf2image 不可用" 安装系统依赖项： ``` # macOS brew install poppler # Ubuntu/Debian sudo apt-get install poppler-utils ``` 然后重新安装 Python 包： ``` pip install --upgrade pdf2image ``` ### "OpenAI API 错误" 常见问题： - **API 密钥无效**：验证密钥是否正确且有效 - **速率限制**：等待后重试，或减小批量大小 - **超时**：在代码中增加超时时间或处理更少的图像 - **配额用尽**：检查 OpenAI 计费仪表板 ### "未找到 filing" 增加回溯时间： ``` DEFAULT_DAYS = 60 # Increase from 30 to 60 days ``` ## 开发 ### 项目结构 ``` 2025FD/ ├── load_xml.py # Main application ├── 2025FD.xml # Cached XML metadata (auto-generated) ├── requirements.txt # Python dependencies └── README.md # This file ``` ### 代码质量 - **类型提示**：函数签名使用类型注解 - **文档字符串**：所有函数的全面文档 - **错误处理**：特定的异常处理和信息丰富的消息 - **日志记录**：彩色控制台输出，便于调试 - **安全性**：无硬编码凭证，基于环境变量的配置 ### 贡献 1. Fork 仓库 2. 创建一个特性分支 3. 进行更改并附带适当的文档 4. 彻底测试（包括 `--test` 模式） 5. 提交拉取请求 ## 许可证 MIT 许可证 - 详见 LICENSE 文件 ## 致谢 - **数据来源**：美国众议院书记官办公室 - **AI 模型**：OpenAI GPT-4 Vision - **PDF 处理**：pdf2image 库 - **社区**：开源贡献者 ## 免责声明（再次强调） **本工具仅供信息目的。它不是投资建议。** 在做出财务决策前，请始终进行自己的研究并咨询合格的专业人士。本工具的创建者对您如何使用此信息不承担任何责任。 ## 支持 如果你觉得这个项目有用，可以考虑支持它： | 货币 | 地址 | |----------|---------| | **Bitcoin (BTC)** | `3QjWqhQbHdHgWeYHTpmorP8Pe1wgDjJy54` | | **Ethereum (ETH)** | `0x5851e6145F4773d1585b8686095FB16E368a4dA1` | | **ZCash (ZEC)** | `t1KSR5YkNPbjqRSCoLKo5AddFWdm9Kzxh1B` |

标签：AI视觉技术, Apex, BSD, MIT许可, PDF处理, Petitpotam, Python, SEO优化, 人工智能, 信息检索, 光学字符识别, 公开数据, 占用监测, 国会成员财务, 国会财务披露, 政府文档, 数据分析工具, 数据挖掘, 数据提取, 文档处理, 无后门, 机器学习, 模式匹配, 用户模式Hook绕过, 结构化数据, 股票交易分析, 自动化分析, 自动化资产收集, 财务数据, 财务监管, 资产管理, 跨站脚本, 逆向工具, 金融分析