Metadata-Version: 2.4
Name: citedhealth
Version: 0.1.0
Summary: Evidence-based supplement research API client — search ingredients, conditions, evidence grades, and PubMed papers from Cited Health.
Project-URL: Homepage, https://citedhealth.com
Project-URL: Documentation, https://citedhealth.com/developers/
Project-URL: Repository, https://github.com/dobestan/citedhealth
Project-URL: API, https://citedhealth.com/api/openapi.json
Author-email: "Cited Health Inc." <dev@citedhealth.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cited,citedhealth,clinical,evidence,evidence-grading,health,ingredients,pubmed,research,supplements
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: typer>=0.15; extra == 'all'
Provides-Extra: api
Requires-Dist: httpx>=0.27; extra == 'api'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.15; extra == 'cli'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# citedhealth

[![PyPI](https://img.shields.io/pypi/v/citedhealth)](https://pypi.org/project/citedhealth/)
[![Python](https://img.shields.io/pypi/pyversions/citedhealth)](https://pypi.org/project/citedhealth/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/citedhealth/)

Pure Python API client for [Cited Health](https://citedhealth.com) — the evidence-based supplement research platform where every health claim is backed by peer-reviewed PubMed research. Search ingredients, conditions, evidence grades (A-F), and indexed papers. Free, no authentication required.

Cited Health maintains a growing network of supplement review sites covering hair health, sleep, and more. The platform indexes PubMed papers, extracts study data using AI, and calculates evidence grades from A (Strong — multiple RCTs/meta-analyses) to F (Negative — most studies show no effect).

> **Explore the evidence at [citedhealth.com](https://citedhealth.com)** — [Ingredients](https://citedhealth.com/api/ingredients/) · [Evidence](https://citedhealth.com/api/evidence/) · [Papers](https://citedhealth.com/api/papers/) · [Developer Docs](https://citedhealth.com/developers/)

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [Search Ingredients](#search-ingredients)
  - [Check Evidence Grades](#check-evidence-grades)
  - [Search PubMed Papers](#search-pubmed-papers)
  - [Embed Evidence Badges](#embed-evidence-badges)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [API Reference](#api-reference)
- [Learn More About Evidence-Based Supplements](#learn-more-about-evidence-based-supplements)
- [License](#license)

## Install

```bash
# Core (zero dependencies)
pip install citedhealth

# With API client (adds httpx)
pip install "citedhealth[api]"

# With CLI (adds typer + rich)
pip install "citedhealth[cli]"

# With MCP server for AI assistants
pip install "citedhealth[mcp]"

# Everything
pip install "citedhealth[all]"
```

## Quick Start

```python
from citedhealth.api import CitedHealth

with CitedHealth() as api:
    # Search for supplement ingredients
    data = api.ingredients(q="biotin")
    print(data["results"][0]["name"])  # Biotin

    # Check evidence for a supplement-condition pair
    evidence = api.evidence(ingredient="biotin", condition="hair-loss")
    link = evidence["results"][0]
    print(f"Grade: {link['grade']}, Studies: {link['total_studies']}")

    # Get embeddable badge data
    badge = api.badge_data("biotin", "hair-loss")
    print(f"{badge['ingredient']} for {badge['condition']}: Grade {badge['grade']}")
```

## What You Can Do

### Search Ingredients

Cited Health catalogs supplement ingredients with their mechanisms of action, categories, and evidence profiles. Each ingredient is linked to conditions through evidence grades.

```python
from citedhealth.api import CitedHealth

with CitedHealth() as api:
    # List all ingredients
    all_ingredients = api.ingredients()

    # Search by name
    results = api.ingredients(q="melatonin")

    # Filter by category (vitamins, herbs, amino-acids, minerals, etc.)
    vitamins = api.ingredients(category="vitamins")
```

Learn more: [Browse Ingredients](https://citedhealth.com/) · [Developer Docs](https://citedhealth.com/developers/)

### Check Evidence Grades

The evidence grading engine analyzes PubMed studies and calculates grades from A to F:

| Grade | Label | Criteria |
|-------|-------|----------|
| A | Strong | Multiple RCTs/meta-analyses, consistent positive results |
| B | Moderate | At least one RCT, mostly consistent |
| C | Limited | Small studies, some positive signals |
| D | Preliminary | In vitro, case reports, pilot studies |
| F | Negative | <30% of studies show positive effects |

```python
from citedhealth.api import CitedHealth

with CitedHealth() as api:
    # Check evidence for biotin and hair loss
    evidence = api.evidence(ingredient="biotin", condition="hair-loss")
    for link in evidence["results"]:
        print(f"{link['grade']}: {link['ingredient']['name']} for {link['condition']['name']}")
        print(f"  {link['total_studies']} studies, {link['total_participants']} participants")
```

Learn more: [Evidence Reviews](https://citedhealth.com/evidence/) · [Grading Methodology](https://citedhealth.com/editorial-policy/)

### Search PubMed Papers

All papers in Cited Health are indexed from PubMed and enriched with citation data from Semantic Scholar.

```python
from citedhealth.api import CitedHealth

with CitedHealth() as api:
    # Search papers by title
    papers = api.papers(q="melatonin sleep quality")

    # Filter by publication year
    recent = api.papers(q="biotin", year=2024)
    for paper in recent["results"]:
        print(f"[PMID {paper['pmid']}] {paper['title']}")
```

Learn more: [Browse Papers](https://citedhealth.com/papers/) · [OpenAPI Spec](https://citedhealth.com/api/openapi.json)

### Embed Evidence Badges

Get badge data to display evidence grades on external sites. Each badge shows the grade, study count, and links back to the full evidence review.

```python
from citedhealth.api import CitedHealth

with CitedHealth() as api:
    badge = api.badge_data("biotin", "hair-loss")
    print(f"Grade: {badge['grade']} ({badge['grade_label']})")
    print(f"Studies: {badge['studies']}, Participants: {badge['participants']}")
    print(f"Evidence page: {badge['url']}")
```

Or embed directly with a script tag:
```html
<script src="https://citedhealth.com/embed/biotin/for/hair-loss/badge.js"></script>
```

## Command-Line Interface

```bash
# Search ingredients
citedhealth ingredients --query biotin

# Check evidence links
citedhealth evidence --ingredient biotin --condition hair-loss

# Search papers
citedhealth papers --query "melatonin sleep" --year 2024

# Get badge data
citedhealth badge biotin hair-loss
```

## MCP Server (Claude, Cursor, Windsurf)

Add to your `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "citedhealth": {
            "command": "uvx",
            "args": ["--from", "citedhealth[mcp]", "python", "-m", "citedhealth.mcp_server"]
        }
    }
}
```

Available tools:
- `search_ingredients` — Search supplement ingredients
- `check_evidence` — Check evidence grade for a supplement-condition pair
- `search_papers` — Search PubMed-indexed papers

## API Reference

| Method | Description | Parameters |
|--------|-------------|------------|
| `ingredients()` | List/search ingredients | `q`, `category`, `page`, `page_size` |
| `papers()` | List/search papers | `q`, `year`, `page`, `page_size` |
| `evidence()` | List evidence links | `ingredient`, `condition`, `page`, `page_size` |
| `badge_data()` | Get embed badge data | `ingredient_slug`, `condition_slug` |
| `openapi_spec()` | Get OpenAPI 3.1.0 spec | — |

## Learn More About Evidence-Based Supplements

- **API**: [REST API Documentation](https://citedhealth.com/developers/) · [OpenAPI 3.1.0 Spec](https://citedhealth.com/api/openapi.json)
- **Browse**: [Ingredients](https://citedhealth.com/) · [Evidence Reviews](https://citedhealth.com/evidence/) · [Papers](https://citedhealth.com/papers/)
- **Guides**: [Editorial Policy](https://citedhealth.com/editorial-policy/) · [Medical Disclaimer](https://citedhealth.com/medical-disclaimer/)
- **Embed**: [Badge Widget](https://citedhealth.com/developers/#embed-evidence-badges) · [Citation Formats](https://citedhealth.com/developers/)

## License

MIT — see [LICENSE](LICENSE).
