From 4a8a906377c44c848e538e78eaec39cc6f5bf758 Mon Sep 17 00:00:00 2001 From: Dreaming Computers Date: Fri, 30 Jan 2026 12:16:53 +0700 Subject: [PATCH] chore: move internal docs under _internal --- docs/flux_i2i_plan.md | 47 ----------- docs/flux_i2i_status.md | 9 -- docs/flux_i2i_tasks.md | 32 -------- docs/implementation_plan.md | 107 ------------------------ docs/node_from_spec.md | 159 ------------------------------------ kie_api/seedream45_edit.py | 2 +- 6 files changed, 1 insertion(+), 355 deletions(-) delete mode 100644 docs/flux_i2i_plan.md delete mode 100644 docs/flux_i2i_status.md delete mode 100644 docs/flux_i2i_tasks.md delete mode 100644 docs/implementation_plan.md delete mode 100644 docs/node_from_spec.md diff --git a/docs/flux_i2i_plan.md b/docs/flux_i2i_plan.md deleted file mode 100644 index 32c02c8..0000000 --- a/docs/flux_i2i_plan.md +++ /dev/null @@ -1,47 +0,0 @@ -# Flux 2 I2I Nodes — Plan - -## Spec scan (source of truth) -- `_internal/docs/KIE_API_FLUX-2-PRO-I2I_SPEC.md` -- `_internal/docs/KIE_AI-FLUX-2-FLEX-I2I_SPEC.MD` - -## Field comparison (Pro vs Flex) -Same fields in both specs: -- `model` (string; only value differs) -- `input.input_urls` (required, array URL, 1–8 images) -- `input.prompt` (required, 3–5000 chars) -- `input.aspect_ratio` (required enum) -- `input.resolution` (required enum) -- `callBackUrl` (optional) - -Enumerations (identical): -- `aspect_ratio`: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, auto -- `resolution`: 1K, 2K - -Conclusion: inputs/outputs are identical; only `model` differs. - -## Node architecture decision -We can implement a **single node** with a `model` dropdown: -- `flux-2/pro-image-to-image` -- `flux-2/flex-image-to-image` - -Conditions satisfied: -- All other parameters are the same in both specs. -- Output type is the same (IMAGE). - -## Helper vs node split -Helper: -- `kie_api/flux2_i2i.py` (new) -- Accept `model` as a required argument. -- Handle upload, createTask, poll, download, decode. - -Node: -- `KIE_Flux2_I2I` in `nodes.py` -- `model` dropdown + inputs from spec -- Calls `run_flux2_i2i(...)` - -Docs: -- `web/docs/KIE_Flux2_I2I.md` (new) - -## Open questions (confirm before code) -1) Should we allow 1–8 images (batch) or force 1 image? -2) Do you want `model` in node name or just in a dropdown? diff --git a/docs/flux_i2i_status.md b/docs/flux_i2i_status.md deleted file mode 100644 index 0845027..0000000 --- a/docs/flux_i2i_status.md +++ /dev/null @@ -1,9 +0,0 @@ -# Flux 2 I2I — Status - -Last updated: 2026-01-30 - -- [x] Helper added (`kie_api/flux2_i2i.py`) -- [x] Node wrapper added (`nodes.py`) -- [x] Node registered in mappings (`nodes.py`) -- [x] Node docs added (`web/docs/KIE_Flux2_I2I.md`) -- [x] Compile check (`python3 -m py_compile nodes.py kie_api/flux2_i2i.py`) diff --git a/docs/flux_i2i_tasks.md b/docs/flux_i2i_tasks.md deleted file mode 100644 index 6cb2f80..0000000 --- a/docs/flux_i2i_tasks.md +++ /dev/null @@ -1,32 +0,0 @@ -# Flux 2 I2I — Task List - -## Phase 0: Agree on scope -- Confirm single node with model dropdown is acceptable. -- Confirm allowed image count (1 vs 1–8). - -## Phase 1: Spec-to-helper -- Add `kie_api/flux2_i2i.py` - - constants: MODEL_OPTIONS, ASPECT_RATIO_OPTIONS, RESOLUTION_OPTIONS - - validate prompt length (3–5000) - - validate images tensor shape and count - - upload images (1..8) - - createTask + poll + extract result URLs - - download + decode to tensor - -## Phase 2: Node wrapper -- Add class `KIE_Flux2_I2I` to `nodes.py` -- `INPUT_TYPES` reflects spec (plus `model` dropdown, `log`) -- Call `run_flux2_i2i(...)` -- Add HELP text - -## Phase 3: Register node -- Import new helper in `nodes.py` -- Add to `NODE_CLASS_MAPPINGS` -- Add to `NODE_DISPLAY_NAME_MAPPINGS` - -## Phase 4: Docs -- Add `web/docs/KIE_Flux2_I2I.md` -- Include inputs/outputs + enums + defaults - -## Phase 5: Sanity checks -- `python3 -m py_compile nodes.py kie_api/flux2_i2i.py` diff --git a/docs/implementation_plan.md b/docs/implementation_plan.md deleted file mode 100644 index ef4a9b1..0000000 --- a/docs/implementation_plan.md +++ /dev/null @@ -1,107 +0,0 @@ -# ComfyUI Node + Helper Separation Plan - -## Goals -- Keep model-specific API logic in helpers (`kie_api/*`). -- Keep ComfyUI node definitions in `nodes.py` (or a future `nodes/` package). -- Ensure every node relies on helpers instead of re-implementing API calls. -- Document best practices and track follow-up fixes. - -## Current Nodes (as of Jan 30, 2026) -Image: -- Nano Banana Pro (image) -- Seedream 4.5 (text-to-image) -- Seedream 4.5 (edit) - -Video: -- Kling 2.5 I2V Pro -- Kling 2.6 I2V -- Kling 2.6 T2V -- Kling 2.6 Motion I2V -- Seedance V1 Pro Fast I2V -- Seedance 1.5 Pro I2V/T2V - -Helpers: -- auth, credits, http, log, jobs, results -- upload, images, video, validation, grid, prompt_lists -- model-specific helpers: nanobanana, seedream45_t2i, seedream45_edit, seedance*, kling* - -## Best Practices Implementation (Current Standard) -1) **Nodes are thin wrappers.** - - Node `generate()` methods delegate to helper functions (`run_*`). - - Node I/O uses ComfyUI types (`IMAGE`, `VIDEO`, `STRING`, `INT`, `BOOLEAN`). - -2) **Helpers encapsulate the full job lifecycle.** - - Validation → upload → create task → poll → download/decode → credits logging. - - Shared behavior is already centralized in `jobs.py`, `upload.py`, `images.py`, `video.py`, `validation.py`. - -3) **Consistent error handling.** - - `TransientKieError` signals retryable failures (HTTP 429 or 5xx, transient task failure states). - - Non-retry errors raise `RuntimeError` with clear messages. - -4) **Logging is centralized and predictable.** - - `_log()` is used for all progress messages. - - Nodes expose a `log` flag and pass it through. - -5) **Enum inputs are pinned.** - - ComfyUI node options use COMBOs that map to pinned server enums (`duration`, `aspect_ratio`, etc.). - -6) **Helpers own logic; nodes own UI.** - - No API calls, uploads, or polling logic inside nodes. - - Nodes should only translate ComfyUI inputs → helper inputs and return helper outputs. - -7) **Docs reflect actual behavior.** - - Node docs in `web/docs/` mirror the helper inputs/outputs and current defaults. - - HELP text and `INPUT_TYPES` must match. - -## Things To Review / Fix (Cleanup Targets) -1) **Duplicate `createTask` logic across helpers.** - - `nanobanana.py`, `kling25_i2v.py`, `kling26_i2v.py`, `kling26_t2v.py`, `kling26motion_i2v.py`, - `seedance*`, `seedream*` all implement request + error handling for `createTask`. - - Candidate: move to `jobs.py` or a `requests.py` helper for shared API calls. - -2) **Duplicate image upload + validation patterns.** - - Each model re-validates image tensor shapes, slices batches, and uploads via `_upload_image`. - - Candidate: a shared helper (e.g. `_upload_first_image`, `_upload_images_limit`). - -3) **Node inputs do not expose all documented parameters.** - - Several node HELP blocks mention `poll_interval_s`, `timeout_s`, and retry settings, - but these are not exposed in `INPUT_TYPES`. - - Decide whether to: - - expose them via `INPUT_TYPES`, or - - remove from HELP to avoid confusion. - -4) **Model docs vs helper docs drift risk.** - - `web/docs/` contains node pages; helper behavior lives in `kie_api/*`. - - Add a short helper summary section per model doc or generate them from helpers. - -5) **Category naming consistency.** - - Some helpers appear as nodes in `kie/helpers` (grid, prompt parsing), while others are `kie/api`. - - Clarify if helper nodes should live under a dedicated category and be separated from API nodes in UI. - -## Cleanup Task List (Initial) -### 2) Normalize helper APIs (createTask + upload + validation) -- Extract a shared `create_task()` helper (or move into `jobs.py`) to remove per-model duplication. -- Add shared helpers for common upload patterns: - - upload first image - - upload optional tail image - - upload list of images with a max limit -- Consolidate image shape validation helpers (single image vs batch) into `validation.py`. - -### 3) Align node HELP with `INPUT_TYPES` -- Audit each node in `nodes.py` for: - - missing inputs referenced in HELP - - defaults or ranges that differ between HELP and `INPUT_TYPES` -- Either expose these inputs or remove them from HELP to avoid mismatch. - -### 4) Keep docs in sync with helpers -- For each model in `web/docs/`, add a short “Helper behavior” section: - - validation rules - - retry behavior - - polling defaults - - output format -- Add a checklist to update docs when helper defaults change. - -## Next Steps (if approved) -1) Create a dedicated “Best Practices + Implementation Checklist” doc for adding new models. -2) Start Cleanup Task List item 3 (HELP vs INPUT_TYPES) as the first low-hanging task. -3) After cleanup item 3, draft a new node using the standard pattern. diff --git a/docs/node_from_spec.md b/docs/node_from_spec.md deleted file mode 100644 index 54eba50..0000000 --- a/docs/node_from_spec.md +++ /dev/null @@ -1,159 +0,0 @@ -# Building ComfyUI Nodes From KIE API Specs - -This is the ground-truth process for turning a pinned KIE API spec into: -- a helper (model runner) in `kie_api/` -- a ComfyUI node wrapper in `nodes.py` -- a matching user-facing doc in `web/docs/` - -## Source Material (What We Actually Use) -Primary inputs: -- `_internal/docs/KIE_API_*_SPEC.md` and other spec files in `_internal/docs/` -- `_internal/docs/COMFYUI_NODE_CHEATSHEET.md` -- `_internal/docs/REPO_RULES.md` -- Existing node + helper implementations (`nodes.py`, `kie_api/*.py`) - -Note: There is no `codecs/` folder in this repo. If one appears later, add it to this list. - -## Non-Negotiable Rules (Do Not Hallucinate) -- Never invent fields or options that are not in a spec. -- If a spec is incomplete or ambiguous, stop and request clarification. -- The helper owns API logic. The node is a thin wrapper only. -- ComfyUI image tensors are **BHWC float32** in **[0..1]**. -- Video outputs must remain compatible with ComfyUI `SaveVideo`. - -## Step 1: Parse the Spec (Pin the Facts) -From the spec file, extract these fields exactly: -- **Model name** (string used in the payload `model`) -- **Input fields** (required vs optional) -- **Allowed options** (enumerations for combos) -- **Input constraints** (max lengths, valid ranges, max count) -- **Response shape** (task id, result URLs, failure fields) - -If you cannot find a field in the spec, do not add it to the node. - -## Step 2: Decide Helper vs Node Responsibilities -Helpers (model runners) MUST do: -- prompt validation (length/range) -- image/video upload (if input URLs are required) -- task creation and polling -- result parsing and download/decoding -- logging + credit logging - -Nodes MUST do: -- define ComfyUI inputs/outputs -- call exactly one helper function -- return the helper output without modification - -## Step 3: Map Spec Inputs to ComfyUI Inputs -Use these mapping rules (always prefer existing patterns): - -Spec field type -> ComfyUI type: -- string prompt -> `STRING` (multiline) -- boolean -> `BOOLEAN` -- number -> `FLOAT` (with min/max/step if in spec) -- integer -> `INT` (with min/max if in spec) -- enum -> `COMBO` with the exact options list -- image URL(s) -> `IMAGE` (ComfyUI tensors), then upload in helper -- video URL(s) -> `VIDEO`, then upload in helper - -Required vs optional: -- Spec **required** -> `required` section of `INPUT_TYPES` -- Spec **optional** -> `optional` section of `INPUT_TYPES` - -Image and video rules: -- If spec allows 1..N images, accept a batch `IMAGE` input and enforce max N. -- If spec allows optional image list, permit `images=None` and skip upload. -- Video inputs are passed through the existing video helpers. - -## Step 4: Implement the Helper (Model Runner) -Location: `kie_api/.py` - -Required responsibilities: -1) Validate inputs -2) Upload any images/videos (convert tensors to bytes) -3) Create task (`createTask`) -4) Poll until completion (`recordInfo`) -5) Parse result URLs -6) Download output and convert to ComfyUI types - -Existing helpers to reuse: -- `kie_api/auth.py` (`_load_api_key`) -- `kie_api/jobs.py` (`_poll_task_until_complete`) -- `kie_api/upload.py` (image/video upload + conversions) -- `kie_api/images.py` (image download + tensor decode) -- `kie_api/video.py` (video download + SaveVideo-compatible output) -- `kie_api/results.py` (result URL extraction) -- `kie_api/validation.py` (prompt validation) -- `kie_api/log.py` (logging) -- `kie_api/credits.py` (credits logging) - -Helper output contract: -- Image models return `torch.Tensor` with shape [B, H, W, C], float32, 0..1 -- Video models return a SaveVideo-compatible object (match existing video nodes) - -## Step 5: Implement the Node Wrapper -Location: `nodes.py` - -Requirements: -- Keep node `generate()` minimal: just call helper and return results. -- `INPUT_TYPES`, `RETURN_TYPES`, `RETURN_NAMES`, `FUNCTION`, `CATEGORY` are required. -- `HELP` must match the actual node inputs and defaults. -- Expose enums as `COMBO` options exactly as listed in the spec. -- If spec includes optional inputs, include them under `optional`. - -## Step 6: Register the Node -Ensure: -- The node class is imported in `nodes.py` -- It appears in `NODE_CLASS_MAPPINGS` -- It has a name in `NODE_DISPLAY_NAME_MAPPINGS` - -## Step 7: Document the Node (web/docs) -Create or update `web/docs/.md`: -- Match the exact ComfyUI inputs and outputs -- Include defaults and enums -- Add a brief “Helper behavior” summary: - - validation rules - - polling defaults - - retry behavior (if any) - -## Helper/Node Consistency Checklist -Before declaring done: -- Node HELP matches INPUT_TYPES (no hidden inputs). -- Helper validates all required fields and enum options. -- Spec-required inputs are not optional in the node. -- All options in the spec are represented as COMBOs. -- Output type is correct (IMAGE or VIDEO). - -## Spec-to-Node Quick Example (Image-to-Image) -Spec fields: -- model: "flux-2/pro-image-to-image" -- input.input_urls (required, 1..8) -- input.prompt (required, max 5000) -- input.aspect_ratio (required enum) -- input.resolution (required enum) - -ComfyUI node inputs: -- `images: IMAGE` (required) -- `prompt: STRING` (required) -- `aspect_ratio: COMBO` (required) -- `resolution: COMBO` (required) -- `log: BOOLEAN` (optional, local-only) - -Helper responsibilities: -- Validate prompt length -- Validate `images` tensor shape and count (max 8) -- Upload images to URLs -- Build payload with `input_urls` -- Create task + poll -- Download result URL and decode to tensor - -## When Specs Are Incomplete -If a spec: -- omits an option list -- lacks a max length/range -- conflicts with existing helper behavior - -Then: -1) Do not guess defaults. -2) Add a TODO in the spec doc. -3) Ask for clarification or source doc before coding. diff --git a/kie_api/seedream45_edit.py b/kie_api/seedream45_edit.py index c4d4d3c..b309778 100644 --- a/kie_api/seedream45_edit.py +++ b/kie_api/seedream45_edit.py @@ -1,7 +1,7 @@ """Seedream 4.5 image edit helper. Implements the Seedream 4.5 edit workflow as documented in -`docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md`. +`_internal/docs/KIE_API_SEEDREAM_45_EDIT_SPEC.md`. This module: - validates inputs