Metadata-Version: 2.4
Name: mad-search
Version: 0.1.0
Summary: Search OpenAlex for academic articles using YAML-frontmatter markdown files
Project-URL: Homepage, https://codeberg.org/divinemadman/mad-search
Project-URL: Repository, https://codeberg.org/divinemadman/mad-search.git
Project-URL: Issues, https://codeberg.org/divinemadman/mad-search/issues
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: pyalex>=0.21
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# mad-search

[![Codeberg](https://img.shields.io/badge/hosted-Codeberg-2185D0?logo=codeberg)](https://codeberg.org/divinemadman/mad-search)

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

## Requirements

- Python 3.13+
- A free [OpenAlex API key](https://openalex.org/settings/api)

## Installation

```bash
# 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:

```markdown
---
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:

```bash
uv run mad-search search.md
```

Results are appended to the same file, overwriting any previous results.

## 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), and abstract
- **Idempotent** — re-running replaces the previous results section

## Output

Results are appended as a markdown table with detail sections:

```markdown
## 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)
- **Abstract:** ...
```

## License

MIT — see [LICENSE](LICENSE).
