Skip to content

TNH Scholar README

TNH Scholar is an AI-driven project designed to explore, query, process and translate the teachings of Thich Nhat Hanh and the Plum Village community. The project provides tools for practitioners and scholars to engage with mindfulness and spiritual wisdom through natural language processing and machine learning models.

Vision & Goals

TNH Scholar aims to make the teachings of Thich Nhat Hanh and the Plum Village tradition more accessible and discoverable through modern AI techniques. By combining natural language processing, machine learning, semantic search, and careful curation, we create pathways for practitioners and scholars to translate, search, organize, process and otherwise find meaningful connections among the body of teachings.

Features

TNH Scholar is currently in active prototyping. Key capabilities:

  • Audio and transcript processing: audio-transcribe with diarization and YouTube support
  • Text formatting and translation: tnh-gen CLI for punctuation, translation, sectioning, and prompt-driven processing. See ADR-TG01 and ADR-TG02 for architecture details.
  • Acquisition utilities: ytt-fetch for transcripts; token-count and nfmt for prep and planning
  • Setup and configuration: tnh-setup plus guided config in Getting Started
  • Prompt system: See ADRs under docs/architecture/prompt-system/index.md for decisions and roadmap

⚠️ Rapid Prototype Phase (0.x): TNH Scholar is in active development with no backward compatibility guarantees. Breaking changes may occur in ANY 0.x release (including patches). Pin to a specific version if stability is needed: pip install tnh-scholar==0.3.0. See ADR-PP01 for versioning policy.

Quick Start

Installation (PyPI)

pip install tnh-scholar
tnh-setup

Prerequisites: Python 3.12.4+, OpenAI API key (CLI tools), Google Vision (optional OCR), pip or Poetry.

Development setup (from source)

Follow DEV_SETUP.md for the full workflow. Short version:

pyenv install 3.12.4
poetry config virtualenvs.in-project true
make setup-dev    # Full dev environment (recommended)
make build-all    # Full rebuild (poetry update, yt-dlp, pipx, docs)
make pipx-build   # Install CLI tools globally (audio-transcribe, tnh-gen, etc.)

Set OpenAI credentials

export OPENAI_API_KEY="your-api-key"

Example usage

Transcribe Audio from YouTube:

audio-transcribe --yt_url "https://youtube.com/watch?v=example" --split --transcribe

Download Video Transcripts:

ytt-fetch "https://youtube.com/watch?v=example" -l en -o transcript.txt

Process Text with tnh-gen:

# List available prompts
tnh-gen list

# Run a prompt on a file
tnh-gen run --prompt translate --input-file input.txt --var source_lang=vi --var target_lang=en

Getting Started

  • Practitioners: Install, configure credentials, and follow the Quick Start Guide; workflows live in the User Guide.
  • Developers: Set up via DEV_SETUP.md and Contributing; review System Design and the CLI docs; run make docs to view locally.
  • Project Philosophy & Vision: Developers and researchers should review the conceptual foundations in docs/project/vision.md, docs/project/philosophy.md, docs/project/principles.md, and docs/project/conceptual-architecture.md to understand the system’s long-term direction and design intent.
  • Researchers: Explore Research for experiments and direction; see Architecture for pipelines/ADRs (e.g., ADR-K01).

Documentation Overview

Comprehensive documentation is available in multiple formats:

Documentation Structure

  • Getting Started – Installation, setup, and first steps
  • CLI Docs – Command-line tool documentation
  • User Guide – Detailed usage guides, prompts, and workflows
  • API Reference – Python API documentation for programmatic use
  • Architecture – Design decisions, ADRs, and system overview
  • Development – Contributing guidelines and development setup
  • Research – Research notes, experiments, and background
  • Documentation Operations – Documentation roadmap and maintenance

Architecture Overview

Development

Common commands:

  • make setup-dev - Full development environment setup
  • make build-all - Full rebuild (poetry update, yt-dlp, pipx tools, docs)
  • make update - Update dependencies and reinstall pipx tools
  • make pipx-build - Install CLI tools globally via pipx (editable mode)
  • make test, make lint, make format - Testing and code quality
  • make docs, make ci-check - Documentation and CI validation
  • poetry run mypy src/ - Type checking

CLI Tool Access:

All CLI tools can be installed globally via pipx for easy access in any shell:

make pipx-build  # Installs: audio-transcribe, tnh-gen, ytt-fetch, token-count, nfmt, etc.

Optional dependency groups (development only): tnh-scholar[ocr], tnh-scholar[gui], tnh-scholar[query], tnh-scholar[dev]

Troubleshooting and workflows: DEV_SETUP.md

Contributing

See CONTRIBUTING.md for coding standards, testing expectations, and PR workflow. We welcome contributions from practitioners, developers, and scholars.

Project Status

TNH Scholar is currently in alpha stage (v0.3.0). Expect ongoing API and workflow changes during active development.

Support & Community

Documentation Map

For an auto-generated list of every document (titles and metadata), see the Documentation Index.

License

This project is licensed under the GPL-3.0 License.

For more information, visit the full documentation or explore the source code.