LangChain.FileUploader.FileGoogle (LangChain v0.8.12)

Uploads files to Google Gemini's File API.

Google uses a two-step resumable upload protocol internally, but this is abstracted away — callers simply call upload/3.

Usage

{:ok, uploader} = LangChain.FileUploader.FileGoogle.new(%{api_key: "AI..."})

{:ok, result} = LangChain.FileUploader.upload(uploader, file_bytes, %{
  filename: "document.pdf",
  mime_type: "application/pdf"
})

result.file_id
#=> "files/abc-123"

result.file_uri
#=> "https://generativelanguage.googleapis.com/v1beta/files/abc-123"

Google identifies files by resource name (e.g. "files/abc-123"), which is stored as file_id in the returned FileResult. The file_uri is also available for use with ContentPart.file_url!/2.

Note: Files uploaded to Gemini expire after 48 hours.

Client-side direct upload

Step 2 can be performed by a browser or mobile client instead of your server. Call request_upload_url/5 with the client's origin and forward the returned URL to the client — the client then PUTs the file bytes to that URL directly.

{:ok, upload_url} =
  FileGoogle.request_upload_url(uploader, "doc.pdf", "application/pdf", 12_345,
    origin: "https://app.example.com"
  )

The :origin option is required for browser uploads because Google uses it to set Access-Control-Allow-Origin on the step 2 response.

Summary

Types

t()

Functions

delete(uploader, file_name)

Delete a file by its resource name.

get(uploader, file_name)

Retrieve file metadata by its resource name.

new(attrs \\ %{})

Setup a Google file uploader configuration.

new!(attrs \\ %{})

Setup a Google file uploader configuration and return it or raise an error if invalid.

request_upload_url(uploader, display_name, mime_type, byte_count, opts \\ [])

Request a presigned upload URL from Google's resumable upload endpoint (step 1 of 2).

upload_file_bytes(uploader, upload_url, file_bytes, byte_count)

Upload raw file bytes to a presigned upload URL (step 2 of 2).

Types

t()

@type t() :: %LangChain.FileUploader.FileGoogle{
  api_key: term(),
  endpoint: term(),
  receive_timeout: term(),
  req_opts: term()
}

Functions

delete(uploader, file_name)

Delete a file by its resource name.

file_name must be the Google resource name in the form "files/{id}", e.g. "files/abc-123". This is the file_id value stored in FileResult.

get(uploader, file_name)

Retrieve file metadata by its resource name.

file_name must be the Google resource name in the form "files/{id}", e.g. "files/abc-123". This is the file_id value stored in FileResult.

new(attrs \\ %{})

@spec new(attrs :: map()) :: {:ok, t()} | {:error, Ecto.Changeset.t()}

Setup a Google file uploader configuration.

new!(attrs \\ %{})

@spec new!(attrs :: map()) :: t() | no_return()

Setup a Google file uploader configuration and return it or raise an error if invalid.

request_upload_url(uploader, display_name, mime_type, byte_count, opts \\ [])

@spec request_upload_url(t(), String.t(), String.t(), non_neg_integer(), keyword()) ::
  {:ok, String.t()} | {:error, LangChain.LangChainError.t()}

Request a presigned upload URL from Google's resumable upload endpoint (step 1 of 2).

Returns {:ok, upload_url} on success, or {:error, LangChainError.t()} on failure. The returned URL can be passed to upload_file_bytes/4 to complete the upload, or forwarded directly to a client (e.g. a browser or mobile app) so it can upload the file bytes itself without routing them through your server.

Options

:origin — When step 2 will be performed by a browser or mobile client, pass the client's origin (scheme + host, e.g. "https://app.example.com"). Google uses this origin to set Access-Control-Allow-Origin on the step 2 response, allowing the cross-origin upload to succeed. Omit when step 2 is performed server-side.

upload_file_bytes(uploader, upload_url, file_bytes, byte_count)

@spec upload_file_bytes(t(), String.t(), binary(), non_neg_integer()) ::
  {:ok, LangChain.FileUploader.FileResult.t()}
  | {:error, LangChain.LangChainError.t()}

Upload raw file bytes to a presigned upload URL (step 2 of 2).

upload_url is obtained from request_upload_url/4. Returns {:ok, FileResult.t()} on success, or {:error, LangChainError.t()} on failure.