From SEC Filings to Trustworthy AI Evidence: Engineering SECAgents
How an event-driven acquisition architecture turns regulatory disclosures into structured, verifiable inputs for financial AI.
Introduction: The Problem Before the Model
Large language models have made it remarkably easy to demonstrate sophisticated financial analysis. Retrieve a company’s SEC filing, provide its contents to a model, and ask for an assessment of its financial performance, operating risks, or management commentary. The result may be coherent, detailed, and persuasive.
But how do we know the model received the information it needed?
A financial filing is not simply a collection of paragraphs. It contains financial statements, tables, footnotes, accounting disclosures, management commentary, and relationships between reported values. Its contents may be represented through complex HTML, inline XBRL markup, and document structures that vary considerably across issuers and reporting periods.
An application can successfully download a filing while failing to recover important portions of its contents. It can extract a financial value while losing the context that gives the value meaning. It can produce a plausible analysis from evidence that was already incomplete before the model began reasoning.
These are not primarily language-model problems. They are problems of data acquisition, parsing, validation, and evidence management.
This is the engineering challenge addressed by SECAgents, an open-source system for acquiring and processing SEC disclosures.
SECAgents is the second component in a three-project architecture. OpenAgentFabric provides the distributed execution infrastructure. SECAgents uses that foundation to discover, retrieve, parse, and preserve financial disclosures. InvestmentIntelligence then uses the resulting information for evidence-driven financial investigations.
The objective is to separate three distinct engineering questions: Can the system execute reliably? Can it acquire and preserve the necessary evidence? And can it reason correctly about that evidence?
Each requires a different set of mechanisms, tests, and failure controls.
1. Designing the Acquisition Pipeline
SECAgents organizes SEC document processing into three independently operating agents: the Watcher, Fetcher, and Parser.
The Watcher discovers qualifying filings through SEC EDGAR. The Fetcher downloads the source documents and records their integrity information. The Parser transforms those documents into structured artifacts containing narrative text, document structure, tables, and XBRL information.
The agents communicate through events using Redis Streams and the execution infrastructure provided by OpenAgentFabric.
Figure 1. SECAgents’ event-driven acquisition architecture. Three specialized agents operate on OpenAgentFabric, using Redis Streams to coordinate discovery, retrieval, and parsing while preserving source integrity and producing structured financial evidence.
This separation is more consequential than it might initially appear.
Document discovery has different failure characteristics from document retrieval. A temporary SEC access failure differs from an invalid document reference. Both differ from a parser encountering an unfamiliar HTML structure. Combining these responsibilities into one procedure makes failures harder to isolate, diagnose, and recover from.
With separate agents, each stage has a defined responsibility and output. The Watcher identifies work. The Fetcher acquires source material. The Parser converts that material into representations suitable for subsequent processing.
The architecture also allows the stages to operate asynchronously. A newly discovered filing need not be parsed within the same execution context that discovered it. Each component can process its assigned work independently, while the shared infrastructure coordinates event delivery and execution state.
In an initial end-to-end demonstration, SECAgents processed eight filings across Apple, Microsoft, Amazon, and JPMorgan Chase. The pipeline generated eight parsed artifacts. After processing, both the Fetcher and Parser consumer groups reported zero pending messages and zero consumer lag.
These results demonstrate a functioning acquisition pipeline in the tested configuration. They do not establish production-scale throughput or universal document coverage.
The important architectural result is that acquisition responsibilities are independently executable, observable, and testable.
2. What OpenAgentFabric Contributes
The first article in this series, Beyond the LLM: Engineering Reliable Agentic Systems, examined why distributed AI applications require more than capable models. They also require reliable event delivery, workflow identity, execution ownership, recovery, and consistent completion behavior.
SECAgents demonstrates the value of placing those responsibilities in a shared framework.
Each agent concentrates on its domain-specific operation. The Watcher understands SEC filing discovery. The Fetcher understands document acquisition. The Parser understands SEC document structure. None needs to independently design a message transport, consumer lifecycle, or workflow correlation mechanism.
The Parser illustrates this separation. It extends OpenAgentFabric’s BaseAgent, subscribes to document-fetched events, validates the incoming payload, processes the source document, stores the parsed artifact, and returns a document-parsed event.
The event retains correlation and causation identifiers, preserving the relationship between the processing operation and the event that initiated it.
This arrangement has practical consequences during development. When a new filing structure requires changes to the Parser, the developer can modify the extraction logic without redesigning how work reaches the agent or how its output is delivered to downstream consumers.
The framework does not make the domain-specific algorithms correct. It removes a substantial category of infrastructure responsibilities so that developers can concentrate on making those algorithms correct.
This distinction is central to the design. Reliable execution and correct data extraction are complementary properties, but neither guarantees the other.
3. Source Acquisition and Integrity
The acquisition process begins with the Watcher monitoring configured companies for qualifying SEC filings.
The Watcher publishes discovery events and maintains Redis-backed markers to avoid repeatedly publishing the same filing within its configured namespace. This distinguishes the discovery of new work from the repeated observation of a filing during subsequent polling cycles.
The Fetcher then retrieves the source document and creates an artifact reference for downstream processing.
An artifact reference is more useful than an anonymous block of downloaded HTML because it establishes the identity of the document being processed.
The Parser verifies the incoming source artifact before attempting extraction. It validates the expected artifact type, resolves the referenced local file, verifies that the file resides within the configured artifact directory, and rejects missing or empty documents. When a source checksum is supplied, it checks the actual source bytes against that value.
These checks address different failure conditions. Path validation restricts access to the intended artifact storage area. File existence and content checks prevent invalid inputs from being treated as legitimate documents. Checksum verification helps establish that the document being processed matches the artifact identified by the preceding stage.
None of these controls establishes the accuracy of the financial disclosures themselves. They establish a more fundamental property: the system can identify and verify the source material used in its processing.
That is the foundation for evidence provenance.
4. Preserving the Structure of Financial Disclosures
One of the most important design decisions in SECAgents is that a financial filing should not be reduced prematurely to an undifferentiated string of text.
Document structure contains information.
A heading identifies the subject of a disclosure. A table establishes relationships between rows, columns, and values. A footnote may qualify an accounting observation. Narrative order provides context, while inline XBRL tags connect reported values to accounting concepts and reporting periods.
Flattening these structures into plain text can destroy information that subsequent analysis needs.
SECAgents therefore produces a structured document representation containing blocks for paragraphs, headings, lists, and tables. It also produces consolidated text for consumers that require a continuous narrative representation.
Tables are preserved as structured rows and cells, including information about header cells and declared row or column spans. The parser also extracts inline XBRL facts and produces normalized XBRL information.
These representations support different analytical requirements.
A historical comparison of reported financial values benefits from structured accounting observations and their reporting context. An investigation into management’s explanation of deteriorating operating conditions may depend on narrative disclosures and the paragraphs surrounding them.
A dependable acquisition layer should make both forms available rather than forcing every analytical question through a single flattened document.
This matters especially when the consumer is a language model. A model may be capable of interpreting complex evidence, but it cannot reliably recover information that was discarded during extraction.
The quality of downstream reasoning therefore depends on decisions made much earlier in the processing pipeline.
5. A Real Failure: NVIDIA’s Filing Structure
During development, NVIDIA filings exposed a weakness in the original narrative extraction logic.
The filings were successfully retrieved, but important narrative material was not recovered. Their HTML structures differed from the assumptions built into the parser, particularly through the use of div-based containers for narrative content.
This was a dangerous failure mode because the acquisition process could appear successful while the resulting evidence was incomplete.
The information was present in the source filing. The extraction logic simply failed to recover it.
Correcting the problem required the parser to traverse nested HTML structures more carefully, recognizing meaningful document boundaries while preserving narrative text and avoiding the accidental loss or absorption of tables.
The revised implementation recursively processes document elements, handles text within nested containers, and excludes selected non-narrative inline XBRL metadata.
Validation against two NVIDIA filings produced the following results:
FilingNarrative paragraphsTablesnvda-20260125.htm1,13664nvda-20260726.htm51052
Get Costab’s stories in your inbox
Join Medium for free to get updates from this writer.
Both validations passed the narrative recovery and table preservation checks.
These results demonstrate a concrete engineering correction. They do not establish perfect extraction across every SEC filing, but they show that a specific failure was identified, corrected, and tested against documents that previously exposed the weakness.
The larger lesson is that data acquisition requires independent correctness criteria.
A successful download is not proof of successful extraction. A nonempty parser result is not proof of completeness. And a convincing language-model summary is not proof that the source document was adequately represented.
For financial AI, extraction quality must be evaluated before the resulting evidence reaches the analytical layer.
6. Validating Financial Facts Against an Independent Reference
Structural completeness is necessary, but it is not sufficient.
A parser may recover narrative sections and preserve tables while still incorrectly extracting or normalizing individual financial observations. A numerical value may be assigned to the wrong accounting concept, reporting period, or context.
For this reason, SECAgents includes validation utilities that compare selected extracted information against SEC reference data.
In a separate Apple financial-summary validation, 18 of 18 selected financial facts matched SEC Company Facts for the tested filing.
This result measures something different from the NVIDIA tests.
The NVIDIA validation examines whether the parser successfully recovers document content and preserves structural elements. The Apple validation examines agreement between selected extracted financial observations and an independent SEC reference representation.
Neither test proves universal correctness.
The Apple result covers a defined selection of facts from a particular filing. It does not establish that every accounting concept is correctly normalized or that every issuer’s financial disclosures can be processed without error.
Nevertheless, the two tests are complementary. Together, they illustrate why a financial acquisition system needs multiple forms of validation rather than a single pass-or-fail measure.
A system may be structurally complete but numerically incorrect. It may extract numerical facts correctly while omitting important narrative context.
Reliable financial research requires attention to both.
7. Provenance and Reproducibility
A financial research system should be able to explain not only what information it used, but where that information came from.
SECAgents preserves source metadata in its parsed artifacts, including company identity, accession number, filing type, filing date, source artifact reference, and checksum information.
The Parser produces a structured JSON artifact containing the extracted document representation and XBRL information. It also calculates a checksum for the resulting artifact.
This establishes a relationship between the original filing and the representation supplied to downstream processing.
That relationship is essential for reproducibility.
Suppose a later parser revision changes the treatment of a particular table. Because the original filing and parsed representation are distinguishable artifacts, the same source can be processed again and the outputs compared.
Similarly, if an analyst questions a financial observation, the application has a basis for identifying which filing and parsed artifact supplied the underlying information.
The Parser also writes its output through a temporary file and atomically replaces the target artifact. This reduces the risk of another component encountering a partially written JSON document.
These mechanisms establish artifact-level provenance and integrity. They do not, by themselves, provide complete statement-level evidence tracing. A filing checksum identifies a document; it does not identify the exact sentence or table cell supporting every subsequent analytical claim.
That more granular relationship must be maintained by downstream evidence and investigation systems.
But without reliable source identity and artifact integrity, building such a relationship becomes substantially more difficult.
8. Security and Governance at the Acquisition Boundary
External documents are untrusted input. Their contents may include malformed markup, unexpected structures, or text that resembles instructions to an AI system.
An application must distinguish between information it is authorized to analyze and instructions it is authorized to execute.
SECAgents establishes basic boundaries through source artifact validation, path restrictions, and integrity checks. These controls help ensure that the Parser processes the intended class of artifacts from the configured storage location.
They are not a complete security sandbox.
The broader architecture provides opportunities for additional controls. OpenAgentFabric’s shared LLM execution interface creates an integration point for governance around model invocation. Controlled tool interfaces and isolated execution environments could extend those protections to actions performed by agents.
For example, a financial research agent could be authorized to retrieve SEC disclosures and write evidence artifacts while being restricted from accessing unrelated files or unauthorized network resources.
Such policies are easier to apply consistently when applications use shared execution interfaces rather than embedding independent model and tool clients throughout their code.
Centralizing model invocation does not automatically confine external actions, however. Effective confinement also requires enforcement at tool and operating-system boundaries.
These broader governance mechanisms should be understood as architectural integration opportunities, not as a claim that SECAgents currently implements a complete agent security environment.
The principle remains important: a document may provide evidence to an investigation, but its contents should not determine the application’s authority to act.
9. From Acquisition to Financial Intelligence
SECAgents is not intended to make investment decisions. Its responsibility is to acquire and structure information so that downstream systems can perform analysis.
This separation becomes particularly important in InvestmentIntelligence, which combines structured financial observations, deterministic calculations, documentary evidence, and language-model interpretation.
Consider an investigation into whether a company’s reported earnings reflect sustainable operating performance.
The analysis may require comparisons between earnings and cash flow, examination of capital expenditures, historical financial trends, and management disclosures explaining changes in the business.
A language model can help interpret this evidence, but it should not be responsible for inventing missing observations or reconstructing source material lost during parsing.
By separating acquisition from analysis, the architecture gives each layer a defined responsibility.
SECAgents supplies the source documents and extracted representations. InvestmentIntelligence evaluates financial observations, organizes investigations, and applies its own evidence and validation requirements.
A failure in narrative interpretation need not invalidate independently verified financial data. Conversely, an extraction failure can be identified as an acquisition problem rather than hidden inside a model-generated explanation.
This is an important departure from systems that treat financial analysis as a single prompt containing a large collection of document text.
The objective is not merely to produce a plausible answer. It is to construct a research process in which the origin, transformation, and interpretation of evidence can be examined independently.
That separation makes the system easier to test, debug, and extend.
Conclusion: Reliable Intelligence Begins Before Reasoning
The first article in this series examined the distributed infrastructure required to coordinate agentic applications reliably.
SECAgents addresses the next engineering problem: acquiring and transforming external information into structured, identifiable, and verifiable artifacts.
Its three-stage architecture separates discovery, retrieval, and parsing. Its integration with OpenAgentFabric provides a shared execution model. Its parser preserves document structure and accounting information rather than reducing every filing to undifferentiated text. Its artifact-handling mechanisms maintain the source identity and integrity information needed for reproducible processing.
The NVIDIA parser failure illustrates the importance of structural extraction correctness. The Apple financial-fact validation illustrates a complementary requirement: extracted numerical observations must be checked against authoritative reference information.
Together, they demonstrate that reliable evidence acquisition requires more than successful document retrieval.
As language models become more capable, the reliability of the information supplied to them becomes more important, not less.
Better reasoning cannot compensate for evidence that was never acquired, incorrectly extracted, or stripped of its context.
That is the engineering responsibility SECAgents was built to address.
This is the second article in a three-part technical series examining OpenAgentFabric, SECAgents, and InvestmentIntelligence.
Source code: https://github.com/costab06/SECAgents
Related projects: https://github.com/costab06/OpenAgentFabric · https://github.com/costab06/InvestmentIntelligence
