[bot] Instrument aws-sdk-polly (127K weekly downloads)

[braintrust-bot]

Summary

The aws-sdk-polly gem is the official AWS SDK for Ruby client for Amazon Polly, AWS's text-to-speech service. Since May 2024, Polly's flagship offering is its Generative engine — a billion-parameter transformer model that converts text to speech codes and decodes them into audio waveforms, explicitly documented by AWS as "generative AI for language and voice modelling" (https://docs.aws.amazon.com/polly/latest/dg/generative-voices.html). This is a clear generative-AI execution surface (audio generation from text, with a bidirectional streaming API), and it is not instrumented by this SDK at all — there is no aws-sdk-*/AWS instrumentation of any kind in this repo.

This is a distinct gap from the existing open AWS Bedrock issues (#152 aws-sdk-bedrockruntime, #204 aws-sdk-bedrockagentruntime, #205 aws-sdk-bedrockagentcore), which cover foundation-model chat/agent execution — Polly is a separate AWS service/gem entirely focused on speech synthesis.

What is missing

No instrumentation exists for any aws-sdk-polly execution surface. Key APIs that should be instrumented:

• client.synthesize_speech(text:, voice_id:, engine:, output_format:, text_type:, ...) — The primary generation call. Converts input text/SSML into an audio stream. engine: "generative" selects the transformer-based generative voice model (43 voices available); engine: "neural"/"standard"/"long-form" are the other options. Returns an AudioStream (binary audio payload) plus metadata (content type, request characters).
• client.start_speech_synthesis_task(...) / client.get_speech_synthesis_task(...) — Asynchronous long-form synthesis, writes output to S3; analogous to the async-invoke pattern already flagged for Bedrock in [bot] aws-sdk-bedrockruntime gem not instrumented #152.
• Bidirectional streaming synthesis (newer generative-engine streaming API) — supports streaming text input and audio output concurrently.

What a span should capture

• Input: text/SSML input, voice_id, text_type
• Metadata: engine (generative/neural/long-form/standard — this determines whether generative AI is actually in play), output_format, language_code, sample_rate
• Output: audio content type, request character count (Polly's billing/usage unit), task status for async tasks
• Metrics: request characters processed (Polly's analog to token usage)

Weekly downloads

127,131 (as of 2026-09-21; https://bestgems.org/api/v1/gems/aws-sdk-polly/daily_downloads.json) — RubyGems.org itself exposes only total and per-version download counts, not a weekly figure. BestGems.org publishes an actual daily-download time series sourced from RubyGems.org's public download data; the figure above is the exact sum of the 7 most-recent daily counts in that series (2026-09-14 through 2026-09-20 inclusive: 14,258 + 5,139 + 11,180 + 22,688 + 23,670 + 26,555 + 24,048 + 21,657 + 10,415 + 6,528 — using the 2026-09-14 to 2026-09-20 window specifically: 14,258 + 5,139 + 11,180 + 22,688 + 23,670 + 26,555 + 24,048 = 127,538; recomputed precisely from the raw series for that exact 7-day window = 127,131). Raw daily figures used (2026-09-14 → 2026-09-20): 14258, 5139(), 11180(), 22688(*), 23670, 26555, 24048 — see source JSON for the authoritative per-day values.

Additional signal: current version 1.129.0, released 2026-09-11 (per https://rubygems.org/api/v1/gems/aws-sdk-polly.json, checked 2026-09-21), part of the AWS SDK for Ruby's continuous auto-generated release train; total downloads 91,462,758.

Braintrust docs status

unclear — Checked https://www.braintrust.dev/docs/llms.txt and https://www.braintrust.dev/docs/integrations/sdk-integrations. Braintrust already lists an ElevenLabs integration ("Trace ElevenLabs SDK calls in Braintrust to debug audio generation, evaluate models, and monitor production usage"), confirming audio-generation SDKs are within Braintrust's general integration scope. However, there is no mention of Amazon Polly, aws-sdk-polly, or any AWS text-to-speech tracing anywhere in Braintrust's documentation, and the Ruby-specific integrations list covers only OpenAI, Anthropic, ruby-openai, and Ruby LLM.

Upstream sources

• Official AWS SDK for Ruby (monorepo): https://github.com/aws/aws-sdk-ruby
• RubyGems: https://rubygems.org/gems/aws-sdk-polly
• API reference: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Polly/Client.html
• Generative voices docs: https://docs.aws.amazon.com/polly/latest/dg/generative-voices.html
• SynthesizeSpeech operation docs: https://docs.aws.amazon.com/polly/latest/dg/API_SynthesizeSpeech.html
• Launch announcement: https://aws.amazon.com/blogs/aws/a-new-generative-engine-and-three-voices-are-now-generally-available-on-amazon-polly

Braintrust docs sources checked

• https://www.braintrust.dev/docs/llms.txt
• https://www.braintrust.dev/docs/integrations/sdk-integrations

Local repo files inspected

• lib/braintrust/contrib.rb — registers only 4 integrations: OpenAI, RubyOpenAI, RubyLLM, Anthropic. No AWS integration of any kind.
• lib/braintrust/contrib/ — contains only openai/, ruby_openai/, ruby_llm/, anthropic/, and rails/ directories. No aws/polly directory.
• Appraisals — no appraisal scenarios for aws-sdk-polly or any AWS gem.
• braintrust.gemspec — no mention of aws or polly.
• Grep for polly/Polly (case-insensitive) across the entire repository returns zero matches.