From 06e0a87a62a6a5bf46ddd7f46a378e5ff86384ef Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 2 Oct 2026 09:31:43 +1000 Subject: [PATCH] feat(messaging): transcribe Telegram voice notes A Telegram voice note was stored as the placeholder "[voice message]" and nothing turned its audio into text, so the agent could not read it. Add a channel-neutral Transcriber capability to the messaging media layer (internal/domain/messaging), an ai-sdk Whisper implementation behind it (internal/infrastructure/transcription), and wire it for Telegram. The capability is config-driven like the other model roles: models.transcription names a provider/model, the matching [providers.*] entry carries the credential (api_key_env or an api_key secret ref), and a missing role, provider, class or credential degrades to today's behaviour with a log -- never an error that fails the turn. A transcribed note replaces its placeholder with "[voice transcription]" followed by the transcript, preserving any caption, so stored history shows the agent it is reading a machine transcript. --- config.example.toml | 5 + internal/app/archiemessaging/compose.go | 1 + internal/app/archiemessaging/config.go | 29 ++++ internal/app/archiemessaging/config_test.go | 64 +++++++ internal/channels/telegram/inboundmedia.go | 21 ++- .../channels/telegram/inboundmedia_test.go | 162 ++++++++++++++++++ internal/channels/telegram/telegram.go | 37 +++- internal/domain/messaging/transcribe.go | 53 ++++++ internal/domain/messaging/transcribe_test.go | 50 ++++++ .../transcription/transcription.go | 150 ++++++++++++++++ .../transcription/transcription_test.go | 156 +++++++++++++++++ 11 files changed, 716 insertions(+), 12 deletions(-) create mode 100644 internal/domain/messaging/transcribe.go create mode 100644 internal/domain/messaging/transcribe_test.go create mode 100644 internal/infrastructure/transcription/transcription.go create mode 100644 internal/infrastructure/transcription/transcription_test.go diff --git a/config.example.toml b/config.example.toml index 45bc3619f..50d2d6a4c 100644 --- a/config.example.toml +++ b/config.example.toml @@ -115,6 +115,11 @@ builder = "openai/gpt-5.4" # (curators first). Unset, or a credential that fails to resolve, degrades # to the capability reporting unavailable -- archied still starts. # embedding = "openai/text-embedding-3-small" +# `transcription` is optional: it turns Telegram voice notes into text before +# the turn is dispatched, behind a "[voice transcription]" marker. Read by +# archie-messaging. Unset, or a provider that does not resolve, leaves the +# voice note as its media placeholder -- the turn still runs. +# transcription = "openai/whisper-1" [providers.openai] class = "openai" diff --git a/internal/app/archiemessaging/compose.go b/internal/app/archiemessaging/compose.go index 8380a6e18..f1681db75 100644 --- a/internal/app/archiemessaging/compose.go +++ b/internal/app/archiemessaging/compose.go @@ -82,6 +82,7 @@ func compose(ctx context.Context, d deps) (*Service, error) { } tg := telegram.New(d.Config.TelegramToken, d.Config.Telegram.AllowedUserIDs, d.Log) tg.Settings = d.Settings + tg.Transcriber = d.Config.Transcriber configureTelegram(ctx, tg, d.Config, d.Chat, d.Log) if err := srv.add("telegram", tg, telegramValidateConfigMap(d.Config.Telegram)); err != nil { return nil, err diff --git a/internal/app/archiemessaging/config.go b/internal/app/archiemessaging/config.go index 1d1883e9e..72f73a5e1 100644 --- a/internal/app/archiemessaging/config.go +++ b/internal/app/archiemessaging/config.go @@ -8,7 +8,9 @@ import ( "os" "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/messaging" "github.com/samcharles93/archie-core/internal/infrastructure/configuration" + "github.com/samcharles93/archie-core/internal/infrastructure/transcription" "github.com/samcharles93/archie-core/internal/secret" ) @@ -30,6 +32,11 @@ type ResolvedConfig struct { BotUser string HealthURL string ShowToolCalls bool + // Transcriber is the optional voice-transcription capability. Nil means it + // is not configured (or its provider did not resolve), and a voice note + // keeps its media note. Constructed from [models].transcription and the + // matching [providers.*] entry. + Transcriber messaging.Transcriber } type projection struct { @@ -43,6 +50,8 @@ type projection struct { botUser string healthURL string showToolCalls bool + models map[string]string + providers map[string]config.Provider } // Resolve loads the configuration, extracts the messaging projection, resolves @@ -92,6 +101,7 @@ func Resolve(o Options, log *slog.Logger) (ResolvedConfig, error) { BotUser: proj.botUser, HealthURL: proj.healthURL, ShowToolCalls: proj.showToolCalls, + Transcriber: setupTranscriber(proj, secrets, log), }, nil } @@ -121,6 +131,8 @@ func project(cfg config.Config) projection { botUser: cfg.BotUser, healthURL: cfg.Health.URL(), showToolCalls: cfg.Chat.ShowToolCalls, + models: cfg.Models, + providers: cfg.Providers, } } @@ -165,3 +177,20 @@ func resolveWebhookSecret(route config.WebhookRoute, secrets *secret.Registry) ( } return "", nil } + +// setupTranscriber builds the optional voice-transcription capability. A +// client is wired only when [models].transcription names a provider/model and +// that provider's credential resolves; a configured-but-unusable role is +// logged so the degradation is visible, while a role that was never +// configured is silent (mirrors archied's setupEmbeddings). +func setupTranscriber(proj projection, secrets *secret.Registry, log *slog.Logger) messaging.Transcriber { + client, ok := transcription.New(proj.models, proj.providers, transcription.Options{ResolveSecret: secrets.Resolve}) + if ok { + log.Info("voice transcription enabled", "role", transcription.Role) + return client + } + if proj.models[transcription.Role] != "" { + log.Warn("voice transcription configured but unavailable; capability disabled", "role", transcription.Role) + } + return nil +} diff --git a/internal/app/archiemessaging/config_test.go b/internal/app/archiemessaging/config_test.go index 11834f5b4..b03c72869 100644 --- a/internal/app/archiemessaging/config_test.go +++ b/internal/app/archiemessaging/config_test.go @@ -72,6 +72,70 @@ allowed_user_ids = [12345] } } +func TestResolveBuildsTranscriberFromModelRole(t *testing.T) { + write := func(t *testing.T, extra string) string { + t.Helper() + tmp := t.TempDir() + path := filepath.Join(tmp, "config.toml") + content := ` +bot_user = "testbot" + +[services.gateway] +target = "127.0.0.1:8999" +` + extra + if err := os.WriteFile(path, []byte(content), 0o600); err != nil { + t.Fatal(err) + } + return path + } + + t.Run("configured role wires a transcriber", func(t *testing.T) { + path := write(t, ` +[models] +transcription = "local/whisper-large-v3" + +[providers.local] +class = "openai-compatible" +base_url = "http://127.0.0.1:8080/v1" +`) + resolved, err := Resolve(Options{Config: path}, slog.Default()) + if err != nil { + t.Fatalf("Resolve: %v", err) + } + if resolved.Transcriber == nil { + t.Error("Transcriber = nil, want a client built from [models].transcription") + } + }) + + t.Run("absent role degrades to nil", func(t *testing.T) { + resolved, err := Resolve(Options{Config: write(t, "")}, slog.Default()) + if err != nil { + t.Fatalf("Resolve: %v", err) + } + if resolved.Transcriber != nil { + t.Errorf("Transcriber = %v, want nil when no role is configured", resolved.Transcriber) + } + }) + + t.Run("configured but unusable role degrades to nil", func(t *testing.T) { + path := write(t, ` +[models] +transcription = "openai/whisper-1" + +[providers.openai] +class = "openai" +api_key_env = "TRANSCRIPTION_TEST_UNSET_KEY" +`) + resolved, err := Resolve(Options{Config: path}, slog.Default()) + if err != nil { + t.Fatalf("Resolve: %v", err) + } + if resolved.Transcriber != nil { + t.Errorf("Transcriber = %v, want nil when the credential is missing", resolved.Transcriber) + } + }) +} + func TestServiceStartAndStop(t *testing.T) { d := deps{ Config: ResolvedConfig{ diff --git a/internal/channels/telegram/inboundmedia.go b/internal/channels/telegram/inboundmedia.go index 51ace7f4c..f6b1b3086 100644 --- a/internal/channels/telegram/inboundmedia.go +++ b/internal/channels/telegram/inboundmedia.go @@ -21,6 +21,9 @@ type inboundMedia struct { // note is a bracketed, self-describing placeholder such as "[photo]" // or "[document: report.pdf]". note string + // transcribe marks audio a configured Transcriber should turn into text + // (a Telegram voice note). False leaves the note as-is. + transcribe bool } // extractInboundMedia maps a Telegram message onto the attachment it @@ -40,42 +43,42 @@ func extractInboundMedia(msg *models.Message) (inboundMedia, bool) { } } } - return inboundMedia{att, "[photo]"}, true + return inboundMedia{attachment: att, note: "[photo]"}, true case msg.Document != nil: - return inboundMedia{messaging.MediaAttachment{ + return inboundMedia{attachment: messaging.MediaAttachment{ Type: "document", FileID: msg.Document.FileID, MIMEType: msg.Document.MimeType, FileName: msg.Document.FileName, FileSize: nilIfZero(msg.Document.FileSize), - }, documentNote(msg.Document.FileName)}, true + }, note: documentNote(msg.Document.FileName)}, true case msg.Video != nil: - return inboundMedia{videoAttachment(msg.Video.FileID, msg.Video.MimeType, nilIfZero(msg.Video.FileSize), &msg.Video.Width, &msg.Video.Height, &msg.Video.Duration), "[video]"}, true + return inboundMedia{attachment: videoAttachment(msg.Video.FileID, msg.Video.MimeType, nilIfZero(msg.Video.FileSize), &msg.Video.Width, &msg.Video.Height, &msg.Video.Duration), note: "[video]"}, true case msg.VideoNote != nil: size := int64(msg.VideoNote.FileSize) - return inboundMedia{videoAttachment(msg.VideoNote.FileID, "video/mp4", nilIfZero(size), nil, nil, &msg.VideoNote.Duration), "[video message]"}, true + return inboundMedia{attachment: videoAttachment(msg.VideoNote.FileID, "video/mp4", nilIfZero(size), nil, nil, &msg.VideoNote.Duration), note: "[video message]"}, true case msg.Audio != nil: - return inboundMedia{messaging.MediaAttachment{ + return inboundMedia{attachment: messaging.MediaAttachment{ Type: "audio", FileID: msg.Audio.FileID, MIMEType: msg.Audio.MimeType, FileName: msg.Audio.FileName, FileSize: nilIfZero(msg.Audio.FileSize), Duration: &msg.Audio.Duration, - }, "[audio]"}, true + }, note: "[audio]"}, true case msg.Voice != nil: - return inboundMedia{messaging.MediaAttachment{ + return inboundMedia{attachment: messaging.MediaAttachment{ Type: "audio", FileID: msg.Voice.FileID, MIMEType: msg.Voice.MimeType, FileSize: nilIfZero(msg.Voice.FileSize), Duration: &msg.Voice.Duration, - }, "[voice message]"}, true + }, note: "[voice message]", transcribe: true}, true } return inboundMedia{}, false } diff --git a/internal/channels/telegram/inboundmedia_test.go b/internal/channels/telegram/inboundmedia_test.go index 51ae49844..2fb4f9026 100644 --- a/internal/channels/telegram/inboundmedia_test.go +++ b/internal/channels/telegram/inboundmedia_test.go @@ -333,6 +333,168 @@ func TestDefaultHandlerSilentForNonContentMessages(t *testing.T) { } } +// fakeTranscriber records the audio it was handed and returns a fixed +// transcript, so a test can assert both that transcription ran on the +// downloaded bytes and what the turn then carried. +type fakeTranscriber struct { + text string + err error + calls int + audio []byte +} + +var _ messaging.Transcriber = (*fakeTranscriber)(nil) + +func (f *fakeTranscriber) Transcribe(_ context.Context, audio []byte) (string, error) { + f.calls++ + f.audio = append([]byte(nil), audio...) + return f.text, f.err +} + +// voiceUpdate is a Telegram voice note from the authorized sender. +func voiceUpdate(fileID string) *models.Message { + return &models.Message{ + ID: 11, + Date: 1, + From: &models.User{ID: 42, Username: "sam"}, + Chat: models.Chat{ID: 7, Type: "private"}, + Voice: &models.Voice{FileID: fileID, MimeType: "audio/ogg", Duration: 8}, + } +} + +// TestDefaultHandlerTranscribesVoiceNoteIntoText drives the behaviour this +// feature exists for: a configured Transcriber turns the downloaded voice +// note into the turn's text, behind a provenance marker so the agent knows +// it is reading a machine transcript. +func TestDefaultHandlerTranscribesVoiceNoteIntoText(t *testing.T) { + voiceBytes := []byte("ogg-voice-bytes") + b, _ := newRecordedAPI(t, func(w http.ResponseWriter, r *http.Request) bool { + if strings.HasPrefix(r.URL.Path, "/file/bot1:test/") { + _, _ = w.Write(voiceBytes) + return true + } + return false + }) + + inboundCh := make(chan messaging.Inbound, 1) + client := &fakeChatContract{ + streamFunc: func(_ context.Context, in messaging.Inbound) (<-chan messaging.ChatEvent, error) { + inboundCh <- in + ch := make(chan messaging.ChatEvent, 1) + ch <- messaging.ChatEvent{Kind: "done", Text: "done", SessionID: "s1"} + close(ch) + return ch, nil + }, + } + transcriber := &fakeTranscriber{text: "turn the lights on"} + g := testMediaGateway(b) + g.Transcriber = transcriber + + g.defaultHandler(client)(context.Background(), b, &models.Update{Message: voiceUpdate("voice1")}) + + select { + case in := <-inboundCh: + want := "[voice transcription]\nturn the lights on" + if in.Message.Text != want { + t.Errorf("Text = %q, want %q", in.Message.Text, want) + } + if len(in.Media) != 1 || in.Media[0].Type != "audio" { + t.Fatalf("inbound media = %#v, want the voice attachment", in.Media) + } + if transcriber.calls != 1 { + t.Fatalf("Transcribe calls = %d, want 1", transcriber.calls) + } + if string(transcriber.audio) != string(voiceBytes) { + t.Errorf("Transcribe received %q, want the downloaded voice bytes", transcriber.audio) + } + case <-time.After(5 * time.Second): + t.Fatal("voice note never reached the chat turn") + } +} + +// TestDefaultHandlerKeepsVoiceNoteWhenTranscriptionUnavailable pins the +// degradation the config contract requires: with no Transcriber the voice +// note still becomes a turn, carrying today's "[voice message]" note rather +// than failing or going silent. +func TestDefaultHandlerKeepsVoiceNoteWhenTranscriptionUnavailable(t *testing.T) { + b, _ := newRecordedAPI(t, func(w http.ResponseWriter, r *http.Request) bool { + if strings.HasPrefix(r.URL.Path, "/file/bot1:test/") { + _, _ = w.Write([]byte("ogg-voice-bytes")) + return true + } + return false + }) + + inboundCh := make(chan messaging.Inbound, 1) + client := &fakeChatContract{ + streamFunc: func(_ context.Context, in messaging.Inbound) (<-chan messaging.ChatEvent, error) { + inboundCh <- in + ch := make(chan messaging.ChatEvent, 1) + ch <- messaging.ChatEvent{Kind: "done", Text: "done", SessionID: "s1"} + close(ch) + return ch, nil + }, + } + g := testMediaGateway(b) // Transcriber left nil on purpose + + g.defaultHandler(client)(context.Background(), b, &models.Update{Message: voiceUpdate("voice1")}) + + select { + case in := <-inboundCh: + if in.Message.Text != "[voice message]" { + t.Errorf("Text = %q, want the media note preserved", in.Message.Text) + } + case <-time.After(5 * time.Second): + t.Fatal("voice note was dropped when transcription was unavailable") + } +} + +// TestDefaultHandlerDoesNotTranscribePlainAudio keeps the flag scoped to +// voice notes: a forwarded music file must not spend a transcription call. +func TestDefaultHandlerDoesNotTranscribePlainAudio(t *testing.T) { + b, _ := newRecordedAPI(t, func(w http.ResponseWriter, r *http.Request) bool { + if strings.HasPrefix(r.URL.Path, "/file/bot1:test/") { + _, _ = w.Write([]byte("mp3-bytes")) + return true + } + return false + }) + + inboundCh := make(chan messaging.Inbound, 1) + client := &fakeChatContract{ + streamFunc: func(_ context.Context, in messaging.Inbound) (<-chan messaging.ChatEvent, error) { + inboundCh <- in + ch := make(chan messaging.ChatEvent, 1) + ch <- messaging.ChatEvent{Kind: "done", Text: "done", SessionID: "s1"} + close(ch) + return ch, nil + }, + } + transcriber := &fakeTranscriber{text: "should not be used"} + g := testMediaGateway(b) + g.Transcriber = transcriber + + g.defaultHandler(client)(context.Background(), b, &models.Update{Message: &models.Message{ + ID: 12, + Date: 1, + From: &models.User{ID: 42, Username: "sam"}, + Chat: models.Chat{ID: 7, Type: "private"}, + Audio: &models.Audio{FileID: "aud1", FileName: "song.mp3", MimeType: "audio/mpeg", Duration: 200}, + }}) + + select { + case in := <-inboundCh: + if in.Message.Text != "[audio]" { + t.Errorf("Text = %q, want the plain audio note", in.Message.Text) + } + if transcriber.calls != 0 { + t.Errorf("Transcribe calls = %d, want 0 for non-voice audio", transcriber.calls) + } + case <-time.After(5 * time.Second): + t.Fatal("audio update never reached the chat turn") + } +} + // TestDownloadMediaCoversSuccessAndLimits exercises the download the turn // relies on: the Bot API getFile lookup, the file fetch, and the size gate. func TestDownloadMediaCoversSuccessAndLimits(t *testing.T) { diff --git a/internal/channels/telegram/telegram.go b/internal/channels/telegram/telegram.go index 12a21d381..575ace7ad 100644 --- a/internal/channels/telegram/telegram.go +++ b/internal/channels/telegram/telegram.go @@ -50,6 +50,12 @@ type Gateway struct { Updates UpdateService // Settings executes control-plane commands in this authenticated adapter. Settings *messaging.SettingsCommand + // Transcriber turns voice notes into text before their turn is dispatched. + // Nil means the capability is not configured (or its provider did not + // resolve): a voice note then keeps its "[voice message]" note, exactly + // the behaviour before transcription existed. The composition root owns + // construction, so this adapter never holds a provider credential itself. + Transcriber messaging.Transcriber // ResolveActor maps a channel-native sender to an authenticated Archie // identity. Nil deliberately permits reads but makes writes fail closed. ResolveActor func(int64) (string, bool) @@ -614,8 +620,9 @@ func (g *Gateway) handleCallback(ctx context.Context, b *bot.Bot, update *models // turnInbound renders a Telegram message as the channel-neutral inbound a // chat turn is built from, with media attachments attached. ok is false // for messages with neither text nor media, which are not turns at all. -func turnInbound(msg *models.Message) (messaging.Inbound, bool) { - media, hasMedia := extractInboundMedia(msg) +// media/hasMedia are the caller's already-extracted attachment, so the +// caller keeps the voice-note flag it needs without extracting twice. +func turnInbound(msg *models.Message, media inboundMedia, hasMedia bool) (messaging.Inbound, bool) { if !hasMedia && msg.Text == "" { return messaging.Inbound{}, false } @@ -643,10 +650,12 @@ func turnInbound(msg *models.Message) (messaging.Inbound, bool) { } func (g *Gateway) submitTurn(ctx context.Context, b *bot.Bot, msg *models.Message, client messaging.ChatContract) { - gm, isTurn := turnInbound(msg) + media, hasMedia := extractInboundMedia(msg) + gm, isTurn := turnInbound(msg, media, hasMedia) if !isTurn { return } + transcribeVoice := hasMedia && media.transcribe // The lane key must be the session, so that /stop -- which resolves // the same key -- reaches the turn the sender is actually watching. @@ -656,6 +665,7 @@ func (g *Gateway) submitTurn(ctx context.Context, b *bot.Bot, msg *models.Messag if !g.fetchTurnMedia(turnCtx, b, &gm, chatID, threadID) { return } + g.transcribeVoiceNote(turnCtx, &gm, msg.Caption, transcribeVoice) // If the turn invokes a tool that requires human approval, // the dispatch layer blocks on this approver. Nil is fine @@ -766,6 +776,27 @@ func (g *Gateway) fetchTurnMedia(ctx context.Context, b *bot.Bot, gm *messaging. return true } +// transcribeVoiceNote replaces a voice note's stored placeholder with the +// transcript, so the agent reads what was said rather than "[voice message]". +// It degrades: a nil Transcriber, an error, or an empty transcript leaves the +// placeholder in place -- a turn must never fail because transcription was +// unavailable. +func (g *Gateway) transcribeVoiceNote(ctx context.Context, gm *messaging.Inbound, caption string, wanted bool) { + if !wanted || g.Transcriber == nil || len(gm.Media) == 0 { + return + } + transcript, err := g.Transcriber.Transcribe(ctx, gm.Media[0].Data) + if err != nil { + g.log.Warn("voice transcription failed; keeping the media note", "error", err) + return + } + if strings.TrimSpace(transcript) == "" { + g.log.Info("voice transcription produced no text; keeping the media note") + return + } + gm.Message.Text = messaging.TranscribedText(transcript, caption) +} + // ── helpers ────────────────────────────────────────────────────── // conversationID addresses the chat a Telegram message arrived in: the diff --git a/internal/domain/messaging/transcribe.go b/internal/domain/messaging/transcribe.go new file mode 100644 index 000000000..aa95b78ad --- /dev/null +++ b/internal/domain/messaging/transcribe.go @@ -0,0 +1,53 @@ +package messaging + +import ( + "context" + "errors" + "strings" +) + +// ErrTranscriptionUnavailable reports that the transcription capability +// cannot serve right now: no role configured, an unknown or unsupported +// provider, or a credential that could not be resolved. Infrastructure +// implementations wrap it so a caller can degrade -- keep the media note -- +// instead of failing the turn. +var ErrTranscriptionUnavailable = errors.New("transcription capability unavailable") + +// Transcriber turns recorded audio into text. It is a channel-neutral, +// call-scoped capability: the messaging media layer defines what a +// transcription is, and each frontend supplies the bytes its platform +// produced. Implementations live in internal/infrastructure/transcription; +// the domain never imports one. +// +// The same shape as image.Provider and embedding.Client: no Lifecycle, +// because "can the capability serve right now" is exactly what a returned +// error already communicates, and a missing capability must degrade rather +// than fail the turn it arrived on. +type Transcriber interface { + // Transcribe returns the transcript of audio, which must be non-empty. + // A failure is an error, never a panic; any error means the caller keeps + // the media note rather than failing the turn. + Transcribe(ctx context.Context, audio []byte) (string, error) +} + +// TranscriptionProvenance prefixes text a Transcriber produced. Stored +// history is text-only, so without this marker a later reader (the model in +// a following turn, the dashboard transcript) cannot tell a machine +// transcript from something the sender typed. +const TranscriptionProvenance = "[voice transcription]" + +// TranscribedText renders a transcript as the text an inbound voice note +// contributes to the turn, keeping any caption the sender attached after the +// transcript. An empty transcript still yields the provenance marker, so the +// agent knows audio arrived rather than silently treating the message as +// empty. +func TranscribedText(transcript, caption string) string { + parts := []string{TranscriptionProvenance} + if t := strings.TrimSpace(transcript); t != "" { + parts = append(parts, t) + } + if c := strings.TrimSpace(caption); c != "" { + parts = append(parts, c) + } + return strings.Join(parts, "\n") +} diff --git a/internal/domain/messaging/transcribe_test.go b/internal/domain/messaging/transcribe_test.go new file mode 100644 index 000000000..7978e23f6 --- /dev/null +++ b/internal/domain/messaging/transcribe_test.go @@ -0,0 +1,50 @@ +package messaging + +import "testing" + +// TestTranscribedTextMarksProvenanceAndKeepsCaption pins the stored shape of +// a transcribed voice note: history is text-only and the original bytes are +// gone, so the marker is the only thing that tells a later reader the words +// came from a machine transcript, and the sender's caption must survive it. +func TestTranscribedTextMarksProvenanceAndKeepsCaption(t *testing.T) { + cases := []struct { + name string + transcript string + caption string + want string + }{ + { + name: "transcript alone carries the marker", + transcript: "hello there", + want: "[voice transcription]\nhello there", + }, + { + name: "surrounding whitespace is trimmed", + transcript: " spaced ", + want: "[voice transcription]\nspaced", + }, + { + name: "caption follows the transcript", + transcript: "what time is it", + caption: "ignore the background noise", + want: "[voice transcription]\nwhat time is it\nignore the background noise", + }, + { + name: "caption without a transcript keeps its own line", + caption: "sent by mistake", + want: "[voice transcription]\nsent by mistake", + }, + { + name: "empty transcript still marks provenance", + transcript: " ", + want: "[voice transcription]", + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := TranscribedText(tc.transcript, tc.caption); got != tc.want { + t.Errorf("TranscribedText(%q, %q) = %q, want %q", tc.transcript, tc.caption, got, tc.want) + } + }) + } +} diff --git a/internal/infrastructure/transcription/transcription.go b/internal/infrastructure/transcription/transcription.go new file mode 100644 index 000000000..83dcb0116 --- /dev/null +++ b/internal/infrastructure/transcription/transcription.go @@ -0,0 +1,150 @@ +// Package transcription implements the internal/domain/messaging.Transcriber +// contract over the ai-sdk provider SDKs already vendored for chat, so voice +// notes are transcribed through the same providers table and model-role +// convention chat models and the embedding capability already use. +package transcription + +import ( + "context" + "fmt" + "net/http" + "os" + "strings" + "time" + + "github.com/samcharles93/ai-sdk/provider/groq" + "github.com/samcharles93/ai-sdk/provider/openai" + sdktranscribe "github.com/samcharles93/ai-sdk/transcribe" + + "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/messaging" +) + +// Role is the [models] key transcription consumers use, matching the +// "builder"/"planner"/"triage" role convention chat models and the +// embedding capability already use. +const Role = "transcription" + +// DefaultTimeout bounds one transcription request when Options.Timeout is +// unset. It is generous relative to a chat request because transcription +// uploads the whole audio file before the provider answers. +const DefaultTimeout = 60 * time.Second + +// Options configures New. +type Options struct { + // Getenv resolves a provider's APIKeyEnv to its credential. Defaults to + // os.Getenv; overridable for tests. + Getenv func(string) string + // ResolveSecret resolves a provider's api_key secret reference. Nil means + // secret references cannot be resolved, so such a provider degrades. + ResolveSecret func(config.SecretRef) (string, error) + // Timeout bounds one transcription request. Defaults to DefaultTimeout. + Timeout time.Duration +} + +// New builds a transcription client from models[Role] and the matching +// providers entry. It reports (nil, false) rather than an error when the +// capability is not usable right now -- no role configured, an unknown +// provider, an unsupported provider class, or a missing/blank credential -- +// per the credential-missing-degrades-not-fatal rule (AGENTS.md): callers +// keep the media note, never fail the turn or daemon startup, over this. +func New(models map[string]string, providers map[string]config.Provider, opts Options) (messaging.Transcriber, bool) { + getenv := opts.Getenv + if getenv == nil { + getenv = os.Getenv + } + timeout := opts.Timeout + if timeout <= 0 { + timeout = DefaultTimeout + } + + providerID, modelID, ok := parseModelRef(models[Role]) + if !ok { + return nil, false + } + provider, ok := providers[providerID] + if !ok { + return nil, false + } + apiKey, ok := resolveCredential(provider, getenv, opts.ResolveSecret) + if !ok { + return nil, false + } + sdkProvider, err := newSDKProvider(provider.Class, apiKey, provider.BaseURL, &http.Client{Timeout: timeout}) + if err != nil { + return nil, false + } + return &client{client: sdktranscribe.NewClient(sdkProvider), model: modelID}, true +} + +// resolveCredential returns the provider's key and whether the provider may +// be used. A provider that names neither an env var nor a secret reference is +// permitted with an empty key: a self-hosted OpenAI-compatible backend is +// unauthenticated, and the provider constructor rejects an empty key for the +// hosted classes that require one. +func resolveCredential(provider config.Provider, getenv func(string) string, resolveSecret func(config.SecretRef) (string, error)) (string, bool) { + switch { + case provider.APIKeyEnv != "": + key := strings.TrimSpace(getenv(provider.APIKeyEnv)) + return key, key != "" + case provider.APIKey != (config.SecretRef{}): + if resolveSecret == nil { + return "", false + } + key, err := resolveSecret(provider.APIKey) + if err != nil { + return "", false + } + key = strings.TrimSpace(key) + return key, key != "" + default: + return "", true + } +} + +// parseModelRef splits a "provider/model" role value without depending on an +// ai-sdk Runtime instance (mirrors internal/infrastructure/embedding). +func parseModelRef(ref string) (providerID, modelID string, ok bool) { + ref = strings.TrimSpace(ref) + if ref == "" { + return "", "", false + } + providerID, modelID, hasSlash := strings.Cut(ref, "/") + providerID, modelID = strings.TrimSpace(providerID), strings.TrimSpace(modelID) + if !hasSlash || providerID == "" || modelID == "" { + return "", "", false + } + return providerID, modelID, true +} + +// newSDKProvider constructs the ai-sdk transcribe.Provider for a config class. +// Only classes that speak the Whisper-compatible /audio/transcriptions +// endpoint are supported; any other class degrades like a missing role rather +// than gaining a special-cased partial wiring. +func newSDKProvider(class, apiKey, baseURL string, httpClient *http.Client) (sdktranscribe.Provider, error) { + switch class { + case "openai", "openai-compatible": + return openai.New(openai.Config{APIKey: apiKey, BaseURL: baseURL, HTTPClient: httpClient}) + case "groq": + return groq.New(groq.Config{APIKey: apiKey, BaseURL: baseURL, HTTPClient: httpClient}) + default: + return nil, fmt.Errorf("transcription: provider class %q does not support transcription", class) + } +} + +// client adapts an ai-sdk transcribe.Client to messaging.Transcriber. +type client struct { + client *sdktranscribe.Client + model string +} + +func (c *client) Transcribe(ctx context.Context, audio []byte) (string, error) { + if len(audio) == 0 { + return "", fmt.Errorf("%w: no audio to transcribe", messaging.ErrTranscriptionUnavailable) + } + resp, err := c.client.Transcribe(ctx, sdktranscribe.TranscribeRequest{Model: c.model, Audio: audio}) + if err != nil { + return "", fmt.Errorf("%w: %w", messaging.ErrTranscriptionUnavailable, err) + } + return strings.TrimSpace(resp.Text), nil +} diff --git a/internal/infrastructure/transcription/transcription_test.go b/internal/infrastructure/transcription/transcription_test.go new file mode 100644 index 000000000..bbcdca5a0 --- /dev/null +++ b/internal/infrastructure/transcription/transcription_test.go @@ -0,0 +1,156 @@ +package transcription + +import ( + "context" + "errors" + "io" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/messaging" +) + +// TestNewDegradesRatherThanErroring pins the credential-missing-degrades +// contract: every reason the capability cannot serve right now yields +// (nil, false), so the channel keeps the media note instead of failing. +func TestNewDegradesRatherThanErroring(t *testing.T) { + configured := config.Provider{Class: "openai", APIKeyEnv: "TRANSCRIPTION_TEST_KEY"} + cases := []struct { + name string + models map[string]string + providers map[string]config.Provider + env map[string]string + }{ + { + name: "no role configured", + providers: map[string]config.Provider{"openai": configured}, + }, + { + name: "role names a provider that is not configured", + models: map[string]string{Role: "openai/whisper-1"}, + }, + { + name: "role is not a provider/model ref", + models: map[string]string{Role: "whisper-1"}, + }, + { + name: "provider class does not support transcription", + models: map[string]string{Role: "anthropic/whisper-1"}, + providers: map[string]config.Provider{"anthropic": {Class: "anthropic", APIKeyEnv: "TRANSCRIPTION_TEST_KEY"}}, + env: map[string]string{"TRANSCRIPTION_TEST_KEY": "secret"}, + }, + { + name: "credential env var is unset", + models: map[string]string{Role: "openai/whisper-1"}, + providers: map[string]config.Provider{"openai": configured}, + }, + { + name: "credential env var resolves empty", + models: map[string]string{Role: "openai/whisper-1"}, + providers: map[string]config.Provider{"openai": configured}, + env: map[string]string{"TRANSCRIPTION_TEST_KEY": " "}, + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + client, ok := New(tc.models, tc.providers, Options{ + Getenv: func(k string) string { return tc.env[k] }, + }) + if ok || client != nil { + t.Fatalf("New() = (%v, %v), want (nil, false)", client, ok) + } + }) + } +} + +// TestNewResolvesSecretReference proves the api_key path a `[providers.*]` +// entry written with a secret engine takes is wired, not silently ignored +// in favour of api_key_env only. +func TestNewResolvesSecretReference(t *testing.T) { + provider := config.Provider{Class: "openai", APIKey: config.SecretRef{Engine: "bws", Key: "OPENAI"}} + client, ok := New( + map[string]string{Role: "openai/whisper-1"}, + map[string]config.Provider{"openai": provider}, + Options{ResolveSecret: func(ref config.SecretRef) (string, error) { + if ref.Key != "OPENAI" { + t.Fatalf("ResolveSecret ref = %#v, want the provider's reference", ref) + } + return "from-engine", nil + }}, + ) + if !ok || client == nil { + t.Fatal("New() with a resolvable secret reference = (nil, false), want a client") + } + + // An unresolvable reference degrades instead of returning a broken client. + if c, ok := New( + map[string]string{Role: "openai/whisper-1"}, + map[string]config.Provider{"openai": provider}, + Options{ResolveSecret: func(config.SecretRef) (string, error) { return "", errors.New("no secret") }}, + ); ok || c != nil { + t.Fatalf("New() with an unresolvable reference = (%v, %v), want (nil, false)", c, ok) + } +} + +// TestTranscribeCallsTheWhisperEndpoint proves the adapter actually sends +// the audio and returns the provider's text, against a fake +// Whisper-compatible server (a local OpenAI-compatible backend needs no +// credential, which is what a self-hosted Ollama-style server looks like). +func TestTranscribeCallsTheWhisperEndpoint(t *testing.T) { + var gotModel, gotAudio string + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path != "/v1/audio/transcriptions" { + t.Errorf("request path = %q, want /v1/audio/transcriptions", r.URL.Path) + } + gotModel = r.FormValue("model") + if file, _, err := r.FormFile("file"); err == nil { + defer file.Close() + data, _ := io.ReadAll(file) + gotAudio = string(data) + } + _, _ = w.Write([]byte(`{"text":" turn on the lights "}`)) + })) + t.Cleanup(srv.Close) + + client, ok := New( + map[string]string{Role: "local/whisper-large-v3"}, + map[string]config.Provider{"local": {Class: "openai-compatible", BaseURL: srv.URL + "/v1"}}, + Options{}, + ) + if !ok { + t.Fatal("New() with a local openai-compatible provider degraded, want a client") + } + + text, err := client.Transcribe(context.Background(), []byte("OggS\x00fake-audio")) + if err != nil { + t.Fatalf("Transcribe() error = %v", err) + } + if text != "turn on the lights" { + t.Errorf("Transcribe() = %q, want the trimmed provider text", text) + } + if gotModel != "whisper-large-v3" { + t.Errorf("model field = %q, want the model from the role ref", gotModel) + } + if !strings.Contains(gotAudio, "fake-audio") { + t.Errorf("file field = %q, want the audio bytes", gotAudio) + } +} + +// TestTranscribeRejectsEmptyAudio proves the contract's non-empty-audio +// requirement is enforced with the typed sentinel, not a provider error. +func TestTranscribeRejectsEmptyAudio(t *testing.T) { + client, ok := New( + map[string]string{Role: "local/whisper-large-v3"}, + map[string]config.Provider{"local": {Class: "openai-compatible", BaseURL: "http://127.0.0.1:1/v1"}}, + Options{}, + ) + if !ok { + t.Fatal("New() degraded for a local openai-compatible provider") + } + if _, err := client.Transcribe(context.Background(), nil); !errors.Is(err, messaging.ErrTranscriptionUnavailable) { + t.Fatalf("Transcribe(nil) error = %v, want ErrTranscriptionUnavailable", err) + } +}