LangChain.FileUploader behaviour (LangChain v0.8.4)

Behaviour for uploading files to LLM providers.

Provides a unified interface for uploading files to OpenAI, Anthropic, and Google Gemini. Each provider returns a LangChain.FileUploader.FileResult containing the file reference needed for subsequent API calls.

Usage

# OpenAI
{:ok, uploader} = LangChain.FileUploader.FileOpenAI.new(%{api_key: "sk-..."})
{:ok, result} = LangChain.FileUploader.upload(uploader, file_bytes, %{
  filename: "doc.pdf",
  mime_type: "application/pdf"
})
result.file_id
#=> "file-abc123"

# Google Gemini
{:ok, uploader} = LangChain.FileUploader.FileGoogle.new(%{api_key: "AI..."})
{:ok, result} = LangChain.FileUploader.upload(uploader, file_bytes, %{
  filename: "doc.pdf",
  mime_type: "application/pdf"
})
result.file_uri
#=> "https://generativelanguage.googleapis.com/v1beta/files/..."

File Metadata

The file_meta map passed to upload/3 accepts the following keys:

:filename (required) - The name to give the uploaded file.
:mime_type (required) - The MIME type of the file content.
:purpose - Provider-specific purpose string. Used by OpenAI (e.g. "user_data", "assistants"). Ignored by other providers.
:display_name - A human-readable display name. Used by Google. Falls back to :filename if not provided.

Summary

Types

delete_result()

file_meta()

get_result()

list_result()

upload_result()

Callbacks

delete(config, file_ref)

Delete a previously uploaded file by its ID or URI.

get(config, file_ref)

Retrieve metadata for a previously uploaded file by its ID.

list(config)

List files previously uploaded to the provider.

upload(config, file_bytes, file_meta)

Upload file bytes to the provider and return a FileResult on success.

Functions

delete(uploader, file_ref)

Delete a file using any configured uploader implementation.

get(uploader, file_ref)

Retrieve file metadata using any configured uploader implementation.

list(uploader)

List files using any configured uploader implementation.

upload(uploader, file_bytes, file_meta)

Upload a file using any configured uploader implementation.

Types

delete_result()

@type delete_result() :: :ok | {:error, LangChain.LangChainError.t()}

file_meta()

@type file_meta() :: %{
  :filename => String.t(),
  :mime_type => String.t(),
  optional(:purpose) => String.t(),
  optional(:display_name) => String.t()
}

get_result()

@type get_result() ::
  {:ok, LangChain.FileUploader.FileResult.t()}
  | {:error, LangChain.LangChainError.t()}

list_result()

@type list_result() ::
  {:ok, [LangChain.FileUploader.FileResult.t()]}
  | {:error, LangChain.LangChainError.t()}

upload_result()

@type upload_result() ::
  {:ok, LangChain.FileUploader.FileResult.t()}
  | {:error, LangChain.LangChainError.t()}

Callbacks

delete(config, file_ref)

(optional)

@callback delete(
  config :: struct(),
  file_ref :: LangChain.FileUploader.FileResult.t() | String.t()
) ::
  delete_result()

Delete a previously uploaded file by its ID or URI.

get(config, file_ref)

(optional)

@callback get(
  config :: struct(),
  file_ref :: LangChain.FileUploader.FileResult.t() | String.t()
) ::
  get_result()

Retrieve metadata for a previously uploaded file by its ID.

list(config)

(optional)

@callback list(config :: struct()) :: list_result()

List files previously uploaded to the provider.

upload(config, file_bytes, file_meta)

@callback upload(config :: struct(), file_bytes :: binary(), file_meta :: file_meta()) ::
  upload_result()

Upload file bytes to the provider and return a FileResult on success.

Functions

delete(uploader, file_ref)

@spec delete(
  struct(),
  LangChain.FileUploader.FileResult.t() | String.t()
) :: delete_result()

Delete a file using any configured uploader implementation.

Returns an error if the provider does not implement delete/2.

get(uploader, file_ref)

@spec get(
  struct(),
  LangChain.FileUploader.FileResult.t() | String.t()
) :: get_result()

Retrieve file metadata using any configured uploader implementation.

Returns an error if the provider does not implement get/2.

list(uploader)

@spec list(struct()) :: list_result()

List files using any configured uploader implementation.

Returns an error if the provider does not implement list/1.

upload(uploader, file_bytes, file_meta)

@spec upload(struct(), binary(), file_meta()) :: upload_result()

Upload a file using any configured uploader implementation.

Delegates to the provider module's upload/3 callback.