mad-search

Search OpenAlex for academic articles using YAML-frontmatter markdown files.

Requirements

• Python 3.13+
• A free OpenAlex API key

Installation

# run directly with uv
uv run mad-search path/to/search.md

# or install globally
uv tool install mad-search

Usage

Create a markdown file with YAML frontmatter:

---
api_key: your_key_here
query: "(machine learning AND climate) OR large language models"
journals:
  - Nature
  - Science
year_from: 2020
year_to: 2025
---

Run it:

uv run mad-search search.md

Results are written to out/<input>.md (the input file is never modified — keeping your API key safe).

Features

• Boolean search — AND, OR, NOT with parentheses, passed directly to OpenAlex's Elasticsearch backend
• Journal filter — names auto-resolved to ISSNs via the OpenAlex Sources endpoint
• Year range — optional year_from / year_to constraints
• Result re-ranking — results scored by title match (40%), abstract match (20%), and concept overlap (40%) after retrieval
• Structured output — summary table plus detail sections with DOI, citation count, FWCI, concepts (top 5, score ≥ 0.3), topics, and abstract
• Idempotent — re-running overwrites out/<input>.md

Output

Results are written to out/<input>.md as a markdown table with detail sections:

## Results — 5 paper(s) found

| # | Title | DOI | Journal | Year | Citations | Authors |
|---|---|---|---|---|---|---|

---

### 1. Paper Title

- **DOI:** `10.xxx/...`
- **Authors:** ...
- **Journal:** ...
- **Citations:** 124 | FWCI: 3.2
- **Concepts:** Climate Science (0.92), Machine Learning (0.87)
- **Topics:** Machine Learning (0.99), Climate Science (0.85)
- **Abstract:** ...

License

MIT — see LICENSE.