feat(ai): add attachment support

[hwbrzzl]

Summary

• Adds request-scoped image and document attachments to AI prompts and streams.
• Resolves attachments lazily from bytes, readers, paths, URLs, uploads, or filesystem storage without persisting them in conversation history.
• Sends attachment constructors from the root ai package with helper constructors like ai.DocumentFromPath(...) and ai.ImageFromPath(...).

Closes goravel/goravel#918

Why

AI conversations can now include files or images on a single prompt call without changing agent construction or storing binary data in message history. The public attachment API now lives in the root ai package, so callers can attach documents and images directly from common sources on each prompt or stream call.

conversation, err := facades.AI().Agent(&agents.SupportAgent{})
if err != nil {
	return ctx.Response().String(http.StatusInternalServerError, err.Error())
}

response, err := conversation.Prompt("Summarize these files", ai.WithAttachments(
	ai.DocumentFromPath("storage/app/report.pdf"),
	ai.ImageFromPath("storage/app/chart.png"),
))
if err != nil {
	return ctx.Response().String(http.StatusInternalServerError, err.Error())
}

return ctx.Response().Success().Json(http.Json{
	"summary": response.Text(),
})

[codecov]

Codecov Report

❌ Patch coverage is 80.82707% with 51 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.29%. Comparing base (4aa64cf) to head (e28608b).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
ai/file.go	74.66%	24 Missing and 14 partials ⚠️
ai/openai/provider.go	79.31%	6 Missing and 6 partials ⚠️
ai/option.go	95.45%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1455      +/-   ##
==========================================
+ Coverage   69.22%   69.29%   +0.06%     
==========================================
  Files         363      364       +1     
  Lines       28479    28713     +234     
==========================================
+ Hits        19715    19896     +181     
- Misses       7893     7925      +32     
- Partials      871      892      +21     

☔ 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

Adds request-scoped attachments to AI prompt/stream calls so images/files can be sent with the active user turn (including tool-call follow-ups) without persisting binary data in the conversation history.

Changes:

• Introduces Attachment / AttachmentKind contracts and plumbs attachments through AgentPrompt.
• Adds per-call PromptOptions (model, attachments, middlewares) and updates Conversation.Prompt/Stream to accept them.
• Extends the OpenAI provider to emit multimodal user content parts for image/file attachments, with accompanying test coverage.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
mocks/ai/PromptOptionFunc.go	Adds mock for prompt option function type.
mocks/ai/PromptOption.go	Adds mock for PromptOption.
mocks/ai/Conversation.go	Updates mock conversation Prompt/Stream to accept variadic PromptOption.
mocks/ai/Attachment.go	Adds mock for Attachment.
contracts/ai/provider.go	Extends AgentPrompt with Attachments.
contracts/ai/option.go	Adds PromptOptions/PromptOption and adapts Option for prompt-scoped use.
contracts/ai/attachment.go	Introduces attachment contract types.
contracts/ai/ai.go	Updates conversation interface to accept prompt options.
ai/option.go	Adds WithAttachment(s) and nil-filter helpers for attachments.
ai/openai/provider.go	Builds multimodal OpenAI messages including image/file parts.
ai/openai/provider_test.go	Adds tests validating message building with attachments.
ai/conversation.go	Applies per-call prompt options and keeps attachments request-scoped across tool loops/streams.
ai/conversation_test.go	Adds tests ensuring attachments aren’t persisted and are kept on tool follow-ups.
ai/attachment.go	Adds attachment constructors/resolvers for bytes/readers/paths/storage with lazy resolution.
ai/attachment_test.go	Adds tests for attachment constructors and caching behavior.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

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

[hwbrzzl]

Addressed the latest attachment API review feedback.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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