econlens 0.2.0

Precise real-world-example news search and spaced-repetition study tools for IB Economics — offline-first, explainable, classic IR (BM25).

EconLens 🔎

Find precise, current real-world news examples for any IB Economics concept — ranked, explainable, and offline-first.

---

The hardest marks on IB Economics Paper 1 (b) — the 15-mark Evaluate / Discuss / Examine questions — reward real-world examples (RWE). EconLens turns any syllabus concept into a ranked list of current news stories you can cite, with the date, source, and a link back to the original article.

$ econlens news inflation

🔎 Inflation  [macro/inflation]
   1. [13.6] US inflation rose at fastest pace in three years as energy costs surge
          2026-05-28 · The Guardian — Economics
          https://www.theguardian.com/business/2026/may/28/...
   2. [ 4.0] US PCE inflation rate hits three-year high …
   ...
   see also: monetary_policy, interest_rates, deflation

Why it's different

• 🎯 Precise, not a keyword dump — each concept has a hand-tuned keyword set (must / boost / exclude), so "minimum wage" never returns "minimum balance".
• 🔬 Explainable — classic Okapi BM25 ranking with title-field weighting. Run with --why to see exactly which keywords and how recent each result is. Fully deterministic: the same news yields the same ranking, every time.
• 🕒 Recency-aware — RWE must be current, so fresher stories get a bounded, half-life recency bonus, and --since 30d trims the search to a window.
• 🆓 Offline-first & free — pulls from key-less sources (economics RSS feeds + the free GDELT news API), fetched concurrently so the wait is the slowest single source, not their sum. An optional NewsAPI key adds coverage but is never required.
• 🤖 Scriptable — --json emits structured results (status on stderr) so you can pipe EconLens into other tools.
• 🧩 Data-driven — concepts live in a YAML ontology; contributors extend coverage by editing data, not code. The schema reserves a course field so other curricula (A-Level, AP) can be added later.
• 🔒 Copyright-safe — only the headline, link, date, and source are stored; article bodies are never copied. Results always link to the original.

Quickstart

pip install econlens

Or from source:

git clone https://github.com/HarryXin0919/econlens.git
cd econlens
pip install -e .          # add .[dev] for tests

# list the concepts (35 across micro / macro / global / development)
econlens concepts
econlens concepts --unit macro

# find real-world examples for a concept
econlens news minimum_wage
econlens news tariffs --why            # show which keywords + how recent each match is
econlens news inflation --since 30d    # only stories from the last 30 days (also 2w, 3m, 1y)
econlens news inflation --no-gdelt     # RSS only (faster; skips the slower GDELT API)
econlens news tariffs --json           # structured output for piping into other tools

GDELT can take 10–20 s and feeds occasionally hiccup; EconLens fetches every source concurrently, with a per-source timeout and retries, so one slow source never sinks the search.

Concepts covered (v0.2)

35 core IB Economics concepts:

Unit	Examples
Micro	PED/PES, market failure, externalities, carbon/sugar tax, subsidies, minimum wage, price floors, monopoly, oligopoly, competition policy, labour markets
Macro	inflation, deflation, interest rates, monetary & fiscal policy, government debt, unemployment, economic growth, supply-side policy
Global	free trade, protectionism, tariffs, exchange rates, balance of payments
Development	economic development, poverty & inequality, foreign aid

Add more by editing econlens/data/ontology.yaml — see CONTRIBUTING.md.

Optional: more sources via NewsAPI

The free GDELT + RSS sources need no setup. To also query NewsAPI (free tier: 100 requests/day, non-commercial), copy config.example.py to config_local.py and add your key, or set the NEWSAPI_KEY environment variable. config_local.py is git-ignored and never committed.

Roadmap

• Phase 1 — concept ontology + multi-source fetch + BM25 ranking (econlens news)
• v0.2 — recency-aware ranking, concurrent fetch, --since / --json
• Phase 2 — syllabus-organised practice questions (econlens questions)
• Phase 3 — spaced-repetition review (SM-2) (econlens review)
• Phase 4 — optional Streamlit web UI

Design & contributing

The ranking model, ontology design, and source handling are documented in docs/DESIGN.md. To add concepts, keywords, or news sources, see CONTRIBUTING.md.

License

MIT — see LICENSE.