Skill: tangweigang-jpg/sec-edgar-tools (version 0.3.3)

--- name: sec-edgar-tools description: |- 从 SEC EDGAR 系统获取和解析公司监管文件，支持 SEC 文件检索、财务报表（10-K/10-Q）提取、内部人交易（Form 4）追踪及机构持仓（13F）分析。。 license: Proprietary. See LICENSE.txt in project root. compatibility: Designed for Doramagic-host ecosystem (Claude Code / openclaw / Cursor). Requires Python 3.12+ with uv package manager. metadata: version: "v6.1" blueprint_id: "finance-bp-070" compiled_at: "2026-04-22T13:00:24.449859+00:00" capability_markets: "multi-market" capability_activities: "data-sourcing" sop_version: "crystal-compilation-v6.1" --- # SEC EDGAR 工具 (sec-edgar-tools) > 从 SEC EDGAR 系统获取和解析公司监管文件，支持 SEC 文件检索、财务报表（10-K/10-Q）提取、内部人交易（Form 4）追踪及机构持仓（13F）分析。 ## Pipeline `data_collection -> data_storage -> factor_computation -> target_selection -> trading_execution -> visualization` ## Top Use Cases (55 total) ### SEC Filing Discovery and Company Lookup (`UC-101`) Discovering and retrieving SEC filings for companies to understand their regulatory submissions, corporate actions, and financial disclosures **Triggers**: sec filings, company lookup, edgar search ### Company Financials Retrieval (`UC-102`) Extracting financial data from SEC filings to analyze company performance, including income statements, balance sheets, and cash flows **Triggers**: financials, income statement, balance sheet ### Insider Transaction Tracking (Form 4) (`UC-103`) Tracking insider buying and selling activities by processing Form 4 filings to identify significant insider transactions and ownership changes **Triggers**: insider trading, form 4, insider transactions For all **55** use cases, see [references/USE_CASES.md](references/USE_CASES.md). **Execute trigger**: `When user intent matches intent_router.uc_entries[].positive_terms AND user uses action verb (run/execute/跑/执行/backtest/fetch/collect)` ## What I'll Ask You - Target market: A-share (default), HK, or crypto? (US stocks in ZVT are half-baked — stockus_nasdaq_AAPL exists but coverage is thin) - Data source / provider: eastmoney (free, no account), joinquant (account+paid), baostock (free, good history), akshare, or qmt (broker)? - Strategy type: MACD golden-cross, MA crossover, volume breakout, fundamental screen, or custom factor? - Time range: start_timestamp and end_timestamp for backtest period - Target entity IDs: specific stocks (stock_sh_600000) or index components (SZ1000)? ## Semantic Locks (Fatal) | ID | Rule | On Violation | |---|---|---| | `SL-01` | Execute sell orders before buy orders in every trading cycle | halt | | `SL-02` | Trading signals MUST use next-bar execution (no look-ahead) | halt | | `SL-03` | Entity IDs MUST follow format entity_type_exchange_code | halt | | `SL-04` | DataFrame index MUST be MultiIndex (entity_id, timestamp) | halt | | `SL-05` | TradingSignal MUST have EXACTLY ONE of: position_pct, order_money, order_amount | halt | | `SL-06` | filter_result column semantics: True=BUY, False=SELL, None/NaN=NO ACTION | halt | | `SL-07` | Transformer MUST run BEFORE Accumulator in factor pipeline | halt | | `SL-08` | MACD parameters locked: fast=12, slow=26, signal=9 | halt | Full lock definitions: [references/LOCKS.md](references/LOCKS.md) ## Top Anti-Patterns (14 total) - **`AP-DATA-SOURCING-001`**: Missing or invalid User-Agent headers for SEC API requests - **`AP-DATA-SOURCING-002`**: Ignoring external API rate limits causing IP blocking - **`AP-DATA-SOURCING-003`**: No HTTP timeout configuration causing indefinite hangs All 14 anti-patterns: [references/ANTI_PATTERNS.md](references/ANTI_PATTERNS.md) ## Evidence Quality Notice > [QUALITY NOTICE] This crystal was compiled from blueprint finance-bp-070. Evidence verify ratio = 39.3% and audit fail total = 36. Generated results may have uncaptured requirement gaps. Verify critical decisions against source files (LATEST.yaml / LATEST.jsonl). ## Reference Files | File | Contents | When to Load | |---|---|---| | [references/seed.yaml](references/seed.yaml) | V6+ 全量权威 (source-of-truth) | 有行为/决策争议时必读 | | [references/ANTI_PATTERNS.md](references/ANTI_PATTERNS.md) | 14 条跨项目反模式 | 开始实现前 | | [references/WISDOM.md](references/WISDOM.md) | 跨项目精华借鉴 | 架构决策时 | | [references/CONSTRAINTS.md](references/CONSTRAINTS.md) | domain + fatal 约束 | 规则冲突时 | | [references/USE_CASES.md](references/USE_CASES.md) | 全量 KUC-* 业务场景 | 需要完整示例时 | | [references/LOCKS.md](references/LOCKS.md) | SL-* + preconditions + hints | 生成回测/交易代码前 | | [references/COMPONENTS.md](references/COMPONENTS.md) | AST 组件地图（按 module 拆分）| 查 API 时 | --- *Compiled by Doramagic crystal-compilation-v6.1 from `finance-bp-070` blueprint at 2026-04-22T13:00:24.449859+00:00.* *See [human_summary.md](human_summary.md) for non-technical overview.*

