Comfy-Org · christian-byrne · Nov 30, 2025
@@ -0,0 +1,95 @@
+# Template Ranking System
+
+Usage-based ordering for workflow templates with position bias normalization.
+
+Scores are pre-computed and normalized offline and shipped as static JSON (mirrors `sorted-custom-node-map.json` pattern for node search).
+
+## Sort Modes
+
+| Mode           | Formula                                          | Description            |
+| -------------- | ------------------------------------------------ | ---------------------- |
+| `default`      | `usage × 0.5 + internal × 0.3 + freshness × 0.2` | Curated recommendation |
+| `popular`      | `usage × 0.9 + freshness × 0.1`                  | Pure user-driven       |
+| `newest`       | Date sort                                        | Existing               |
+| `alphabetical` | Name sort                                        | Existing               |
+
+Freshness computed at runtime from `template.date`: `1.0 / (1 + daysSinceAdded / 90)`, min 0.1.
+
+## Data Files
+
+**Usage scores** (generated from Mixpanel):
+
+```
+public/assets/template-usage-scores.json  # { "template_name": 0.95, ... } normalized 0-1
+```
+
+**Search rank** (set per-template in workflow_templates repo):
+
+```json
+// In templates/index.json, add to any template:
+{
+  "name": "some_template",
+  "searchRank": 8,  // Scale 1-10, default 5
+  ...
+}
+```
+
+| searchRank | Effect                       |
+| ---------- | ---------------------------- |
+| 1-4        | Demote (bury in results)     |
+| 5          | Neutral (default if not set) |
+| 6-10       | Promote (boost in results)   |
+
+## Position Bias Correction
+
+Raw usage reflects true preference AND UI position bias. We use linear interpolation:
+
+```
+correction = 1 + (position - 1) / (maxPosition - 1)
+normalizedUsage = rawUsage × correction
+```
+
+| Position | Boost |
+| -------- | ----- |
+| 1        | 1.0×  |
+| 50       | 1.28× |
+| 100      | 1.57× |
+| 175      | 2.0×  |
+
+Templates buried at the bottom get up to 2× boost to compensate for reduced visibility.
+
+---
+
+## Updating Scores
+
+```bash
+# 1. Export from Mixpanel https://mixpanel.com/s/21GKgr (export as CSV)
+# 2. Run script
+pnpm generate:template-scores --input ./mixpanel-export.csv
+
+# 3. Commit
+git add public/assets/template-usage-scores.json
+git commit -m "[feat] Update template ranking scores"
+```
+
+**Script options:**
+
+- `--input, -i` — Mixpanel CSV (required)
+- `--ui-order, -u` — templates index.json path (default: fetches from repo)
+- `--output, -o` — output dir (default: `public/assets/`)
+
+**Expected CSV format:**
+
+```csv
+template_name,count
+01_qwen_t2i_subgraphed,1085
+video_wan2_2_14B_animate,713
+```
+
+**Manual ranking adjustments:** Set `searchRank` on templates in `workflow_templates` repo's `index.json`:
+
+- `1-4` = demote (bury in results)
+- `5` = neutral (default)
+- `6-10` = promote (boost in results)
+
+**Update frequency:** Monthly, or after major template additions.
@@ -25,6 +25,7 @@
     "format:check": "prettier --check './**/*.{js,ts,tsx,vue,mts}' --cache",
     "format:no-cache": "prettier --write './**/*.{js,ts,tsx,vue,mts}' --list-different",
     "format": "prettier --write './**/*.{js,ts,tsx,vue,mts}' --cache --list-different",
+    "generate:template-scores": "tsx scripts/generate-template-scores.ts",
     "json-schema": "tsx scripts/generate-json-schema.ts",
     "knip:no-cache": "knip",
     "knip": "knip --cache",

