Files

You do not construct this class yourself. The client owns a FileManager and exposes it as client.files. Its operations return RagInputUploadResponse and RagInputBatchItemResult instances, documented in Models.

class arango_ai_sdk.resources.FileManager(communication, db_name)

Manage the files a project will ingest, through the communication layer.

Uploading is what it offers today; the rest of file management follows in later releases.

Parameters:
  • communication (Communication) – Shared transport. This namespace calls send_request and nothing else.

  • db_name (str) – Database the files are organised under. The files themselves live in the platform’s storage backend; the database scopes their management and access. Taken from the client, so no upload asks for it.

upload_file(path, *, scope=(), name=None, custom_metadata=None, timeout=300.0)

Upload one file and return the stored version.

The file is streamed from disk, never read into memory as a whole.

Parameters:
  • path (str or os.PathLike) – File to upload.

  • scope (Sequence[str], optional) – Ordered scope labels the file is placed under, for example ["acme", "legal"]. No scoping means the file is database-scoped.

  • name (str, optional) – Name the file is stored under. Defaults to the file’s own name.

  • custom_metadata (Mapping[str, str], optional) – Flat string-to-string metadata kept with this version and returned on later reads. Replaced, not merged, by the next version.

  • timeout (float, optional) – Seconds to wait for the platform’s answer. Raise it for very large files.

Returns:

The stored version, as the platform described it.

Return type:

RagInputUploadResponse

Raises:
  • FileNotFoundError – path does not exist, or is a folder.

  • InvalidFileScopeError – scope breaks the platform’s rules. Normally raised before sending, since the SDK applies the platform’s rules first.

  • EmptyFileError – The file has no content. Normally raised before sending.

  • InvalidFileMetadataError – The platform rejected custom_metadata.

  • FileUploadFailedError – The platform could not store the file and reports having rolled the upload back.

  • ServiceError – Any other error answer from the platform.

upload_files(files, *, scope=(), custom_metadata=None, timeout=300.0)

Upload several files in one request, each stored under its own name.

Give the files either as a list of paths that all share scope, or as a mapping from path to scope when they go to different places. The platform stores them one by one: a file it rejects is reported in its own result and does not stop the others.

One request carries at most 100 files and 2 GiB in total. Larger sets are refused before anything is sent; split them across calls.

Parameters:
  • files (Iterable[str or os.PathLike] or Mapping[str or os.PathLike, Sequence[str]]) – The files to upload: paths that all share scope, or a mapping from each path to the scope it is placed under. A path listed twice is uploaded twice, as two versions.

  • scope (Sequence[str], optional) – Ordered scope labels every file is placed under. Used with a list of paths; with a mapping, each file already has its scope and this argument is ignored.

  • custom_metadata (Mapping[str, str], optional) – Metadata kept with every uploaded version.

  • timeout (float, optional) – Seconds to wait for the platform’s answer.

Returns:

One result per file, in the given order. status is "ok" for a stored file and "error" for a rejected one, whose reason is in detail.

Return type:

list[RagInputBatchItemResult]

Raises:
  • ValueError – No files were given.

  • FileNotFoundError – A path does not exist, or is a folder.

  • InvalidFileScopeError – A scope breaks the platform’s rules. Normally raised before sending, since the SDK applies the platform’s rules first.

  • FileBatchTooLargeError – More than 100 files, or more than 2 GiB in total. Normally raised before sending.

  • InvalidFileMetadataError – The platform rejected custom_metadata.

  • ServiceError – Any other error answer from the platform.

upload_folder(folder, *, scope=(), custom_metadata=None, timeout=300.0)

Upload the files directly inside a folder, all under one scope.

Only the folder’s own files are taken; subfolders and their contents are ignored. Otherwise this is upload_files() with the folder’s files, so the same limits and errors apply.

Parameters:
  • folder (str or os.PathLike) – Folder whose files to upload.

  • scope (Sequence[str], optional) – Ordered scope labels every file is placed under.

  • custom_metadata (Mapping[str, str], optional) – Metadata kept with every uploaded version.

  • timeout (float, optional) – Seconds to wait for the platform’s answer.

Returns:

One result per file, in alphabetical order of the file names.

Return type:

list[RagInputBatchItemResult]

Raises: