@polymorphism-tech/morph-spec 8.28.0 → 8.31.0

package/framework/standards/ai-agents/modalities-speech-to-text.md

@@ -1,171 +1,171 @@
-# Modalities — Speech to Text (Audio to Text)
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 2 (on-keyword)
-> **Keywords:** speech to text, transcription, whisper, audio to text, voice transcription
-> **Read by Claude in:** implement (quando o projeto precisa transcrever áudio para texto)
-
-**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.x. Last-verified: 2026-05-19.
-
----
-
-## Quando usar STT
-
-Use quando o input real do usuário é áudio e você precisa de texto para processamento downstream:
-
-- **Transcrição de reuniões:** gravar áudio da reunião → transcrever → alimentar um Status Agent que extrai ações, decisões e responsáveis
-- **Notas de voz:** usuário fala → transcreve → salva como nota textual ou input para outro agente
-- **Suporte por voz:** áudio do cliente → transcreve → agente de roteamento classifica e responde
-
-**Fluxo típico:** `áudio (bytes/arquivo)` → `TranscriptionService` → `texto` → `AIAgent` downstream
-
-Transcrição é uma **chamada de serviço**, não um agente conversacional. Use `AudioClient` diretamente via DI — não crie `AIAgent` para isso.
-
-**Não se aplica** quando o input já é texto. Se o áudio foi transcrito por outra ferramenta, use o texto diretamente.
-
----
-
-## A API
-
-No OpenAI SDK (.NET 2.x), o caminho é `AudioClient.TranscribeAudio`:
-
-```csharp
-using OpenAI.Audio;
-
-AudioClient client = new("whisper-1", apiKey);
-AudioTranscription transcription = await client.TranscribeAudioAsync(audioFilePath);
-string text = transcription.Text;
-```
-
-O projeto injeta `AudioClient` via DI. Para transcrição com timestamps (ex: sincronização de legenda), use `AudioTranscriptionOptions` com `ResponseFormat = AudioTranscriptionFormat.Verbose`.
-
----
-
-## Exemplo C# completo
-
-```csharp
-using OpenAI.Audio;
-using Microsoft.Extensions.Configuration;
-
-public sealed class TranscriptionService
-{
-    private readonly AudioClient _client;
-
-    public TranscriptionService(IConfiguration config)
-    {
-        var model = config["Transcription:Model"] ?? "whisper-1";
-        var apiKey = config["OpenAI:ApiKey"]!;
-        _client = new AudioClient(model, apiKey);
-    }
-
-    /// <summary>
-    /// Transcreve áudio a partir de um arquivo e retorna texto simples.
-    /// O transcript retornado pode ser passado diretamente como input para um AIAgent downstream.
-    /// </summary>
-    public async Task<string> TranscribeAsync(string audioFilePath, CancellationToken ct = default)
-    {
-        AudioTranscription transcription = await _client.TranscribeAudioAsync(audioFilePath, cancellationToken: ct);
-        return transcription.Text;
-    }
-
-    /// <summary>
-    /// Transcreve áudio a partir de bytes (ex: upload do usuário) e retorna texto simples.
-    /// </summary>
-    public async Task<string> TranscribeBytesAsync(
-        Stream audioStream,
-        string fileName,
-        string mediaType = "audio/mpeg",
-        CancellationToken ct = default)
-    {
-        var options = new AudioTranscriptionOptions
-        {
-            ResponseFormat = AudioTranscriptionFormat.Simple
-        };
-
-        AudioTranscription transcription = await _client.TranscribeAudioAsync(
-            audioStream, fileName, options, cancellationToken: ct);
-        return transcription.Text;
-    }
-
-    /// <summary>
-    /// Transcreve com timestamps por palavra e segmento (útil para legendas ou busca por trecho).
-    /// </summary>
-    public async Task<AudioTranscription> TranscribeVerboseAsync(string audioFilePath, CancellationToken ct = default)
-    {
-        var options = new AudioTranscriptionOptions
-        {
-            ResponseFormat         = AudioTranscriptionFormat.Verbose,
-            TimestampGranularities = { AudioTimestampGranularity.Word, AudioTimestampGranularity.Segment }
-        };
-
-        return await _client.TranscribeAudioAsync(audioFilePath, options, cancellationToken: ct);
-    }
-}
-```
-
-**Alimentando um agente downstream com o transcript:**
-
-```csharp
-// O transcript é texto puro — basta passar como input para qualquer AIAgent
-string transcript = await _transcription.TranscribeAsync("meeting-2024-05-19.mp3");
-
-// Ex: Status Agent que extrai ações da reunião
-AgentResponse<MeetingActions> actions = await _statusAgent.RunAsync<MeetingActions>(
-    $"Extraia ações, decisões e responsáveis desta transcrição:\n\n{transcript}");
-```
-
-**Registro DI:**
-
-```csharp
-// Program.cs
-builder.Services.AddSingleton<TranscriptionService>();
-```
-
----
-
-## Formatos e limites
-
-> Valores verificados contra OpenAI Whisper API (2026-05-19). Confirme limites atuais na documentação do provider ao fazer deploy.
-
-| Aspecto | Detalhe |
-|---------|---------|
-| Formatos suportados | `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm` |
-| Limite por request | **25 MB** por arquivo (OpenAI Whisper) |
-| Duração aproximada | ~1h de áudio ≈ 25MB em MP3 128kbps |
-| Áudio longo | Pré-processe client-side: divida em chunks antes de enviar (ffmpeg, NAudio, etc.) — não há API de chunking automático no SDK |
-| Idiomas | Whisper suporta 99 idiomas; especifique `Language = "pt"` em `AudioTranscriptionOptions` para melhor acurácia em português |
-
-**Chunking de áudio longo:** para arquivos acima de 25MB, divida o arquivo em segmentos de ~20MB antes de enviar. Concatene os textos retornados. Não há sobreposição automática — adicione alguns segundos de overlap entre chunks se a precisão nos cortes for crítica.
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Por quê é errado | Jeito certo |
-|--------------|-----------------|-------------|
-| Transcrever quando o input já é texto | Custo e latência desnecessários | Use o texto diretamente como input do agente downstream |
-| Enviar áudio longo (>25MB) sem chunking | O provider rejeita a request com erro 413 | Divida client-side em chunks ≤20MB antes de enviar |
-| Criar `AIAgent` para transcrição | `AudioClient` não é `IChatClient`; o pipeline é simples (bytes → texto) | Injete `TranscriptionService` via DI — é um serviço, não um agente |
-| Ignorar o idioma do áudio | Whisper infere o idioma, mas pode errar em áudios com muita sigla ou sotaque | Especifique `Language` em `AudioTranscriptionOptions` quando o idioma for conhecido |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] `AudioClient` injetado via DI — não instanciado inline
-- [ ] Áudio longo (>25MB) tratado com chunking antes de enviar ao provider
-- [ ] Transcript retornado como `string` e passado como input ao agente downstream — sem re-formatação manual
-- [ ] `Language` especificado em `AudioTranscriptionOptions` quando o idioma do áudio é conhecido
-- [ ] Model e API key vêm de config, não hardcoded
-
----
-
-## References
-
-- `ai-agents-setup` — packages, DI, e providers disponíveis
-- `ai-agents-providers-model-registry` — padrão de alias; adapte para resolver `AudioClient` por provider
-- OpenAI .NET SDK — `AudioClient`: https://github.com/openai/openai-dotnet
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/modalities-speech-to-text.md v1.0 (2026-05-19)*
+# Modalities — Speech to Text (Audio to Text)
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** speech to text, transcription, whisper, audio to text, voice transcription
+> **Read by Claude in:** implement (quando o projeto precisa transcrever áudio para texto)
+
+**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.x. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar STT
+
+Use quando o input real do usuário é áudio e você precisa de texto para processamento downstream:
+
+- **Transcrição de reuniões:** gravar áudio da reunião → transcrever → alimentar um Status Agent que extrai ações, decisões e responsáveis
+- **Notas de voz:** usuário fala → transcreve → salva como nota textual ou input para outro agente
+- **Suporte por voz:** áudio do cliente → transcreve → agente de roteamento classifica e responde
+
+**Fluxo típico:** `áudio (bytes/arquivo)` → `TranscriptionService` → `texto` → `AIAgent` downstream
+
+Transcrição é uma **chamada de serviço**, não um agente conversacional. Use `AudioClient` diretamente via DI — não crie `AIAgent` para isso.
+
+**Não se aplica** quando o input já é texto. Se o áudio foi transcrito por outra ferramenta, use o texto diretamente.
+
+---
+
+## A API
+
+No OpenAI SDK (.NET 2.x), o caminho é `AudioClient.TranscribeAudio`:
+
+```csharp
+using OpenAI.Audio;
+
+AudioClient client = new("whisper-1", apiKey);
+AudioTranscription transcription = await client.TranscribeAudioAsync(audioFilePath);
+string text = transcription.Text;
+```
+
+O projeto injeta `AudioClient` via DI. Para transcrição com timestamps (ex: sincronização de legenda), use `AudioTranscriptionOptions` com `ResponseFormat = AudioTranscriptionFormat.Verbose`.
+
+---
+
+## Exemplo C# completo
+
+```csharp
+using OpenAI.Audio;
+using Microsoft.Extensions.Configuration;
+
+public sealed class TranscriptionService
+{
+    private readonly AudioClient _client;
+
+    public TranscriptionService(IConfiguration config)
+    {
+        var model = config["Transcription:Model"] ?? "whisper-1";
+        var apiKey = config["OpenAI:ApiKey"]!;
+        _client = new AudioClient(model, apiKey);
+    }
+
+    /// <summary>
+    /// Transcreve áudio a partir de um arquivo e retorna texto simples.
+    /// O transcript retornado pode ser passado diretamente como input para um AIAgent downstream.
+    /// </summary>
+    public async Task<string> TranscribeAsync(string audioFilePath, CancellationToken ct = default)
+    {
+        AudioTranscription transcription = await _client.TranscribeAudioAsync(audioFilePath, cancellationToken: ct);
+        return transcription.Text;
+    }
+
+    /// <summary>
+    /// Transcreve áudio a partir de bytes (ex: upload do usuário) e retorna texto simples.
+    /// </summary>
+    public async Task<string> TranscribeBytesAsync(
+        Stream audioStream,
+        string fileName,
+        string mediaType = "audio/mpeg",
+        CancellationToken ct = default)
+    {
+        var options = new AudioTranscriptionOptions
+        {
+            ResponseFormat = AudioTranscriptionFormat.Simple
+        };
+
+        AudioTranscription transcription = await _client.TranscribeAudioAsync(
+            audioStream, fileName, options, cancellationToken: ct);
+        return transcription.Text;
+    }
+
+    /// <summary>
+    /// Transcreve com timestamps por palavra e segmento (útil para legendas ou busca por trecho).
+    /// </summary>
+    public async Task<AudioTranscription> TranscribeVerboseAsync(string audioFilePath, CancellationToken ct = default)
+    {
+        var options = new AudioTranscriptionOptions
+        {
+            ResponseFormat         = AudioTranscriptionFormat.Verbose,
+            TimestampGranularities = { AudioTimestampGranularity.Word, AudioTimestampGranularity.Segment }
+        };
+
+        return await _client.TranscribeAudioAsync(audioFilePath, options, cancellationToken: ct);
+    }
+}
+```
+
+**Alimentando um agente downstream com o transcript:**
+
+```csharp
+// O transcript é texto puro — basta passar como input para qualquer AIAgent
+string transcript = await _transcription.TranscribeAsync("meeting-2024-05-19.mp3");
+
+// Ex: Status Agent que extrai ações da reunião
+AgentResponse<MeetingActions> actions = await _statusAgent.RunAsync<MeetingActions>(
+    $"Extraia ações, decisões e responsáveis desta transcrição:\n\n{transcript}");
+```
+
+**Registro DI:**
+
+```csharp
+// Program.cs
+builder.Services.AddSingleton<TranscriptionService>();
+```
+
+---
+
+## Formatos e limites
+
+> Valores verificados contra OpenAI Whisper API (2026-05-19). Confirme limites atuais na documentação do provider ao fazer deploy.
+
+| Aspecto | Detalhe |
+|---------|---------|
+| Formatos suportados | `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm` |
+| Limite por request | **25 MB** por arquivo (OpenAI Whisper) |
+| Duração aproximada | ~1h de áudio ≈ 25MB em MP3 128kbps |
+| Áudio longo | Pré-processe client-side: divida em chunks antes de enviar (ffmpeg, NAudio, etc.) — não há API de chunking automático no SDK |
+| Idiomas | Whisper suporta 99 idiomas; especifique `Language = "pt"` em `AudioTranscriptionOptions` para melhor acurácia em português |
+
+**Chunking de áudio longo:** para arquivos acima de 25MB, divida o arquivo em segmentos de ~20MB antes de enviar. Concatene os textos retornados. Não há sobreposição automática — adicione alguns segundos de overlap entre chunks se a precisão nos cortes for crítica.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é errado | Jeito certo |
+|--------------|-----------------|-------------|
+| Transcrever quando o input já é texto | Custo e latência desnecessários | Use o texto diretamente como input do agente downstream |
+| Enviar áudio longo (>25MB) sem chunking | O provider rejeita a request com erro 413 | Divida client-side em chunks ≤20MB antes de enviar |
+| Criar `AIAgent` para transcrição | `AudioClient` não é `IChatClient`; o pipeline é simples (bytes → texto) | Injete `TranscriptionService` via DI — é um serviço, não um agente |
+| Ignorar o idioma do áudio | Whisper infere o idioma, mas pode errar em áudios com muita sigla ou sotaque | Especifique `Language` em `AudioTranscriptionOptions` quando o idioma for conhecido |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `AudioClient` injetado via DI — não instanciado inline
+- [ ] Áudio longo (>25MB) tratado com chunking antes de enviar ao provider
+- [ ] Transcript retornado como `string` e passado como input ao agente downstream — sem re-formatação manual
+- [ ] `Language` especificado em `AudioTranscriptionOptions` quando o idioma do áudio é conhecido
+- [ ] Model e API key vêm de config, não hardcoded
+
+---
+
+## References
+
+- `ai-agents-setup` — packages, DI, e providers disponíveis
+- `ai-agents-providers-model-registry` — padrão de alias; adapte para resolver `AudioClient` por provider
+- OpenAI .NET SDK — `AudioClient`: https://github.com/openai/openai-dotnet
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/modalities-speech-to-text.md v1.0 (2026-05-19)*