feat(ai): add transcription support (#1470)

* feat(ai): add transcription support

* fix(ai): address transcription review comments

* fix(ai): remove unused transcription test field

* fix(ai): reject typed nil transcription files

* optimize

* fix(ai): restore image.Of and add FromStorage test coverage

Agent-Logs-Url: https://github.com/goravel/framework/sessions/fd686dee-9139-4d5c-9ad1-2922227e7dd6

Co-authored-by: hwbrzzl <24771476+hwbrzzl@users.noreply.github.com>

* optimize

* optimize

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: hwbrzzl <24771476+hwbrzzl@users.noreply.github.com>

Author: hwbrzzl

ai/application.go

@@ -44,6 +44,10 @@ func (r *Application) Image(prompt string) contractsai.ImageRequest {
 	return NewImageRequest(r.ctx, r, prompt)
 }
 
+func (r *Application) Transcription(file contractsai.StorableFile) contractsai.TranscriptionRequest {
+	return NewTranscriptionRequest(r.ctx, r, file)
+}
+
 func (r *Application) putFile(ctx context.Context, file contractsai.StorableFile, options ...contractsai.Option) (contractsai.FileResponse, error) {
 	_, providerName, provider, err := r.resolveProvider(options)
 	if err != nil {
@@ -128,6 +132,23 @@ func (r *Application) image(ctx context.Context, prompt contractsai.ImagePrompt,
 	return imageProvider.Image(ctx, prompt)
 }
 
+func (r *Application) transcription(ctx context.Context, prompt contractsai.TranscriptionPrompt, options ...contractsai.Option) (contractsai.TranscriptionResponse, error) {
+	opts, providerName, provider, err := r.resolveProvider(options)
+	if err != nil {
+		return nil, err
+	}
+	if prompt.Model == "" {
+		prompt.Model = opts.Model
+	}
+
+	transcriptionProvider, ok := provider.(contractsai.TranscriptionProvider)
+	if !ok {
+		return nil, errors.AIProviderDoesNotSupportTranscription.Args(providerName)
+	}
+
+	return transcriptionProvider.Transcription(ctx, prompt)
+}
+
 func (r *Application) resolveProvider(options []contractsai.Option) (*contractsai.Options, string, contractsai.Provider, error) {
 	opts := &contractsai.Options{}
 	for _, option := range options {

ai/application_test.go

@@ -478,12 +478,72 @@ func TestApplication_Audio(t *testing.T) {
 	assert.Equal(t, "welcome to goravel", req.prompt)
 	assert.Equal(t, "default", req.provider)
 	assert.Equal(t, "gpt-4o-mini-tts", req.model)
-	assert.Equal(t, defaultMaleVoice, req.voice)
+	assert.Equal(t, DefaultMaleVoice, req.voice)
 	assert.Equal(t, "Speak slowly", req.instructions)
 	assert.Equal(t, 2*time.Second, req.timeout)
 
 	assert.Same(t, req, request.Female())
-	assert.Equal(t, defaultFemaleVoice, req.voice)
+	assert.Equal(t, DefaultFemaleVoice, req.voice)
+}
+
+func TestApplication_Transcription(t *testing.T) {
+	ctx := context.Background()
+	config := contractsai.Config{
+		Default: "default",
+		Providers: map[string]contractsai.ProviderConfig{
+			"default": {Via: mocksai.NewProvider(t)},
+		},
+	}
+	file := mocksai.NewStorableFile(t)
+
+	app := NewApplication(ctx, config)
+	request := app.Transcription(file).Provider("default").Model("gpt-4o-mini-transcribe").Language("en").Diarize().Timeout(2 * time.Second)
+
+	req, ok := request.(*transcriptionRequest)
+	assert.True(t, ok)
+	assert.Equal(t, ctx, req.ctx)
+	assert.Equal(t, app, req.app)
+	assert.Equal(t, file, req.file)
+	assert.Equal(t, "default", req.provider)
+	assert.Equal(t, "gpt-4o-mini-transcribe", req.model)
+	assert.Equal(t, "en", req.language)
+	assert.True(t, req.diarize)
+	assert.Equal(t, 2*time.Second, req.timeout)
+}
+
+func TestTranscriptionRequest_Generate(t *testing.T) {
+	ctx := context.Background()
+	provider := &applicationTranscriptionProviderStub{}
+	config := contractsai.Config{
+		Default: "default",
+		Providers: map[string]contractsai.ProviderConfig{
+			"default": {Via: provider},
+		},
+	}
+	file := mocksai.NewStorableFile(t)
+
+	app := NewApplication(context.Background(), config)
+	response := &applicationTranscriptionResponseStub{}
+	provider.response = response
+
+	result, err := app.Transcription(file).
+		Provider("default").
+		Model("gpt-4o-mini-transcribe").
+		Language("en").
+		Diarize().
+		Timeout(3 * time.Second).
+		Generate()
+
+	require.NoError(t, err)
+	assert.Equal(t, response, result)
+	assert.Equal(t, ctx, provider.ctx)
+	assert.Equal(t, contractsai.TranscriptionPrompt{
+		File:     file,
+		Model:    "gpt-4o-mini-transcribe",
+		Language: "en",
+		Diarize:  true,
+		Timeout:  3 * time.Second,
+	}, provider.prompt)
 }
 
 func TestAudioRequest_Generate(t *testing.T) {
@@ -514,7 +574,7 @@ func TestAudioRequest_Generate(t *testing.T) {
 	assert.Equal(t, contractsai.AudioPrompt{
 		Prompt:       "welcome to goravel",
 		Model:        "gpt-4o-mini-tts",
-		Voice:        defaultMaleVoice,
+		Voice:        DefaultMaleVoice,
 		Instructions: "Speak slowly",
 		Timeout:      3 * time.Second,
 	}, provider.prompt)
@@ -554,7 +614,7 @@ func TestApplication_audio(t *testing.T) {
 			options: []contractsai.Option{WithProvider("openai")},
 			prompt: contractsai.AudioPrompt{
 				Prompt: "welcome to goravel",
-				Voice:  defaultFemaleVoice,
+				Voice:  DefaultFemaleVoice,
 			},
 			setup: func() contractsai.Config {
 				provider := &applicationAudioProviderStub{}
@@ -569,7 +629,7 @@ func TestApplication_audio(t *testing.T) {
 			},
 			expectPrompt: contractsai.AudioPrompt{
 				Prompt: "welcome to goravel",
-				Voice:  defaultFemaleVoice,
+				Voice:  DefaultFemaleVoice,
 			},
 		},
 		{
@@ -607,6 +667,70 @@ func TestApplication_audio(t *testing.T) {
 	}
 }
 
+func TestApplication_transcription(t *testing.T) {
+	file := mocksai.NewStorableFile(t)
+	tests := []struct {
+		name         string
+		options      []contractsai.Option
+		prompt       contractsai.TranscriptionPrompt
+		setup        func() contractsai.Config
+		expectError  error
+		expectPrompt contractsai.TranscriptionPrompt
+	}{
+		{
+			name:    "success with default model",
+			options: []contractsai.Option{WithProvider("openai")},
+			prompt: contractsai.TranscriptionPrompt{
+				File: file,
+			},
+			setup: func() contractsai.Config {
+				provider := &applicationTranscriptionProviderStub{}
+				provider.response = &applicationTranscriptionResponseStub{}
+				return contractsai.Config{
+					Default: "default",
+					Providers: map[string]contractsai.ProviderConfig{
+						"default": {Via: mocksai.NewProvider(t)},
+						"openai":  {Via: provider},
+					},
+				}
+			},
+			expectPrompt: contractsai.TranscriptionPrompt{File: file},
+		},
+		{
+			name: "provider does not support transcription",
+			prompt: contractsai.TranscriptionPrompt{
+				File: file,
+			},
+			setup: func() contractsai.Config {
+				return contractsai.Config{
+					Default: "default",
+					Providers: map[string]contractsai.ProviderConfig{
+						"default": {Via: mocksai.NewProvider(t)},
+					},
+				}
+			},
+			expectError: errors.AIProviderDoesNotSupportTranscription.Args("default"),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			app := NewApplication(context.Background(), tt.setup())
+			response, err := app.transcription(context.Background(), tt.prompt, tt.options...)
+			assert.Equal(t, tt.expectError, err)
+			if tt.expectError != nil {
+				assert.Nil(t, response)
+				return
+			}
+
+			require.NotNil(t, response)
+			provider, ok := app.config.Providers["openai"].Via.(*applicationTranscriptionProviderStub)
+			require.True(t, ok)
+			assert.Equal(t, tt.expectPrompt, provider.prompt)
+		})
+	}
+}
+
 func TestApplication_image(t *testing.T) {
 	tests := []struct {
 		name        string
@@ -825,6 +949,13 @@ type applicationAudioProviderStub struct {
 	err      error
 }
 
+type applicationTranscriptionProviderStub struct {
+	ctx      context.Context
+	prompt   contractsai.TranscriptionPrompt
+	response contractsai.TranscriptionResponse
+	err      error
+}
+
 func (p *applicationAudioProviderStub) Prompt(context.Context, contractsai.AgentPrompt) (contractsai.AgentResponse, error) {
 	return nil, nil
 }
@@ -839,6 +970,20 @@ func (p *applicationAudioProviderStub) Audio(ctx context.Context, prompt contrac
 	return p.response, p.err
 }
 
+func (p *applicationTranscriptionProviderStub) Prompt(context.Context, contractsai.AgentPrompt) (contractsai.AgentResponse, error) {
+	return nil, nil
+}
+
+func (p *applicationTranscriptionProviderStub) Stream(context.Context, contractsai.AgentPrompt) (contractsai.StreamableAgentResponse, error) {
+	return nil, nil
+}
+
+func (p *applicationTranscriptionProviderStub) Transcription(ctx context.Context, prompt contractsai.TranscriptionPrompt) (contractsai.TranscriptionResponse, error) {
+	p.ctx = ctx
+	p.prompt = prompt
+	return p.response, p.err
+}
+
 type applicationAudioResponseStub struct {
 	storePath       []string
 	storePathResult string
@@ -902,6 +1047,28 @@ func (r *applicationAudioResponseStub) Then(callback func(contractsai.AudioRespo
 	return r
 }
 
+type applicationTranscriptionResponseStub struct {
+	text     string
+	segments []contractsai.TranscriptionSegment
+	usage    contractsai.Usage
+}
+
+func (r *applicationTranscriptionResponseStub) Text() string { return r.text }
+
+func (r *applicationTranscriptionResponseStub) Segments() []contractsai.TranscriptionSegment {
+	return append([]contractsai.TranscriptionSegment(nil), r.segments...)
+}
+
+func (r *applicationTranscriptionResponseStub) Usage() contractsai.Usage { return r.usage }
+
+func (r *applicationTranscriptionResponseStub) Then(callback func(contractsai.TranscriptionResponse)) contractsai.TranscriptionResponse {
+	if callback != nil {
+		callback(r)
+	}
+
+	return r
+}
+
 func (m *applicationTestMiddleware) Handle(ctx context.Context, prompt contractsai.AgentPrompt, next contractsai.Next) (contractsai.AgentResponse, error) {
 	response, err := next(ctx, prompt)
 	if err != nil {

ai/audio_request.go

@@ -23,7 +23,7 @@ func NewAudioRequest(ctx context.Context, app *Application, prompt string) contr
 		ctx:    ctx,
 		app:    app,
 		prompt: prompt,
-		voice:  defaultFemaleVoice,
+		voice:  DefaultFemaleVoice,
 	}
 }
 
@@ -43,12 +43,12 @@ func (r *audioRequest) Voice(voice string) contractsai.AudioRequest {
 }
 
 func (r *audioRequest) Male() contractsai.AudioRequest {
-	r.voice = defaultMaleVoice
+	r.voice = DefaultMaleVoice
 	return r
 }
 
 func (r *audioRequest) Female() contractsai.AudioRequest {
-	r.voice = defaultFemaleVoice
+	r.voice = DefaultFemaleVoice
 	return r
 }
 

ai/audio_voice.go

@@ -1,4 +1,4 @@
 package ai
 
-const defaultMaleVoice = "default-male"
-const defaultFemaleVoice = "default-female"
+const DefaultMaleVoice = "default-male"
+const DefaultFemaleVoice = "default-female"

ai/image/image.go

@@ -2,7 +2,6 @@ package image
 
 import (
 	contractsai "github.com/goravel/framework/contracts/ai"
-	"github.com/goravel/framework/facades"
 )
 
 type Quality = contractsai.ImageQuality
@@ -17,7 +16,3 @@ const (
 	SizePortrait  = contractsai.ImageSizePortrait
 	SizeLandscape = contractsai.ImageSizeLandscape
 )
-
-func Of(prompt string) contractsai.ImageRequest {
-	return facades.AI().Image(prompt)
-}