Metadata-Version: 2.4
Name: pubmed-search
Version: 0.6.0
Summary: CLI and Python SDK for biomedical literature search with MeSH, PICO, and intelligent query expansion
Project-URL: Homepage, https://github.com/PiaoyangGuohai1/pubmed-search
Project-URL: Repository, https://github.com/PiaoyangGuohai1/pubmed-search
Project-URL: Issues, https://github.com/PiaoyangGuohai1/pubmed-search/issues
Author-email: u9401066 <u9401066@gap.kmu.edu.tw>
Maintainer: PiaoyangGuohai1
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cli,entrez,literature,medical,ncbi,pubmed,research,sdk,search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Requires-Dist: apscheduler<4,>=3.10
Requires-Dist: biopython>=1.81
Requires-Dist: cachetools>=5.0.0
Requires-Dist: click>=8.1
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: dependency-injector>=4.48.3
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic-settings<3,>=2.10
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: pylatexenc>=2.10
Requires-Dist: pywin32>=311; sys_platform == 'win32'
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.9
Requires-Dist: toons>=0.5.4
Provides-Extra: all
Requires-Dist: click>=8.1; extra == 'all'
Requires-Dist: rich>=13.9; extra == 'all'
Provides-Extra: cli
Requires-Dist: click>=8.1; extra == 'cli'
Requires-Dist: rich>=13.9; extra == 'cli'
Description-Content-Type: text/markdown

# PubMed Search

CLI and Python SDK for biomedical literature search, query analysis, citation export, full-text lookup, and multi-source academic enrichment.

This repository is CLI/SDK-first. The primary runtime surface is the `pubmed-search` shell command, which is friendly to Codex-like coding agents, terminal workflows, and scripts. The Python package also exposes reusable clients and application services for projects that need direct imports.

## Origin and Attribution

This CLI/SDK mainline is maintained at [`PiaoyangGuohai1/pubmed-search`](https://github.com/PiaoyangGuohai1/pubmed-search). It is derived from and inspired by [`u9401066/pubmed-search-mcp`](https://github.com/u9401066/pubmed-search-mcp), with the Apache-2.0 license and upstream attribution preserved. The original MCP-oriented fork remains a legacy reference; this repository maintains the terminal and Python SDK surfaces.

## Install

```bash
pip install pubmed-search
```

For local development from this repository:

```bash
pip install -e .
```

Optional NCBI credentials can be provided through flags or environment variables:

```bash
export NCBI_EMAIL="you@example.com"
export NCBI_API_KEY="optional_ncbi_key"
```

## CLI

```bash
pubmed-search --help
pubmed-search search "MASLD cardiovascular risk" --format json --limit 5
pubmed-search strategy "MASLD cardiovascular risk" --format json
pubmed-search analyze-query "MASLD cardiovascular risk" --format json
pubmed-search details 38905512 --format markdown
pubmed-search export 38905512 --format ris
pubmed-search fulltext 38905512 --format markdown
pubmed-search timeline "MASLD cardiovascular risk" --limit 20 --format markdown
```

Core commands:

| Command | Purpose |
| --- | --- |
| `search` | Search biomedical literature across PubMed and optional academic sources. |
| `strategy` | Generate MeSH expansion and search strategy materials. |
| `analyze-query` | Analyze intent, complexity, identifiers, PICO, and source recommendations without running a search. |
| `details` | Fetch detailed metadata for one or more PMIDs. |
| `export` | Export citations as BibTeX, RIS, CSV, MEDLINE, CSL JSON, or JSON. |
| `fulltext` | Locate full-text access through available source resolvers. |
| `text-mined` | Retrieve text-mined biomedical terms when source data is available. |
| `related` | Find related articles for a PMID. |
| `metrics` | Fetch citation metrics where supported. |
| `timeline` | Build research timeline summaries from a query or PMID set. |
| `cite-tree` | Explore citation/reference relationships around a root PMID. |
| `pico` | Parse a clinical question into PICO-style components. |
| `gene`, `compound`, `clinvar` | Query NCBI extended databases. |

Use `--format json` for agent and script workflows. Use `--output path` to write command output directly to a file.

## Python SDK

```python
from pubmed_search import LiteratureSearcher, QueryAnalyzer, export_articles

searcher = LiteratureSearcher(email="you@example.com")
articles = searcher.search("MASLD cardiovascular risk", limit=5)

for article in articles:
    print(article["pmid"], article["title"])

analysis = QueryAnalyzer().analyze("MASLD cardiovascular risk")
print(analysis.intent, analysis.complexity)

bibtex = export_articles(articles, fmt="bibtex")
```

Useful imports include:

- `LiteratureSearcher` for PubMed search/details/citation metrics.
- `SearchStrategyGenerator` for MeSH and query strategy generation.
- `QueryAnalyzer` and `ResultAggregator` for application-level search planning.
- `EuropePMCClient`, `NCBIExtendedClient`, and source client factories for external data sources.
- `export_articles`, `export_bibtex`, `export_ris`, `export_csv`, `export_medline`, and `export_json` for citation output.

## Architecture

The codebase keeps the retrieval product independent from any host application:

```text
src/pubmed_search/
  cli/             click commands and terminal formatting
  application/     search planning, export, fulltext, timeline, and session services
  domain/          article and pipeline entities
  infrastructure/  NCBI, Europe PMC, OpenAlex, Semantic Scholar, Crossref, Unpaywall, and other adapters
  shared/          settings, logging, cache, and cross-cutting helpers
```

The CLI imports application services directly. Presentation-specific protocol servers are not part of the main package. If a protocol adapter is needed again later, it should live in a separate package that depends on `pubmed-search`.

## Development

```bash
pip install -e .[all]
pytest
ruff check .
```

The editable package installs only the `pubmed-search` console command.

## Citation

If you use this software in research or internal methods documentation, cite the repository metadata in [CITATION.cff](CITATION.cff).
