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:
ABCStorage backend for files uploaded by clients and referenced by URL later.
- abstractmethod async save(filename: str, contents: bytes) str[source]
Store a file and return the URL later passed to
load()ordelete().- 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()ordelete().
- class pipecat.utils.file_storage.LocalFileStorage(folder: str, max_files: int = 10)[source]
Bases:
FileStorageDefault 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.- __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.