feat(assets) Add asset file_path and display_name response fields

[synap5e]

What this does
Adds 2 new optional fields to the asset system's Asset (and AssetCreated) schema:

• file_path: The asset's path on disk (if it has one). Includes the models/{checkpoints,vae,...}/ or {input,output}/ prefix.
• display_name: The asset's human-readable display name. Conventionally a the path within prefix, and what is displayed in the loading widget.

Motivation

In asset mode, the asset response's name field is overloaded. Depending on the asset's origin, the same field carries:

• The ID for consumers
• The rendered display label
• (Sometimes) The file path they resolve to

In asset-mode, the frontend has ~10 widget and upload sites that read name or fall back to asset_hash to extract whichever role they need, with per-backend branching where the heuristics differ.

file_path exposes the full namespace-relative locator (models/checkpoints/flux/model.safetensors) as a dedicated field. display_name exposes the within-bucket path (flux/model.safetensors). The frontend can read what it needs without inferring from value shape or branching on backend.

Changes

• Add file_path and display_name to the Asset output schema, inherited by AssetCreated.
• Populate both fields in the shared asset response builder used by list, detail, upload/create, create-from-hash, and update responses.
• Add path helpers that convert stored absolute reference paths into logical asset paths:
  • media assets: {input,output,temp}/...
  • model assets: models/<bucket>/...
• Keep unknown or non-file-backed references nullable/omitted, matching existing exclude_none response behavior.
• Document the new fields in OpenAPI.
• Add focused tests for path computation, upload/list/detail response fields, and hash-only fast-path compatibility.

Verification

• uv run --with-requirements requirements.txt --with-requirements tests-unit/requirements.txt pytest -q tests-unit/assets_test/services/test_path_utils.py tests-unit/assets_test/test_uploads.py::test_upload_response_includes_file_path_and_display_name tests-unit/assets_test/test_uploads.py::test_upload_fastpath_from_existing_hash_no_file tests-unit/assets_test/test_crud.py::test_metadata_filename_is_set_for_seed_asset_without_hash
• uv run --with ruff ruff check app/assets/api/routes.py app/assets/api/schemas_out.py app/assets/services/path_utils.py tests-unit/assets_test/services/test_path_utils.py tests-unit/assets_test/test_uploads.py tests-unit/assets_test/test_crud.py

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d71a4e5e-b1c9-4ca6-9f5e-c0a0389dccf2

📥 Commits

Reviewing files that changed from the base of the PR and between 72e3f60 and f003032.

📒 Files selected for processing (6)

• app/assets/api/routes.py
• app/assets/api/schemas_out.py
• app/assets/services/path_utils.py
• openapi.yaml
• tests-unit/assets_test/services/test_path_utils.py
• tests-unit/assets_test/test_uploads.py

---

📝 Walkthrough

Walkthrough

This PR extends the Asset API model to expose logical file paths and display names. It introduces path computation helpers in path_utils.py (including compute_paths_for_response, compute_file_path, compute_display_name, and get_asset_root_bucket_and_filepath) along with a RootCategory type alias. The Asset schema is updated to mark name as deprecated and add optional file_path and display_name fields. The routes layer integrates the new helpers to populate these fields in responses. OpenAPI documentation is updated to reflect the schema changes, and comprehensive test coverage validates path computation logic and end-to-end asset upload and retrieval flows.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.86% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding two new response fields (file_path and display_name) to the asset schema.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the motivation, changes made, and verification steps.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mattmillerai]

Heads up on the x-runtime: [cloud, local] tags here — the established convention in this file is that absence of x-runtime means both runtimes populate the field (i.e. it's the default). All 177 existing x-runtime usages in this file are [cloud] only — they mark cloud-only divergence from the default-both behavior. [cloud, local] is redundant with no tag and introduces a second pattern.

Two cleaner options:

1. Drop the x-runtime: [cloud, local] tags entirely — absence carries the same meaning, and the existing 177 [cloud] usages stay self-consistent. This is what the convention currently calls for.
2. Keep them and file a separate convention-change discussion if there's a reason explicit-over-implicit is preferable here — but that's a wider change that should be applied uniformly, not selectively.

(1) is the smaller change and avoids introducing dual conventions in the same file.

— mattmiller@comfy.org

[guill]

I think this function relies on a flawed assumption that all models will be in the models directory. As an example, the built-in SaveCheckpoint, SaveLora, etc. models actually save to the outputs directory but are still loadable as models.
If possible, I would really like to avoid special-casing models as that's usually going to fail for edge cases. Could you explain a bit more about why we actually need the bucket as a first-class concept?

[guill]

I know this isn't actually new to this PR, but I'm a little concerned about the assumption that models will be exactly one of these. We should make sure this works for cases like the built-in SaveCheckpoint or SaveLora nodes where the model is located under the outputs directory, but should also be treated as a model.