feat(ai): add audio generation support (goravel#1467)

Author: hwbrzzl

ai/application.go

@@ -36,8 +36,12 @@ func (r *Application) Agent(agent contractsai.Agent, options ...contractsai.Opti
 	return NewConversation(r.ctx, agent, provider, model, middlewares), nil
 }
 
-func (r *Application) Image(prompt string, options ...contractsai.Option) contractsai.ImageRequest {
-	return NewImageRequest(r.ctx, r, prompt, options...)
+func (r *Application) Audio(prompt string) contractsai.AudioRequest {
+	return NewAudioRequest(r.ctx, r, prompt)
+}
+
+func (r *Application) Image(prompt string) contractsai.ImageRequest {
+	return NewImageRequest(r.ctx, r, prompt)
 }
 
 func (r *Application) putFile(ctx context.Context, file contractsai.StorableFile, options ...contractsai.Option) (contractsai.FileResponse, error) {
@@ -90,6 +94,23 @@ func (r *Application) deleteFile(ctx context.Context, id string, options ...cont
 	return fileProvider.DeleteFile(ctx, id)
 }
 
+func (r *Application) audio(ctx context.Context, prompt contractsai.AudioPrompt, options ...contractsai.Option) (contractsai.AudioResponse, error) {
+	opts, providerName, provider, err := r.resolveProvider(options)
+	if err != nil {
+		return nil, err
+	}
+	if prompt.Model == "" {
+		prompt.Model = opts.Model
+	}
+
+	audioProvider, ok := provider.(contractsai.AudioProvider)
+	if !ok {
+		return nil, errors.AIProviderDoesNotSupportAudio.Args(providerName)
+	}
+
+	return audioProvider.Audio(ctx, prompt)
+}
+
 func (r *Application) image(ctx context.Context, prompt contractsai.ImagePrompt, options ...contractsai.Option) (contractsai.ImageResponse, error) {
 	opts, providerName, provider, err := r.resolveProvider(options)
 	if err != nil {

ai/application_test.go

@@ -347,7 +347,7 @@ func TestApplication_Image(t *testing.T) {
 	}
 
 	app := NewApplication(ctx, config)
-	request := app.Image("draw a cat", WithProvider("default"), WithModel("gpt-image-1"))
+	request := app.Image("draw a cat").Provider("default").Model("gpt-image-1")
 
 	req, ok := request.(*imageRequest)
 	assert.True(t, ok)
@@ -459,6 +459,154 @@ func TestImageRequest_StoreUsesResponseStore(t *testing.T) {
 	assert.Empty(t, response.storePath)
 }
 
+func TestApplication_Audio(t *testing.T) {
+	ctx := context.Background()
+	config := contractsai.Config{
+		Default: "default",
+		Providers: map[string]contractsai.ProviderConfig{
+			"default": {Via: mocksai.NewProvider(t)},
+		},
+	}
+
+	app := NewApplication(ctx, config)
+	request := app.Audio("welcome to goravel").Provider("default").Model("gpt-4o-mini-tts").Male().Instructions("Speak slowly").Timeout(2 * time.Second)
+
+	req, ok := request.(*audioRequest)
+	assert.True(t, ok)
+	assert.Equal(t, ctx, req.ctx)
+	assert.Equal(t, app, req.app)
+	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, "Speak slowly", req.instructions)
+	assert.Equal(t, 2*time.Second, req.timeout)
+
+	assert.Same(t, req, request.Female())
+	assert.Equal(t, defaultFemaleVoice, req.voice)
+}
+
+func TestAudioRequest_Generate(t *testing.T) {
+	ctx := context.Background()
+	provider := &applicationAudioProviderStub{}
+	config := contractsai.Config{
+		Default: "default",
+		Providers: map[string]contractsai.ProviderConfig{
+			"default": {Via: provider},
+		},
+	}
+
+	app := NewApplication(context.Background(), config)
+	response := &applicationAudioResponseStub{}
+	provider.response = response
+
+	result, err := app.Audio("welcome to goravel").
+		Provider("default").
+		Model("gpt-4o-mini-tts").
+		Male().
+		Instructions("Speak slowly").
+		Timeout(3 * time.Second).
+		Generate()
+
+	require.NoError(t, err)
+	assert.Equal(t, response, result)
+	assert.Equal(t, ctx, provider.ctx)
+	assert.Equal(t, contractsai.AudioPrompt{
+		Prompt:       "welcome to goravel",
+		Model:        "gpt-4o-mini-tts",
+		Voice:        defaultMaleVoice,
+		Instructions: "Speak slowly",
+		Timeout:      3 * time.Second,
+	}, provider.prompt)
+}
+
+func TestAudioRequest_StoreUsesResponseStore(t *testing.T) {
+	provider := &applicationAudioProviderStub{}
+	app := NewApplication(context.Background(), contractsai.Config{
+		Default: "default",
+		Providers: map[string]contractsai.ProviderConfig{
+			"default": {Via: provider},
+		},
+	})
+	response := &applicationAudioResponseStub{storePathResult: "audio/generated.mp3"}
+	provider.response = response
+
+	path, err := app.Audio("welcome to goravel").Store()
+
+	require.NoError(t, err)
+	assert.Equal(t, "audio/generated.mp3", path)
+	assert.Equal(t, 1, response.storeCalls)
+	assert.Equal(t, 0, response.storeAsCalls)
+	assert.Empty(t, response.storePath)
+}
+
+func TestApplication_audio(t *testing.T) {
+	tests := []struct {
+		name         string
+		options      []contractsai.Option
+		prompt       contractsai.AudioPrompt
+		setup        func() contractsai.Config
+		expectError  error
+		expectPrompt contractsai.AudioPrompt
+	}{
+		{
+			name:    "success with default model",
+			options: []contractsai.Option{WithProvider("openai")},
+			prompt: contractsai.AudioPrompt{
+				Prompt: "welcome to goravel",
+				Voice:  defaultFemaleVoice,
+			},
+			setup: func() contractsai.Config {
+				provider := &applicationAudioProviderStub{}
+				provider.response = &applicationAudioResponseStub{}
+				return contractsai.Config{
+					Default: "default",
+					Providers: map[string]contractsai.ProviderConfig{
+						"default": {Via: mocksai.NewProvider(t)},
+						"openai":  {Via: provider},
+					},
+				}
+			},
+			expectPrompt: contractsai.AudioPrompt{
+				Prompt: "welcome to goravel",
+				Voice:  defaultFemaleVoice,
+			},
+		},
+		{
+			name: "provider does not support audio",
+			prompt: contractsai.AudioPrompt{
+				Prompt: "welcome to goravel",
+			},
+			setup: func() contractsai.Config {
+				return contractsai.Config{
+					Default: "default",
+					Providers: map[string]contractsai.ProviderConfig{
+						"default": {Via: mocksai.NewProvider(t)},
+					},
+				}
+			},
+			expectError: errors.AIProviderDoesNotSupportAudio.Args("default"),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			app := NewApplication(context.Background(), tt.setup())
+			response, err := app.audio(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.(*applicationAudioProviderStub)
+			require.True(t, ok)
+			assert.Equal(t, tt.expectPrompt, provider.prompt)
+		})
+	}
+}
+
 func TestApplication_image(t *testing.T) {
 	tests := []struct {
 		name        string
@@ -670,6 +818,90 @@ func (r *applicationImageResponseStub) Then(callback func(contractsai.ImageRespo
 	return r
 }
 
+type applicationAudioProviderStub struct {
+	ctx      context.Context
+	prompt   contractsai.AudioPrompt
+	response contractsai.AudioResponse
+	err      error
+}
+
+func (p *applicationAudioProviderStub) Prompt(context.Context, contractsai.AgentPrompt) (contractsai.AgentResponse, error) {
+	return nil, nil
+}
+
+func (p *applicationAudioProviderStub) Stream(context.Context, contractsai.AgentPrompt) (contractsai.StreamableAgentResponse, error) {
+	return nil, nil
+}
+
+func (p *applicationAudioProviderStub) Audio(ctx context.Context, prompt contractsai.AudioPrompt) (contractsai.AudioResponse, error) {
+	p.ctx = ctx
+	p.prompt = prompt
+	return p.response, p.err
+}
+
+type applicationAudioResponseStub struct {
+	storePath       []string
+	storePathResult string
+	storeAsName     string
+	storeAsPath     []string
+	storeCalls      int
+	storeAsCalls    int
+}
+
+func (r *applicationAudioResponseStub) Content() ([]byte, error) {
+	return []byte("audio"), nil
+}
+
+func (r *applicationAudioResponseStub) MimeType() string { return "audio/mpeg" }
+
+func (r *applicationAudioResponseStub) Store(disk ...string) (string, error) {
+	r.storeCalls++
+	r.storePath = append([]string(nil), disk...)
+	if r.storePathResult != "" {
+		return r.storePathResult, nil
+	}
+
+	content, err := r.Content()
+	if err != nil {
+		return "", err
+	}
+
+	resolvedDisk, err := resolveAudioStoreDisk(disk)
+	if err != nil {
+		return "", err
+	}
+
+	return audioStorer{}.Store(content, "generated.mp3", resolvedDisk)
+}
+
+func (r *applicationAudioResponseStub) StoreAs(path string, disk ...string) (string, error) {
+	r.storeAsCalls++
+	r.storeAsName = path
+	r.storeAsPath = append([]string(nil), disk...)
+
+	content, err := r.Content()
+	if err != nil {
+		return "", err
+	}
+
+	resolvedDisk, err := resolveAudioStoreDisk(disk)
+	if err != nil {
+		return "", err
+	}
+
+	return audioStorer{}.StoreAs(content, path, resolvedDisk)
+}
+
+func (r *applicationAudioResponseStub) Usage() contractsai.Usage { return nil }
+
+func (r *applicationAudioResponseStub) Then(callback func(contractsai.AudioResponse)) contractsai.AudioResponse {
+	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

@@ -0,0 +1,99 @@
+package ai
+
+import (
+	"context"
+	"time"
+
+	contractsai "github.com/goravel/framework/contracts/ai"
+)
+
+type audioRequest struct {
+	ctx          context.Context
+	app          *Application
+	prompt       string
+	provider     string
+	model        string
+	voice        string
+	instructions string
+	timeout      time.Duration
+}
+
+func NewAudioRequest(ctx context.Context, app *Application, prompt string) contractsai.AudioRequest {
+	return &audioRequest{
+		ctx:    ctx,
+		app:    app,
+		prompt: prompt,
+		voice:  defaultFemaleVoice,
+	}
+}
+
+func (r *audioRequest) Model(model string) contractsai.AudioRequest {
+	r.model = model
+	return r
+}
+
+func (r *audioRequest) Provider(provider string) contractsai.AudioRequest {
+	r.provider = provider
+	return r
+}
+
+func (r *audioRequest) Voice(voice string) contractsai.AudioRequest {
+	r.voice = voice
+	return r
+}
+
+func (r *audioRequest) Male() contractsai.AudioRequest {
+	r.voice = defaultMaleVoice
+	return r
+}
+
+func (r *audioRequest) Female() contractsai.AudioRequest {
+	r.voice = defaultFemaleVoice
+	return r
+}
+
+func (r *audioRequest) Instructions(instructions string) contractsai.AudioRequest {
+	r.instructions = instructions
+	return r
+}
+
+func (r *audioRequest) Timeout(timeout time.Duration) contractsai.AudioRequest {
+	r.timeout = timeout
+	return r
+}
+
+func (r *audioRequest) Store(disk ...string) (string, error) {
+	response, err := r.Generate()
+	if err != nil {
+		return "", err
+	}
+
+	return response.Store(disk...)
+}
+
+func (r *audioRequest) StoreAs(path string, disk ...string) (string, error) {
+	response, err := r.Generate()
+	if err != nil {
+		return "", err
+	}
+
+	return response.StoreAs(path, disk...)
+}
+
+func (r *audioRequest) Generate() (contractsai.AudioResponse, error) {
+	options := make([]contractsai.Option, 0, 2)
+	if r.provider != "" {
+		options = append(options, WithProvider(r.provider))
+	}
+	if r.model != "" {
+		options = append(options, WithModel(r.model))
+	}
+
+	return r.app.audio(r.ctx, contractsai.AudioPrompt{
+		Prompt:       r.prompt,
+		Model:        r.model,
+		Voice:        r.voice,
+		Instructions: r.instructions,
+		Timeout:      r.timeout,
+	}, options...)
+}