file_storage

Pluggable storage for files uploaded by clients and referenced by URL later.

FileStorage is the shared interface between the development runner’s POST /files upload endpoint, which saves uploads and hands the resulting URL back to the client, and the LLM service’s FileResolver, which loads the bytes back when the client references that URL in a send-file message. Passing the same storage instance to both means they agree on where uploads live without each needing its own copy of the configuration, and lets a deployment swap in a backend other than local disk by implementing this interface.

The URL is the contract: FileStorage.save() returns one, callers pass it back unmodified, and each implementation mints whatever form it can later resolve — pipecat:<id> for LocalFileStorage, or e.g. gs:// / s3:// for a custom cloud backend (which the LLM provider may then even fetch itself, without FileStorage.load() being involved at all).

class pipecat.utils.file_storage.FileStorage[source]

Bases: ABC

Storage backend for files uploaded by clients and referenced by URL later.

delete_after_load: bool = False
abstractmethod async save(filename: str, contents: bytes) → str[source]

Store a file and return the URL later passed to load() or delete().

Parameters:
  • filename – The original filename, for backends that want to keep it (e.g. for content-type sniffing). Storage implementations should not use it to derive the returned URL.

  • contents – The raw file contents.

Returns:

A URL identifying the stored file, in whatever form this backend can later resolve. Callers must pass it back unmodified to load() or delete().

abstractmethod async load(file_url: str) → bytes[source]

Return the stored contents for file_url.

Parameters:

file_url – A URL previously returned by save().

Raises:

FileNotFoundError – If file_url is invalid or no longer stored.

abstractmethod async delete(file_url: str) → None[source]

Remove the stored file for file_url, if present.

Parameters:

file_url – A URL previously returned by save().

class pipecat.utils.file_storage.LocalFileStorage(folder: str, max_files: int = 10)[source]

Bases: FileStorage

Default storage backend: files on local disk, addressed as pipecat:<hex>.

Suitable for local development and single-process deployments. The pipecat: scheme makes the URLs recognizable in logs and client payloads; the random hex suffix can’t be used for path traversal and doesn’t leak the original filename.

delete_after_load: bool = True
__init__(folder: str, max_files: int = 10)[source]

Initialize local file storage.

Parameters:
  • folder – Directory to store files in. Created on first save if missing.

  • max_files – Maximum number of files to retain; oldest files (by mtime) are deleted once this is exceeded. Set to 0 to disable trimming.

async save(filename: str, contents: bytes) → str[source]

Write contents to a new randomly-named file and return its pipecat: URL.

async load(file_url: str) → bytes[source]

Read and return the contents stored under file_url.

async delete(file_url: str) → None[source]

Delete the file stored under file_url, if it exists.