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.