ExAgent.FileRef (ExAgent v0.3.0)

Copy Markdown View Source

Reference to a file previously uploaded to an LLM provider.

Holds the provider-specific file identifier (OpenAI file_id, Gemini file_uri, or whichever a custom provider uses) so that uploaded files can be referenced in chat messages without re-sending the binary data.

Examples

iex> {:ok, ref} = ExAgent.FileRef.new(provider: :openai, file_id: "file-abc123", mime_type: "application/pdf")
iex> ref.file_id
"file-abc123"

iex> {:ok, ref} = ExAgent.FileRef.new(provider: :gemini, file_uri: "https://example.com/files/abc", mime_type: "image/png")
iex> ref.file_uri
"https://example.com/files/abc"

iex> ExAgent.FileRef.new(provider: :openai, mime_type: "image/png")
{:error, "OpenAI file references require :file_id"}

iex> ExAgent.FileRef.new(provider: :gemini, mime_type: "image/png")
{:error, "Gemini file references require :file_uri"}

Summary

Types

t()

Functions

expired?(file_ref)

Returns true if the file reference has expired.

new(attrs)

Creates a new file reference with validated attributes.

Types

t()

@type t() :: %ExAgent.FileRef{
  expires_at: DateTime.t() | nil,
  file_id: String.t() | nil,
  file_uri: String.t() | nil,
  filename: String.t() | nil,
  mime_type: String.t(),
  provider: atom()
}

Functions

expired?(file_ref)

@spec expired?(t()) :: boolean()

Returns true if the file reference has expired.

Gemini files expire 48 hours after upload. OpenAI files do not expire.

Examples

iex> {:ok, ref} = ExAgent.FileRef.new(provider: :openai, file_id: "f-1", mime_type: "text/plain")
iex> ExAgent.FileRef.expired?(ref)
false

new(attrs)

@spec new(keyword()) :: {:ok, t()} | {:error, String.t()}

Creates a new file reference with validated attributes.

Options

  • :provider (required) - :openai, :gemini, or the atom naming a custom provider that implements ExAgent.Provider.upload/4
  • :mime_type (required) - MIME type of the uploaded file
  • :file_id - OpenAI file ID (required for :openai provider)
  • :file_uri - Gemini file URI (required for :gemini provider)
  • :filename - Original filename
  • :expires_at - Expiration datetime (Gemini files expire after 48h)