sanatan-verse-sdk 0.30.5

Python SDK for creating verse-based content sites with AI translations, multimedia (images, audio), semantic search, RAG-grounded Puranic context, and deployment

Sanatan Verse SDK - Python SDK for Spiritual Verse Collections

Complete toolkit for generating rich multimedia content for spiritual text collections (Hanuman Chalisa, Sundar Kaand, etc.)

Features

• 🔄 Complete Workflow: Generate media and embeddings from canonical sources - all in one command
• 📖 Canonical Sources: Local YAML files ensure text accuracy and quality
• 🎨 AI Images: Generate themed images with DALL-E 3
• 🎵 Audio Pronunciation: Full and slow-speed audio with ElevenLabs
• 🔍 Semantic Search: Vector embeddings for intelligent verse discovery
• 📚 Multi-Collection: Organized support for multiple verse collections
• 🎨 Theme System: Customizable visual styles (modern, traditional, kids-friendly, etc.)

Quick Start

New Project Setup (Recommended)

# 1. Install
pip install sanatan-verse-sdk

# 2. Create project with collection templates
verse-init --project-name my-verse-project --collection hanuman-chalisa
cd my-verse-project

# 3. Configure API keys
cp .env.example .env
# Edit .env and add your API keys from:
# - OpenAI: https://platform.openai.com/api-keys
# - ElevenLabs: https://elevenlabs.io/app/settings/api-keys

# 4. Add canonical Devanagari text
# Edit data/verses/hanuman-chalisa.yaml with actual verse text

# 5. Validate setup
verse-validate

# 6. Generate multimedia content
verse-generate --collection hanuman-chalisa --verse 1

What you get: Verse file, AI-generated image, audio (full + slow speed), and search embeddings!

Existing Project

# Validate and fix structure
verse-validate --fix

# Generate content
verse-generate --collection hanuman-chalisa --verse 15

# Check status
verse-status --collection hanuman-chalisa

Advanced Usage

# Multiple collections at once
verse-init --collection hanuman-chalisa --collection sundar-kaand

# Custom number of sample verses
verse-init --collection my-collection --num-verses 10

# Generate specific components only
verse-generate --collection sundar-kaand --verse 3 --image
verse-generate --collection sundar-kaand --verse 3 --audio

# Skip embeddings update (faster)
verse-generate --collection hanuman-chalisa --verse 15 --no-update-embeddings

What Gets Generated

Each verse generation creates:

• 🎨 Image: images/{collection}/{theme}/verse-01.png (DALL-E 3)
• 🎵 Audio (full): audio/{collection}/verse-01-full.mp3 (ElevenLabs)
• 🎵 Audio (slow): audio/{collection}/verse-01-slow.mp3 (0.75x speed)
• 🔍 Embeddings: data/embeddings.json (for semantic search)

Text Source: Canonical Devanagari text from data/verses/{collection}.yaml (Local Verses Guide)

Installation

pip install sanatan-verse-sdk

Commands

Project Setup

• verse-init - Initialize new project with recommended structure
• verse-validate - Validate project structure and configuration

Content Generation

• verse-generate - Complete orchestrator for verse content (text fetching, multimedia generation, embeddings)
• verse-translate - Translate verses into multiple languages (Hindi, Spanish, French, etc.)
• verse-images - Generate images using DALL-E 3
• verse-audio - Generate audio pronunciations using ElevenLabs
• verse-embeddings - Generate vector embeddings for semantic search (multi-collection guide)

Puranic Context

• verse-index-sources - Index Puranic source texts (PDFs, TXTs) into episodes and embeddings for RAG retrieval
• verse-puranic-context - Generate Puranic context boxes for verses (RAG-grounded or GPT-4o free recall)

Project Management

• verse-add - Add new verse entries to collections (supports multi-chapter formats)
• verse-status - Check status, completion, and validate text against canonical source
• verse-sync - Sync verse text with canonical source (fix mismatches)
• verse-deploy - Deploy Cloudflare Worker for API proxy

Configuration

Copy the example environment file and add your API keys:

cp .env.example .env
# Edit .env and add your API keys

See the Usage Guide for detailed information on project structure, workflows, batch processing, and cost optimization.

Documentation

• Usage Guide - Project setup, workflows, batch processing, and best practices
• Local Verses Guide - Using local YAML files for verse text
• Chapter-Based Formats - Multi-chapter collections (Bhagavad Gita, etc.)
• Command Reference - Detailed documentation for all commands
• Development Guide - Setup and contributing to verse-sdk
• Troubleshooting - Common issues and solutions
• Multi-Collection Guide - Working with multiple collections
• Publishing Guide - For maintainers

Example Project

Hanuman GPT - Multi-collection project with Hanuman Chalisa, Sundar Kaand, and Sankat Mochan Hanumanashtak

Requirements

• Python 3.8+
• OpenAI API key (for text/images/embeddings)
• ElevenLabs API key (for audio)

License

MIT License - See LICENSE file for details

Support

• GitHub Issues
• Documentation
• Troubleshooting Guide