feat(ai): add audio generation support

[hwbrzzl]

Summary

• Add a fluent facades.AI().Audio(...) API for text-to-speech generation with provider, model, voice, instructions, timeout, and storage support.
• Add OpenAI audio generation support, including default audio model resolution, placeholder voice mapping, and audio response MIME-aware storage behavior.
• Simplify AI.Image(...) to use request-level configuration so image and audio requests follow the same fluent setup pattern.

Closes goravel/goravel#918

Why

Goravel's AI package already supports text, files, and image generation, but it did not have a first-class text-to-speech flow. This change adds an audio request/response pipeline that matches the existing fluent AI patterns, so applications can generate speech directly through the facade and store the result without needing provider-specific wiring in user code.

package controllers

import (
	"time"

	"github.com/goravel/framework/facades"
)

type AudioController struct{}

func (r *AudioController) Welcome() (string, error) {
	return facades.AI().
		Audio("Welcome to Goravel").
		Provider("openai").
		Model("gpt-4o-mini-tts").
		Female().
		Instructions("Speak clearly and warmly").
		Timeout(30 * time.Second).
		StoreAs("audio/welcome.mp3")
}

This also keeps the public surface more consistent by moving image selection to the fluent request instead of mixing constructor options with request methods. That avoids duplicate ways to set provider and model, while the OpenAI implementation supplies sensible defaults for the initial runtime slice.

[codecov]

Codecov Report

❌ Patch coverage is 77.43363% with 51 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.26%. Comparing base (950dc14) to head (dda0b4b).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
ai/openai/provider.go	69.69%	16 Missing and 4 partials ⚠️
ai/response.go	74.41%	10 Missing and 1 partial ⚠️
ai/audio_request.go	80.00%	9 Missing and 1 partial ⚠️
ai/media_storage.go	77.77%	4 Missing and 4 partials ⚠️
ai/application.go	85.71%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1467      +/-   ##
==========================================
+ Coverage   69.19%   69.26%   +0.07%     
==========================================
  Files         370      373       +3     
  Lines       29338    29523     +185     
==========================================
+ Hits        20300    20450     +150     
- Misses       8106     8135      +29     
- Partials      932      938       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR adds first-class audio (text-to-speech) generation to the AI facade/API, extends the OpenAI provider to implement audio generation with sensible defaults, and aligns the image generation API to the same fluent request pattern.

Changes:

• Introduces fluent AI.Audio(prompt) / AudioRequest / AudioResponse contracts plus framework implementations for generating and storing audio.
• Adds OpenAI audio generation support (default audio model config, default voice mapping, response MIME-type handling).
• Simplifies AI.Image(...) to remove constructor options and rely on request-level configuration (.Provider(...), .Model(...), etc.).

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
mocks/ai/AudioResponse.go	Adds mock for the new contracts/ai.AudioResponse interface.
mocks/ai/AudioRequest.go	Adds mock for the new contracts/ai.AudioRequest fluent request interface.
mocks/ai/AudioProvider.go	Adds mock for the new contracts/ai.AudioProvider interface.
mocks/ai/AI.go	Updates AI mock to include Audio(prompt) and changes Image(prompt) signature (removes options).
errors/list.go	Adds centralized error definitions for audio flow (prompt, store path/name, provider capability).
contracts/ai/response.go	Introduces AudioResponse contract (content, MIME type, storage, usage, callbacks).
contracts/ai/provider.go	Adds AudioPrompt and AudioProvider contract for provider implementations.
contracts/ai/config.go	Extends model config with Models.Audio.Default.
contracts/ai/audio.go	Adds AudioRequest contract defining the fluent audio request API.
contracts/ai/ai.go	Adds Audio(prompt) to the AI facade contract and updates Image(prompt) signature.
ai/response.go	Implements audioResponse (content cloning, MIME-aware filename extension, storage helpers).
ai/openai/provider.go	Implements OpenAI audio generation, default audio model resolution, voice mapping, and response parsing.
ai/openai/provider_test.go	Updates provider config expectations to include the audio default model.
ai/image/image.go	Updates image helper Of(prompt) to match the new AI.Image(prompt) signature.
ai/image/image_test.go	Adjusts image helper tests to reflect the new Image(prompt) signature.
ai/image_request.go	Removes image constructor options parsing; relies on fluent request configuration instead.
ai/audio_voice.go	Defines internal constants for default male/female voice selectors.
ai/audio_storage.go	Adds audio storage implementation (Store/StoreAs) similar to image storage behavior.
ai/audio_request.go	Adds fluent audioRequest implementation (provider/model/voice/instructions/timeout + Store/Generate).
ai/application.go	Adds Application.Audio(prompt) and provider dispatch for audio (audio(...)).
ai/application_test.go	Updates image request test to use fluent request configuration (no constructor options).

[hwbrzzl]

Addressed the latest annotation in commit 8264e3a by refactoring the shared media storage path normalization and write helpers.

[Copilot]

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 2 comments.