Skip to content
Back to search

fojin

Buddhist Digital Text Platform — 10,500+ texts, 613 sources, trilingual cross-canon, AI Q&A (RAG), knowledge graph, full-text search

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/xr843/fojin with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/xr843/fojin'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xr843--fojin/badge.svg)](/listings/xr843--fojin)

HTML

<a href="/listings/xr843--fojin"><img src="/api/listings/xr843--fojin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/xr843/fojin.git
cd fojin
cp .env.example .env        # edit POSTGRES_PASSWORD before starting
docker compose up -d         # database migrations run automatically

Then visit: **http://localhost:3000**

> API docs at http://localhost:8000/docs

After first startup, the platform has the database schema and source metadata but **no text content**. To import texts from public data sources:

# Import CBETA catalog (auto-scans local xml-p5 directory or fetches from remote)
docker exec fojin-backend python scripts/import_catalog.py

# Import CBETA full text content (requires xml-p5 repository)
docker exec fojin-backend python scripts/import_content.py --all --xml-dir /data/xml-p5

# Generate embeddings for AI Q&A (supports incremental processing)
docker exec fojin-backend python -m scripts.archive.misc.generate_embeddings --source cbeta

# Import SuttaCentral Early Buddhist Texts
docker exec fojin-backend python scripts/archive/imports/import_suttacentral.py

# See all available importers (one-off importers live under archive/)
ls backend/scripts/archive/imports/

