v2.9.1 - Google STT & OpenRouter Embeddings

Release v2.9.1

This release adds two major features: Google Speech-to-Text support using Gemini API and OpenRouter as an embedding provider.

🎙️ Google Speech-to-Text Support

Implements Google Speech-to-Text provider using Gemini API's audio transcription capabilities (gemini-2.5-flash and gemini-2.0-flash).

Key Features

• Gemini API Integration: Simple API key authentication (no OAuth2/service accounts needed)
• Multi-format Support: Automatic MIME type detection for MP3, WAV, AIFF, AAC, OGG, FLAC
• Language Hints: Specify language for better transcription accuracy
• Custom Prompts: Guide transcription focus (e.g., "Focus on technical terminology")
• Async Support: Both sync (transcribe) and async (atranscribe) methods
• BinaryIO Support: Works with file-like objects

Usage Example

from esperanto.factory import AIFactory

# Basic usage
transcriber = AIFactory.create_speech_to_text("google", "gemini-2.5-flash")
result = transcriber.transcribe("audio.mp3")
print(result.text)

# With language hint
result = transcriber.transcribe("audio.mp3", language="pt")

# With custom prompt
result = transcriber.transcribe(
    "audio.mp3",
    prompt="Focus on technical terminology"
)

# Async
result = await transcriber.atranscribe("audio.mp3")

Testing

• ✅ 26 comprehensive unit tests with 98% code coverage
• ✅ Validated with real Gemini API using 2.76MB Portuguese podcast audio
• ✅ All tests passing

🔄 OpenRouter Embedding Support

Add OpenRouter as an embedding model provider, enabling access to 60+ embedding providers through OpenRouter's unified API.

Key Features

• Multiple Providers: Access OpenAI, Cohere, Voyage, Jina, and more through one API
• Consistent Interface: Follows Esperanto's patterns for seamless integration
• Dedicated Endpoint: Uses OpenRouter's /embeddings/models endpoint for accurate model discovery
• Full Async Support: Both embed() and aembed() methods
• Environment Variables: Supports OPENROUTER_API_KEY and OPENROUTER_BASE_URL

Usage Example

from esperanto.factory import AIFactory

# Create OpenRouter embedding model
model = AIFactory.create_embedding(
    "openrouter",
    "openai/text-embedding-3-small",
    config={"api_key": "your-api-key"}
)

# Generate embeddings
embeddings = model.embed(["Hello", "World"])

# Async
embeddings = await model.aembed(["Hello", "World"])

Testing

• ✅ 17 comprehensive unit tests with 100% code coverage
• ✅ All 189 embedding provider tests pass
• ✅ Zero regressions in test suite

📝 Documentation Updates

Google STT

• Updated README.md provider support matrix
• Enhanced docs/providers/google.md with complete STT section
• Updated docs/capabilities/speech-to-text.md with Google examples

OpenRouter Embeddings

• Added to factory provider list
• Available via standard create_embedding() interface

🔧 Technical Details

Google STT Implementation

• Provider: GoogleSpeechToTextModel in src/esperanto/providers/stt/google.py (306 lines)
• Tests: 26 unit tests in tests/providers/stt/test_google.py (368 lines)
• Factory Registration: Integrated in AIFactory.create_speech_to_text()

OpenRouter Embeddings Implementation

• Provider: OpenRouterEmbeddingModel in src/esperanto/providers/embedding/openrouter.py (165 lines)
• Tests: 17 unit tests in tests/providers/embedding/test_openrouter_provider.py (336 lines)
• Factory Registration: Integrated in AIFactory.create_embedding()
• Pattern: Inherits from OpenAIEmbeddingModel following the same pattern as OpenRouterLanguageModel

📦 Files Changed

Google STT

• src/esperanto/providers/stt/google.py (new, 306 lines)
• tests/providers/stt/test_google.py (new, 368 lines)
• src/esperanto/factory.py (+1 line)
• README.md (+4/-4 lines)
• docs/providers/google.md (+89 lines)
• docs/capabilities/speech-to-text.md (+27 lines)

OpenRouter Embeddings

• src/esperanto/providers/embedding/openrouter.py (new, 165 lines)
• tests/providers/embedding/test_openrouter_provider.py (new, 336 lines)
• src/esperanto/factory.py (+1 line)

Total Changes: ~1,300 insertions across both features

🔗 Related PRs

• #43 - feat: add Google Speech-to-Text support using Gemini API
• #44 - feat: add OpenRouter embedding provider support

⬆️ Upgrade Instructions

pip install --upgrade esperanto
# or
uv add esperanto@2.9.1

Both features are immediately available after upgrade with no breaking changes.