bme-growth-screener
Screens every company listed on BME Growth, the Spanish growth market, against seven filters read from 4Founders Capital's four published investment criteria. Plain Python code rebuilds the universe as of a date from the public BME API, downloads each candidate's filings, applies the filters and checks every figure on its page. AI agents (Claude Code, Codex or any agent that reads AGENTS.md) do what the code cannot: read scanned pages, tell a founder's holding from a fund's, and judge, with file and page, whether technology is the product and whether a growth plan has been published.
On the 28 Oct 2026 universe: 109 listed, 55 operating companies once the SOCIMIs are removed, 35 inside the EUR 5-80M band, 34 candidates after one exclusion by name, and 1 PASS / 0 NEEDS_DATA / 33 FAIL. The pass is Cuatroochenta.
Example output: examples/report-2026-10-28.html, a copy of the runs/2026-10-28/report.html that the pipeline writes. It is one self-contained file: download it and open it in a browser (GitHub shows only the source). Figures taken from filings link to the PDF at the page they were read from. dashboard/index.html shows the workflow as a graph and dashboard/results.html the funnel and the pass.
Run it with your AI
git clone https://github.com/ignasigarciamartine-arch/bme-growth-screener
cd bme-growth-screener
claude # or: codex
/screen # Claude Code; with Codex, ask it to follow AGENTS.md
/screen (.claude/commands/screen.md) makes the agent the orchestrator: it runs the code, reads the work queue, hands each item to the reader, shareholders or filter agent (.claude/agents/), and runs the code again until the queue is empty. AGENTS.md holds the same loop and the rules for agents other than Claude Code.
Run the code alone
Python 3.11 or later. No system tools: PDFs are read with pypdfium2, a pip wheel that bundles PDFium.
python -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
python -m screener run --as-of 2026-10-28
python -m screener todo --as-of 2026-10-28
python -m pytest
run --as-of 2026-10-28 reads the versioned snapshot in data/snapshots/2026-10-28/ (the universe and the list of documents for that date), downloads the documents it lists from the BME API and the Lighthouse site into cache/, and applies the readings already versioned in data/extracted/2026-10-28/. The first run fetches about 1 GB; later runs read the cache. Output goes to runs/2026-10-28/: report.html, screened.csv (one row per candidate, with a source for every filter input), funnel.md, todo.csv and the check files. todo prints the agents' work queue: per company, the next filter still to read or judge. With the readings in this repo it is empty.
| Flag | What it does |
|---|
--offline | No network: the snapshot and cache/ only. Stops with a message if the snapshot is missing. |
--rebuild-snapshot | Rebuilds the universe and the document list from the BME API before running. A date with no snapshot is rebuilt anyway. |
--no-ocr | Skips the OCR re-check of figures read on page images. |
Rebuilding is why snapshots are versioned. Market cap uses the last close on or before the date, and the 2026-10-28 snapshot was taken during that day, with the 27 Oct close. Rebuilt the next day it takes the 28 Oct close: same 109 companies and same documents, different prices.
Tesseract is optional. With it, every run searches the figures read on scanned pages again by OCR; without it the verdicts are the same and the run lists the figures it could not re-check. Install it with winget install UB-Mannheim.TesseractOCR (Windows), brew install tesseract (macOS) or sudo apt install tesseract-ocr (Debian/Ubuntu), or point the TESSERACT variable at the executable.
python -m pytest runs 42 tests. Three need the downloaded documents and are skipped until the first run has filled cache/.
Method
Seven filters, from 4Founders' published criteria
The filters live in config/criteria.toml. Each one names the published criterion it comes from; where the criterion gives no number, the bar is mine and the file says so.
| Filter | Bar | Read by |
|---|
| C1 | Ticket fit (criterion 03) | Market cap EUR 5-80M, so a EUR 100K-4M ticket is about 5-20% of the company | code |
| C2 | Strong tech component (criterion 02) | BME sector 06; any other sector fails unless an agent shows, with file and page, that technology is the product | code + agent |
| C3 | Scale (criterion 02) | Revenue CAGR over 3 years of at least 20% | code |
| C4 | Ownership (criterion 01) | Founders, directors and management hold at least 20% | agent |
| C5 | International mindset (criterion 01) | At least 25% of revenue outside Spain | agent |
| C6 | Ambition (criterion 01) | A published growth plan with quantified targets and a date | agent |
| C7 | Clean accounts | Clean audit opinion, no material uncertainty on going concern | code + agent |
Before screening, the SOCIMIs (Spanish REITs) and two other property vehicles named in the config are removed: they are not operating companies.
Thresholds are never edited in place. A change goes into the [[changelog]] of the same file with its date, filter and reason, and applies to every company. The earlier criteria (F1-F8, a EUR 1-10M public-equity mandate) are replaced there by C1-C7 and remain in the git history.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
