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.
This commit is contained in:
sam committed 2026-10-02 09:36:48 +10:00
1 parent aab9e10edd
commit df3eb523ec
11 files changed
+716 -12

No files matched your search

+5
View File
@@ -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"
+1
View File
@@ -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
+29
View File
@@ -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
}
@@ -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{
+12 -9
View File
@@ -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
}
@@ -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) {
+34 -3
View File
@@ -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
+53
View File
@@ -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")
}
@@ -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)
}
})
}
}
@@ -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
}
@@ -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)
}
}