# widesutra

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

Python SDK for [WideSutra](https://widesutra.com) — Buddhist scriptures, Tipitaka, Pali Canon, figures, and concepts. Access 5 scripture collections, 15 books, 5,326 texts with Pali originals, 10 Buddhist figures, and 15 core concepts through a typed Python API client, CLI, and MCP server.

WideSutra is part of the [WideHoly](https://wideholy.com) multi-religion scripture platform. The REST API serves structured data extracted from primary Buddhist sources including the Pali Canon (Tipitaka), Mahayana sutras, and scholarly translations. Every text includes the original Pali alongside English translations.

> **Explore Buddhist scriptures at [widesutra.com](https://widesutra.com)** — collections, texts, figures, concepts, and glossary.

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You'll Find on WideSutra](#what-youll-find-on-widesutra)
  - [Buddhist Scripture Collections](#buddhist-scripture-collections)
  - [Key Texts and Translations](#key-texts-and-translations)
  - [Buddhist Figures](#buddhist-figures)
  - [Core Concepts](#core-concepts)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [API Endpoints](#api-endpoints)
- [API Reference](#api-reference)
- [WideHoly Scripture Platform](#wideholy-scripture-platform)
- [License](#license)

## Install

```bash
# Core SDK (includes httpx)
pip install widesutra

# With CLI support
pip install "widesutra[cli]"

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

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

## Quick Start

```python
from widesutra import WideSutra

with WideSutra() as client:
    # Browse scripture collections (Tipitaka, Mahayana Sutras)
    collections = client.list_collections(tradition="theravada")

    # Get a specific book
    book = client.get_book("dhammapada")
    print(book["name"])          # Dhammapada
    print(book["pali_name"])     # Dhammapada
    print(book["chapter_count"]) # 26

    # Read a verse with Pali original
    text = client.get_text("dhammapada", 1, 1, translation="sujato")
    print(text["results"][0]["text"])       # English translation
    print(text["results"][0]["text_pali"])  # Pali original

    # Search across all scriptures
    results = client.search("four noble truths")

    # Explore Buddhist figures
    buddha = client.get_figure("siddhartha-gautama")
    print(buddha["name"])        # Siddhartha Gautama
    print(buddha["pali_name"])   # Siddhattha Gotama
    print(buddha["is_buddha"])   # True

    # Look up core concepts
    concept = client.get_concept("four-noble-truths")
    print(concept["pali_term"])  # Cattari Ariyasaccani

    # Browse Pali/Sanskrit glossary
    glossary = client.list_glossary()
```

## What You'll Find on WideSutra

### Buddhist Scripture Collections

WideSutra organizes Buddhist scriptures into 5 collections spanning the major traditions. The Tipitaka (Pali Canon), the oldest surviving complete Buddhist canon, contains over 3,500 texts preserved in the Pali language. The Theravada tradition regards it as the most authentic record of the Buddha's teachings, compiled at the First Buddhist Council shortly after the Buddha's parinibbana.

| Collection | Tradition | Texts | Description |
|-----------|-----------|-------|-------------|
| Tipitaka | Theravada | 3,500+ | Three Baskets: Vinaya, Sutta, Abhidhamma |
| Mahayana Sutras | Mahayana | 600+ | Heart Sutra, Diamond Sutra, Lotus Sutra |
| Chinese Canon | East Asian | 500+ | Taisho Tripitaka selections |
| Tibetan Canon | Vajrayana | 300+ | Kangyur and Tengyur selections |
| Pali Commentaries | Theravada | 400+ | Buddhaghosa's Visuddhimagga and Atthakatha |

The Tipitaka's three "baskets" each serve a distinct purpose: the Vinaya Pitaka contains monastic rules and their origin stories, the Sutta Pitaka preserves the Buddha's discourses, and the Abhidhamma Pitaka provides systematic philosophical analysis of mind and matter.

```python
from widesutra import WideSutra

with WideSutra() as client:
    # List all Theravada collections
    collections = client.list_collections(tradition="theravada")
    for c in collections.get("results", []):
        print(f"{c['name']}: {c['text_count']} texts")

    # Get Tipitaka collection details
    tipitaka = client.get_collection("tipitaka")
    print(tipitaka["description"])
```

### Key Texts and Translations

WideSutra provides 5,326 scripture texts with parallel Pali originals and English translations. The Dhammapada, a collection of 423 verses in 26 chapters, is among the most widely read Buddhist texts. Each verse is stored with the original Pali, transliteration, and translations by scholars including Bhikkhu Sujato and Thanissaro Bhikkhu.

| Book | Collection | Chapters | Language | Notable Content |
|------|-----------|----------|----------|----------------|
| Dhammapada | Sutta Pitaka | 26 | Pali | 423 verses on the path of truth |
| Heart Sutra | Prajnaparamita | 1 | Sanskrit | Core teaching on emptiness (sunyata) |
| Diamond Sutra | Prajnaparamita | 32 | Sanskrit | Dialogue on the nature of perception |
| Lotus Sutra | Mahayana | 28 | Sanskrit | Universal buddhahood, skillful means |
| Majjhima Nikaya | Sutta Pitaka | 152 | Pali | Middle-length discourses of the Buddha |

Every text in WideSutra includes a structured reference (e.g., "Dhp 1:1" for Dhammapada Chapter 1, Verse 1) following standard academic citation formats used in Pali Text Society publications.

```python
from widesutra import WideSutra

with WideSutra() as client:
    # Read the opening verse of the Dhammapada
    verse = client.get_text("dhammapada", 1, 1, translation="sujato")
    v = verse["results"][0]
    print(f"{v['reference']}")  # Dhp 1:1
    print(f"Pali: {v['text_pali']}")
    print(f"English: {v['text']}")

    # Search for teachings on mindfulness
    results = client.search("mindfulness", limit=5)
    for r in results.get("results", []):
        print(f"{r['reference']}: {r['text'][:80]}...")
```

### Buddhist Figures

WideSutra catalogs 10 key Buddhist figures across traditions, from the historical Buddha to important disciples and bodhisattvas. Each entry includes names in Pali and Sanskrit, biographical information, tradition affiliation, and links to relevant scripture passages.

| Figure | Pali Name | Sanskrit Name | Tradition | Role |
|--------|-----------|---------------|-----------|------|
| Siddhartha Gautama | Siddhattha Gotama | Siddhartha Gautama | All | The historical Buddha |
| Sariputta | Sariputta | Shariputra | Theravada | Chief disciple, wisdom |
| Moggallana | Moggallana | Maudgalyayana | Theravada | Chief disciple, psychic powers |
| Ananda | Ananda | Ananda | All | Personal attendant of the Buddha |
| Mahakassapa | Mahakassapa | Mahakashyapa | All | Convener of the First Council |
| Avalokiteshvara | — | Avalokiteshvara | Mahayana | Bodhisattva of compassion |
| Manjushri | — | Manjushri | Mahayana | Bodhisattva of wisdom |
| Nagarjuna | — | Nagarjuna | Mahayana | Founder of Madhyamaka philosophy |
| Buddhaghosa | Buddhaghosa | Buddhaghosa | Theravada | Author of the Visuddhimagga |
| Milinda | Milinda | Menander I | Theravada | Greek king, subject of Milindapanha |

```python
from widesutra import WideSutra

with WideSutra() as client:
    # Get the historical Buddha
    buddha = client.get_figure("siddhartha-gautama")
    print(f"{buddha['name']} ({buddha['pali_name']})")
    print(f"Title: {buddha['title']}")

    # List Theravada figures
    figures = client.list_figures(tradition="theravada")
    for f in figures.get("results", []):
        print(f"- {f['name']}: {f.get('title', '')}")
```

### Core Concepts

WideSutra covers 15 core Buddhist concepts with Pali and Sanskrit terminology, doctrinal context, and links to primary source texts. These concepts form the philosophical foundation of Buddhist thought across all traditions.

| Concept | Pali | Sanskrit | Category |
|---------|------|----------|----------|
| Four Noble Truths | Cattari Ariyasaccani | Catvary Aryasatyani | Doctrine |
| Noble Eightfold Path | Ariya Atthangika Magga | Arya Astangika Marga | Practice |
| Dependent Origination | Paticca Samuppada | Pratitya Samutpada | Doctrine |
| Three Marks of Existence | Tilakkhana | Trilakshana | Doctrine |
| Nirvana | Nibbana | Nirvana | Soteriology |
| Five Aggregates | Panca Khandha | Panca Skandha | Psychology |
| Karma | Kamma | Karma | Ethics |
| Samsara | Samsara | Samsara | Cosmology |
| Emptiness | Sunnata | Sunyata | Philosophy |
| Bodhisattva | Bodhisatta | Bodhisattva | Mahayana |
| Middle Way | Majjhima Patipada | Madhyama Pratipad | Doctrine |
| Mindfulness | Sati | Smrti | Practice |
| Compassion | Karuna | Karuna | Ethics |
| Impermanence | Anicca | Anitya | Doctrine |
| Non-self | Anatta | Anatman | Doctrine |

The Four Noble Truths (Cattari Ariyasaccani) form the core framework of Buddhist teaching: the truth of suffering (dukkha), its origin (samudaya), its cessation (nirodha), and the path leading to its cessation (magga). This teaching was delivered in the Buddha's first sermon at the Deer Park in Sarnath, preserved in the Dhammacakkappavattana Sutta (SN 56.11).

```python
from widesutra import WideSutra

with WideSutra() as client:
    # Look up the Four Noble Truths
    concept = client.get_concept("four-noble-truths")
    print(f"{concept['name']}")
    print(f"Pali: {concept['pali_term']}")
    print(f"Sanskrit: {concept['sanskrit_term']}")
    print(f"Category: {concept['category']}")

    # List all doctrinal concepts
    concepts = client.list_concepts(category="doctrine")
    for c in concepts.get("results", []):
        print(f"- {c['name']} ({c.get('pali_term', '')})")
```

## Command-Line Interface

```bash
# Search Buddhist scriptures
widesutra search "four noble truths"
widesutra search "mindfulness" --limit 5

# Get collection details
widesutra collection tipitaka

# Get book details
widesutra book dhammapada

# Look up a Buddhist figure
widesutra figure siddhartha-gautama

# Look up a core concept
widesutra concept four-noble-truths
```

## MCP Server (Claude, Cursor, Windsurf)

### Claude Desktop

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

### Cursor / Windsurf

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

Available MCP tools:
- `list_collections` — List Buddhist scripture collections, filter by tradition
- `get_collection` — Get collection details by slug
- `list_figures` — List Buddhist figures, filter by tradition
- `get_figure` — Get figure details by slug
- `list_concepts` — List Buddhist concepts, filter by category
- `search_sutra` — Search Buddhist scriptures by keyword

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/sutra/collections/` | List scripture collections |
| GET | `/api/v1/sutra/collections/{slug}/` | Collection details |
| GET | `/api/v1/sutra/books/` | List books (filter: `collection__slug`) |
| GET | `/api/v1/sutra/books/{slug}/` | Book details |
| GET | `/api/v1/sutra/chapters/` | List chapters (filter: `book__slug`) |
| GET | `/api/v1/sutra/texts/` | List/search texts (filter: book, chapter, translation) |
| GET | `/api/v1/sutra/translations/` | List translations |
| GET | `/api/v1/sutra/translations/{code}/` | Translation details |
| GET | `/api/v1/sutra/figures/` | List Buddhist figures (filter: `tradition`) |
| GET | `/api/v1/sutra/figures/{slug}/` | Figure details |
| GET | `/api/v1/sutra/concepts/` | List Buddhist concepts (filter: `category`) |
| GET | `/api/v1/sutra/concepts/{slug}/` | Concept details |
| GET | `/api/v1/sutra/topics/` | List topics |
| GET | `/api/v1/sutra/topics/{slug}/` | Topic details |
| GET | `/api/v1/sutra/glossary/` | List Pali/Sanskrit glossary |
| GET | `/api/v1/sutra/glossary/{slug}/` | Glossary term details |

### Example

```bash
curl -s "https://widesutra.com/api/v1/sutra/figures/siddhartha-gautama/"
```

```json
{
  "id": 1,
  "name": "Siddhartha Gautama",
  "slug": "siddhartha-gautama",
  "pali_name": "Siddhattha Gotama",
  "sanskrit_name": "Siddhartha Gautama",
  "title": "The Buddha",
  "tradition": "All traditions",
  "description": "The historical founder of Buddhism...",
  "is_buddha": true,
  "wikidata_id": "Q9441",
  "url": "/figures/siddhartha-gautama/"
}
```

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

## API Reference

| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `list_collections()` | `tradition?` | `dict` | List scripture collections |
| `get_collection()` | `slug` | `dict` | Get collection by slug |
| `list_books()` | `collection?` | `dict` | List books, optional collection filter |
| `get_book()` | `slug` | `dict` | Get book by slug |
| `get_text()` | `book, chapter, verse, translation?` | `dict` | Get specific scripture text |
| `search()` | `query, limit?` | `dict` | Search scripture texts |
| `list_translations()` | — | `dict` | List available translations |
| `get_translation()` | `code` | `dict` | Get translation by code |
| `list_figures()` | `tradition?` | `dict` | List Buddhist figures |
| `get_figure()` | `slug` | `dict` | Get figure by slug |
| `list_concepts()` | `category?` | `dict` | List Buddhist concepts |
| `get_concept()` | `slug` | `dict` | Get concept by slug |
| `list_topics()` | — | `dict` | List Buddhist topics |
| `get_topic()` | `slug` | `dict` | Get topic by slug |
| `list_glossary()` | — | `dict` | List Pali/Sanskrit glossary |
| `get_glossary_term()` | `slug` | `dict` | Get glossary term by slug |

## WideHoly Scripture Platform

Part of the [WideHoly](https://wideholy.com) multi-religion scripture platform.

| Site | Domain | Focus |
|------|--------|-------|
| WideBible | [widebible.com](https://widebible.com) | Bible verses, cross-references, study tools |
| WideQuran | [widequran.com](https://widequran.com) | Quran surahs, ayahs, hadiths, tafsir |
| WideTorah | [widetorah.com](https://widetorah.com) | Torah, Talmud, Mishnah, Rashi commentary |
| **WideSutra** | [widesutra.com](https://widesutra.com) | **Buddhist scriptures, Tipitaka, Pali Canon** |
| WideGita | [widegita.com](https://widegita.com) | Bhagavad Gita, Upanishads, Vedic texts |
| WideHoly | [wideholy.com](https://wideholy.com) | Multi-religion hub, cross-tradition search |

## Learn More About Buddhist Scriptures

- **Scripture**: [Collections](https://widesutra.com/collections/) · [Translations](https://widesutra.com/developers/)
- **Reference**: [Figures](https://widesutra.com/figures/) · [Topics](https://widesutra.com/topics/) · [Glossary](https://widesutra.com/glossary/)
- **Study**: [Concepts](https://widesutra.com/concepts/) · [Pali Canon](https://widesutra.com/collections/)
- **Tools**: [Search](https://widesutra.com/) · [Developer Docs](https://widesutra.com/developers/)
- **API**: [Developer Docs](https://widesutra.com/developers/) · [OpenAPI Spec](https://widesutra.com/api/schema/)

## License

MIT
