market_screener_rag is an offline command-line tool that tells you which stock-picking approach survived backtesting in each of six markets and applies it to a bundled snapshot of company data.
Open-source tools · How-to · Equity screening research
How to use market_screener_rag: backtested stock strategies by country
Revised
· v1.0.0 · what changed
Code: github.com/herrrickshaw/market_screener_rag
Watch the walkthrough
Watch on YouTube: youtu.be/3hloP1KwL5I
What it is for
Most stock factors do not work everywhere. This tool keeps a short knowledge base of what the authors' backtests found for each market, including the results that failed. It reports each strategy's historical earnings with its significance tests (t-stat and Deflated Sharpe), and it states clearly when a market has no edge.
You can ask it for a market's strategy, run that market's screen on a bundled snapshot of company ratios to see example picks, list the historical earnings of every strategy, or ask a free-form question. Answers come from the stored backtest results. The tool does not invent numbers.
It is for learning and research. It is not a trading system.
Who it is for
- Students and analysts who want to see how backtested evidence differs by market
- Engineers who want a small example of a rule-based knowledge base with TF-IDF search (no model, no API)
- Anyone who wants a plain-language look at why nulls and failed strategies matter
- Investment advice. The README and every output say research and education only
- Live trading. All earnings are gross of costs and short-borrow, on survivorship-biased universes
- Using the picks as they are. The snapshot is bundled data, not a live feed, so validate each name yourself
What you need
| Requirement | Why | How to get it |
|---|---|---|
| Python 3 | runs screener_rag.py | python.org, or brew install python. The repo does not state a minimum version |
| pandas, scikit-learn, tabulate | the three packages in requirements.txt: tables, TF-IDF search and table printing | pip install -r requirements.txt |
| Disk and RAM | small bundled data files and charts | A few tens of MB. Any laptop will do |
| Internet access | only to clone the repo and install packages | Not needed to run the tool afterwards |
| API keys, GPU, model downloads | not required | The README says there is no paid API and no model download. A local LM Studio or ollama server is mentioned only as an optional extra |
Get the code and an AI assistant
You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:
| Tool | What you need | Best for |
|---|---|---|
| GitHub | Free account to fork or star; git to clone, or the green Code button, then Download ZIP, or open in Codespaces | Getting the code and keeping up with updates |
| Claude Code | Claude subscription or API key; run claude inside the cloned folder | Letting the AI read and run the whole repo |
| Gemini CLI | Google account; run gemini inside the cloned folder | The same hands-on workflow with Gemini |
| Claude.ai, Gemini or ChatGPT in the browser | A chat account; upload README.md and the files you care about (or paste the output of git ls-files) | Understanding the project and asking questions without installing anything |
| Other tools (Copilot Chat, Cursor, Codex CLI) | Open the cloned folder in the tool and point it at README.md first | Editing and extending the code |
git clone https://github.com/herrrickshaw/market_screener_rag.git
cd market_screener_rag
claude # or: geminiInstall
- Clone the repo and create a virtual environment.
git clone https://github.com/herrrickshaw/market_screener_rag.git cd market_screener_rag python3 -m venv .venv source .venv/bin/activate - Install the three dependencies.
pip install -r requirements.txt
Quick start: commands and what you should see
See the winning strategy for one market (Korea).
python screener_rag.py strategy KRA page headed Korea, winning strategy (backtested). Character: mean-reversion. Book: full long/short. It lists the long and short rules and the earnings, including +4.83% per 6 months at t 4.17, and ends with the verdict TRUST and a research-only note.
Compare the historical earnings of every market's strategy.
python screener_rag.py earningsA table with one row per market (India, US, Korea, Europe, Japan, China), each with its strategy, earnings and significance. Japan shows +6.6% per 6 months (t 4.84). China shows value failing, with a spread near 0% (t 0.04), which the tool labels a real null result.
Apply the India screen to the bundled snapshot.
python screener_rag.py screen INA long list of 15 cheap-for-quality names with PE, PB, ROE and a valuation score, all marked UNDERPRICED. It ends with: no short book, because shorting fails in India (-1.0% per 6 months), and a note that the list is gross of costs and not investment advice.
Ask a free-form question.
python screener_rag.py ask "does value work in china"The line (best match: China), then the China page. The verdict is that value-reversion fails in China (a powered null) and that a value screen should not be run there.
See the one finding that holds across markets.
python screener_rag.py universalA short note that momentum/trend in bull regimes is the one metric that works in nearly every market and survives the multiple-testing check. Mean-reversion is fragile everywhere.
Ways to use it
| Method | How it works |
|---|---|
| Command line | python screener_rag.py with the commands strategy, screen, earnings, universal and ask, as listed in the README. |
| Read the knowledge base | winning_strategies.json holds the per-market rules and results. The bundled data/ folder holds the ratio snapshot the screen runs on. |
| Learn the terms | GLOSSARY.md explains momentum, PE, t-stat and Deflated Sharpe in plain English. Charts such as edge_matrix.png are in the repo root. |
| Through an AI assistant | Open the cloned folder in Claude Code or Gemini CLI and ask it to run commands and explain the output. The repo has no web UI or Python API documented. |
Sample prompts for your AI assistant
Copy, paste and edit the parts in [brackets].
- Read README.md and GLOSSARY.md and explain in plain English what a t-stat and a Deflated Sharpe ratio tell me about a strategy.
- Run python screener_rag.py earnings and summarise which markets have a tested edge, which have a null result, and which do not have enough data.
- Explain why the tool says there is no short book in India, and show me where that comes from in winning_strategies.json.
- I want to see how screen rules are applied. Walk me through the screen code in screener_rag.py for Korea, step by step, without changing anything.
- How would I add my own market or strategy to winning_strategies.json? List the fields I would need and the data I would have to bring.
- List every reason I should not trade on these picks, using the limits written in the README.
Limits and honest caveats
- Research and education only. Not investment advice.
- All earnings are gross of costs and short-borrow, on survivorship-biased universes. Read the spreads, not the levels.
- Capacity is small: roughly 300 to 500 thousand dollars before the illiquidity edge decays. The tool says the real edge is illiquidity, not size.
- Annualised figures are indicative, not compounded guarantees.
- The Japan panel is a sample of about 1,437 firms, and China coverage is thin (426 of about 3,454 liquid stocks).
- The screen runs on a bundled snapshot of ratios, not live data. Validate each name before acting on it.
- The repo has no test suite or evaluation harness. The demo ran the command-line tool only, so the backtests were not re-run or independently checked.
- The demo showed only the first lines of the India screen. The output shown in the video is trimmed.
Sources: the market_screener_rag README, GLOSSARY.md, requirements.txt and winning_strategies.json, and the demo run of 18 October 2026.
- v1.0.0 — 18 October 2026 — first published.
About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.
