# wideholy

[![PyPI](https://img.shields.io/pypi/v/wideholy)](https://pypi.org/project/wideholy/)
[![Python](https://img.shields.io/pypi/pyversions/wideholy)](https://pypi.org/project/wideholy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Python SDK for **WideHoly** — cross-religion scripture search, verse comparison, verse of the day, religious calendar, and commentary across 5 world religions. Access 236,866 scripture records spanning Christianity (124K verses), Islam (31K ayahs), Judaism (69K verses), Hinduism (6K verses), and Buddhism (5K texts) through a unified API.

Built on the [WideHoly](https://wideholy.com) platform, which aggregates scripture data from 5 religion-specific sites — [WideBible](https://widebible.com), [WideQuran](https://widequran.com), [WideTorah](https://widetorah.com), [WideGita](https://widegita.com), and [WideSutra](https://widesutra.com) — into a single cross-religion hub with comparison tools, shared topics, and a unified religious calendar.

> **Explore the interactive tools at [wideholy.com](https://wideholy.com)** — [Compare Verses](https://wideholy.com/developers/), [Religious Calendar](https://wideholy.com/developers/), [Cross-Religion Topics](https://wideholy.com/topics/)

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You'll Find on WideHoly](#what-youll-find-on-wideholy)
  - [Five World Scriptures](#five-world-scriptures)
  - [Cross-Religion Comparison](#cross-religion-comparison)
  - [Religious Calendar](#religious-calendar)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About World Scriptures](#learn-more-about-world-scriptures)
- [WideHoly Family](#wideholy-family)
- [License](#license)

## Install

```bash
# Core (no dependencies)
pip install wideholy

# With API client
pip install "wideholy[api]"

# With CLI
pip install "wideholy[cli]"

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

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

## Quick Start

```python
from wideholy.api import WideHoly

with WideHoly() as client:
    # Get today's verse of the day from the Bible
    votd = client.verse_of_the_day("bible")
    print(votd["reference"])  # e.g. "Psalm 23:1"
    print(votd["text"])       # "The LORD is my shepherd; I shall not want."

    # Compare Genesis 1:1 with Quran Al-Fatihah 1
    result = client.compare("bible:genesis.1.1", "quran:al-fatihah.1")
    print(result["verse_a"]["text"])  # "In the beginning God created..."
    print(result["verse_b"]["text"])  # "In the name of Allah..."

    # Search across all religions
    suggestions = client.search_suggest("love")
    for s in suggestions["suggestions"]:
        print(f"  {s['religion']}: {s['text']} ({s['type']})")
```

## What You'll Find on WideHoly

### Five World Scriptures

WideHoly aggregates scripture data from 5 major world religions, each with its own dedicated site for deep exploration. The hub API provides unified cross-religion access to all 236,866 records.

| Religion | Scripture | Books | Records | Translations | Native Script |
|----------|-----------|-------|---------|-------------|---------------|
| Christianity | Holy Bible | 66 books (OT + NT) | 124,425 verses | KJV, NIV, ESV, NASB, NLT, ASV | English (Greek/Hebrew source) |
| Islam | Holy Quran | 114 surahs | 31,102 ayahs | Sahih International, Pickthall, Yusuf Ali | Arabic |
| Judaism | Tanakh + Talmud | 24 books + 63 tractates | 69,213 verses + 2,121 dapim | JPS, Koren, Artscroll | Hebrew / Aramaic |
| Hinduism | Bhagavad Gita | 18 chapters | 6,800 verses | Swami Mukundananda, Eknath Easwaran | Sanskrit / Devanagari |
| Buddhism | Tripitaka + Mahayana | 5 collections | 5,326 texts | Thanissaro Bhikkhu, Bhikkhu Bodhi | Pali / Sanskrit |

Each religion's data includes structured metadata: book/surah/chapter hierarchy, verse references, multiple translation editions, original language text, and cross-referenced topics for thematic exploration.

```python
# Get a random verse from any religion
verse = client.random_verse()
print(f"[{verse['religion']}] {verse['reference']}: {verse['text']}")

# Get today's Quran verse
quran_votd = client.verse_of_the_day("quran")
print(quran_votd["text"])  # Today's selected ayah in English
```

Learn more: [WideBible](https://widebible.com) · [WideQuran](https://widequran.com) · [WideTorah](https://widetorah.com)

### Cross-Religion Comparison

WideHoly provides 10 universal spiritual themes for cross-religion comparison, showing how different traditions address the same fundamental questions of human existence. Each theme includes curated verses and scholarly summaries from all 5 religions.

| Topic | Description | Religions |
|-------|-------------|-----------|
| Creation | Origin of the universe and humanity | Bible, Quran, Torah, Gita, Sutra |
| Prayer | Communication with the divine | Bible, Quran, Torah, Gita, Sutra |
| Love | Divine and human love | Bible, Quran, Torah, Gita, Sutra |
| Afterlife | Death, judgment, and eternal life | Bible, Quran, Torah, Gita, Sutra |
| Compassion | Mercy, kindness, and empathy | Bible, Quran, Torah, Gita, Sutra |
| Fasting | Spiritual discipline and abstinence | Bible, Quran, Torah, Gita, Sutra |
| Forgiveness | Repentance and divine pardon | Bible, Quran, Torah, Gita, Sutra |
| Gratitude | Thankfulness and praise | Bible, Quran, Torah, Gita, Sutra |
| Justice | Righteousness and moral law | Bible, Quran, Torah, Gita, Sutra |
| Wisdom | Knowledge, understanding, and truth | Bible, Quran, Torah, Gita, Sutra |

```python
# Compare how religions discuss creation
creation = client.cross_religion("creation")
for religion, data in creation["religions"].items():
    print(f"{religion}: {data['summary']}")
    for verse in data["verses"]:
        print(f"  [{verse['reference']}] {verse['text'][:80]}...")

# Compare specific verses side by side
result = client.compare("bible:genesis.1.1", "quran:al-fatihah.1")
print(f"Bible:  {result['verse_a']['text']}")
print(f"Quran:  {result['verse_b']['text']}")
print(f"Cross-religion: {not result['same_religion']}")  # True
```

Learn more: [Compare Verses](https://wideholy.com/developers/) · [Cross-Religion Topics](https://wideholy.com/topics/)

### Religious Calendar

WideHoly tracks 50 major religious events across all 5 traditions for 2026, including holidays, fasts, festivals, and observances. Events are sourced from each religion's liturgical calendar.

| Religion | Events | Examples |
|----------|--------|---------|
| Christianity | Easter, Christmas, Lent, Pentecost, Advent | Easter: April 5, 2026 |
| Islam | Ramadan, Eid al-Fitr, Eid al-Adha, Mawlid | Ramadan begins: February 18, 2026 |
| Judaism | Passover, Rosh Hashanah, Yom Kippur, Sukkot | Passover: April 2-9, 2026 |
| Hinduism | Diwali, Holi, Navratri, Maha Shivaratri | Diwali: October 20, 2026 |
| Buddhism | Vesak, Asalha Puja, Kathina, Magha Puja | Vesak: May 12, 2026 |

```python
# Get all religious events for March 2026
events = client.calendar(month=3)
for e in events["events"]:
    print(f"  {e['date']}  {e['religion']:10s}  {e['name']}")

# Get only Torah/Jewish holidays
torah_events = client.calendar(religion="torah")
for e in torah_events["events"]:
    print(f"  {e['date']}  {e['name']}")
```

Learn more: [Religious Calendar](https://wideholy.com/developers/)

## Command-Line Interface

```bash
# Verse of the day
wideholy votd                                   # Bible (default)
wideholy votd --religion quran                  # Quran

# Random verse
wideholy random                                 # Any religion
wideholy random --religion torah                # Torah only

# Compare two verses
wideholy compare genesis.1.1 john.1.1           # Same religion
wideholy compare bible:genesis.1.1 quran:al-fatihah.1  # Cross-religion

# Search across all religions
wideholy search love
wideholy search prayer --religion bible

# Topic verses across religions
wideholy topic creation
wideholy topic wisdom

# Cross-religion thematic comparison
wideholy cross-religion prayer
wideholy cross-religion afterlife

# Religious calendar
wideholy calendar                               # All events, all religions
wideholy calendar --religion torah --month 3    # Torah events in March
wideholy calendar --month 12                    # December events

# Commentary (Quran tafsir, Torah Rashi, Gita commentaries)
wideholy commentary quran:al-fatihah.1
wideholy commentary torah:genesis.1.1

# Raw JSON output (for scripting)
wideholy json verse-of-the-day
```

## MCP Server (Claude, Cursor, Windsurf)

### Claude Desktop

Add to `claude_desktop_config.json`:

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

### Cursor

Add to `.cursor/mcp.json`:

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

### Windsurf

Add to `~/.windsurf/mcp.json`:

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

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `verse_of_the_day` | Get curated daily verse for any religion |
| `random_verse` | Random verse from one or all religions |
| `compare_verses` | Side-by-side verse comparison (same or cross-religion) |
| `search_suggest` | Autocomplete search across topics, people, glossary |
| `topic_verses` | Verses for a topic across all religions |
| `cross_religion_topic` | Thematic comparison (creation, love, prayer, etc.) |
| `religious_calendar` | Religious holidays and observances |
| `verse_commentary` | Commentary (Quran tafsir, Torah Rashi, Gita) |

## REST API Client

```python
from wideholy.api import WideHoly

client = WideHoly()

# 1. Verse of the day — curated daily selection
votd = client.verse_of_the_day("bible")
# {"religion": "bible", "reference": "Psalm 23:1", "text": "...", "date": "2026-03-24"}

# 2. Random verse — serendipitous discovery
verse = client.random_verse("gita")
# {"religion": "gita", "reference": "Gita 2:47", "text": "...", "book": "gita"}

# 3. Compare — cross-religion or same-religion side-by-side
cmp = client.compare("bible:genesis.1.1", "quran:al-fatihah.1")
# {"verse_a": {...}, "verse_b": {...}, "same_religion": false}

# 4. Search suggest — topics, people, glossary terms
results = client.search_suggest("moses")
# {"suggestions": [{"text": "Moses", "type": "person", "religion": "bible"}, ...]}

# 5. Topic verses — aggregated across religions
topic = client.topic_verses("love")
# {"topic": "love", "religions_found": ["bible", "quran", ...], "verses": {...}}

# 6. Cross-religion — thematic comparison with summaries
cross = client.cross_religion("creation")
# {"topic": "creation", "title": "Creation", "religions": {"bible": {...}, "quran": {...}}}

# 7. Calendar — religious holidays and observances
cal = client.calendar(religion="torah", month=4)
# {"year": 2026, "month": 4, "religion": "torah", "events": [...]}

# 8. Commentary — scholarly annotations
comm = client.commentary("quran:al-fatihah.1")
# {"verse_ref": "quran:al-fatihah.1", "religion": "quran", "commentaries": [...]}

client.close()
```

## API Reference

| Method | Endpoint | Description |
|--------|----------|-------------|
| `verse_of_the_day(religion, date)` | `GET /api/v1/verse-of-the-day/` | Curated verse of the day, deterministic per date |
| `random_verse(religion)` | `GET /api/v1/random/` | Random verse, optionally filtered by religion |
| `compare(ref_a, ref_b)` | `GET /api/v1/compare/` | Side-by-side verse comparison |
| `search_suggest(query, religion)` | `GET /api/v1/search/suggest/` | Autocomplete across topics, people, glossary |
| `topic_verses(topic)` | `GET /api/v1/topics/{slug}/verses/` | Verses for a topic across religions |
| `cross_religion(topic)` | `GET /api/v1/cross-religion/{topic}/` | Thematic comparison with summaries |
| `calendar(religion, year, month)` | `GET /api/v1/calendar/` | Religious holidays and observances |
| `commentary(verse_ref)` | `GET /api/v1/commentary/{verse_ref}/` | Scholarly commentary (tafsir, Rashi, Gita) |

Full API documentation at [wideholy.com/developers/](https://wideholy.com/developers/).
OpenAPI 3.1.0 spec: [wideholy.com/api/schema/](https://wideholy.com/api/schema/).

## Learn More About World Scriptures

- **Compare**: [Verse Comparison Tool](https://wideholy.com/developers/) · [Cross-Religion Topics](https://wideholy.com/topics/)
- **Calendar**: [Religious Calendar 2026](https://wideholy.com/developers/)
- **Browse**: [Bible Books](https://widebible.com) · [Quran Surahs](https://widequran.com) · [Torah Books](https://widetorah.com) · [Gita Chapters](https://widegita.com) · [Buddhist Sutras](https://widesutra.com)
- **API**: [REST API Docs](https://wideholy.com/developers/) · [OpenAPI Spec](https://wideholy.com/api/schema/)

## WideHoly Family

| Site | Domain | Focus |
|------|--------|-------|
| WideBible | [widebible.com](https://widebible.com) | 66 books, 124K verses, 6 translations, commentaries |
| WideQuran | [widequran.com](https://widequran.com) | 114 surahs, 31K ayahs, tafsir, hadith collections |
| WideTorah | [widetorah.com](https://widetorah.com) | 24 Tanakh books, 63 Talmud tractates, Rashi commentary |
| WideGita | [widegita.com](https://widegita.com) | 18 chapters, 6,800 verses, Sanskrit, multiple commentaries |
| WideSutra | [widesutra.com](https://widesutra.com) | 5 collections, 5,326 texts, Pali/Sanskrit traditions |
| **WideHoly** | [**wideholy.com**](https://wideholy.com) | **Cross-religion hub — comparison, calendar, unified search** |

## License

MIT License. See [LICENSE](LICENSE) for details.
