jduval7/filings-agent

## 1. The problem
Every public company files an annual report with the SEC, called a 10-K. Each 10-K shows this
year's figures next to the previous years'. Sometimes a previous year's figure is not the number the
company reported the first time. This is called a restatement.
For example, GE reported net income of $225 million for 2022. A year later, its next 10-K showed
$339 million for the same year.
Seeing that the number changed is easy. Knowing why it changed is the hard part, and the reason
decides what the change means:
| Reason | What it means for someone using the old figures |
| Stock split | Per-share figures were rescaled. Nothing changed in the business. |
| Spin-off | Past years were redrawn to show only the part of the company that remains. |
| New accounting standard | The rules changed, so old and new years are measured differently. |
| Reclassification | Amounts moved between lines. Totals usually stay the same. |
| Error correction | The first number was wrong. |
The reason is written somewhere in a report of around 150 pages, often without the word "restate".
Today someone has to read the report to find it.
## What this agent does
Given a list of companies, it reads their 10-Ks and:
1. extracts key figures (revenue, net income, debt and others), each with the line it came from;
2. finds figures that a later report changed;
3. explains the reason for each change with a quote from the report, and checks that the quote is
really there;
4. checks with accounting rules whether that reason can explain that change;
5. sends anything code can't confirm to a person, who sees the evidence for every possible reason;
6. publishes the figures, the decisions and a short memo, once.
Every figure is graded against XBRL, the SEC's machine-readable copy of the same reports. The agent
never sees it.
Built with LangGraph and LangSmith, with models on Amazon Bedrock. Python 3.12, FastAPI,
pyright strict, 428 offline tests, and a React review screen for the person in the loop.
> Screen recording: youtu.be/3K4nv5uo2GY · Repository: github.com/jduval7/filings-agent
## Quickstart
You need uv and Node 22 (or 20.19+). No credentials, no model calls:
bash
git clone https://github.com/jduval7/filings-agent.git && cd filings-agent
make demo # then open http://localhost:8000
The review screen opens with a Demo panel of nine scenes, one per design decision. Each links to
its traces and experiments in LangSmith. To run it on live SEC data, see
Run it yourself.
## How to read this
| Read | You'll learn |
| Why it matters and what makes it hard | why this needs an agent you can check, not just a model |
| How it works | the steps, and where code checks the model |
| One failure, start to finish | how the evals found a real mistake and what I changed |
| How I know it works, then EVALS.md | the datasets, the checks and the results before and after |
| Where it falls short and the traces | what still fails, and LangSmith links to see it yourself |
Each design choice, with its evidence and date, is in DECISIONS.md.
## 2. Why it matters
Investors, analysts and auditors use past figures to compare years, build models and test
strategies. If an old figure changed and they don't know why, they can reach the wrong conclusion.