path: human_summary.md
content: # Human Summary

> I help you build quant strategies on A-share with ZVT — from data fetch to backtest, one flow. Just tell me what you want; I'll write the code, you don't have to dig docs. (Heads up: ZVT natively supports A-share, HK, and crypto. US stocks — stockus_nasdaq_AAPL — are half-baked; don't bother for serious work.)

## What I Can Do

- **tagline**: I help you build quant strategies on A-share with ZVT — from data fetch to backtest, one flow. Just tell me what you want; I'll write the code, you don't have to dig docs. (Heads up: ZVT natively supports A-share, HK, and crypto. US stocks — stockus_nasdaq_AAPL — are half-baked; don't bother for serious work.)
- **use_cases**: ['Insider Transaction Tracking (Form 4)', 'Company Financials Retrieval', 'SEC Filing Discovery and Company Lookup', 'A-share MACD daily golden-cross backtest with hfq price adjustment from eastmoney', 'End-to-end ZVT pipeline: FinanceRecorder + GoodCompanyFactor + StockTrader', 'Multi-factor strategy with TargetSelector (AND mode) combining MACD + volume breakout', 'Index composition data collection (SZ1000, SZ2000) with EM recorder']

## What I Ask You

- Target market: A-share (default), HK, or crypto? (US stocks in ZVT are half-baked — stockus_nasdaq_AAPL exists but coverage is thin)
- Data source / provider: eastmoney (free, no account), joinquant (account+paid), baostock (free, good history), akshare, or qmt (broker)?
- Strategy type: MACD golden-cross, MA crossover, volume breakout, fundamental screen, or custom factor?
- Time range: start_timestamp and end_timestamp for backtest period
- Target entity IDs: specific stocks (stock_sh_600000) or index components (SZ1000)?


path: references/ANTI_PATTERNS.md
content: # Anti-Patterns (Cross-Project)

Total: **14**

## finance-bp-070--edgartools (2)

### `AP-DATA-SOURCING-004` — Invalidating XBRL period types for balance sheet analysis <sub>(high)</sub>

Balance sheets represent point-in-time snapshots (instant periods), not ranges (duration periods). Using duration periods for balance sheet statements causes stockholder equity and other line items to show nonsensical date ranges, corrupting financial calculations that depend on accurate period associations.

### `AP-DATA-SOURCING-012` — Large document parsing without streaming causing OOM errors <sub>(high)</sub>

SEC filings can exceed 160MB, and parsing large documents in memory without streaming causes OOM errors that crash the entire service for all users. Documents exceeding 10MB require switching to streaming parsers to prevent extreme memory usage.

## finance-bp-070--edgartools, finance-bp-079--akshare, finance-bp-084--eastmoney, finance-bp-114--edgar-crawler (1)

### `AP-DATA-SOURCING-002` — Ignoring external API rate limits causing IP blocking <sub>(high)</sub>

Multiple financial data sources (SEC EDGAR, Sina, Eastmoney, TuShare) enforce strict rate limits (10 req/sec, 120 calls/minute). Exceeding these triggers temporary IP blocks lasting 10-60 minutes, causing complete data unavailability. Immediate retry attempts during blocks extend the block duration significantly.

## finance-bp-070--edgartools, finance-bp-114--edgar-crawler (1)

### `AP-DATA-SOURCING-001` — Missing or invalid User-Agent headers for SEC API requests <sub>(high)</sub>

SEC EDGAR requires valid User-Agent identity with contact information in headers. Without this, requests are rejected with 403 Forbidden errors, completely blocking all filing access. Both edgartools and edgar-crawler enforce this constraint as fundamental to any data retrieval operation.

## finance-bp-079--akshare (4)

### `AP-DATA-SOURCING-003` — No HTTP timeout configuration causing indefinite hangs <sub>(high)</sub>

HTTP requests to external financial data sources (Yahoo, Sina, Eastmoney) without timeout values can hang indefinitely on blocked connections. This freezes the entire application and prevents data collection from all other sources, creating cascading failures across the system.

### `AP-DATA-SOURCING-005` — Malformed or empty JSON responses causing silent failures <sub>(medium)</sub>

Financial API responses containing malformed JSON raise unhandled ValueError exceptions, crashing downstream processing. Similarly, empty JSON responses (empty dict, list, null) masquerading as valid data cause silent failures producing empty DataFrames or misleading results in financial analysis.

### `AP-DATA-SOURCING-006` — Source-specific symbol mapping errors causing data corruption <sub>(high)</sub>

Stock symbols require source-specific formatting (sh/sz prefixes for Sina, numeric codes for THS, etc.). Incorrect symbol mapping causes API calls to return empty results or wrong data, corrupting financial datasets with missing records or entirely incorrect tickers being stored.

### `AP-DATA-SOURCING-013` — Column mapping length mismatch causing DataFrame errors <sub>(medium)</sub>

Column mapping constants with length mismatch against actual API response columns cause ValueError exceptions during DataFrame construction. Raw field names (f1, f2, f12) must be mapped to meaningful names (最新价, 涨跌幅) with exact column count alignment.

## finance-bp-103--ArcticDB (3)

### `AP-DATA-SOURCING-007` — Using unsupported DataFrame types with time-series storage <sub>(high)</sub>

ArcticDB does not support MultiIndex columns, PyArrow-backed pandas DataFrames, or timedelta64 columns. Attempting to write these DataFrame types raises ArcticDbNotYetImplemented exceptions, causing write failures and permanent data loss if not properly handled before storage operations.

### `AP-DATA-SOURCING-008` — Non-atomic storage writes causing concurrent access corruption <sub>(high)</sub>

Storage backends without atomic write_if_none operations can cause data corruption under concurrent multi-writer access. Similarly, updating reference keys before atom keys complete allows readers to access incomplete or missing data, breaking version chain integrity.

### `AP-DATA-SOURCING-014` — Pruning snapshot-protected versions breaking point-in-time recovery <sub>(high)</sub>

Deleting or pruning versions that are referenced by existing snapshots breaks historical data access. Snapshots provide point-in-time recovery capabilities, and removing their referenced versions causes read failures when users attempt to access data from specific snapshots.

## finance-bp-114--edgar-crawler (1)

### `AP-DATA-SOURCING-010` — 8-K filing item numbering scheme mismatch for historical filings <sub>(medium)</sub>

8-K filings use obsolete item numbering (1-12) before 2004-08-23 and new numbering (1.01-9.01) after. Using the wrong numbering scheme causes no matches for historical filings, resulting in empty item sections and complete extraction failure for pre-2004 data.

## finance-bp-128--yfinance (2)

### `AP-DATA-SOURCING-009` — Missing timezone-aware DatetimeIndex causing DST offset errors <sub>(high)</sub>

Price history DataFrames returned without timezone-aware DatetimeIndex cause incorrect timestamp interpretation when combined with other timezone-aware data. This leads to 23-25 hour offset errors during daylight saving time transitions, corrupting historical price calculations.

### `AP-DATA-SOURCING-011` — Yahoo Finance missing crumb authentication causing 401/403 errors <sub>(high)</sub>

Yahoo Finance API requires crumb and cookie authentication with every request. Without proper crumb management, API calls return 401 Unauthorized or HTML error pages instead of JSON data, breaking all downstream price and financial data processing.


path: references/COMPONENTS.md
content: # Component Capability Map

**Project**: finance-bp-070--edgartools
**Scan date**: 2026-04-22
**Stats**: {'total_files': 10, 'total_classes': 45, 'total_functions': 0, 'total_stages': 10}

## Modules (10)

- [sec_edgar_data_retrieval](components/sec_edgar_data_retrieval.md): 5 classes
- [html_document_parsing](components/html_document_parsing.md): 5 classes
- [xbrl_financial_data_processing](components/xbrl_financial_data_processing.md): 6 classes
- [multi-period_statement_stitching](components/multi-period_statement_stitching.md): 4 classes
- [entity_resolution_and_company_data](components/entity_resolution_and_company_data.md): 4 classes
- [ownership_and_insider_transaction_reporting](components/ownership_and_insider_transaction_reporting.md): 4 classes
- [ai_integration_layer](components/ai_integration_layer.md): 6 classes
- [asset-backed_securities_data](components/asset-backed_securities_data.md): 3 classes
- [financial_statement_rendering](components/financial_statement_rendering.md): 5 classes
- [filing_search_and_discovery](components/filing_search_and_discovery.md): 3 classes


path: references/CONSTRAINTS.md
content: # Constraints

## preservation_manifest

```yaml
required_objects:
  business_decisions_count: 145
  fatal_constraints_count: 46
  non_fatal_constraints_count: 303
  use_cases_count: 55
  semantic_locks_count: 12
  preconditions_count: 4
  evidence_quality_rules_count: 2
  traceback_scenarios_count: 5

```

## Domain Constraints Injected (16)

- **`SHARED-DS-RL-001`** <sub>(fatal)</sub>: Rate Limit + 指数退避重试：所有外部数据 API 调用必须实施速率限制控制 和指数退避重试（Exponential Backoff with Jitter）。收到 429/503 响应后 立即重试是反模式，会加剧服务端压力并触发 IP 封禁。 最大重试次数 3-5 次，退避基数 1-2 秒，最大退避 60 秒。
- **`SHARED-DS-RL-002`** <sub>(high)</sub>: 批量 API 调用必须控制并发数（max_workers），不可无限制并行。 免费 API（akshare/tushare 免费版）通常限制为 1-3 并发； 付费 API 也有并发上限（tushare 积分制，不同积分对应不同并发）。 超出并发限制会触发 429 或 IP 封禁。推荐使用 asyncio.Semaphore 或 ThreadPoolExecutor 的 max_workers 参数显式控制。
- **`SHARED-DS-RL-003`** <sub>(high)</sub>: API Token / 凭证安全：数据源 API key（tushare token / akshare 无需 token 但 其他商业数据源需要）不可硬编码在代码中，必须通过环境变量或配置文件读取。 硬编码 token 提交到 Git 会导致 token 泄露和费用损失。
- **`SHARED-DS-RL-004`** <sub>(medium)</sub>: 请求节流（Throttling）：对同一 API 的批量请求应在请求间插入最小间隔 （akshare 部分接口要求 ≥ 0.5s；tushare 免费版每分钟 200 次）。 纯代码 sleep 不如令牌桶（Token Bucket）算法精确，推荐使用 ratelimit 或 slowapi 等成熟库。
- **`SHARED-DS-MISS-001`** <sub>(high)</sub>: 停牌日数据缺失策略：停牌股票在停牌期间无成交数据，数据库中会出现日期缺口。 缺失日期不可使用 forward-fill（会产生虚假成交量）； 应在数据库中以 is_suspended=True 标记，量和成交额填 0，价格保留前一日收盘价。 因子计算时必须过滤 is_suspended=True 的行。
- **`SHARED-DS-MISS-002`** <sub>(medium)</sub>: 新上市股票的历史数据边界：新股上市首日开始在数据库中出现，但其上市前 无历史数据。若因子计算的 lookback 期超过上市天数，会产生所有 NaN 因子值。 采集时应记录每只股票的上市日期（list_date），采集逻辑应以上市日期为起点， 不以固定开始日期。
- **`SHARED-DS-MISS-003`** <sub>(high)</sub>: 退市股票的数据完整性：已退市股票在主流数据源（akshare/tushare）中依然 可以查询历史数据（退市前的历史），但退市日期后无数据。 历史股票池构建时必须包含已退市股票（否则幸存者偏差）， 且采集时需明确处理退市日截止边界。
- **`SHARED-DS-MISS-004`** <sub>(high)</sub>: 多数据源数据对账（Cross-Source Reconciliation）：同一数据（如收盘价） 从不同数据源（akshare/tushare/baostock）获取可能存在细微差异 （不同复权方式/不同节假日处理/除息调整时间不同）。 应在 pipeline 中实施多源对账检查，差异超阈值（如 0.1%）时记录告警并人工确认。
- **`SHARED-DS-TIME-001`** <sub>(high)</sub>: 时间戳精度与类型一致性：数据库中时间戳应使用统一的数据类型 （timestamp 而非 varchar/int）。混用字符串日期（'2024-01-15'）和 Timestamp 对象是比较、索引、merge 出现细微 bug 的常见来源， 应在 pipeline 入口处强制转换。
- **`SHARED-DS-TIME-002`** <sub>(high)</sub>: 交易时间与自然时间的区分：日线数据的"日期"通常对应交易日（T日）， 而新闻/公告数据的"时间"是自然时间。合并两类数据时，必须将自然时间 映射到下一个可用交易日（next available trading day）， 否则会产生"公告在T日，但T日盘中已经可用"的 lookahead 问题。
- **`SHARED-DS-TIME-003`** <sub>(medium)</sub>: 夏令时（DST）处理：采集美股/欧洲股市数据时，夏令时切换日（3月/11月） 会导致同一 HH:MM 时刻对应不同的 UTC 时间，若未处理，当日时序数据 会出现1小时的漂移。应始终以 UTC 存储，展示时按市场本地时区转换。
- **`SHARED-DS-INCR-001`** <sub>(high)</sub>: 增量更新幂等性：数据更新脚本必须是幂等的（多次运行结果相同）。 若脚本因网络中断在中途失败，重新运行时不应产生重复数据或数据缺口。 实现方式：先写入临时表，校验后 UPSERT 到主表，不直接 INSERT/APPEND。
- **`SHARED-DS-INCR-002`** <sub>(high)</sub>: 数据完整性检验（数据校验和/行数检查）：每次数据更新后， 应对关键字段做完整性检验：行数是否在预期范围内、价格是否为正数、 日期是否连续（无缺失交易日）。缺少自动校验的数据管道是"沉默腐烂"的根源。
- **`SHARED-DS-INCR-003`** <sub>(medium)</sub>: 数据版本化：数据管道的输出数据应版本化管理（data versioning）。 当数据源更新了历史数据（如修订调整后的财务数据）， 旧版本数据应保留可追溯，不应静默覆盖，以便对比版本间差异及复现历史回测。
- **`SHARED-DS-INCR-004`** <sub>(medium)</sub>: 数据对齐到交易日历边界：采集完成后，应验证所有股票/资产的数据覆盖 完整性与交易日历的一致性。每只股票在每个交易日都应有一行数据 （停牌标记，不是缺失）。通过 pivot_table 检查 NaN 比例是有效的快速诊断手段。
- **`SHARED-DS-INCR-005`** <sub>(medium)</sub>: 缓存策略（Caching）：频繁读取的静态/低频更新数据（如股票信息、行业分类、 指数成分股）应本地缓存，避免每次运行重复 API 调用。 缓存必须设置过期时间（TTL），防止使用过期的行业分类或已失效的成分股信息。


path: references/LOCKS.md
content: # Semantic Locks + Preconditions

## Semantic Locks (12)

### `SL-01` <sub>(on_violation: fatal)</sub>
Execute sell orders before buy orders in every trading cycle

### `SL-02` <sub>(on_violation: fatal)</sub>
Trading signals MUST use next-bar execution (no look-ahead)

### `SL-03` <sub>(on_violation: fatal)</sub>
Entity IDs MUST follow format entity_type_exchange_code

### `SL-04` <sub>(on_violation: fatal)</sub>
DataFrame index MUST be MultiIndex (entity_id, timestamp)

### `SL-05` <sub>(on_violation: fatal)</sub>
TradingSignal MUST have EXACTLY ONE of: position_pct, order_money, order_amount

### `SL-06` <sub>(on_violation: fatal)</sub>
filter_result column semantics: True=BUY, False=SELL, None/NaN=NO ACTION

### `SL-07` <sub>(on_violation: fatal)</sub>
Transformer MUST run BEFORE Accumulator in factor pipeline

### `SL-08` <sub>(on_violation: fatal)</sub>
MACD parameters locked: fast=12, slow=26, signal=9

### `SL-09` <sub>(on_violation: warning)</sub>
Default transaction costs: buy_cost=0.001, sell_cost=0.001, slippage=0.001

### `SL-10` <sub>(on_violation: fatal)</sub>
A-share equity trading is T+1 (no same-day close of buy positions)

### `SL-11` <sub>(on_violation: fatal)</sub>
Recorder subclass MUST define provider AND data_schema class attributes

### `SL-12` <sub>(on_violation: fatal)</sub>
Factor result_df MUST contain either 'filter_result' OR 'score_result' column

## Preconditions (4)

- **`PC-01`**: `python3 -c 'import zvt; print(zvt.__version__)'` → on_fail: Run: python3 -m pip install zvt then re-run: python3 -m zvt.init_dirs to initialize data directories
- **`PC-02`**: `python3 -c "from zvt.api.kdata import get_kdata; df = get_kdata(entity_ids=['stock_sh_600000'], limit=1); assert df is not None and len(df) > 0, 'No kdata found'"` → on_fail: Run recorder first: python3 -m zvt.recorders.em.em_stock_kdata_recorder --entity_ids stock_sh_600000 (replace with your target entity IDs)
- **`PC-03`**: `python3 -c "import os; from pathlib import Path; zvt_home = Path(os.environ.get('ZVT_HOME', Path.home() / '.zvt')); assert zvt_home.exists(), f'ZVT home not found: {zvt_home}'"` → on_fail: Run: python3 -m zvt.init_dirs
- **`PC-04`**: `python3 -c "import os, tempfile; from pathlib import Path; zvt_home = Path(os.environ.get('ZVT_HOME', Path.home() / '.zvt')); test_f = zvt_home / '.write_test'; test_f.touch(); test_f.unlink()"` → on_fail: Check directory permissions: chmod u+w ~/.zvt or set ZVT_HOME environment variable to a writable location


path: references/USE_CASES.md
content: # Known Use Cases (KUC)

Total: **55**

## `KUC-101`
**Source**: `docs/Usage.ipynb`

Discovering and retrieving SEC filings for companies to understand their regulatory submissions, corporate actions, and financial disclosures.

## `KUC-102`
**Source**: `docs/doctest.py`

Extracting financial data from SEC filings to analyze company performance, including income statements, balance sheets, and cash flows.

## `KUC-103`
**Source**: `docs/examples/insider_transactions.py`

Tracking insider buying and selling activities by processing Form 4 filings to identify significant insider transactions and ownership changes.

## `KUC-104`
**Source**: `notebooks/13f-institutional-holdings-python.ipynb`

Analyzing institutional investment holdings from 13F filings to understand portfolio composition, top holdings, and changes in positions over time.

## `KUC-105`
**Source**: `docs/examples/crowdfunding.py`

Tracking Regulation CF crowdfunding campaigns through their complete lifecycle including initial filings, amendments, updates, and termination.

## `KUC-106`
**Source**: `notebooks/Reading-Data-From-XBRL.ipynb`

Extracting structured financial data from XBRL-tagged filings including income statements, balance sheets, and cash flow statements with period history.

## `KUC-107`
**Source**: `notebooks/10k-business-description-python.ipynb`

Extracting and analyzing sections from 10-K annual reports including business descriptions, risk factors, and MD&A for fundamental analysis.

## `KUC-108`
**Source**: `notebooks/8k-earnings-release-python.ipynb`

Finding and extracting earnings information from 8-K current reports including press releases, financial tables, and earnings-related disclosures.

## `KUC-109`
**Source**: `notebooks/etf-fund-holdings-python.ipynb`

Analyzing ETF portfolio holdings from NPORT-P filings to understand fund composition, top positions, and allocation by sector or country.

## `KUC-110`
**Source**: `notebooks/executive-compensation-sec-python.ipynb`

Analyzing executive compensation from DEF 14A proxy statements including CEO pay, pay-vs-performance metrics, and compensation trends.

## `KUC-111`
**Source**: `notebooks/10q-quarterly-earnings-python.ipynb`

Comparing quarterly financial results across companies or tracking a single company's quarterly performance over multiple periods.

## `KUC-112`
**Source**: `notebooks/compare-company-financials-python.ipynb`

Comparing financial metrics across multiple companies to benchmark performance, profitability, and growth metrics.

## `KUC-113`
**Source**: `notebooks/monitor-sec-filings-python.ipynb`

Monitoring today's SEC filings to track earnings announcements, insider trading, and other corporate events as they happen.

## `KUC-114`
**Source**: `notebooks/download-sec-filings-bulk-python.ipynb`

Downloading large batches of SEC filings for archival, analysis, or processing with support for multiple output formats (text, markdown, HTML).

## `KUC-115`
**Source**: `notebooks/sec-filing-text-nlp-python.ipynb`

Applying NLP techniques to SEC filings including text extraction, search, section identification, and document chunking for analysis.

## `KUC-116`
**Source**: `notebooks/sec-industry-sic-code-python.ipynb`

Filtering companies and filings by SIC codes and industry classifications to focus research on specific sectors like semiconductors, software, or banking.

## `KUC-117`
**Source**: `notebooks/beneficial-ownership-sec-python.ipynb`

Tracking beneficial ownership changes through Schedule 13D and 13G filings to identify significant shareholders and ownership stakes.

## `KUC-118`
**Source**: `notebooks/money-market-fund-nmfp-python.ipynb`

Analyzing money market fund portfolios from N-MFP filings including holdings, maturity schedules, yield history, and fund composition.

## `KUC-119`
**Source**: `notebooks/mutual-fund-holdings-nport-python.ipynb`

Extracting mutual fund portfolio holdings from NPORT-P filings to analyze fund composition, country allocation, and sector exposure.

## `KUC-120`
**Source**: `notebooks/bdc-business-development-company-python.ipynb`

Researching BDCs including portfolio companies, investment strategies, and financial performance for alternative investment analysis.

## `KUC-121`
**Source**: `notebooks/XBRL2-StitchingStatements.ipynb`

Combining XBRL financial statements across multiple filings or periods to create unified views of financial performance over time.

## `KUC-122`
**Source**: `notebooks/financial-statements-to-dataframe.ipynb`

Exporting financial statements to pandas DataFrames for further analysis, visualization, or integration with other data tools.

## `KUC-123`
**Source**: `notebooks/extract-revenue-earnings-python.ipynb`

Extracting specific financial metrics like revenue, net income, and free cash flow for time series analysis and growth tracking.

## `KUC-124`
**Source**: `notebooks/XBRL2-FactQueries.ipynb`

Querying XBRL facts using semantic search to find specific financial data points, concepts, and dimensional breakdowns.

## `KUC-125`
**Source**: `notebooks/sec-filing-exhibits-python.ipynb`

Accessing and extracting exhibits attached to SEC filings including press releases, supporting documents, and supplemental information.

## `KUC-126`
**Source**: `docs/examples/fund_examples.py`

Navigating fund entities including fund companies, series, and share classes to find and analyze fund information by ticker, CIK, or Series ID.

## `KUC-127`
**Source**: `examples/scripts/ai/ai_context.py`

Generating token-efficient context from SEC filings for consumption by large language models (LLMs) with support for progressive disclosure.

## `KUC-128`
**Source**: `examples/scripts/advanced/ranking_search_examples.py`

Performing relevance-ranked search within SEC filings using BM25 or hybrid algorithms for semantic content discovery.

## `KUC-129`
**Source**: `examples/scripts/advanced/enterprise_config.py`

Configuring EdgarTools for enterprise use cases including custom SEC mirrors, rate limiting, and environment-based configuration profiles.

## `KUC-130`
**Source**: `notebooks/proxy-statement-def14a-python.ipynb`

Analyzing proxy statements (DEF 14A) for governance information including executive compensation, shareholder proposals, and board composition.

## `KUC-131`
**Source**: `docs/examples/formtype_demo_examples.py`

Using FormType enum for IDE autocomplete and type-safe form specification when querying SEC filings.

## `KUC-132`
**Source**: `docs/examples/periodtype_demo_examples.py`

Using PeriodType enum for period specification including annual, quarterly, TTM, and YTD with enhanced validation.

## `KUC-133`
**Source**: `docs/examples/feat004_demo_enhanced_validation.py`

Demonstrating enhanced parameter validation with helpful error messages for invalid form types, periods, and other inputs.

## `KUC-134`
**Source**: `docs/examples/plot_revenue.py`

Creating financial visualizations showing revenue, gross profit, and net income trends over time with professional formatting.

## `KUC-135`
**Source**: `examples/scripts/advanced/section_detection_demo.py`

Automatically detecting and identifying sections within SEC filings using hybrid detection with confidence scoring.

## `KUC-136`
**Source**: `notebooks/revenue-segment-hierarchy-python.ipynb`

Analyzing revenue segmentation and product/service hierarchies within financial statements to understand business composition.

## `KUC-137`
**Source**: `notebooks/fund-census-ncen-python.ipynb`

Analyzing fund census data from N-CEN filings including fund series, service providers, and classification information.

## `KUC-138`
**Source**: `notebooks/sec-comment-letters-python.ipynb`

Accessing and analyzing SEC staff comment letters to understand regulatory review topics and compliance issues.

## `KUC-139`
**Source**: `examples/scripts/basic/entity_facts_dataframe.py`

Exporting company financial facts to pandas DataFrames for custom analysis with filtering by period type and concept.

## `KUC-140`
**Source**: `examples/table_width_example.py`

Controlling table column widths when extracting text from SEC filings for AI/LLM processing to prevent truncation.

## `KUC-141`
**Source**: `notebooks/Beginners-Guide.ipynb`

Getting started with EdgarTools to perform basic SEC filing operations including company lookup, filing retrieval, and financial data access.

## `KUC-142`
**Source**: `notebooks/XBRL2-PeriodViews.ipynb`

Rendering XBRL statements with different period views including quarterly comparisons, annual comparisons, and YTD breakdowns.

## `KUC-143`
**Source**: `docs/examples/feat005_demo_statement_types.py`

Using StatementType enum for organized categorization of financial statements including primary, comprehensive, analytical, and specialized statements.

## `KUC-144`
**Source**: `docs/examples/investment_fund_research.py`

Researching investment fund performance and comparing with competitors using fund entity data and filings.

## `KUC-145`
**Source**: `notebooks/XBRL2-StandardizedStatements.ipynb`

Accessing standardized financial statements (income, balance, cash flow) from XBRL data with consistent formatting.

## `KUC-146`
**Source**: `docs/examples/offering_lifecycle_ai_discovery.py`

Demonstrating AI agent workflow for discovering crowdfunding campaign lifecycle data using context hints without manual API knowledge.

## `KUC-147`
**Source**: `notebooks/XBRL2-NonFinancialStatements.ipynb`

Accessing non-standard XBRL statements such as segment information, revenue by market, and other supplemental disclosures.

## `KUC-148`
**Source**: `notebooks/sec-reference-data-python.ipynb`

Accessing SEC reference data including company tickers, exchange listings, and company metadata for identification and lookup.

## `KUC-149`
**Source**: `tests/demo_to_markdown.ipynb`

Converting SEC filing content to markdown format with proper table formatting for documentation and sharing.

## `KUC-150`
**Source**: `notebooks/Initial-Insider-Transactions.ipynb`

Tracking initial insider filings (Form 3) and subsequent transactions (Form 4) for executive and director ownership reporting.

## `KUC-151`
**Source**: `notebooks/Paging-Through-Filings.ipynb`

Navigating through large sets of SEC filings using pagination methods to access results across multiple pages.

## `KUC-152`
**Source**: `notebooks/XBRL2-CustomTags.ipynb`

Analyzing custom XBRL tags and taxonomy extensions used by companies beyond standard US-GAAP tags.

## `KUC-153`
**Source**: `examples/scripts/ai/skills_usage.py`

Using AI Skills system for specialized SEC analysis workflows with helper functions and documentation.

## `KUC-154`
**Source**: `examples/scripts/ai/basic_docs.py`

Accessing interactive documentation directly within Python for learning the EdgarTools API without external resources.

## `KUC-155`
**Source**: `examples/scripts/advanced/start_page_number_example.py`

Controlling starting page numbers when converting documents to markdown with page break markers.


path: references/WISDOM.md
content: # Cross-Project Wisdom

Total: **8**

## `CW-DATA-SOURCING-001` — Exponential backoff retry with rate limit detection
**From**: finance-bp-079--akshare, finance-bp-114--edgar-crawler · **Applicable to**: data-sourcing

Implement retry logic with exponential backoff specifically for HTTP 429 rate limit responses. Retrying immediately on rate limit errors worsens the block situation. Separate retry logic for transient network errors (TimeoutError, ConnectionError) from permanent errors (ValueError, KeyError) prevents resource waste and masks underlying bugs.

## `CW-DATA-SOURCING-002` — Strict date format validation and standardization
**From**: finance-bp-070--edgartools, finance-bp-079--akshare, finance-bp-084--eastmoney · **Applicable to**: data-sourcing

Validate date formats strictly (YYYY-MM-DD pattern with leap year and month-end checks) before processing XBRL or API data. Convert date strings between formats (YYYYMMDD to YYYY-MM-DD) when storing to databases. Invalid dates corrupt downstream financial calculations.

## `CW-DATA-SOURCING-003` — XBRL fact attribute completeness enforcement
**From**: finance-bp-070--edgartools, finance-bp-114--edgar-crawler · **Applicable to**: data-sourcing

Extract and validate all essential XBRL fact attributes (concept, value, period, unit) from every fact. Missing attributes cause financial analysis queries to return incomplete or misleading results. Period type (instant vs duration) must be correctly distinguished for accurate balance sheet rendering.

## `CW-DATA-SOURCING-004` — Streaming parser threshold for large documents
**From**: finance-bp-070--edgartools, finance-bp-128--yfinance · **Applicable to**: data-sourcing

Implement streaming parser activation when documents exceed configurable thresholds (10MB default). This prevents OOM errors on large NPORT-P filings or bulk document downloads. Also require timezone information for time-series data to prevent DST offset corruption.

## `CW-DATA-SOURCING-005` — Data accuracy disclaimer requirements
**From**: finance-bp-079--akshare, finance-bp-128--yfinance, finance-bp-097--OpenBB · **Applicable to**: data-sourcing

Always present scraped or third-party financial data with proper caveats about accuracy limitations and delays. Claims of guaranteed accuracy, real-time capabilities, or Yahoo/provider affiliation violate terms of service and can lead to user financial losses from reliance on delayed or incorrect data.

## `CW-DATA-SOURCING-006` — Atomic write ordering for versioned storage
**From**: finance-bp-103--ArcticDB · **Applicable to**: data-sourcing

Write atom keys (TABLE_DATA, TABLE_INDEX, VERSION) before updating mutable reference keys (VERSION_REF, SNAPSHOT_REF). Never modify atom keys after writing to preserve content-addressed storage invariants. This prevents readers from accessing incomplete data in multi-writer scenarios.

## `CW-DATA-SOURCING-007` — HTTP status code validation before data processing
**From**: finance-bp-079--akshare, finance-bp-097--OpenBB · **Applicable to**: data-sourcing

Always validate HTTP response status codes before processing response data. Error responses (404, 500) may contain HTML error pages that corrupt downstream JSON parsing. Explicitly check for HTTP 429 and raise RateLimitError for proper handling by callers.

## `CW-DATA-SOURCING-008` — Quality gates for financial recommendations
**From**: finance-bp-084--eastmoney · **Applicable to**: data-sourcing

Apply fundamental quality filters (ROE thresholds, OCF/Profit ratios, debt ratios) before generating financial recommendations. Without quality gates, low-quality stocks may be recommended for positions, leading to investment losses. Separate on-demand computation from scheduled pre-computation to handle API rate limits.


path: references/components/ai_integration_layer.md
content: # ai_integration_layer (6 classes)

## `HasContext.to_context`
`ai_integration_layer/hascontext-to-context.py:0`

## `compose_context`
`ai_integration_layer/compose-context.py:0`

## `TokenOptimizer.optimize`
`ai_integration_layer/tokenoptimizer-optimize.py:0`

## `get_tool_definitions`
`ai_integration_layer/get-tool-definitions.py:0`

## `AI Context Detail`
`ai_integration_layer/ai-context-detail.py:0`

## `Integration Path`
`ai_integration_layer/integration-path.py:0`


path: references/components/asset-backed_securities_data.md
content: # asset-backed_securities_data (3 classes)

## `TenD.get_distribution_report`
`asset-backed_securities_data/tend-get-distribution-report.py:0`

## `CMBSAssetData.to_dataframe`
`asset-backed_securities_data/cmbsassetdata-to-dataframe.py:0`

## `ABS Type`
`asset-backed_securities_data/abs-type.py:0`


path: references/components/entity_resolution_and_company_data.md
content: # entity_resolution_and_company_data (4 classes)

## `Company.get_financials`
`entity_resolution_and_company_data/company-get-financials.py:0`

## `get_entity`
`entity_resolution_and_company_data/get-entity.py:0`

## `Company.filings`
`entity_resolution_and_company_data/company-filings.py:0`

## `Identifier Type`
`entity_resolution_and_company_data/identifier-type.py:0`


path: references/components/filing_search_and_discovery.md
content: # filing_search_and_discovery (3 classes)

## `FastSearch.search`
`filing_search_and_discovery/fastsearch-search.py:0`

## `BDCSearchIndex.find`
`filing_search_and_discovery/bdcsearchindex-find.py:0`

## `Search Type`
`filing_search_and_discovery/search-type.py:0`


path: references/components/financial_statement_rendering.md
content: # financial_statement_rendering (5 classes)

## `Statement.__rich__`
`financial_statement_rendering/statement-rich.py:0`

## `RenderedStatement.to_markdown`
`financial_statement_rendering/renderedstatement-to-markdown.py:0`

## `Statement.to_dataframe`
`financial_statement_rendering/statement-to-dataframe.py:0`

## `Output Format`
`financial_statement_rendering/output-format.py:0`

## `Comparison Display`
`financial_statement_rendering/comparison-display.py:0`


path: references/components/html_document_parsing.md
content: # html_document_parsing (5 classes)

## `Document.parse`
`html_document_parsing/document-parse.py:0`

## `Document.get_section`
`html_document_parsing/document-get-section.py:0`

## `HTMLParser.parse`
`html_document_parsing/htmlparser-parse.py:0`

## `Section Detection Strategy`
`html_document_parsing/section-detection-strategy.py:0`

## `Table Processing`
`html_document_parsing/table-processing.py:0`


path: references/components/multi-period_statement_stitching.md
content: # multi-period_statement_stitching (4 classes)

## `StatementStitcher.stitch`
`multi-period_statement_stitching/statementstitcher-stitch.py:0`

## `StitchedStatement.to_dataframe`
`multi-period_statement_stitching/stitchedstatement-to-dataframe.py:0`

## `XBRLS.get_income_statement`
`multi-period_statement_stitching/xbrls-get-income-statement.py:0`

## `Period Selection Strategy`
`multi-period_statement_stitching/period-selection-strategy.py:0`


path: references/components/ownership_and_insider_transaction_reporting.md
content: # ownership_and_insider_transaction_reporting (4 classes)

## `Form4.transactions`
`ownership_and_insider_transaction_reporting/form4-transactions.py:0`

## `Ownership.get_summary`
`ownership_and_insider_transaction_reporting/ownership-get-summary.py:0`

## `TransactionSummary.to_dataframe`
`ownership_and_insider_transaction_reporting/transactionsummary-to-dataframe.py:0`

## `Form Type`
`ownership_and_insider_transaction_reporting/form-type.py:0`


path: references/components/sec_edgar_data_retrieval.md
content: # sec_edgar_data_retrieval (5 classes)

## `Filings.get_filings`
`sec_edgar_data_retrieval/filings-get-filings.py:0`

## `Filing.document`
`sec_edgar_data_retrieval/filing-document.py:0`

## `Filing.xbrl`
`sec_edgar_data_retrieval/filing-xbrl.py:0`

## `HTTP Client Backend`
`sec_edgar_data_retrieval/http-client-backend.py:0`

## `Filing Index Format`
`sec_edgar_data_retrieval/filing-index-format.py:0`


path: references/components/xbrl_financial_data_processing.md
content: # xbrl_financial_data_processing (6 classes)

## `XBRL.parse`
`xbrl_financial_data_processing/xbrl-parse.py:0`

## `FactsView.get_facts`
`xbrl_financial_data_processing/factsview-get-facts.py:0`

## `FactQuery.by_concept`
`xbrl_financial_data_processing/factquery-by-concept.py:0`

## `ConceptMapper.standardize`
`xbrl_financial_data_processing/conceptmapper-standardize.py:0`

## `Concept Standardization`
`xbrl_financial_data_processing/concept-standardization.py:0`

## `Period Selection`
`xbrl_financial_data_processing/period-selection.py:0`


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector:  ()