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:
1 parent
1d2fcec69e
commit
06e0a87a62
11 files changed
+716
-12
No files matched your search
@@ -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"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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{
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user