Module files 

Provider-owned file upload, metadata, pagination, and bounded downloads.

FileUploadRequest owns validated bytes. Submit it through crate::ProviderBackend::upload_file, retain the returned lifecycle id, and explicitly delete only caller-owned files. FileObject::input_reference may differ from the lifecycle id. Processing readiness and operation support are provider-authored facts rather than assumptions following upload.

Retain ownership through deletion

This requires an OpenAI key and upload/read/delete access. The exact upload id is the cleanup authority; neither a filename nor a list-difference establishes ownership. If upload fails without a returned id, retain the error’s evidence of any uncertain remote outcome rather than deleting a guessed resource.

use std::num::NonZeroUsize;
use providers_kit::{Provider, ProviderBackend, ProviderConfig};
use providers_kit::config::{ApiKey, OpenAiConfig, ProviderKind, TransportConfig};
use providers_kit::files::FileUploadRequest;
let provider = Provider::from_config(ProviderConfig::new(
    ProviderKind::OpenAi(OpenAiConfig::new(ApiKey::new("replace-with-your-key")?)),
    TransportConfig::default(),
))?;
let uploaded = provider
    .upload_file(FileUploadRequest::new(
        "note.txt",
        "text/plain",
        b"owned note".to_vec(),
    )?)
    .await;
let work = async {
    let file = uploaded.as_ref().map_err(Clone::clone)?;
    let info = provider.file_info(file.id.clone()).await?;
    assert_eq!(info.id, file.id);
    let bytes = provider.download_file(file.id.clone(), NonZeroUsize::new(1024).unwrap()).await?;
    assert_eq!(bytes, b"owned note");
    Ok::<(), providers_kit::KitError>(())
}.await;
let deletion = match uploaded {
    Ok(file) => provider.delete_file(file.id).await,
    Err(_) => Ok(()),
};
let shutdown = provider.shutdown().await;
// Retain cleanup errors as supplementary evidence on an earlier failure.
let mut outcome = work;
for cleanup in [deletion, shutdown] {
    if let Err(error) = cleanup {
        outcome = Err(match outcome { Err(primary) => primary.with_supplementary(error), Ok(()) => error });
    }
}
outcome?;

Provider shutdown settles local resources only. Failed deletion remains a remote cleanup obligation; it is not converted into success by shutdown.

Structs

FileListRequest

Validated file-list pagination request.

FileObject

Provider-managed file metadata.

FilePage

One page of provider-managed files.

FileUploadRequest

Validated provider-file upload request.

Enums

FileState

Provider-managed file lifecycle state.