Each importer downloads data directly from the original source (CBETA, SuttaCentral, etc.) — no data is bundled in this repository.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 542 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # FoJin 佛津
  3. ### Ask the Buddhist canon — get cited, verifiable answers.
  4. **AI Q&A grounded in the world's largest open aggregation of Buddhist texts: 600+ sources, 30+ languages, trilingual cross-canon retrieval — every answer linked back to its source passage.**
  5. Ask a question in plain language and FoJin's assistant **"XiaoJin"** answers from the canon itself — Retrieval-Augmented Generation over 670K+ embedded passages, optional cross-encoder reranking and root-sutra recall, **clickable 【《sutra》juan N】 citations** that open the exact source text, anti-hallucination guards, and a citation drawer with **side-by-side 汉 / 巴利 / 藏文 cross-canon parallels**. You can also ask in the voice of **15 historical Buddhist masters**, each scoped to their own tradition's scriptures.
  6. What makes those answers trustworthy is the corpus underneath. FoJin aggregates **612 data sources** into one searchable platform — 10,500+ texts with 19,000+ volumes of full content in Classical Chinese, Pali, Tibetan and Sanskrit, **the first LLM-driven trilingual cross-canon parallel reading platform** (CBETA × SuttaCentral × 84000) with LLM-verified chunk-level alignment, a 110K+ entity knowledge graph on a Deck.GL geo map, and 39 dictionaries with 747K entries. Every feature exists to make the answers more grounded — and to let you go deeper once you have one.
  7. FoJin is built to be **open, cross-canon, verifiable Buddhist knowledge infrastructure** — not just a site to read, but a corpus other tools can *call*. Every passage carries a stable, resolvable cross-canon **URN** (`fojin:cbeta/T0001.1`), and the **[`fojin-mcp`](https://pypi.org/project/fojin-mcp/)** server lets AI assistants (Claude, ChatGPT, any [MCP](https://modelcontextprotocol.io) client) answer from FoJin's cited passages directly — hosted at **`mcp.fojin.ai`**, anonymous, no key required. Any model can also check its own work through the open **[`/api/verify/quote`](https://fojin.ai/developers)** endpoint: hand it a sentence and a citation, and it answers *is this quote real* and *is the citation right* as two separate questions. See **[fojin.ai/developers](https://fojin.ai/developers)**.
  8. [Live Demo](https://fojin.app) &nbsp;&middot;&nbsp; [API Docs](https://fojin.app/docs) &nbsp;&middot;&nbsp; [中文文档](./docs/README_zh.md) &nbsp;&middot;&nbsp; [Discussions](https://github.com/xr843/fojin/discussions) &nbsp;&middot;&nbsp; [Discord](https://discord.gg/76SZeuJekq) &nbsp;&middot;&nbsp; [Report Bug](https://github.com/xr843/fojin/issues)
  9. [![CI](https://github.com/xr843/fojin/actions/workflows/ci.yml/badge.svg)](https://github.com/xr843/fojin/actions/workflows/ci.yml)
  10. [![Security Scan](https://github.com/xr843/fojin/actions/workflows/security.yml/badge.svg)](https://github.com/xr843/fojin/actions/workflows/security.yml)
  11. [![fojin-mcp on PyPI](https://img.shields.io/pypi/v/fojin-mcp?label=fojin-mcp&color=3775A9)](https://pypi.org/project/fojin-mcp/)
  12. [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  13. [![GitHub stars](https://img.shields.io/github/stars/xr843/fojin?style=social)](https://github.com/xr843/fojin)
  14. ![FoJin — Global Buddhist Digital Text Platform](./docs/screenshots/hero.png)
  15. </div>
  16. ---
  17. ## Why FoJin?
  18. Buddhist texts are scattered across hundreds of databases worldwide — CBETA, SuttaCentral, BDRC, SAT, 84000, GRETIL, and many more. Each has its own interface, language, and data format. When you have a *question* — "what does the Heart Sutra mean by 'form is emptiness'?", "how do the Pali and Chinese versions of this passage differ?" — you spend more time hunting for the right passage than understanding it.
  19. **FoJin answers the question for you.** Ask in plain language; XiaoJin retrieves the relevant passages from 612 sources and answers with clickable citations you can verify. Everything else FoJin does — full-text reading, cross-canon alignment, the knowledge graph, 39 dictionaries — exists to make those answers more grounded, and to let you go deeper once you have one:
  20. | What you need | How FoJin helps |
  21. |---|---|
  22. | **Ask a question, get a sourced answer** | **AI Q&A ("XiaoJin")** — RAG over 670K+ passages, reranking, root-sutra recall, clickable 【《sutra》juan N】 citations, cross-canon citation drawer, anti-hallucination guards |
  23. | **Trust the answer** | **Verifiable answers** — deterministic citation whitelist + verbatim-quote downgrade + per-answer trust state; ~98% of *citing* answers served-trustworthy at temp 0 |
  24. | Research a hard, multi-step question | **Research Assistant** (`/research`) — plans across corpus + dictionaries + knowledge graph, then synthesises a cited answer behind the same guards |
  25. | Call FoJin from an AI assistant | **MCP server** — hosted at `mcp.fojin.ai` (no install, no key) or [`uvx fojin-mcp`](https://pypi.org/project/fojin-mcp/); 8 read-only, URN-addressable tools for Claude / ChatGPT |
  26. | **Check whether a quotation is real** | **Open verbatim verification** (`/api/verify/quote`) — for *any* sentence, not just ours: exact / near-miss / absent, with a character-level diff and the right juan when the citation points at the wrong one |
  27. | See how the tradition read a passage | **Commentary alignment** (`/api/commentary/passage`) — for one passage, what the historical commentators wrote on it, anchored to juan and line |
  28. | Listen while you read | **Read-aloud** (`/read-aloud`) — sentence-by-sentence highlighting synced to audio, lock-screen playback |
  29. | Ask in a master's voice | **Master Persona Mode** — 15 historical masters, each with tradition-scoped RAG |
  30. | Find a sutra across databases | **Multi-dimensional search** across 10,500+ texts from 612 sources |
  31. | Read the full text online | **8,900+ texts** with 19,000+ volumes of full content, CBETA-style layout |
  32. | Compare translations | **Parallel reading** in 30+ languages side by side |
  33. | Compare sutras across Buddhist canons | **Trilingual cross-canon parallel reading** — 4,000+ LLM-verified chunk alignments across Chinese / Pali / Tibetan covering Heart Sutra, Vimalakīrti, **Lotus Sutra (法华 ↔ Toh 113, 259 pairs)**, **8,000-verse Prajñāpāramitā (小品般若 ↔ Toh 11, 127 pairs)**, Satipaṭṭhāna + the full Āgama ↔ Nikāya corpus (MN/DN/SN/AN), Dhammapada |
  34. | Look up Buddhist terms | **39 dictionaries**, 747K entries (Chinese/Sanskrit/Pali/Tibetan/English) |
  35. | Explore relationships | **Knowledge graph** with 110K+ entities and 27,900+ relations (22K+ lineage chains) |
  36. | Discover similar texts | **Semantic similarity** powered by 670K+ embedding vectors (pgvector + HNSW) |
  37. | Explore Buddhist geography | **Knowledge Graph Map** — geo-enabled entities, monastery locations, lineage arcs on Deck.GL |
  38. | Track source updates | **Activity Feed** — real-time updates from 612 data sources |
  39. | Explore history visually | **Timeline & Dashboard** — dynasty charts, translation trends, category analytics |
  40. | Save and organize | **Collections, bookmarks, annotations** for personal study |
  41. | Cite in research | **Citation export** (BibTeX, RIS, APA) for academic use |
  42. ## Quick Start
  43. ```bash
  44. git clone https://github.com/xr843/fojin.git
  45. cd fojin
  46. cp .env.example .env # edit POSTGRES_PASSWORD before starting
  47. docker compose up -d # database migrations run automatically
  48. ```
  49. Then visit: **http://localhost:3000**
  50. > API docs at http://localhost:8000/docs
  51. After first startup, the platform has the database schema and source metadata but **no text content**. To import texts from public data sources:
  52. ```bash
  53. # Import CBETA catalog (auto-scans local xml-p5 directory or fetches from remote)
  54. docker exec fojin-backend python scripts/import_catalog.py
  55. # Import CBETA full text content (requires xml-p5 repository)
  56. docker exec fojin-backend python scripts/import_content.py --all --xml-dir /data/xml-p5
  57. # Generate embeddings for AI Q&A (supports incremental processing)
  58. docker exec fojin-backend python -m scripts.archive.misc.generate_embeddings --source cbeta
  59. # Import SuttaCentral Early Buddhist Texts
  60. docker exec fojin-backend python scripts/archive/imports/import_suttacentral.py
  61. # See all available importers (one-off importers live under archive/)
  62. ls backend/scripts/archive/imports/
  63. ```
  64. Each importer downloads data directly from the original source (CBETA, SuttaCentral, etc.) — no data is bundled in this repository.
  65. ## Use FoJin from your AI tools (MCP)
  66. FoJin's verified, cross-canon corpus is callable directly from AI assistants (Claude Desktop, ChatGPT, or any [MCP](https://modelcontextprotocol.io) client) via the published **[`fojin-mcp`](https://pypi.org/project/fojin-mcp/)** server — so the assistant answers Buddhist questions from FoJin's cited passages instead of hallucinating.
  67. Point any MCP client at the hosted endpoint — nothing to install, no key to get:
  68. ```bash
  69. claude mcp add --transport http fojin https://mcp.fojin.ai/mcp
  70. ```
  71. Or run it locally over stdio against your own instance:
  72. ```bash
  73. uvx fojin-mcp # zero-install run
  74. # or: pip install fojin-mcp && fojin-mcp
  75. ```
  76. It exposes eight **read-only** tools over the public API, each returning passages with a stable, resolvable cross-canon **URN** (`fojin:cbeta/T0001.1`):
  77. | Tool | What it does |
  78. |---|---|
  79. | `search_corpus` | Semantic search across the aggregated canon |
  80. | `read_passage` | Read a specific text / volume |
  81. | `get_parallels` | Cross-canon parallels (汉 ↔ 巴利 ↔ 藏) for a passage |
  82. | `lookup_dictionary` | Term lookup across 39 dictionaries |
  83. | `lookup_entity` | Knowledge-graph entity facts |
  84. | `resolve_urn` | Resolve a FoJin URN to its source location |
  85. | `verify_quote` | **Verbatim check** — is this sentence really in the canon, and really where you said? Answers "is the quote real" and "is the citation right" separately, with a character-level diff when it is close but not exact |
  86. | `commentaries` | For one passage, what the historical commentators wrote on it — anchored to juan and line |
  87. Claude Desktop config and ChatGPT setup are in **[`mcp-server/README.md`](mcp-server/README.md)**. The server is a thin, read-only client: it holds no credentials, bundles no corpus, and only calls FoJin's public endpoints — its default target is `https://fojin.app/api`, overridable via `FOJIN_API_BASE_URL` to point at a self-hosted instance.
  88. ## Features
  89. ### Multi-Dimensional Search
  90. Search across Buddhist canons by title, translator, catalog number, or full-text keyword. Powered by Elasticsearch with ICU tokenizer for multi-language support.
  91. <p align="center"><img src="./docs/screenshots/search.png" alt="Search results for Avatamsaka Sutra" width="800"></p>
  92. ### Full-Text Reading
  93. Read 8,900+ Buddhist texts with 19,000+ volumes of full content online. CBETA-style typography with intelligent verse/prose detection, paragraph reflow, and adjustable font size. Navigate by volume, scroll through content, and jump between related texts.
  94. ### Parallel Reading (30 Languages)
  95. Compare translations side by side — Classical Chinese, Sanskrit, Pali, Tibetan, English, Japanese, Korean, Gandhari, and 21 more languages.
  96. ### Dictionary Lookup
  97. 32 authoritative dictionaries with 748,000+ entries across Chinese, Pali, Sanskrit, Tibetan, and English:
  98. **Chinese Buddhist Dictionaries (14)**
  99. - **NTI Reader** (佛学辞典) — 161K entries, Chinese↔English
  100. - **Suihan Lu** (新集藏經音義隨函錄) — 72K entries, Tang dynasty phonetic glossary
  101. - **Fo Guang** (佛光大辭典) — 32K entries
  102. - **Ding Fubao** (丁福保佛学大辞典) — 31K entries
  103. - **Yiqiejing Yinyi** (一切經音義, 慧琳音義) — 23K entries, Buddhist scriptural phonetics
  104. - **Faxiang Dictionary** (法相辭典, 朱芾煌) — 15K entries, Yogācāra terminology
  105. - **Zhonghua Encyclopedia** (中華佛教百科全書) — 6K entries
  106. - **Common Buddhist Terms** (佛學常見詞彙, 陳義孝) — 6K entries
  107. - **Agama Dictionary** (阿含辭典, 莊春江) — 5K entries
  108. - **Fanfanyu** (翻梵語) — 4K entries, Sanskrit-Chinese translation glossary
  109. - **Xu Yinyi** (續一切經音義, 希麟) — 2K entries
  110. - **Yogācāra Glossary** (唯識名詞白話新解) — 2K entries
  111. - **Sanzang Fashu** (三藏法數) — 1K entries
  112. - **Buddhist Origins of Idioms** (俗語佛源) — 567 entries
  113. **Pali Dictionaries (5)**
  114. - **Digital Pali Dictionary** (DPD) — 89K entries, grammar + etymology + examples
  115. - **NCPED** (New Concise Pali-English Dictionary) — 21K entries
  116. - **PTS PED** (Pali Text Society) — 16K entries
  117. - **Buddhadatta** (巴利語辭典, 達摩比丘中譯) — 11K entries, Pali→Chinese
  118. - **SuttaCentral Glossary** — 6K entries
  119. **Sanskrit Dictionaries (4)**
  120. - **Apte** (Practical Sanskrit-English Dictionary) — 35K entries
  121. - **Monier-Williams** (Sanskrit-English Dictionary) — 32K entries
  122. - **Edgerton BHS** (Buddhist Hybrid Sanskrit Dictionary) — 18K entries
  123. - **Fanyi Mingyi Ji** (翻譯名義集) — 1K entries
  124. **Tibetan Dictionaries (2)**
  125. - **Rangjung Yeshe** (Tibetan-English Dictionary) — 74K entries
  126. - **Hopkins** (Tibetan-Sanskrit-English Dictionary) — 18K entries
  127. **Multilingual Reference (4)**
  128. - **Soothill-Hodous** (Chinese Buddhist Terms, Chinese↔English) — 17K entries
  129. - **Mahāvyutpatti** (翻譯名義大集, Sanskrit↔Tibetan↔Chinese) — 9K entries
  130. - **Nanshan Vinaya** (南山律学辞典) — 3K entries
  131. - **Pentaglot** (五體清文鑑, Manchu-Mongolian-Tibetan-Chinese-Sanskrit) — 1K entries
  132. **Specialized (3)**
  133. - **Abhidharma Dictionary** (阿毗達磨辭典) — 1K entries
  134. - **Tiantai Dictionary** (天台教學辭典) — 1K entries
  135. - **DDB** (Digital Dictionary of Buddhism) — CJK Buddhist terminology
  136. ### Knowledge Graph
  137. 110,000+ entities (monasteries, persons, texts, schools, concepts) and 28,000+ relationships — including 22,000+ teacher-student lineage chains from the DILA Authority Database — visualized as an interactive force-directed graph. Click any node to explore connections.
  138. ### Trilingual Cross-Canon Parallel Reading (三语对读)
  139. **The first LLM-driven cross-canon parallel reading system for Buddhist texts.** No other platform provides this: CBETA (汉文), SuttaCentral (Pali), and 84000 (Tibetan) each operate in their own language silo. FoJin bridges them via LLM-verified chunk-level alignment.
  140. **Current coverage (4,000+ chunk-level alignments across 11 pair definitions):**
  141. | Sutra / Corpus | Source | Target | Pairs | Type |
  142. |---|---|---|---:|---|
  143. | **《妙法蓮華經》Lotus Sutra** (2026-06-08) | T0262 罗什 (Chinese) | Toh 113 Kangyur (Tibetan) | **259** | 汉 ↔ 藏 |
  144. | **《小品般若波羅蜜經》8,000-verse Prajñāpāramitā** (2026-06-09) | T0227 罗什 (Chinese) | Toh 11 Aṣṭasāhasrikā (Tibetan) | **127** | 汉 ↔ 藏 |
  145. | 《維摩詰所說經》Vimalakīrti | T0475 罗什 (Chinese) | Toh 176 (Tibetan) | 20 | 汉 ↔ 藏 |
  146. | 《般若波羅蜜多心經》Heart Sutra | T0252 (Chinese) | Toh 21 Kangyur (Tibetan) | 6 | 汉 ↔ 藏 |
  147. | Mahāsatipaṭṭhāna Sutta 念处经 | MN 10 (Pali) | T0026 中阿含 (Chinese) | 50 | 巴 ↔ 汉 |
  148. | Dhammacakkappavattana 转法轮经 | SN 56.11 (Pali) | T0099 杂阿含 (Chinese) | 17 | 巴 ↔ 汉 |
  149. | Dhammapada 法句经 | T0210 (Chinese) | SC 26 vaggas (Pali) | 49 | 汉 ↔ 巴 |
  150. | **Majjhima Nikāya ↔ 中阿含** | All MN suttas (Pali) | T0026 (Chinese) | ~1,800 | 巴 ↔ 汉 |
  151. | **Dīgha Nikāya ↔ 长阿含** | All DN suttas (Pali) | T0001 (Chinese) | ~700 | 巴 ↔ 汉 |
  152. | **Saṃyutta Nikāya 56 ↔ 杂阿含** | SN 56 suttas (Pali) | T0099 (Chinese) | ~150 | 巴 ↔ 汉 |
  153. | **Aṅguttara Nikāya 4 ↔ 增一阿含** | AN 4 suttas (Pali) | T0125 (Chinese) | ~400 | 巴 ↔ 汉 |
  154. Confidence distribution: all pairs ≥ 0.75. Hand-verified precision on the original MVP sample: **100%**. Mahāyāna 汉藏 batches: Lotus Sutra (2026-06-08) at $1.70 / 259 pairs (8.6% accept rate); 8,000-verse Prajñāpāramitā (2026-06-09) at $3.64 / 127 pairs (3.4% accept rate, lower because the sūtra's repetitive paratactic style yields fewer 1:1 chunk-level correspondences).
  155. **How to use:**
  156. 1. **In AI Q&A** — When XiaoJin cites an aligned sutra, the citation drawer shows tabs `[ 汉文 ] [ 巴利 (5) ] [ 藏文 (3) ]`. Click a tab to see the corresponding passage in another canon, rendered with proper Devanagari / Tibetan fonts.
  157. 2. **In the reader** — Click the 🌐 **「多语对读」** (Multilingual Parallel) button in the toolbar. Default tab **「按经对读」** shows sutta-level parallels from SuttaCentral's authoritative Akanuma-style table (3,293 pairs covering all 4 Āgamas ↔ Nikāyas), with Pāli original + Sujato English previews and "read full text" links. Alternate tab **「按段对读」** retains the experimental embedding+LLM chunk-level alignment (pipeline-generated, known to have noise). The panel sits to the left of the AI reading panel; both can be open simultaneously and independently resized.
  158. **Pipeline (`backend/scripts/build_alignments.py`):**
  159. - pgvector top-20 candidate recall within target text's embeddings
  160. - LLM verification (DeepSeek V3) returns `{is_parallel, confidence, reason}` JSON per candidate
  161. - Pairs with `confidence ≥ 0.75` persisted to `alignment_pairs` with unique `(text_a, text_b)` chunk tuple for idempotent re-runs
  162. - `$50` cost ceiling guard (actual MVP spend: **~$0.15**)
  163. - Multi-target resolver supports cases where target is split across rows (e.g., SC Dhammapada's 26 separate vagga texts)
  164. RAG layer automatically includes parallel_chunks in the LLM context when a retrieved chunk has alignments, so answers can naturally reference "the Pali version says…" without hallucinating.
  165. **Growing the alignment set — the flywheel:** beyond the batch pipeline above, an *alignment flywheel* (`backend/app/services/alignment_flywheel.py`) mines new candidate parallels by expanding outward from already-verified pairs — neighbouring chunks tend to align too, so this is both fast and precise where blind nearest-neighbour search drowns in same-language matches. Candidates are staged for **human review** (admin UI at `/admin/alignment/review`) and only promoted into the ground-truth `alignment_pairs` once accepted (`method='flywheel-verified'`). Nothing is auto-promoted — human review is the precision gate — and each verified alignment makes the next round of mining better. A **margin-based candidate router** in `build_alignments.py` routes recalled candidates into auto-accept / LLM-verify / auto-reject bands by ratio-margin, cutting LLM cost while keeping auto-accept off by default so the precision guarantee holds.
  166. **From chunks to sentences — the depth play:** verified chunk pairs seed **sentence-level alignment** (`backend/scripts/refine_sentence_alignments.py` + `services/sentence_align.py`): a pure-Python bertalign-style dynamic program subdivides each aligned paragraph into 1-1 / 1-2 / 2-1 sentence pairs over BGE-M3 cosine similarity, anchored to stable character offsets and stored in `sentence_alignments`. This backs precise 逐句对读 and cross-lingual sentence lookup. Two consumption surfaces already ship: **cross-lingual sentence search** (`GET /api/search/parallel-sentences` — query in Chinese, get aligned Sanskrit/Tibetan sentences over the ~896K-pair MITRA store) and a **versioned, license-stamped public dataset export** (`GET /exports/alignments.jsonl`) that turns the alignment corpus into a citable research artifact. Alignment quality is guarded by a dedicated **eval harness** (gold set + precision/recall/calibration metrics + regression gate) alongside the RAG eval, and MITRA cross-canon parallels feed the RAG context gated by a proxy quality score (`mitra_e_score`).
  167. ### AI Q&A — "XiaoJin"
  168. **This is FoJin's core.** Ask questions in natural language; XiaoJin answers from canonical Buddhist texts using RAG (Retrieval-Augmented Generation) over 670K+ embedding vectors with an HNSW index for fast semantic search. Answers stay grounded because retrieval combines vector similarity, keyword reranking, and **root-sutra recall** (the sutra you asked about is always pulled into context), and every quoted passage is checked against the retrieved sources before it can become a clickable citation. Features include:
  169. - Multi-turn conversation with context awareness
  170. - Keyword + optional API cross-encoder **reranking** for higher answer quality
  171. - **Clickable citations** in 【《经名》第N卷】 format — click to open a side drawer with surrounding context, plus **multi-language tabs for cross-canon parallels** when available (see Trilingual section above)
  172. - **GFM markdown tables** — comparative answers (e.g., "Madhyamaka vs Yogācāra") render as proper tables instead of raw pipe syntax
  173. - **Progressive follow-up suggestions** (concept → related texts → practice)
  174. - **Smart data source recommendations** — when users ask about finding databases, AI automatically recommends relevant sources from 612 data sources via semantic similarity
  175. - **Meta-question handling** — detects self-introduction queries ("who are you" / "what can you do") and skips RAG to give a clean functional overview, instead of randomly citing scriptures
  176. - **Anti-hallucination citation rules** — the system prompt strictly forbids wrapping a text name in 【…】 unless that exact source appeared in the retrieved context, preventing broken citation links
  177. - **Inline split-view in reader** — AI panel opens by default beside the text with a draggable divider; independent scrolling on each side, resizable width persisted to localStorage
  178. - **"Ask XiaoJin" button** on the reader page — select text to ask about it
  179. - **Tab key** cycles through suggested questions in the input box
  180. - BYOK (Bring Your Own Key) support for multiple LLM providers
  181. <p align="center"><img src="./docs/screenshots/ai-chat-answer.png" alt="AI Q&A answering about Xuanzang's disciples" width="800"></p>
  182. ### Verifiable answers — 每一句都能点回原典
  183. Trust is the point. Every answer passes three **deterministic** guards before it reaches you:
  184. - **Citation whitelist** — a 【《sutra》juan N】 citation is stripped or corrected unless that exact source was actually retrieved, so a citation link never points at something FoJin didn't read.
  185. - **Quote verification** — text inside quote marks is checked to be a *verbatim* substring of the retrieved passage (traditional/simplified folded); a non-verbatim "quote" is **downgraded** to plain prose rather than passed off as scripture.
  186. - **Trust state** — each answer is labelled `verified` / `citation_corrected` / `quote_relaxed` / `no_sources` so you can see how grounded it is.
  187. Measured on the eval harness at temperature 0, the raw model is verbatim-faithful only a small fraction of the time — but after the guards **~98% of citing answers are trustworthy**: FoJin either points you to a real source or honestly hedges, and never fabricates scripture. The metric (`served_trustworthy_rate`) is tracked in `backend/eval/faithfulness.py` as a regression gate.
  188. Read that denominator precisely, because we'd rather you knew than were impressed: it counts **answers that cite at all**. An answer that reaches you with no 【…】 citation cites nothing, so it verifies nothing, and it is not in that 98% — the guards can only vouch for claims that name a source. Quote fidelity is reported separately (`verbatim_quote_rate`), on purpose: a run must not be able to improve its score by quoting less.
  189. ### Research Assistant (研究助手)
  190. For multi-step questions a single search can't answer — *"how is śūnyatā treated across Prajñāpāramitā, Madhyamaka and Yogācāra, with cited cross-canon parallels?"* — the research assistant **plans** the question into steps, **retrieves** across the corpus, dictionaries and knowledge graph, then **synthesises** a grounded answer. The synthesis runs through the *same* citation guards as chat, so the agent can plan freely but **cannot cite what it didn't retrieve**. Available at `/research` (sign-in required); API at `POST /api/research/query`.
  191. ### Master Persona Mode (法师模式)
  192. Select a specific Buddhist master to receive answers in their teaching style, grounded in their tradition's core scriptures. 15 historical masters available:
  193. | Master | Tradition | Core Teachings |
  194. |--------|-----------|----------------|
  195. | 龙树 Nāgārjuna | 印度·中观 | 八不中道、缘起性空、二谛中道、戏论寂灭 |
  196. | 智顗 Zhiyi | 天台宗 | 一念三千、三谛圆融、五时八教、止观双修 |
  197. | 慧能 Huineng | 禅宗 | 直指人心、见性成佛、无念无相无住 |
  198. | 玄奘 Xuanzang | 法相唯识宗 | 八识、三性、五位百法、转识成智 |
  199. | 法藏 Fazang | 华严宗 | 法界缘起、四法界、十玄门、六相圆融 |
  200. | 鸠摩罗什 Kumarajiva | 三论宗/中观 | 八不中道、缘起性空、不二法门 |
  201. | 印光 Yinguang | 净土宗 | 信愿行、持名念佛、敦伦尽分 |
  202. | 蕅益 Ouyi | 天台/净土·跨宗派 | 教宗天台行归净土、六信、性相融会 |
  203. | 虚云 Xuyun | 禅宗·五宗兼嗣 | 参话头、起疑情、老实修行 |
  204. | 米拉日巴 Milarepa | 藏传·噶举派 | 雪山闭关瑜伽士、那洛六法、以道歌说法 |
  205. | 阿姜查 Ajahn Chah | 南传·泰国森林禅林派 | 正念、放下、朴素生活化教学 |
  206. | 宗喀巴 Tsongkhapa | 藏传·格鲁派 | 菩提道次第、三主要道、应成中观 |
  207. | 阿底峡 Atiśa Dīpaṃkara | 藏传·噶当派(印藏桥梁) | 菩提道灯论、三士道、七因果 |
  208. | 觉音 Buddhaghosa | 南传·上座部论师 | 清净道论、戒定慧、七清净十六观智 |
  209. | 马哈希 Mahasi Sayadaw | 南传·缅甸内观传统 | 标记现象法、腹部起伏、四念处密集禅修 |
  210. Each master has a 100-150 line enriched system prompt with lineage, core doctrines, speaking style, teaching methods, key allusions, and terminology table. When a master is selected, RAG retrieval is **scoped to their core scriptures** (e.g., selecting Zhiyi only searches 《摩诃止观》《法华玄义》 etc.), providing more precise citations.
  211. Powered by [Master-skill](https://github.com/xr843/Master-skill) — the open-source Buddhist master AI persona framework.
  212. ### Knowledge Graph Map (知识图谱地图)
  213. Visualize 50,000+ geo-enabled Buddhist entities on an interactive world map — monasteries, historical places, persons, and schools. Built with Deck.GL + MapLibre.
  214. - **Entity types**: Monasteries (green), Places (purple), Persons (red), Schools (blue)
  215. - **Lineage arcs**: Toggle 8,000+ teacher-student lineage relations as animated arcs on the map
  216. - **Chinese-only filter**: Quickly filter to show only Chinese-named entities
  217. - **Entity search**: Find entities by name with simplified/traditional Chinese conversion (OpenCC)
  218. - **Interactive tooltips**: Hover to see metadata, country flags, and source attribution
  219. ### Activity Feed (佛学动态)
  220. Track real-time updates from 612 data sources — new texts added, translation releases, manuscript scans, and schema changes. Includes academic content aggregation and platform-wide activity summary.
  221. ### Similar Passages Discovery
  222. When reading any text, the sidebar automatically finds semantically similar passages from other texts using pgvector cosine similarity. Discover cross-textual parallels, related commentaries, and thematic connections across the entire canon.
  223. ### Timeline & Statistics Dashboard
  224. Visualize Buddhist textual history with interactive D3 charts — dynasty distribution, translation trends, language breakdown, category treemap, and top translators. Toggle between scholarly and popular presentation modes.
  225. ### Collections, Bookmarks & Annotations
  226. Save texts to personal collections, bookmark specific passages, and add annotations for study and research.
  227. ### Citation Export
  228. Export citations in BibTeX, RIS, and APA formats for academic papers and reference managers.
  229. ### Multi-Language UI
  230. Available in 9 languages: Simplified Chinese, Traditional Chinese, English, Japanese, Korean, Thai, Vietnamese, Sinhala, and Burmese.
  231. ## Data Sources
  232. <p align="center"><img src="./docs/screenshots/sources.png" alt="612 data sources from 30 countries" width="800"></p>
  233. FoJin aggregates data from major Buddhist digital projects worldwide. Sources are categorized by research field (Han, Theravada, Tibetan, Sanskrit, Dunhuang, Art, Dictionary, Digital Humanities) and filterable by region, language, and type:
  234. | Source | Content | Languages |
  235. |--------|---------|-----------|
  236. | [CBETA](https://cbeta.org) | Chinese Buddhist Canon | Classical Chinese |
  237. | [SuttaCentral](https://suttacentral.net) | Early Buddhist Texts | Pali, Chinese, English |
  238. | [84000](https://84000.co) | Tibetan Buddhist Canon | Tibetan, English, Sanskrit |
  239. | [BDRC](https://bdrc.io) | Tibetan manuscripts (IIIF) | Tibetan |
  240. | [SAT](https://21dzk.l.u-tokyo.ac.jp/SAT/) | Taisho Tripitaka | Chinese, Japanese |
  241. | [DILA](https://authority.dila.edu.tw) | Authority databases (persons, places, catalogs) | Multi-language |
  242. | [GRETIL](http://gretil.sub.uni-goettingen.de) | Sanskrit e-texts | Sanskrit |
  243. | [DSBC](https://www.dsbcproject.org) | Digital Sanskrit Buddhist Canon | Sanskrit |
  244. | [Gandhari.org](https://gandhari.org) | Gandhari manuscripts | Gandhari |
  245. | [VRI Tipitaka](https://tipitaka.org) | Pali Canon (Chattha Sangayana) | Pali |
  246. | [Korean Tripitaka](http://kb.sutra.re.kr) | Goryeo Tripitaka | Chinese, Korean |
  247. | + 602 more... | | |
  248. ## Tech Stack
  249. | Layer | Technology |
  250. |-------|-----------|
  251. | Frontend | React 18, TypeScript, Vite, Ant Design 5, Zustand, TanStack Query, D3.js, Deck.GL + MapLibre (geo map) |
  252. | Backend | FastAPI, SQLAlchemy (async), Pydantic v2, SSE streaming |
  253. | Database | PostgreSQL 15 + pgvector (HNSW index) + pg_trgm |
  254. | Search | Elasticsearch 8 (ICU tokenizer) |
  255. | Cache | Redis 7 |
  256. | AI | RAG (670K+ vectors, BGE-M3, HNSW) + 15 master personas + multi-provider LLM (OpenAI/Anthropic/DeepSeek/DashScope/Gemini/+10 more) + deterministic citation/quote guards |
  257. | Integration | MCP server ([`fojin-mcp`](https://pypi.org/project/fojin-mcp/)) — stdio locally, streamable HTTP hosted at `mcp.fojin.ai` + public REST API with OpenAPI/Swagger docs + cross-canon URN scheme |
  258. | Deploy | Docker Compose, Nginx (gzip, security headers), Cloudflare CDN |
  259. | CI | GitHub Actions (lint, test, security scan) |
  260. ## Architecture
  261. ```
  262. +-------------+
  263. | Cloudflare | (CDN, SSL, DDoS protection)
  264. +------+------+
  265. |
  266. +------+------+
  267. | Nginx | (gzip, security headers, static cache)
  268. +------+------+
  269. |
  270. +-----------+-----------+
  271. | |
  272. +-----+------+ +-----+------+
  273. | React 18 | | FastAPI |
  274. | Vite + D3 | | async SSE |
  275. +-------------+ +------+------+
  276. |
  277. +--------+---------+---------+
  278. | | | |
  279. +-----+--+ +--+----+ +--+---+ +---+--------+
  280. | PG 15 | | ES 8 | |Redis | | LLM APIs |
  281. | pgvector | | ICU | |cache | | (multi- |
  282. | HNSW idx | | | | | | provider) |
  283. +---------+ +-------+ +------+ +------------+
  284. ```
  285. ## Development
  286. ```bash
  287. # Backend
  288. cd backend
  289. python -m venv .venv && source .venv/bin/activate
  290. pip install -r requirements-dev.txt
  291. alembic upgrade head
  292. uvicorn app.main:app --reload
  293. # Frontend
  294. cd frontend
  295. npm install
  296. npm run dev
  297. # Tests
  298. cd backend && pytest tests/ -q
  299. ```
  300. ## Security
  301. - Non-root containers (backend: `app`, frontend: `nginx`)
  302. - Multi-stage Docker builds (no build tools in production)
  303. - Internal services (Postgres, Redis, Elasticsearch, backend, Umami) bound to `127.0.0.1` only
  304. - Memory/CPU limits per container
  305. - CSP, X-Frame-Options, X-Content-Type-Options headers
  306. - Query length limits on all search parameters
  307. - JWT with a 30-day idle budget (sliding renewal, capped 90 days from sign-in); `POST /api/auth/logout-all` revokes every outstanding token. Production requires a strong secret
  308. ### Self-hosting privacy defaults
  309. - **No analytics phone-home.** The Umami tracking script is opt-in via build-time `VITE_UMAMI_URL` + `VITE_UMAMI_WEBSITE_ID`; if either is unset, the frontend ships without telemetry.
  310. - **LLM / embedding traffic is upstream by default.** Stock config calls DeepSeek + SiliconFlow with your platform key — user questions go there. Point `LLM_API_URL` / `EMBEDDING_API_URL` at a local OpenAI-compatible server (vLLM, Ollama, LM Studio) for a fully offline setup, or have each user provide their own key via the in-app BYOK flow.
  311. - **The frontend container binds to `127.0.0.1` by default** (set via `FRONTEND_BIND`), so out of the box it's reachable only from the host — put an authenticated reverse proxy or CDN in front of it as the public entry. If you need direct LAN/remote access without a proxy, set `FRONTEND_BIND=0.0.0.0`; note that Docker publishes ports through its own iptables rules that bypass host firewalls like `ufw`, so anyone who can reach the host on that port hits your instance.
  312. See [SECURITY.md](SECURITY.md) for the full picture.
  313. ## Contributing
  314. Contributions are welcome! Whether it's adding a new data source, improving search, fixing bugs, or translating the UI — we'd love your help.
  315. 1. Fork the repository
  316. 2. Create your feature branch (`git checkout -b feat/amazing-feature`)
  317. 3. Commit your changes (`git commit -m 'Add amazing feature'`)
  318. 4. Push to the branch (`git push origin feat/amazing-feature`)
  319. 5. Open a Pull Request
  320. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
  321. ## Roadmap
  322. - [x] Citation export (BibTeX, RIS, APA)
  323. - [x] Mobile-responsive reader
  324. - [x] Public REST API with rate limiting
  325. - [x] User annotations
  326. - [x] Community-contributed data sources
  327. - [x] Internationalization (i18n) — 9 UI languages
  328. - [x] Embedding-based semantic search (670K+ vectors, HNSW index)
  329. - [x] AI Q&A with RAG, multi-turn context, and streaming
  330. - [x] Similar passages discovery (cross-text semantic matching)
  331. - [x] Timeline visualization and statistics dashboard
  332. - [x] User feedback system and notification center
  333. - [x] Admin dashboard (user management, platform analytics)
  334. - [x] API documentation (OpenAPI/Swagger at `/docs`, ReDoc at `/redoc`)
  335. - [x] AI answer reranking (keyword + optional API cross-encoder)
  336. - [x] Clickable citation links in AI answers
  337. - [x] Progressive follow-up suggestions after AI answers
  338. - [x] "Ask XiaoJin" floating button on reader page
  339. - [x] Tab key to cycle through suggested questions
  340. - [x] CBETA-style text layout with verse/prose detection
  341. - [x] Auto database migration on Docker startup
  342. - [x] AI answer rating (thumbs up/down) for quality tracking
  343. - [x] Research field filtering for data sources (8 categories)
  344. - [x] Admin feedback reply with notification system
  345. - [x] AI-powered data source recommendations in chat (semantic similarity)
  346. - [x] DILA Authority lineage import (22K+ teacher-student relations)
  347. - [x] DILA catalog associations (contributors, places for 2,300+ texts)
  348. - [x] Nanshan Vinaya Dictionary (3,200+ Buddhist precept terms)
  349. - [x] CBETA full-text import — Taishō (T) + Xuzangjing (X): 3,600+ texts, 143M characters, 432K embedding vectors
  350. - [x] Dictionary expansion — 39 dictionaries, 747K entries (DPD, Apte, Mahāvyutpatti, Buddhadatta, Pentaglot, buddhaspace 7 dicts)
  351. - [x] Master Persona Mode — 15 Buddhist masters with tradition-scoped RAG (powered by [Master-skill](https://github.com/xr843/Master-skill))
  352. - [x] Knowledge Graph Map — 50K+ geo entities, Deck.GL + MapLibre, lineage arcs
  353. - [x] Activity Feed — real-time source update tracking, academic feeds
  354. - [x] Inline split-view AI reader panel with draggable divider and independent scrolling
  355. - [x] AI panel auto-open in reader for one-click access to interpretation
  356. - [x] Meta-question detection in chat — recognizes "who are you / what can you do" and skips RAG
  357. - [x] **Trilingual cross-canon parallel reading** — 11 pair definitions, 4,000+ LLM-verified chunk alignments across CBETA / SuttaCentral / 84000 (incl. Lotus Sutra 法华 ↔ Toh 113, 8,000-verse Prajñāpāramitā 小品般若 ↔ Toh 11, the full Āgama ↔ Nikāya corpus, and the original 5 MVP classics)
  358. - [x] Chat citation drawer with multi-language tabs (汉 / 巴 / 藏 side-by-side)
  359. - [x] Reader "多语对读" inline sidebar — dual tabs: sutta-level SC-authoritative parallels + legacy chunk-level RAG alignment; coexists with AI panel, independent drag-resize
  360. - [x] GFM markdown tables in AI answers (remark-gfm) — comparative responses render as proper tables
  361. - [x] Anti-hallucination citation rules (Rule 4/4b) — forbid wrapping non-retrieved sutra names in 【…】
  362. - [x] Server-side SEO meta injection for `/texts/{id}` pages — proper `<title>` / `<description>` per sutra for search engines (SPA route crawlability)
  363. - [x] **Deterministic answer verifiability** — citation whitelist + verbatim-quote downgrade + per-answer trust state; `served_trustworthy_rate` ~98% of citing answers at temp 0 as an eval regression gate
  364. - [x] **Cross-canon URN scheme** — stable, resolvable passage identifiers (`fojin:cbeta/T0001.1`) interoperable with CBETA / SuttaCentral / 84000 / GRETIL / VRI
  365. - [x] **MCP server — published to PyPI as [`fojin-mcp`](https://pypi.org/project/fojin-mcp/)** — 8 read-only, URN-addressable tools; callable from Claude Desktop / ChatGPT
  366. - [x] **Hosted MCP endpoint** — `https://mcp.fojin.ai/mcp` over streamable HTTP; anonymous, rate-limited, no key to obtain
  367. - [x] **Open verbatim quote verification** (`GET /api/verify/quote` + `verify_quote` tool) — works on *any* quotation, not only FoJin's own answers: ES shortlists, Postgres decides, exact / near-miss / absent with a character-level diff; never silently accepts a match in a different juan
  368. - [x] **Commentary alignment** (`GET /api/commentary/passage` + `commentaries` tool) — historical commentaries keyed to a passage, anchored to juan and line; first corpus is the Diamond Sutra (52 commentators, 5,683 aligned segments)
  369. - [x] **Developer portal** ([fojin.ai/developers](https://fojin.ai/developers), formerly `/agents`) + `llms.txt` — one page telling an AI what FoJin exposes and how to call it
  370. - [x] **Read-aloud** (`/read-aloud`) — sentence-synced audio with line highlighting and lock-screen playback (Heart Sutra first)
  371. - [x] **XiaoJin on the homepage** — a draggable companion that answers inline, streaming, without leaving the page
  372. - [x] **Sliding session renewal** — active users are no longer silently demoted to guest every 8 hours; password change still revokes every device
  373. - [x] **Agentic research assistant** (`/research`) — plan → retrieve (corpus + dictionary + KG) → grounded synthesis behind the same citation guards
  374. - [x] **Alignment flywheel** — anchor-expansion candidate mining + human-review promotion (admin UI at `/admin/alignment/review`) into ground-truth alignments
  375. - [x] **Sentence-level cross-canon alignment** — bertalign-style DP over BGE-M3 embeddings subdivides verified chunk pairs into aligned sentence pairs (`sentence_alignments`); pure-Python, no new deps
  376. - [x] **Margin-based candidate router** — ratio-margin bands (auto-accept / LLM-verify / auto-reject) in the alignment builder cut LLM cost while preserving the 100%-precision guarantee (auto-accept off by default)
  377. - [x] **Alignment-quality eval harness** — gold set + deterministic precision/recall/calibration metrics + regression gate mirroring the RAG eval
  378. - [x] **MITRA cross-lingual parallels in RAG** — ~896K Skt/Tib ↔ 汉 sentence pairs gated by a proxy quality score (`mitra_e_score`, NULL-permissive)
  379. - [x] Cross-lingual search (query in Chinese, find Sanskrit/Pali/Tibetan results) — over MITRA sentence parallels (`GET /api/search/parallel-sentences`)
  380. - [x] Open alignment dataset export — versioned, license-stamped JSONL with provenance + `GET /exports/alignments.jsonl` streaming endpoint
  381. - [ ] Trilingual MVP v1.1 — expand to 20+ sutras (Lotus, Avataṃsaka, Madhyamakakārikā, Laṅkāvatāra, full Āgama↔Nikāya)
  382. - [ ] Reader 逐句对读 (sentence-level parallel reading UI) — backend contract shipped (`GET /alignment/sentences/...`, ships dark behind `enable_sentence_parallels`); frontend pending prod sentence data
  383. - [ ] Topic ontology browsing page
  384. - [ ] OCR pipeline for scanned texts
  385. - [ ] Collaborative annotation sharing
  386. - [ ] Integration with Zotero and reference managers
  387. ## License
  388. [Apache License 2.0](LICENSE) — applies to FoJin source code only. Third-party data sources retain their own licenses (CC BY-NC-SA, CC0, CC BY-NC-ND, etc.). See [NOTICE](NOTICE) for details.
  389. ## Acknowledgments
  390. FoJin is built on the generous work of the global Buddhist digital humanities community. Special thanks to:
  391. - [CBETA](https://cbeta.org) — Chinese Buddhist Electronic Text Association
  392. - [SuttaCentral](https://suttacentral.net) — Early Buddhist Texts
  393. - [BDRC](https://bdrc.io) — Buddhist Digital Resource Center
  394. - [84000](https://84000.co) — Translating the Words of the Buddha
  395. - [SAT](https://21dzk.l.u-tokyo.ac.jp/SAT/) — SAT Daizokyo Text Database
  396. - All other data source providers listed in the [Sources page](https://fojin.app/sources)
  397. ## Community
  398. - [LINUX DO](https://linux.do) — Thanks to the LINUX DO community for support and feedback
  399. ## Related Projects
  400. - [Master-skill](https://github.com/xr843/Master-skill) — Buddhist master AI persona framework (powers FoJin's master mode)
  401. - [The Open Buddhist University](https://buddhistuniversity.net) — Free courses, books, and encyclopaedia for Buddhist studies
  402. ---
  403. <div align="center">
  404. **If FoJin is useful for your research, please consider giving it a star!**
  405. [Discussions](https://github.com/xr843/fojin/discussions) &nbsp;&middot;&nbsp; [Issues](https://github.com/xr843/fojin/issues) &nbsp;&middot;&nbsp; [Contributing](CONTRIBUTING.md) &nbsp;&middot;&nbsp; [contact@fojin.app](mailto:contact@fojin.app)
  406. Made with care for the Buddhist studies community.
  407. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.