Implement SEC 13F XML parsing in the institutional data scraper

[Abhilovescars]

TLDR:
The SEC 13F scraper currently locates the filing XML but does not parse the holdings table. parse_13f_holdings() returns an empty DataFrame with a TODO. This blocks the repo’s institutional positioning data path. Please implement XML parsing for the entries and return a cleaned DataFrame with columns such as issuer, cusip, shares, market_value, and put_call.

Summary
The SEC 13F scraper currently retrieves filing metadata and locates the relevant XML document, but it does not parse the holdings table into a usable DataFrame.

In data/scrapers/sec_13f.py, parse_13f_holdings() currently returns an empty DataFrame with a TODO comment:

the filing index is fetched correctly,
the XML file is located correctly,
but the entries are not converted into structured holdings data.
Problem
This blocks the institutional positioning pipeline described in the repo’s data roadmap. The repo uses 13F filings as one of the public observables for the Level 1 / Level 2 mean-field institutional distribution, but the data scraper currently stops at a placeholder.

Expected behavior
parse_13f_holdings(cik, accession) should:

download the final filing XML from SEC EDGAR,
parse the entries,
extract the relevant columns such as:
issuer
cusip
shares
market_value
put_call
return a clean pandas DataFrame for downstream aggregation.
Why this matters
This is one of the key free-data sources identified for the institutional μ^(1) layer in DATA_REQUIREMENTS.md. Completing this parser would materially improve the repo’s ability to build the empirical distribution of institutional positions.

Scope
This issue is focused on:

XML parsing,
DataFrame normalization,
and validation against a known SEC filing sample.
Suggested implementation direction
Use Python’s xml.etree.ElementTree (or equivalent) to parse the nodes and map them to the expected columns described in the docstring.

[Abhilovescars]

would like to know what reviewers think on this!

[paperandbeyond23-gif]

Two things the infoTable won't warn you about before you write that parser. Funds split one position across sub-managers so the raw table double-counts unless you aggregate by CUSIP, and pre-2023 filings report value in thousands while newer ones report whole dollars, which silently 1000x's any comparison across that boundary, both of which I hit. Worth flagging put_call before you store anything too, since a PUT row isn't ownership and most trackers count it as one. I run a hosted parser for this (Edgrapi, 13F and 13D/G and Form 4, nothing else), so weigh that accordingly, but the gotchas apply either way.

[Abhilovescars]

someone commented about the fake stars here, not sure what was that anyways