Metadata-Version: 2.4
Name: econlens
Version: 0.1.0
Summary: Precise real-world-example news search and spaced-repetition study tools for IB Economics — offline-first, explainable, classic IR (BM25).
Author: Harry Xin
License: MIT
Project-URL: Homepage, https://github.com/HarryXin0919/econlens
Project-URL: Repository, https://github.com/HarryXin0919/econlens
Keywords: ib,economics,education,information-retrieval,bm25,news,spaced-repetition,study-tool
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Education
Classifier: Topic :: Text Processing :: Indexing
Classifier: Intended Audience :: Education
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: feedparser>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: web
Requires-Dist: streamlit>=1.30; extra == "web"
Dynamic: license-file

<h1 align="center">EconLens 🔎</h1>

<p align="center">
  <i>Find precise, current real-world news examples for any IB Economics concept —
  ranked, explainable, and offline-first.</i>
</p>

<p align="center">
  <img src="https://img.shields.io/pypi/v/econlens?style=for-the-badge&color=3775AB&label=PyPI" alt="PyPI">
  <img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/IB%20Economics-0E7C61?style=for-the-badge" alt="IB Economics">
  <img src="https://img.shields.io/badge/BM25%20·%20classic%20IR-4B286D?style=for-the-badge" alt="BM25">
  <img src="https://img.shields.io/badge/license-MIT-007396?style=for-the-badge" alt="MIT">
</p>

---

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 every result matched. Fully
  deterministic: the same news yields the same ranking, every time.
- 🆓 **Offline-first & free** — pulls from key-less sources (economics RSS feeds +
  the free GDELT news API). An optional NewsAPI key adds more coverage but is never
  required.
- 🧩 **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

```bash
pip install econlens
```

Or from source:

```bash
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 each result matched
econlens news inflation --no-gdelt   # RSS only (faster; skips the slower GDELT API)
```

> GDELT can take 10–20 s and feeds occasionally hiccup; EconLens times out and
> retries each source independently, so one slow source never sinks a search.

## Concepts covered (v0.1)

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`](econlens/data/ontology.yaml) — see [CONTRIBUTING.md](CONTRIBUTING.md).

## Optional: more sources via NewsAPI

The free GDELT + RSS sources need no setup. To also query [NewsAPI](https://newsapi.org)
(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

- [x] **Phase 1** — concept ontology + multi-source fetch + BM25 ranking (`econlens news`)
- [ ] **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`](docs/DESIGN.md). To add concepts, keywords, or news sources, see
[`CONTRIBUTING.md`](CONTRIBUTING.md).

## License

MIT — see [LICENSE](LICENSE).
