medieval_latina 3.1.2 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16b43f057d59dde5ed50dab23aa1098ae6fc34fdc8194c232be6827882bdc452
-  data.tar.gz: 0d9be075e1e7634985ffc9750578ff355f17b0704da462ad1a9385cae8239755
+  metadata.gz: 47f39ae4c5ce8d0b6b624beae267c9a8e00b2ac44e6c09686e34e825d8671dcd
+  data.tar.gz: a8f8ca9f9357a0453429104a1d8e8423c63dbd3ab4360277993c29c46cb7573f
 SHA512:
-  metadata.gz: 684ff286bdc6379e4fecf3b14168ec967a0ac4d286c1199c9cfa1ff7b5a958037d51812890c721159fdfc86e00a5ddb9717891c105cabf7149781598066c8f07
-  data.tar.gz: bd3e5086934968a1eb8bf70b513cbfdd9721fd0155395648e005a9b46e45f8305909c484a871a09941b74ba775c0e6c3376097c280454286474d3d1c465e644f
+  metadata.gz: d1e79d2981bdc926e0640de05a3d870ea907075f6c3c822be135c89f2060b1abaa386fe50fb4e61325e7d799ab7d216b33329ec58b35b6e9520bc4c1b7367300
+  data.tar.gz: 64dd8015e355efc41bdc754f3720c204dda502d64c0665dfed7830063f8ececb09f5eefefcfd9e520ee105676695f525a6fc1752e4be61e41a2e16f0c1b2eac9

data/.github/workflows/tests.yml

@@ -22,6 +22,7 @@ jobs:
           - '3.2'
           - '3.3'
           - '3.4'
+          - '4.0'
         allow_failures:
           - false
     env:

data/.tool-versions

@@ -1,2 +1,2 @@
 nodejs 24.2.0
-ruby 3.4.1
+ruby 4.0.5

data/AGENTS.md

@@ -0,0 +1,60 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Development Commands
+
+- **Setup**: `bin/setup` - Install dependencies with bundle install
+- **Tests**: `rake spec` or `bundle exec rspec` - Run the full test suite
+- **Linting**: `bin/lint` - Run StandardRB linter and jsonlint on dictionary.json
+- **Build lexicons**: `bin/build` - Regenerate PLS lexicon files from dictionary.json
+- **Console**: `bin/console` - Interactive prompt for experimentation
+- **Install gem locally**: `bundle exec rake install`
+- **Release**: `bundle exec rake release` (after updating version.rb)
+
+## Architecture Overview
+
+This is a Ruby gem that converts medieval Latin text to phonetic English for text-to-speech engines. The architecture consists of:
+
+### Core Components
+
+- **MedievalLatina class** (`lib/medieval_latina.rb`): Main interface with class methods for text conversion and linguistic analysis
+  - `MedievalLatina[text]` - Primary conversion method
+  - Part-of-speech helpers: `verb?`, `noun?`, `adjective?`, `adverb?`
+  - `pronunciations_for(words)` - Extract IPA pronunciations for lexicon building
+
+- **Dictionary system** (`data/dictionary.json`): Large JSON file containing Latin words with metadata including:
+  - IPA pronunciations
+  - Part of speech classifications
+  - Custom pronunciation overrides
+
+- **Lexicon generation** (`lib/medieval_latina/lexicon_builder.rb`, `lib/medieval_latina/lexicon.rb`): Creates PLS (Pronunciation Lexicon Specification) files for AWS Polly and other TTS engines
+
+### Phonetic Conversion Logic
+
+The main conversion algorithm handles:
+- Vowel teams: ae→ay, oe→ay, au→ou
+- Consonant transformations: c→ch/k (soft/hard), g→j/g, j→y, t→ts/t, x→ks
+- Consonant teams: gn→n-y, qu→kw
+- Text preprocessing with I18n transliteration
+
+### Data Flow
+
+1. Text input → word tokenization → dictionary lookup
+2. If word has custom pronunciation → use it
+3. Otherwise → apply phonetic transformation rules
+4. Rejoin with proper punctuation spacing
+
+## Key Files
+
+- `lib/medieval_latina.rb` - Main conversion logic and API
+- `data/dictionary.json` - Latin word database (400KB+)
+- `bin/build` - Splits dictionary into multiple PLS files in lexicons/ directory
+- `.standard.yml` - StandardRB configuration (Ruby 3.2, parallel linting)
+- `medieval_latina.gemspec` - Gem specification (requires Ruby >= 3.2.0)
+
+## Testing
+
+- RSpec test suite in `spec/`
+- Configuration in `.rspec` with documentation format
+- Run specific tests: `bundle exec rspec spec/specific_spec.rb`

