Tubby Quant · open-source research workbench
Run BRAIN-style alphas on your own data, on your own machine. Screen fast in Alpha Lab, validate long/short on a pinned Qlib engine, and let a research loop propose and test ideas while every result keeps the evidence it came from.
Four tools with distinct jobs, from a first idea to a report you can reopen months later. Each one records what it used.
A fast screen for WorldQuant-BRAIN-style FASTEXPR alphas on a fixed book: the same operators, neutralization, truncation and decay conventions, with every operator’s semantics written down. No account, no queue, no rate limit.
Market data is converted once into immutable Qlib snapshots. Nothing in the source is ever modified, and nothing is filled in to look complete. Survivorship-free paths (Sharadar, HistoricalData) keep delisted names in the history.
Built on Qlib 0.9.7. Our pinned, reproducibly built derivative adds signed weights, stock borrow costs and restricted short proceeds, so an alpha’s direction and size carry straight into whole-share positions filled at the next open.
A campaign reads sources, proposes hypotheses that must quote them exactly, tests each expression chronologically after costs, and refines, rejects or promotes it under explicit gates. The reserved holdout is scored once, by a person, and that access is recorded.
Six steps, always in this order. Each leaves a record, so any result can be traced back to the data it came from.
Import once, verify every file, never touch the source.
Rank at each month-end; members count from the next session.
An allow-listed expression language. Anything the engine can’t evaluate is rejected up front.
Top-k long-only, or signed weights scaled to a gross exposure.
Signals from today’s close fill at tomorrow’s open, net of costs and borrow.
Metrics, positions and hashes are written once. A cancelled run is never marked complete.
Two loops with different clocks. The inner one runs itself within budgets; the outer one is where people decide what the next campaign should ask.
arXiv abstracts or a reviewed plan. A proposal must quote the text it builds on, exactly.
A falsifiable price/volume expression, its family, horizon and required fields, from a model or your own agent.
Development then validation, delay 1, after costs, in the same Alpha Lab engine you screen with.
Sharpe, return, turnover and drawdown thresholds you set. Refine, reject, park or promote; failures are kept too.
A person finalizes promoted ideas on the reserved period. The access is recorded before the run; a repeat is labelled reused and never confirmed.
Promoted or confirmed expressions become an Alpha Lab batch and a Qlib validation request, with their provenance attached.
Every cited source needs a verbatim excerpt from the retrieved text. An abstract is labelled as an abstract.
Model calls per day and per campaign, evaluations, ideas per family and refinement depth are explicit numbers in the campaign file.
Promotion and confirmation mean deeper research. The loop places no orders and never reads the holdout on its own.
New in the lab · public release next
Nothing in the way we keep research honest is specific to equities. A domain decides what a candidate is and how it is scored; the harness keeps the count, the seals and the record. Quant is the first branch, machine learning the second, and the next one plugs into the same contract.
Lab harness
Each domain plugs into one contract. The harness supplies everything that makes a search trustworthy.
Every screen, validation, review and holdout access is a line in a ledger that carries the hash of the line before it. Edit or delete one and the chain breaks.
The screen runs on data that physically ends where development ends; validation probes on data that ends where validation ends. Only an explicit final command loads the holdout.
Thresholds, data and code hash into the campaign’s ID. Changing a gate starts a new campaign; it cannot rescue an old candidate.
An agent can submit candidates over MCP. They face the same screen, count and review as everything the search generates.
Domain · autonomous alpha discovery
A typed search writes FASTEXPR expressions, screens them on data that stops where development ends, and spends a scarce validation budget only on fit, diverse candidates. A promotion has to beat the best result that luck alone would have produced from everything tried.
Why the count matters
The research benchmark: an artificial 300-name panel with three planted signals, its null twin with identical noise, and four more null panels with other noise. Known answers, no market data; rerun with tubby-lab benchmark alpha.
Domain · machine learning
Here a hypothesis is a training recipe and an experiment is a bounded training run. Recipes are searched the way alphas are: screened cheaply, validated on rows the screen never saw, and finalized once.
Ridge and logistic regression, histogram gradient-boosted trees, random forests and multilayer perceptrons, written in plain numpy. Every trained model is saved as JSON and reloads to identical predictions.
friedman1
A regression with irreducible noise of exactly 1.0, so the gap between a confirmed model and the best possible model is measured, not guessed.
interaction
A classification task whose true probabilities are kept, so every holdout report sits beside the Bayes-optimal log loss.
null_regression
Features carry no information about the target, so a promotion would be a false discovery. The search validated recipes and promoted none.
Claude Code, Codex or any MCP client can check and simulate alphas, compare a batch, read the saved library and campaign reports, and queue candidates for a lab campaign through one small server. Everything stays inside the data root you launch it with.
$ claude mcp add tubby-alpha-lab -- tubby-alpha-mcp --data-root ~/tubby-data
Added stdio MCP server tubby-alpha-lab
$ tubby-alpha-mcp --data-root ~/tubby-data
tubby-alpha-lab 0.2.0: data root ~/tubby-data
tools list_operators signatures, fields, groups, aliases
check_expression syntax and names, no data
list_datasets prepared snapshots and universes
simulate_alpha BRAIN-style settings, summary and checks
simulate_batch leaderboard and correlated pairs
library_list saved alphas
research_report read-only campaign findings
lab_report discovery and ML funnels, from the ledger
lab_submit queue a candidate; no gate is skippedPython 3.12 and Git. The package installs Alpha Lab, the research loop, the console and the data adapters on Windows, macOS and Linux; the verified long/short Qlib runtime uses the platform setup script.
Windows x64 has installation and synthetic signed-run evidence; macOS is experimental; Linux has no pinned signed runtime. Read the limitations before interpreting any statistic.
$ git clone https://github.com/tubby-labs-research/tubby-quant.git
$ cd tubby-quant && python3.12 -m venv env/core
$ env/core/bin/python -m pip install -e .
$ env/core/bin/tubby-quant --browser --data-root ~/tubby-data
Tubby Qlib Console is running at http://127.0.0.1:…
# later, from the same environment
$ tubby-research run campaign.json --once --allow-model
$ tubby-research report --markdown
$ tubby-research finalize campaign.json
$ tubby-research export campaign.json --output promoted.txt
# the lab domains, on artificial data with known answers
$ tubby-lab demo alpha --root ./lab-alpha
$ tubby-lab benchmark ml --root ./bench-mlThe rules we hold ourselves to, whichever idea we happen to be testing.
We start from proven open-source software, change as little as we can, and write down every change we make.
A result counts when its data, settings and tests are on record. A good-looking chart is not evidence.
Universes, signals and fills follow the calendar. Look-ahead is a bug, not a detail.
Pinned versions, fingerprinted inputs, and rebuilds that match byte for byte.
Results are material for discussion, never a signal to buy or sell. Their limits are written down right beside them.
The framework is free and open source under Apache 2.0. Specific strategies and portfolios stay private.
tubby-quant is on GitHub under Apache 2.0: Alpha Lab, the research loop, the console, the data adapters and the MCP server, with about 2,200 offline tests on synthetic fixtures. Our long/short changes to Qlib live in a separate derivative under Qlib’s MIT license. Strategies, data and results are not part of either.
$ tubby-research demo --root ./demo
{"status": "discovered", "sources": 1, "queued": 2}
{"status": "evaluated", "outcome": "ok"}
{"status": "reviewed", "decision": "refine", "reason": "misses configured gates: Sharpe"}
{"status": "refined", "queued": 1}
{"status": "evaluated", "outcome": "ok"}
{"status": "reviewed", "decision": "reject", "reason": "refinement stalled"}
{"status": "stopped", "evaluations": 3, "queued": 0}
# synthetic data, deterministic responses, no model callsEach stage has to prove itself before the next one starts. Nothing here is a date or a promise of performance.
The public research preview: offline Alpha Lab, verified US daily data with point-in-time universes, signed Qlib validation, a research loop with a sealed holdout, and the MCP server. In the lab: autonomous alpha discovery and a machine-learning domain on one harness, measured on planted-signal benchmarks.
The lab domains in the public framework and the console, full-text sources, fundamentals and groups inside campaigns, automatic hand-off from a confirmed discovery into signed validation, and further domains on the same harness.
Portfolio sleeves from confirmed ideas, a restartable paper account on historical sessions, and decision support for trades placed by people. Automation comes only after that has earned trust.