@@ -0,0 +1,188 @@
+{
+  "03_video_wan2_2_14B_i2v_subgraphed": 1,
+  "01_qwen_t2i_subgraphed": 0.9588,
+  "api_nano_banana_pro": 0.9253,
+  "video_wan2_2_14B_animate": 0.6013,
+  "02_qwen_Image_edit_subgraphed": 0.5489,
+  "video_wan2_2_14B_i2v": 0.4694,
+  "image_flux2": 0.4575,
+  "api_openai_sora_video": 0.4499,
+  "api_ltxv_image_to_video": 0.4341,
+  "image_z_image_turbo": 0.3946,
+  "image_chrono_edit_14B": 0.377,
+  "image_qwen_image_edit_2509": 0.358,
+  "api_wan_image_to_video": 0.3453,
+  "image_netayume_lumina_t2i": 0.3248,
+  "api_ltxv_text_to_video": 0.291,
+  "video_hunyuan_video_1.5_720p_i2v": 0.2876,
+  "video_wan2_2_14B_t2v": 0.2803,
+  "04_hunyuan_3d_2.1_subgraphed": 0.2783,
+  "api_google_gemini_image": 0.2717,
+  "api_flux2": 0.2685,
+  "flux1_krea_dev": 0.2634,
+  "video_wan2.1_alpha_t2v_14B": 0.2341,
+  "flux1_dev_uso_reference_image_gen": 0.2213,
+  "api_wan_text_to_video": 0.2145,
+  "api_bytedance_image_to_video": 0.2077,
+  "image_flux2_fp8": 0.2044,
+  "video_humo": 0.2024,
+  "api_bytedance_seedream4": 0.1892,
+  "3d_hunyuan3d-v2.1": 0.1843,
+  "api_from_photo_2_miniature": 0.1792,
+  "api_wan_text_to_image": 0.1714,
+  "video_wan2_2_14B_flf2v": 0.1668,
+  "api_topaz_video_enhance": 0.1555,
+  "video_hunyuan_video_1.5_720p_t2v": 0.1544,
+  "hiresfix_latent_workflow": 0.1538,
+  "api_veo3": 0.1503,
+  "video_wan2_2_14B_s2v": 0.1496,
+  "video_wan2_2_14B_fun_camera": 0.1404,
+  "api_bytedance_flf2v": 0.1338,
+  "video_wan2_2_14B_fun_inpaint": 0.1288,
+  "video_wan2_2_5B_ti2v": 0.1286,
+  "image_qwen_image": 0.1263,
+  "image_qwen_image_instantx_controlnet": 0.1263,
+  "video_wan2_2_14B_fun_control": 0.1247,
+  "image_chroma1_radiance_text_to_image": 0.1238,
+  "image_qwen_image_instantx_inpainting_controlnet": 0.1215,
+  "image_flux.1_fill_dev_OneReward": 0.1178,
+  "05_audio_ace_step_1_t2a_song_subgraphed": 0.1117,
+  "api_topaz_image_enhance": 0.1109,
+  "flux_kontext_dev_basic": 0.109,
+  "api_bytedance_text_to_video": 0.1055,
+  "video_wan_vace_14B_v2v": 0.1028,
+  "api_rodin_gen2": 0.1015,
+  "video_wan_vace_14B_ref2v": 0.1009,
+  "esrgan_example": 0.0933,
+  "hidream_e1_1": 0.09,
+  "audio_stable_audio_example": 0.0884,
+  "ltxv_image_to_video": 0.0883,
+  "default": 0.0869,
+  "image_qwen_image_edit": 0.0849,
+  "flux_dev_checkpoint_example": 0.0838,
+  "video_wan2_2_5B_fun_control": 0.0821,
+  "image_qwen_image_controlnet_patch": 0.0806,
+  "hiresfix_esrgan_workflow": 0.0799,
+  "image_qwen_image_union_control_lora": 0.0782,
+  "latent_upscale_different_prompt_model": 0.0771,
+  "flux_fill_inpaint_example": 0.077,
+  "lora": 0.0762,
+  "sdxl_simple_example": 0.0727,
+  "image2image": 0.0724,
+  "api_google_gemini": 0.0698,
+  "api_kling_i2v": 0.0698,
+  "flux_dev_full_text_to_image": 0.0677,
+  "api_openai_chat": 0.0634,
+  "sd3.5_simple_example": 0.0621,
+  "hidream_i1_full": 0.062,
+  "hunyuan_video_text_to_video": 0.0611,
+  "video_wan_vace_inpainting": 0.0591,
+  "3d_hunyuan3d_multiview_to_model": 0.0566,
+  "image_to_video_wan": 0.0532,
+  "api_bfl_flux_1_kontext_pro_image": 0.0514,
+  "2_pass_pose_worship": 0.0509,
+  "sdxlturbo_example": 0.05,
+  "api_vidu_reference_to_video": 0.0492,
+  "image_to_video": 0.0469,
+  "flux_redux_model_example": 0.0451,
+  "image_chroma_text_to_image": 0.0451,
+  "video_wan_vace_flf2v": 0.045,
+  "flux_fill_outpaint_example": 0.0434,
+  "api_bfl_flux_1_kontext_multiple_images_input": 0.0422,
+  "audio_ace_step_1_t2a_song": 0.0422,
+  "video_wan_vace_14B_t2v": 0.0412,
+  "wan2.1_fun_control": 0.0412,
+  "flux_depth_lora_example": 0.0402,
+  "image_omnigen2_t2i": 0.0397,
+  "api_runway_gen4_turo_image_to_video": 0.0396,
+  "video_wan_ati": 0.0392,
+  "api_bfl_flux_pro_t2i": 0.0383,
+  "3d_hunyuan3d_image_to_model": 0.0381,
+  "api_vidu_image_to_video": 0.0369,
+  "sdxl_refiner_prompt_example": 0.036,
+  "api_stability_ai_text_to_audio": 0.0358,
+  "api_kling_flf": 0.0346,
+  "hidream_i1_dev": 0.0344,
+  "lora_multiple": 0.0341,
+  "video_wan2_2_5B_fun_inpaint": 0.0339,
+  "3d_hunyuan3d_multiview_to_model_turbo": 0.0324,
+  "depth_t2i_adapter": 0.032,
+  "video_wan_vace_outpainting": 0.0317,
+  "ltxv_text_to_video": 0.0313,
+  "hidream_e1_full": 0.0308,
+  "audio_ace_step_1_m2m_editing": 0.0306,
+  "image_lotus_depth_v1_1": 0.0305,
+  "api_bfl_flux_1_kontext_max_image": 0.0304,
+  "audio_ace_step_1_t2a_instrumentals": 0.0303,
+  "sd3.5_large_canny_controlnet_example": 0.03,
+  "video_wan2.1_fun_camera_v1.1_14B": 0.0299,
+  "depth_controlnet": 0.0294,
+  "flux_canny_model_example": 0.0292,
+  "api_stability_ai_i2i": 0.0286,
+  "sd3.5_large_depth": 0.0282,
+  "sdxl_revision_text_prompts": 0.0282,
+  "api_vidu_start_end_to_video": 0.0276,
+  "image_omnigen2_image_edit": 0.0263,
+  "inpaint_example": 0.0252,
+  "inpaint_model_outpainting": 0.0246,
+  "api_moonvalley_video_to_video_motion_transfer": 0.0243,
+  "wan2.1_flf2v_720_f16": 0.0233,
+  "api_runway_text_to_image": 0.023,
+  "mixing_controlnets": 0.023,
+  "api_rodin_image_to_model": 0.0227,
+  "txt_to_image_to_video": 0.0227,
+  "api_runway_reference_to_image": 0.0226,
+  "api_vidu_text_to_video": 0.0226,
+  "api_stability_ai_audio_to_audio": 0.0222,
+  "api_tripo_multiview_to_model": 0.0221,
+  "api_luma_photon_i2i": 0.0218,
+  "api_openai_image_1_i2i": 0.0216,
+  "api_veo2_i2v": 0.0216,
+  "api_moonvalley_image_to_video": 0.0215,
+  "text_to_video_wan": 0.0206,
+  "api_tripo_image_to_model": 0.0197,
+  "wan2.1_fun_inp": 0.0195,
+  "api_runway_first_last_frame": 0.0194,
+  "api_moonvalley_video_to_video_pose_control": 0.0192,
+  "api_openai_dall_e_3_t2i": 0.0192,
+  "video_wan2.1_fun_camera_v1.1_1.3B": 0.0189,
+  "api_tripo_text_to_model": 0.0179,
+  "api_luma_i2v": 0.0175,
+  "flux_schnell": 0.0175,
+  "api_kling_effects": 0.0172,
+  "flux_schnell_full_text_to_image": 0.0168,
+  "api_stability_ai_sd3.5_i2i": 0.0164,
+  "hidream_i1_fast": 0.0163,
+  "mochi_text_to_video_example": 0.0159,
+  "api_hailuo_minimax_i2v": 0.0158,
+  "api_recraft_vector_gen": 0.0149,
+  "embedding_example": 0.0143,
+  "api_runway_gen3a_turbo_image_to_video": 0.014,
+  "api_luma_photon_style_ref": 0.0137,
+  "sd3.5_large_blur": 0.0136,
+  "api_rodin_multiview_to_model": 0.0135,
+  "api_stability_ai_stable_image_ultra_t2i": 0.013,
+  "controlnet_example": 0.0128,
+  "gligen_textbox_example": 0.0125,
+  "api_recraft_image_gen_with_style_control": 0.0114,
+  "api_pika_scene": 0.0105,
+  "api_pixverse_i2v": 0.0105,
+  "api_luma_t2v": 0.0103,
+  "api_openai_image_1_inpaint": 0.0103,
+  "api_pika_i2v": 0.0102,
+  "api_stability_ai_audio_inpaint": 0.01,
+  "api_ideogram_v3_t2i": 0.0097,
+  "api_stability_ai_sd3.5_t2i": 0.0094,
+  "api_hailuo_minimax_t2v": 0.0091,
+  "api_openai_image_1_multi_inputs": 0.0091,
+  "area_composition": 0.0086,
+  "api_hailuo_minimax_video": 0.008,
+  "api_recraft_image_gen_with_color_control": 0.0077,
+  "api_openai_dall_e_2_inpaint": 0.0076,
+  "api_pixverse_t2v": 0.0073,
+  "api_openai_image_1_t2i": 0.007,
+  "api_moonvalley_text_to_video": 0.0068,
+  "api_pixverse_template_i2v": 0.0064,
+  "area_composition_square_area_for_subject": 0.0055,
+  "api_openai_dall_e_2_t2i": 0.0041
+}