Whale
Agent

by Patrick Taylor

Newsletter Try it

How it works

From a regulator's website to your inbox

Eleven stages. Most of the work is translation and arithmetic. Some stages refuse bad input. This page describes the tool when you run it yourself. The public newsletter is coming soon.

The shape of it

Many filings go in and a few come out. Plain code does the narrowing, and you can read and configure it.

The pipeline, from many filings to a few rows Filings from several regulators enter on the left, pass through reading, pricing, a plausibility check and a size threshold, and a small number of rows leave on the right as an email. Regulators SEC, EDINET, MOPS Vendor feeds optional, paid On-chain optional Same shape one schema, USD Believable? size and price Held back counted, kept Big enough? your threshold Left out too small Your email a few rows

The eleven stages

  1. Decide which sources run today

    A source needs both a switch turned on and, where the provider requires one, a key. A source that is off is recorded with the reason. Your email then says "Taiwan is switched off" and does not look like a quiet day in Taiwan.

  2. Fetch and translate the filings

    Each source has its own reader that fetches the day's filings and rewrites them into one common shape: who filed, what they did, which company, how many shares, at what price, on what date, published when. To add a country, you add one reader.

  3. Work out the dollars

    Three ways, in order. If the filing states an amount, use it and convert the currency. If it states a share count and a price, multiply. If it states a percentage of a company, apply that to the company's value. If none of those are available, the filing keeps no dollar figure and says so.

  4. Add context

    How big the company is, what fraction of it this represents, whether this filer has appeared before, and how this compares to their usual size. Anything not learned stays blank. A blank is never treated as zero.

  5. Ask whether the number could be true

    A separate test from "where did this come from". A position cannot be worth more than the whole company. A share price of forty million dollars is not a share price. Filings that fail are marked, counted and held back rather than deleted. This page explains why.

  6. Score and rank

    Duplicates and later amendments of the same filing are collapsed into one. What remains gets a score from size, the fraction of the company involved, whether the filer is new, and whether several insiders at one company bought in the same window. Then the filings are sorted and split into tiers.

  7. Apply your threshold

    Anything below the size you set does not go in the email. The default is $5M. Setting it to $250,000 is one flag. Everything read is still stored, so changing the threshold does not mean losing the past.

  8. Look for patterns across the window

    Four insiders at one company who each buy $2M do not pass a $5M filter one by one. So pattern detection runs over everything read, and the group total must be a real amount.

  9. Write the words

    Optional, and off by default. With a key, a language model (Gemini free tier, Anthropic or OpenAI) writes the summary sentences. It gets finished strings like "$12.4M" and must copy them. It does not see raw filings or scores and does no arithmetic. With no key, a fixed template writes the sentences. The newsletter will not use a model.

  10. Check every figure against the filings

    Before anything is sent, each sentence containing a number is checked against the underlying filings. If a number does not trace back to a field, the sentence is dropped and the email is rebuilt from the plain version.

  11. Send it

    When you run it yourself with your own email settings, it sends the daily table and a weekly note to the address you set. A separate alerts command can flag very large single positions. A refused send reports a failure, so a run that delivers nothing never looks like a success.

What arrives

If you run it yourself: a daily email with the table, and a weekly note that groups the week into patterns. The weekly note always carries the same block of caveats, including that insider buys carry more information than sells, that the historical effect was concentrated in smaller companies and has weakened since it was published, and that fund holdings data is stale by the time it appears.

Given the same filings and the same date, the daily text, the daily email, the weekly report and the ranking come out identical every time you run it. That is checked by a test. The written prose is the exception and is allowed to vary, but the figures inside it are not.

Set up

Python 3.11 or newer, and a contact email address for the SEC, which the SEC requires of anyone reading their archive in bulk. The free sources need nothing else. Paid feeds are optional and the tool tells you which ones are off.

Tuning it

Profiles are small config files. One watches only US insiders at a $1M threshold and ignores 10% owners. One watches only activist stakes. Settings are layered, and the tool can print each value along with which layer set it, so you can see where each setting came from.