Point-in-Time SEC Fundamentals for Equity Research
Summary
This document describes tools for retrieving company financial statements, SEC company facts, and filing information for US equities. Strategies can use these data in research workflows, while agents can search filings for relevant passages before opening full documents. Company facts can be returned in a compact form or with broader detail, and filings can be queried by type and accession number.
The key backtesting safeguard is point-in-time gating: facts are made available according to their SEC filing dates, while filings use acceptance timestamps when available and filing dates otherwise. Users can also specify an as-of date. The document notes that some entities have no SEC ticker mapping, in which case filing data is reported as unavailable. It describes local response caching and request rate limits as operational features. No trading strategy or performance evidence is presented; the material explains data access and timing behavior, so researchers still need to assess data completeness and build their own investment logic.
Key ideas
- SEC financial statements, company facts, and filings can support deterministic strategies and research agents.
- Point-in-time access gates facts and filings by their public filing or acceptance dates.
- Compact company-facts output can limit the amount of data returned, with broader options available.
- Searching a filing before opening the full document can focus research on relevant passages.
- Some entities lack SEC ticker mappings, so filing data may be unavailable.
Tags
Full text
# fundamentals
SEC Fundamentals
================
.. meta::
:description: LumiBot includes native SEC EDGAR fundamentals for US equities. These are core strategy data tools.
LumiBot includes native SEC EDGAR fundamentals for US equities. These are core
strategy data tools, not AI-only tools: deterministic Python strategies can call
them directly, and AI agents receive the same point-in-time tools as built-ins.
The tools use public SEC APIs directly, require no API key, and cache responses
locally.
Available strategy methods:
.. code-block:: python
self.fundamentals.get_income_statement("AAPL")
self.fundamentals.get_balance_sheet("AAPL")
self.fundamentals.get_cash_flow("AAPL")
self.fundamentals.get_company_facts("AAPL")
self.fundamentals.get_filings("AAPL", form="10-K")
self.fundamentals.search_filing("AAPL", accession_number="...", query="risk")
self.fundamentals.get_filing_document("AAPL", accession_number="...")
``get_company_facts()`` returns a compact latest-facts view by default, capped
at important fields so agent runs do not flood the model context. Pass
``max_facts=None`` for the full compact fact set, or ``raw=True`` for the raw
SEC companyfacts payload when you explicitly need it.
.. image:: ../docs/assets/ai_committee/docs_sec_point_in_time_cache.png
:alt: SEC fundamentals and filing research flow
Point-In-Time Behavior
----------------------
Backtests must not see future financial statements or filings. LumiBot gates SEC
facts and filings by the current strategy datetime unless you explicitly pass
``as_of``. For facts, the SEC ``filed`` date is used. For filings, the SEC
acceptance datetime is used when available, with filing date as the fallback.
Caching
-------
SEC responses are cached under ``~/.lumibot/cache/sec`` by default. Override this
with ``LUMIBOT_SEC_CACHE_DIR``. LumiBot also rate limits SEC requests and sends a
contact-style user agent. Override the default with ``LUMIBOT_SEC_USER_AGENT``.
Agent Tools
-----------
Agents receive these built-ins:
- ``get_income_statement``
- ``get_balance_sheet``
- ``get_cash_flow``
- ``get_company_facts``
- ``get_filings``
- ``search_filing``
- ``get_filing_document``
``get_filings`` for a symbol the SEC ticker map does not list (ETFs, foreign listings, crypto, private names) returns an empty ``filings`` list with ``available: false`` and ``reason: "no_sec_cik"`` instead of an error.
The absence is reported, never filled in.
Prefer ``search_filing`` before reading a full filing document. Annual reports
and quarterly filings can be long, and search keeps the model context focused.
Related Macro Data
------------------
For economic context such as rates, inflation, unemployment, GDP, liquidity, and
credit spreads, use :doc:`macro_data`. SEC fundamentals are company-specific;
FRED macro data is economy and market-regime context.
Filing Search
-------------
.. image:: ../docs/assets/ai_committee/docs_filing_search_workflow.png
:alt: SEC filing search workflow for Lumibot agents
Filing search is useful for agent workflows modeled after real fundamental
research. A researcher can identify a relevant annual report, search for risk
factors or accounting details, and only open the full filing when it needs more
context.
See :doc:`standalone_components` for use in scripts and notebooks.Shown in full with attribution under the source's licence. Licence: GPL-3.0
This summary was written by Stratmill's research agent from the original; it is not a copy of the source.