7f04334398
Literal[api]/Literal[python] subclass overrides are covariant read-only narrowings. Subclass fields stay writable at runtime. - method_definition.py, options_chains.py: pydantic 2.14 types FieldInfo.annotation as TypeForm[Any] | None, which ty rejects in Union[]/Annotated[] and where is expected; bind it as Any. Use FieldInfo.get_default(call_default_factory=True) instead of calling the default_factory union directly. - economy_views.py: read data/obbject_item without None defaults in the IMF shipping views. charting always sets obbject_item, and data is only popped when present and not None.- finra, jodi, eia: annotate @asynccontextmanager/@contextmanager functions with AsyncGenerator/Generator instead of the deprecated AsyncIterator/Iterator return types. - charting: cast the darts forecast dataset to TimeSeries before indexing so .all_values resolves instead of hitting ndarray. - fred, imf, nasdaq, sec, tmx: turn off invalid-attribute-override and invalid-mutable-override for models/** only, following the cboe precedent. Provider models extend the standard models by narrowing query params to Literals or widening fields to Optional, which these rules flag by design. Co-authored-by: dlee-bq <325002271+dlee-bq@users.noreply.github.com>
OpenBB SEC Provider
Free, key-less access to U.S. SEC EDGAR data for the OpenBB Platform — filings, financial statements, fund holdings, ownership, and full-text search, with a built-in OpenBB Workspace backend.
No credentials or API key required. Responses are persisted to a local disk cache so repeated queries are fast and offline-friendly.
Quick start
Launch the OpenBB Workspace backend with no prior install — uv fetches the package and runs it in one step:
uvx openbb-sec serve --host 0.0.0.0 --port 6900
Then add http://localhost:6900 as a custom backend in the OpenBB Workspace.
Installation
pip install openbb-sec
A single install brings the provider, the OpenBB Workspace dashboards, the Filing Viewer MCP, and the openbb-sec command.
Coverage
All endpoints are available under obb.sec.* in the Python/HTTP interface.
| Area | Endpoints |
|---|---|
| Filings & documents | company_filings, latest_financial_reports, filing_headers, htm_file, full_text_search, rss_litigation, exhibit |
| 10-K / 10-Q sections | company_overview, risk_factors, legal_proceedings, disclosures, segment_revenue, financial_statements |
| Proxy statement (DEF 14A) | executive_compensation, pay_versus_performance, beneficial_ownership, management_profiles |
| Funds | nport_disclosure, nport_fund_metrics |
| Reference & lookups | cik_map, symbol_map, institutions_search, sic_search, schema_files |
The SEC provider also implements standard models — financial statements (balance_sheet, income_statement, cash_flow, and their *_growth), compare_company_facts, equity_search, equity_ftd, insider_trading, form_13f, and management_discussion_analysis.
When openbb-equity / openbb-etf are installed these are reached as obb.equity.* / obb.etf.* with provider="sec"; when they are not, the same models register directly as obb.sec.*.
Basic usage
from openbb import obb
# Resolve identifiers
obb.sec.cik_map(symbol="AAPL")
obb.sec.symbol_map(query="0000320193")
# Filings and full-text search
obb.sec.company_filings(symbol="AAPL", form_type="10-K")
obb.sec.full_text_search(query="climate change", form_type="8-K")
# 10-K / 10-Q content (defaults to the latest filing)
obb.sec.risk_factors(symbol="AAPL")
obb.sec.financial_statements(symbol="AAPL", statement_type="balance")
obb.sec.segment_revenue(symbol="AAPL", calendar_year=2023)
# Proxy statement disclosures
obb.sec.executive_compensation(symbol="CAT")
obb.sec.pay_versus_performance(symbol="CAT")
# Fund holdings (N-PORT) and metrics
obb.sec.nport_disclosure(symbol="VTI")
obb.sec.nport_fund_metrics(symbol="VTI")
OpenBB Workspace
The package ships ready-to-use OpenBB Workspace dashboards (SEC Form 10-K/Q and SEC Filings), a Filing Viewer that re-serves EDGAR documents for in-app rendering, and an MCP server that exposes the open document to the Workspace agent as text.
Launch a self-contained Workspace backend:
openbb-sec serve --host 0.0.0.0 --port 6900
Cache management
The openbb-sec command also inspects and manages the disk cache:
openbb-sec info # resolved cache folder, size limit, and disk usage
openbb-sec path # print the resolved cache folder
openbb-sec clear # empty the cache
The cache folder is resolved from, in order of precedence: the --cache-dir argument, the OPENBB_SEC_CACHE_DIR environment variable, the cache_directory preference from openbb.toml / user settings, then the OpenBB default (~/OpenBBUserData/cache/sec).
| Variable | Purpose | Default |
|---|---|---|
OPENBB_SEC_CACHE_DIR |
SEC cache folder | ~/OpenBBUserData/cache/sec |
OPENBB_SEC_CACHE_SIZE_LIMIT |
Max cache size (bytes or e.g. "8GB") |
8GB |
OPENBB_SEC_REQUESTS_PER_SECOND |
EDGAR request rate | 9 |
OPENBB_SEC_MCP_HOST |
Filing Viewer MCP host | 127.0.0.1 |
OPENBB_SEC_MCP_PORT |
Filing Viewer MCP port | 7769 |
Documentation
Full documentation is available at docs.openbb.co.