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

Start with lib/braintrust/contrib.rb and the existing lib/braintrust/contrib/ integration directories, then review the AWS Polly Client operation docs for the listed synthesis APIs. Check Appraisals and braintrust.gemspec for dependency and appraisal conventions. Done means Polly tracing is integrated for the identified execution surfaces, with captured inputs, metadata, outputs, and usage metrics documented and covered by the project’s validation conventions.

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 #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.