Sura

Pronounced "soo-rah". Derived from the Japanese onomatopoeia "surasura" (すらすら), meaning to read or proceed smoothly without interruption.

Sura helps you read English books fluently. It uses AI to analyze your EPUB files and automatically inserts short, context-aware English definitions above difficult words (ruby text). This allows you to read without constantly stopping to check a dictionary.

Unlike standard e-reader dictionaries that only provide generic definitions, Sura understands the context of the sentence and provides the specific meaning intended by the author. The output is a standard EPUB file compatible with Apple Books, Kindle, Kobo, and other readers.

Key Features

• LLM-powered precision
  • Uses any OpenAI-compatible endpoint (OpenAI, Azure, Groq, etc.) to generate concise definitions for each selected word.
• Statistical filtering
  • Uses wordfreq Zipf scores to filter out common words; only genuinely difficult vocabulary is annotated to keep the page clean.
• Universal compatibility
  • The output is a plain EPUB with embedded CSS, readable on iOS, Android, and desktop readers.
• Fast & cheap
  • Async processing with deduplication reduces the number of API calls significantly.

Quick Start

1. Install

$ git clone [https://github.com/your-username/Sura.git](https://github.com/your-username/Sura.git)
$ cd Sura
$ pip install -r requirements.txt

2. Set environment variables

You can use any AI service that supports the OpenAI API format.

Variable	Meaning	Example
API_KEY	Your secret key	export API_KEY="sk-xxxxxxx"
API_BASE_URL	Base URL of the service	export API_BASE_URL="https://api.openai.com/v1"
API_MODEL	Model to use	export API_MODEL="gpt-4o"

3. Run the CLI

$ python main.py input_book.epub output_annotated.epub

The script prints per-chapter annotation counts.

[chapter_001.xhtml] 23 annotations added
[chapter_002.xhtml] 17 annotations added
...
Success: Processed EPUB saved to output_annotated.epub

Advanced Configuration

• Difficulty threshold
  • Adjust DIFFICULTY_THRESHOLD in processor.py (default 3.8). Lowering this value selects fewer words (only the most difficult); raising it selects more words.
• Batch size
  • Tweak MAX_BATCH_SIZE for faster processing or to match specific API rate limits.

Contributing

Feel free to open issues or submit pull requests. All contributions follow the MIT license.

License

MIT License

• see the LICENSE file.

Disclaimer: This tool is not affiliated with Amazon or the Kindle brand. Use this tool only with DRM-free books you legally own.