data/Gemfile

@@ -2,3 +2,8 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in medieval_latina.gemspec
 gemspec
+
+# `logger` stopped being autoloaded under Bundler once it became a bundled gem
+# (Ruby 3.4+) and is no longer in Ruby 4.0's default set. jsonlint requires it
+# without declaring the dependency, so declare it here for `bundle exec jsonlint`.
+gem "logger"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    medieval_latina (3.1.2)
+    medieval_latina (3.2.0)
       i18n
 
 GEM
@@ -19,8 +19,9 @@ GEM
       optimist (~> 3)
     language_server-protocol (3.17.0.3)
     lint_roller (1.1.0)
+    logger (1.7.0)
     mini_portile2 (2.8.9)
-    nokogiri (1.18.9)
+    nokogiri (1.19.3)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
     oj (3.16.5)
@@ -88,6 +89,7 @@ PLATFORMS
 
 DEPENDENCIES
   jsonlint
+  logger
   medieval_latina!
   nokogiri
   rake (~> 12.0)

data/README.md

@@ -3,6 +3,22 @@
 There are good text-to-speech engines for English and classical Latin, but none for medieval Latin.
 `MedievalLatina` converts Latin text to a kind of phonetic spelling that can be read by English language text-to-speech engines.
 
+## Hear it
+
+A line of the Lord's Prayer — *Pater noster qui es in caelis* — spoken by Amazon Polly using this gem's IPA pronunciation lexicon, so you hear MedievalLatina's pronunciation rather than raw Latin:
+
+▶️ **[Play the sample](https://github.com/jaysonvirissimo/medieval_latina/raw/master/audio/pater-noster.mp3)** (`audio/pater-noster.mp3`)
+
+<!-- Inline player: drag-and-drop audio/pater-noster.mp3 into a GitHub PR/comment composer to
+     mint a https://github.com/user-attachments/assets/<id> URL, then paste that URL on its own
+     line directly below to render an inline audio player in the rendered README. -->
+
+- **Text:** *Pater noster qui es in caelis* — "Our Father, who art in heaven", the traditional Latin Lord's Prayer (public domain).
+- **Gem output:** `MedievalLatina["Pater noster qui es in caelis"]` → `"pah-tare nohstayr kwee es een chaylees"`.
+- **Voice:** Amazon Polly **Bianca** (Italian, `it-IT`, neural engine), driven by MedievalLatina's IPA via a PLS lexicon.
+- **Reproduce:** `ruby -Ilib bin/sample_audio Bianca` (requires AWS credentials in the environment and the `aws-sdk-polly` gem).
+- **Provenance:** audio generated with Amazon Polly on 2026-06-07; Polly output may be used and redistributed under the [AWS Service Terms](https://aws.amazon.com/service-terms/).
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -40,7 +56,8 @@ responsiveVoice.speak(sentence, "UK English Female");
 polly = Aws::Polly::Client.new
 s3 = Aws::S3::Client.new
 
-sentence = "PATER NOSTER qui es in caelis"
+# Lowercase so the text matches the lexicon's (case-sensitive) lowercase graphemes.
+sentence = "pater noster qui es in caelis"
 
 words = sentence.split(" ")
 pronunciations = MedievalLatina.pronunciations_for(words)

data/bin/sample_audio

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Generates the README's spoken sample with Amazon Polly, using MedievalLatina's
+# IPA pronunciations via a PLS lexicon so Polly pronounces the Latin our way.
+#
+# Usage:
+#   AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY must be in the environment.
+#   aws-sdk-polly must be available, e.g. run through a bundle that provides it:
+#     BUNDLE_GEMFILE=/path/to/aws/Gemfile bundle exec ruby -Ilib bin/sample_audio Joanna
+#   Output: tmp/sample-<voice>.mp3
+#
+# Credentials are read from the AWS SDK default chain only; they are never echoed,
+# logged, or written to disk.
+
+require "medieval_latina"
+require "aws-sdk-polly"
+require "fileutils"
+
+# us-east-1 is where the voices/engines below are available; override via env if needed.
+REGION = ENV["AWS_REGION"] || ENV["AWS_DEFAULT_REGION"] || "us-east-1"
+# Polly matches lexicon graphemes case-sensitively and our graphemes are lowercase,
+# so synthesize from lowercased text (the README still shows it capitalized).
+SENTENCE = "pater noster qui es in caelis"
+
+# Polly applies a lexicon only when its xml:lang matches the voice's language, and
+# lexicons work on the standard/neural engines (not generative). Each voice below is
+# paired with the matching lexicon language and a lexicon-capable engine.
+VOICES = {
+  "Joanna" => {lang: "en-US", engine: "neural"},
+  "Matthew" => {lang: "en-US", engine: "neural"},
+  "Danielle" => {lang: "en-US", engine: "neural"},
+  "Stephen" => {lang: "en-US", engine: "neural"},
+  "Bianca" => {lang: "it-IT", engine: "neural"},
+  "Carla" => {lang: "it-IT", engine: "standard"},
+  "Giorgio" => {lang: "it-IT", engine: "standard"}
+}.freeze
+
+LEXICON_NAMES = {"en-US" => "MedievalLatinaEnUs", "it-IT" => "MedievalLatinaItIt"}.freeze
+
+abort "Usage: #{$PROGRAM_NAME} <voice>\nChoices: #{VOICES.keys.join(", ")}" if ARGV.empty?
+
+voice = ARGV[0]
+config = VOICES[voice]
+abort "Unknown voice #{voice.inspect}. Choose one of: #{VOICES.keys.join(", ")}" unless config
+
+# Build the {word => IPA} map from the gem's dictionary for every word in the sentence.
+pronunciations = MedievalLatina.pronunciations_for(SENTENCE.split)
+
+# Build a lexicon whose xml:lang matches the voice's language (Polly applies a lexicon
+# only when the languages match).
+lang = config[:lang]
+lexicon_name = LEXICON_NAMES[lang]
+lexicon = MedievalLatina::LexiconBuilder.new(pronunciations, lang: lang).call.to_s
+
+polly = Aws::Polly::Client.new(region: REGION)
+polly.put_lexicon(name: lexicon_name, content: lexicon) # idempotent; overwrites
+
+FileUtils.mkdir_p("tmp")
+output_path = "tmp/sample-#{voice}.mp3"
+
+# Always remove the lexicon from the AWS account, even if synthesis/write raises.
+begin
+  response = polly.synthesize_speech(
+    text: SENTENCE,
+    lexicon_names: [lexicon_name],
+    voice_id: voice,
+    engine: config[:engine],
+    output_format: "mp3"
+  )
+  File.binwrite(output_path, response.audio_stream.read)
+ensure
+  polly.delete_lexicon(name: lexicon_name)
+end
+
+puts "#{voice} (#{lang}, #{config[:engine]}) -> #{output_path} (#{File.size(output_path)} bytes)"