# Kling Minimal Watcher Proposal

## Goal
Remove LLM from routine waiting/polling. Let code handle task-state watching, result download, and manifest updates. Let the LLM handle only interpretation and user-facing reporting.

## Minimal Design (practical v1)

### 1. Create step
When a Kling task is created, immediately append one record to a small task registry JSON/SQLite row:
- endpoint
- model_name
- task_id
- external_task_id
- prompt_summary
- input_asset_summary
- created_at
- expected_output_dir
- status=`submitted`

### 2. Watcher loop (non-LLM)
A lightweight Python worker runs every 30-60s (cron or background loop):
- load tasks with status in `submitted|processing`
- query Kling once per task
- if still processing -> update latest status timestamp only
- if succeed -> download result URL immediately, save under pipeline output structure, write manifest, set status=`succeed`
- if failed -> record `task_status_msg`, status=`failed`

### 3. Output artifacts
For each finished task, write:
- downloaded file under the existing output structure
- one compact manifest JSON with:
  - endpoint
  - model
  - task_id
  - final_status
  - output_path
  - original_result_url
  - unit_deduction
  - prompt_summary
  - input_asset_summary

### 4. LLM handoff boundary
Only after status becomes `succeed` or `failed` should the LLM be invoked to:
- summarize what happened
- compare outputs
- update docs/policy if warranted
- message the user

## Why this is the minimum useful version
- no browser
- no callback server required on day one
- no big new architecture
- replaces wasteful LLM polling with one small worker
- keeps context small because the LLM reads compact manifests, not long wait-state history

## Recommended first implementation
- storage: reuse SQLite task table if already present; otherwise one JSON registry is fine
- runner: `scripts/kling_watcher.py`
- schedule: every 1 minute via cron or one background loop
- download path: existing `outputs/privacy-safe-tests/...` or pipeline output folder per run

## Rule of thumb
Facts are stored by code. Interpretation is done by the LLM.