@cliptude/cli 0.1.21 → 0.1.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -17,6 +17,27 @@ pip install -e .
17
17
  cliptude auth login
18
18
  ```
19
19
 
20
+ ## Cliptude desktop app
21
+
22
+ The desktop app ships this CLI and MCP server, so nothing needs installing: in the app, open
23
+ **Settings → Connect an AI assistant** and click **Add** for Claude Desktop or Cursor, or copy the
24
+ command for Claude Code or Codex. Videos are then made in the app with your own provider keys.
25
+ ChatGPT only connects to servers on the internet, so it uses cliptude.com.
26
+
27
+ Where the CLI and MCP send jobs:
28
+
29
+ | | |
30
+ |---|---|
31
+ | `cliptude use desktop` | the running desktop app (fails with "Open Cliptude" when it is closed) |
32
+ | `cliptude use cloud` | cliptude.com |
33
+ | `cliptude use auto` (default) | the desktop app while it is running, else cliptude.com |
34
+ | `cliptude use` | show where jobs go now |
35
+
36
+ `CLIPTUDE_TARGET` overrides the saved choice, and `CLIPTUDE_BASE_URL` overrides both. The app's port
37
+ changes every launch: the CLI reads it from `desktop-runtime.json` and its key from `local-api.json`
38
+ in the app's data folder. The desktop gets only that local key and cliptude.com only your cliptude.com
39
+ login. A `CLIPTUDE_API_KEY` in the environment, without `CLIPTUDE_TARGET`, means cliptude.com.
40
+
20
41
  ## Commands
21
42
 
22
43
  ```bash
@@ -54,7 +75,13 @@ To revise a finished video, `editor` opens its timeline (item ids, times, text),
54
75
  On Faceless Documentary, Faceless Top 10, Avatar Video and Vector Explainer templates an agent can plan every visual and leave Cliptude
55
76
  only the voicing, sourcing and rendering:
56
77
 
57
- 1. `cliptude plan-job` (stops at `plan_ready`), `cliptude narration <job>`.
78
+ 1. `cliptude plan-job` (stops at `plan_ready`), `cliptude narration <job>`. Like every job, it answers first with a
79
+ review of its settings; music, sound effects, transitions, animations and web sources are on by default, and any the
80
+ template turns off (`no_music`, `no_sound_effects`, `no_transitions`, `no_motion_graphics`, ...) need the user's
81
+ approval in `--acknowledge`.
82
+ Your own footage: `cliptude upload-media <job> trailer.mp4 --split-shots` cuts a whole source into checked 3-12 s
83
+ clips on its cuts and prints their keep ids; each upload's notes say what the build review would report (a
84
+ watermark, an end screen, captions).
58
85
  2. `cliptude catalog --compact`, then `--types a,b` for full entries (`--premium` lists only the premium boards).
59
86
  3. `cliptude plan-check <job> plan.json` until valid, `cliptude plan-lock <job> plan.json`, `cliptude continue <job>`.
60
87
  The job stops at `ready_for_edit`: built and charged, not rendered.
@@ -64,11 +91,14 @@ only the voicing, sourcing and rendering:
64
91
  media reused, nothing more charged.
65
92
  6. Render once: `cliptude editor <job>`, `cliptude render <project> --wait`.
66
93
 
94
+ Aim for two builds: one to review, one to ship. The skill's "One pass" section has the order of work (footage budget,
95
+ sources split by shot, people's photos first, picture assignment by script, person-card caps).
96
+
67
97
  MCP tools: `create_plan_job`, `get_narration`, `get_kind_catalog`, `check_plan`, `lock_plan`, `get_plan`,
68
98
  `continue_job`, `get_plan_review`, `get_plan_report`, then `open_editor_project` and `render_project`.
69
99
  The plan sets the look (theme, style, colours, music), every graphic with its own data, colours and sound, the
70
100
  footage under every beat, the transition on each cut, two-image reveals, and free sound effects; `get_kind_catalog`
71
- lists the graphics, `transitions`, `reveal_styles` and `sounds` (with previews). The plan schema and rules are in
101
+ lists the graphics, `transitions`, `reveal_styles`, `clip_effects` and `sounds` (with previews). The plan schema and rules are in
72
102
  `skills/cliptude-plan/SKILL.md`. The job costs the same as the website price.
73
103
 
74
104
  ### Product videos from a store
@@ -0,0 +1,444 @@
1
+ """MCP Apps (interactive widgets) for hosts that render them: Claude Desktop, claude.ai, ChatGPT.
2
+
3
+ Spec: https://modelcontextprotocol.io/specification/draft/extensions/apps (SEP-1865, `io.modelcontextprotocol/ui`).
4
+
5
+ Each widget is a `ui://cliptude/...` HTML resource (served as `text/html;profile=mcp-app`) that the host shows in a
6
+ sandboxed iframe next to a tool's result:
7
+
8
+ - list_avatars -> ui://cliptude/avatars.html avatar thumbnails, pick one
9
+ - list_voices -> ui://cliptude/voices.html play voice previews, pick one
10
+ - list_vector_characters -> ui://cliptude/characters.html Vector Explainer cast and uploads, pick one
11
+ - get_render, show_video -> ui://cliptude/player.html watch the MP4, or "not rendered yet"
12
+ - show_choices -> ui://cliptude/choices.html music (play), backgrounds, style packs, themes, captions
13
+ - show_publish_kit -> ui://cliptude/publish-kit.html thumbnails, title ideas, description, chapters, tags
14
+ - list_templates -> ui://cliptude/templates.html template gallery, "Use this template"
15
+ - create_template, get_template
16
+ -> ui://cliptude/template.html one template's card: voice, presenter, music, look, switches
17
+ - create_job, create_plan_job, create_script, create_voiceover, continue_job, render_product_video,
18
+ draft_product_script, run_agent, render_project, create_avatar
19
+ -> ui://cliptude/review.html the 428 review to confirm (or the result card)
20
+ - get_job, get_product_video_status, get_narration
21
+ -> ui://cliptude/job.html progress card, the script to approve, or the publish kit
22
+
23
+ The existing tools keep their names, parameters and JSON (the text content stays the same for clients without
24
+ Apps); `bind_existing_tools` adds `_meta.ui.resourceUri` (plus ChatGPT's `openai/outputTemplate` alias) and tags a
25
+ 428 review with the tool that returned it (`tool`), so the review widget knows what to call again.
26
+
27
+ A widget picks by posting a `ui/message` into the chat ("Use the voice ... (voice_id ...)"), so the model gets the
28
+ id without the user typing it. Calls a widget makes itself (`tools/call`) happen only on the user's click: the
29
+ review widget's Confirm resends the reviewed call with its review_token, never on its own.
30
+ """
31
+
32
+ from __future__ import annotations
33
+
34
+ import functools
35
+ from collections.abc import Callable
36
+ from importlib import resources
37
+ from typing import Annotated, Any
38
+
39
+ from pydantic import Field
40
+
41
+ try: # mcp >= 2.3 ships the Apps extension; older SDKs simply serve no widgets.
42
+ from mcp.server.apps import APP_MIME_TYPE, Apps, ResourceCsp, ResourcePermissions
43
+ except ImportError: # pragma: no cover - exercised only on an old SDK
44
+ Apps = None # type: ignore[assignment,misc]
45
+ APP_MIME_TYPE = "text/html;profile=mcp-app"
46
+ ResourceCsp = ResourcePermissions = None # type: ignore[assignment,misc]
47
+
48
+ AVATARS_URI = "ui://cliptude/avatars.html"
49
+ VOICES_URI = "ui://cliptude/voices.html"
50
+ CHARACTERS_URI = "ui://cliptude/characters.html"
51
+ PLAYER_URI = "ui://cliptude/player.html"
52
+ CHOICES_URI = "ui://cliptude/choices.html"
53
+ PUBLISH_KIT_URI = "ui://cliptude/publish-kit.html"
54
+ TEMPLATES_URI = "ui://cliptude/templates.html"
55
+ TEMPLATE_URI = "ui://cliptude/template.html"
56
+ REVIEW_URI = "ui://cliptude/review.html"
57
+ JOB_URI = "ui://cliptude/job.html"
58
+
59
+ # uri -> (file, name, description)
60
+ WIDGETS: dict[str, tuple[str, str, str]] = {
61
+ AVATARS_URI: ("avatars.html", "Avatar picker", "Avatar thumbnails to pick the presenter of an Avatar Video."),
62
+ VOICES_URI: ("voices.html", "Voice picker", "Voice previews to listen to and pick a narration voice."),
63
+ CHARACTERS_URI: ("characters.html", "Character picker", "Vector Explainer characters to pick from."),
64
+ PLAYER_URI: ("player.html", "Video player", "Plays a finished Cliptude MP4, or shows that it is not rendered yet."),
65
+ CHOICES_URI: ("choices.html", "Setting picker", "Previews of music, backgrounds and styles to pick a template setting."),
66
+ PUBLISH_KIT_URI: ("publish-kit.html", "Publish kit", "Thumbnails, title ideas, description, chapters and tags."),
67
+ TEMPLATES_URI: ("templates.html", "Templates", "The user's saved templates, to pick one for a video."),
68
+ TEMPLATE_URI: ("template.html", "Template", "One template: voice, presenter, music, background, style and switches."),
69
+ REVIEW_URI: ("review.html", "Review and confirm", "What a job or spend does and costs, for the user to confirm."),
70
+ JOB_URI: ("job.html", "Job", "A job's progress, its script to approve, or its publish kit when ready."),
71
+ }
72
+
73
+ # Tools whose first call answers with a 428 review (detail.review + review_token) before they spend credits.
74
+ REVIEW_TOOLS: tuple[str, ...] = (
75
+ "create_job", "create_plan_job", "create_script", "create_voiceover", "continue_job", "render_product_video",
76
+ "draft_product_script", "run_agent", "render_project", "create_avatar",
77
+ )
78
+ # Of those, the ones that take acknowledge ids (the job review's acknowledgements_required).
79
+ ACKNOWLEDGE_TOOLS: frozenset[str] = frozenset({
80
+ "create_job", "create_plan_job", "create_script", "create_voiceover", "draft_product_script",
81
+ })
82
+
83
+ # Existing tools that get a widget, by name.
84
+ BOUND_TOOLS: dict[str, str] = {
85
+ "list_avatars": AVATARS_URI,
86
+ "list_voices": VOICES_URI,
87
+ "list_vector_characters": CHARACTERS_URI,
88
+ "get_render": PLAYER_URI,
89
+ "list_templates": TEMPLATES_URI,
90
+ "create_template": TEMPLATE_URI,
91
+ "get_template": TEMPLATE_URI,
92
+ "get_job": JOB_URI,
93
+ "get_product_video_status": JOB_URI,
94
+ "get_narration": JOB_URI,
95
+ **{name: REVIEW_URI for name in REVIEW_TOOLS},
96
+ }
97
+
98
+ # Tools a widget calls itself (tools/call). ChatGPT wants openai/widgetAccessible on them.
99
+ WIDGET_CALLED_TOOLS: frozenset[str] = frozenset({
100
+ *REVIEW_TOOLS, "list_avatars", "design_voice_previews", "save_designed_voice", "clone_voice", "show_publish_kit",
101
+ })
102
+
103
+ # ChatGPT's short status lines while a widget tool runs and after (openai/toolInvocation/*, at most 64 chars).
104
+ INVOCATION_TEXT: dict[str, tuple[str, str]] = {
105
+ "list_avatars": ("Loading avatars…", "Avatars ready"),
106
+ "list_voices": ("Loading voices…", "Voices ready"),
107
+ "list_vector_characters": ("Loading characters…", "Characters ready"),
108
+ "get_render": ("Checking the export…", "Export checked"),
109
+ "show_video": ("Loading the video…", "Video ready"),
110
+ "show_choices": ("Loading choices…", "Choices ready"),
111
+ "show_publish_kit": ("Opening the publish kit…", "Publish kit ready"),
112
+ "list_templates": ("Loading templates…", "Templates ready"),
113
+ "create_template": ("Saving the template…", "Template saved"),
114
+ "get_template": ("Loading the template…", "Template ready"),
115
+ "get_job": ("Checking the job…", "Job checked"),
116
+ "get_product_video_status": ("Checking the product video…", "Product video checked"),
117
+ "get_narration": ("Loading the narration…", "Narration ready"),
118
+ **{name: ("Preparing the review…", "Review ready") for name in REVIEW_TOOLS},
119
+ }
120
+
121
+ # Where the widgets' pictures, audio and video come from (CSP img-src/media-src via resourceDomains).
122
+ MEDIA_DOMAINS: tuple[str, ...] = (
123
+ # Avatar previews (videos/avatar_preview.py: HeyGen thumbnails proxied and signed, because HeyGen's own
124
+ # files2.heygen.ai links answer 403 to browsers), built-in Vector characters (/static/vector_explainer/),
125
+ # uploaded characters (/media/), library music (/static/music/), thumbnails not yet on the CDN (/media/).
126
+ "https://cliptude.com",
127
+ "https://www.cliptude.com",
128
+ # Public R2 bucket: library background thumbnails, generated thumbnails, uploaded backgrounds, samples.
129
+ "https://cdn.cliptude.com",
130
+ # Signed MP4 links of finished videos and editor renders (private R2 bucket, videos/r2_storage.py).
131
+ "https://*.r2.cloudflarestorage.com",
132
+ # Voice previews: ElevenLabs (shared-library previews on storage.googleapis.com/eleven-public-prod and the
133
+ # API host), Cartesia (preview_file_url), Voicetory (preview_audio). MiniMax and Inworld have none.
134
+ "https://storage.googleapis.com",
135
+ "https://api.us.elevenlabs.io",
136
+ "https://api.elevenlabs.io",
137
+ "https://files.cartesia.ai",
138
+ "https://voicetory.com",
139
+ )
140
+ # The Desktop app serves its own media on a random localhost port (stdio MCP only).
141
+ LOCAL_MEDIA_DOMAINS: tuple[str, ...] = ("http://127.0.0.1:*", "http://localhost:*")
142
+
143
+ # show_choices: field -> (kind the widget draws, heading)
144
+ CHOICE_FIELDS: dict[str, tuple[str, str]] = {
145
+ "background_music_library_file": ("music", "Background music"),
146
+ "background_image": ("image", "Background"),
147
+ "faceless_documentary_style": ("style", "Style pack"),
148
+ "visual_theme": ("theme", "Visual theme"),
149
+ "caption_style": ("caption", "Caption style"),
150
+ "vector_illustration_style": ("text", "Illustration style"),
151
+ "vector_reveal_mode": ("text", "Motion"),
152
+ }
153
+ # Fields an agent-planned video also sets in its plan's look.
154
+ _PLAN_LOOK_FIELDS = frozenset({"background_music_library_file", "visual_theme", "faceless_documentary_style"})
155
+
156
+
157
+ def _permissions() -> dict[str, Any]:
158
+ if ResourcePermissions is None:
159
+ return {}
160
+ return {
161
+ # Copy buttons (titles, description, tags) use the Clipboard API.
162
+ PUBLISH_KIT_URI: ResourcePermissions(clipboard_write={}),
163
+ # "Clone a voice" can record a sample in the widget; uploading a file works without it.
164
+ VOICES_URI: ResourcePermissions(microphone={}),
165
+ }
166
+
167
+
168
+ _PERMISSIONS = _permissions()
169
+
170
+
171
+ def apps_available() -> bool:
172
+ return Apps is not None
173
+
174
+
175
+ def widget_html(file_name: str) -> str:
176
+ """A widget's HTML with the shared bridge and stylesheet inlined (no external script or style)."""
177
+ pkg = resources.files("cliptude_mcp") / "widgets"
178
+ html = (pkg / file_name).read_text(encoding="utf-8")
179
+ bridge = (pkg / "bridge.js").read_text(encoding="utf-8")
180
+ css = (pkg / "base.css").read_text(encoding="utf-8")
181
+ views = (pkg / "views.js").read_text(encoding="utf-8")
182
+ html = html.replace("/*@BASE_CSS@*/", css).replace("/*@BRIDGE_JS@*/", bridge)
183
+ return html.replace("/*@VIEWS_JS@*/", views)
184
+
185
+
186
+ def media_domains(*, local: bool) -> list[str]:
187
+ return list(MEDIA_DOMAINS) + (list(LOCAL_MEDIA_DOMAINS) if local else [])
188
+
189
+
190
+ def _openai_meta(name: str, uri: str) -> dict[str, Any]:
191
+ """ChatGPT's aliases (Apps SDK reference): it reads `_meta.ui.resourceUri` too, and documents these."""
192
+ meta: dict[str, Any] = {"openai/outputTemplate": uri}
193
+ invoking, invoked = INVOCATION_TEXT.get(name, ("", ""))
194
+ if invoking:
195
+ meta["openai/toolInvocation/invoking"] = invoking[:64]
196
+ meta["openai/toolInvocation/invoked"] = invoked[:64]
197
+ if name in WIDGET_CALLED_TOOLS:
198
+ meta["openai/widgetAccessible"] = True
199
+ return meta
200
+
201
+
202
+ def _ui_meta(uri: str, name: str = "") -> dict[str, Any]:
203
+ # `ui.resourceUri` is the spec's key; the flat `ui/resourceUri` is its deprecated form, kept for hosts that
204
+ # shipped before the rename.
205
+ return {"ui": {"resourceUri": uri}, "ui/resourceUri": uri, **_openai_meta(name, uri)}
206
+
207
+
208
+ def _resource_meta(uri: str, description: str, *, local: bool) -> dict[str, Any]:
209
+ """`_meta` of a widget resource: the spec's `ui` block plus ChatGPT's openai/widget* aliases."""
210
+ domains = media_domains(local=local)
211
+ ui: dict[str, Any] = {"csp": ResourceCsp(resource_domains=domains).model_dump(by_alias=True, exclude_none=True)}
212
+ permissions = _PERMISSIONS.get(uri)
213
+ if permissions is not None:
214
+ ui["permissions"] = permissions.model_dump(by_alias=True, exclude_none=True)
215
+ ui["prefersBorder"] = True
216
+ return {
217
+ "ui": ui,
218
+ # The widgets fetch nothing themselves (no connect_domains); pictures, audio and video come from these.
219
+ "openai/widgetCSP": {"connect_domains": [], "resource_domains": domains},
220
+ "openai/widgetDescription": description,
221
+ "openai/widgetPrefersBorder": True,
222
+ }
223
+
224
+
225
+ def build_apps(
226
+ client: Callable[[], Any],
227
+ err: Callable[[Exception], dict[str, Any]],
228
+ *,
229
+ local: bool,
230
+ ):
231
+ """The Apps extension with every widget resource and the new show_* tools; None on an SDK without Apps."""
232
+ if Apps is None:
233
+ return None
234
+ from mcp.types import ToolAnnotations
235
+
236
+ from mcp.server.mcpserver.resources import TextResource
237
+
238
+ apps = Apps()
239
+ for uri, (file_name, name, description) in WIDGETS.items():
240
+ apps.add_resource(
241
+ TextResource(
242
+ uri=uri,
243
+ name=name,
244
+ title=name,
245
+ description=description,
246
+ mime_type=APP_MIME_TYPE,
247
+ meta=_resource_meta(uri, description, local=local),
248
+ text=widget_html(file_name),
249
+ )
250
+ )
251
+
252
+ @apps.tool(
253
+ resource_uri=CHOICES_URI,
254
+ meta={"ui/resourceUri": CHOICES_URI, **_openai_meta("show_choices", CHOICES_URI)},
255
+ name="show_choices",
256
+ title="Show setting choices",
257
+ annotations=ToolAnnotations(title="Show setting choices", read_only_hint=True, open_world_hint=False),
258
+ )
259
+ def show_choices(
260
+ format: Annotated[str, Field(description="Video format, e.g. faceless_documentary or vector_explainer")],
261
+ field: Annotated[
262
+ str,
263
+ Field(description="Setting to choose: " + ", ".join(CHOICE_FIELDS)),
264
+ ],
265
+ ) -> dict[str, Any]:
266
+ """Let the user preview and pick one template setting: background music (play each track), background picture, style pack (colour swatches), visual theme, caption style, or the Vector Explainer illustration style / motion. In hosts that show apps the user picks in a widget and the choice arrives as their message; otherwise read choices and ask. Returns {field, choices:[{value, label, ...preview links}], default, usage}."""
267
+ field = (field or "").strip()
268
+ if field not in CHOICE_FIELDS:
269
+ return {"error": f"field must be one of: {', '.join(CHOICE_FIELDS)}"}
270
+ try:
271
+ options = client().template_options(format)
272
+ except Exception as exc:
273
+ return err(exc)
274
+ return choices_payload(options, format, field)
275
+
276
+ @apps.tool(
277
+ resource_uri=PLAYER_URI,
278
+ meta={"ui/resourceUri": PLAYER_URI, **_openai_meta("show_video", PLAYER_URI)},
279
+ name="show_video",
280
+ title="Show video",
281
+ annotations=ToolAnnotations(title="Show video", read_only_hint=True, open_world_hint=False),
282
+ )
283
+ def show_video(
284
+ job_id: Annotated[str, Field(min_length=8, description="Job / video UUID")],
285
+ ) -> dict[str, Any]:
286
+ """Show a finished job's MP4 in a player the user can watch in the chat (hosts that show apps), with an open link. For an edited video, get_render shows its export the same way. Returns {job_id, title, status, url}; url is empty until the video is ready."""
287
+ try:
288
+ job = client().get_job(job_id)
289
+ except Exception as exc:
290
+ return err(exc)
291
+ return video_payload(job, job_id)
292
+
293
+ @apps.tool(
294
+ resource_uri=PUBLISH_KIT_URI,
295
+ meta={"ui/resourceUri": PUBLISH_KIT_URI, **_openai_meta("show_publish_kit", PUBLISH_KIT_URI)},
296
+ name="show_publish_kit",
297
+ title="Show publish kit",
298
+ annotations=ToolAnnotations(title="Show publish kit", read_only_hint=False, destructive_hint=False, open_world_hint=False),
299
+ )
300
+ def show_publish_kit(
301
+ job_id: Annotated[str, Field(min_length=8, description="Completed video job id")],
302
+ ) -> dict[str, Any]:
303
+ """The finished video in a player, then its generated thumbnails, title ideas, YouTube description, chapters and tags with copy buttons (hosts that show apps). Call it as soon as a video is ready (rendered, or built and waiting for review): it is the one place the user watches the video and gets everything to publish it. Opens the video's editor project like open_editor_project. Returns {job_id, project_id, title, video, thumbnails, publish_metadata}; video.url is the latest export, else the job's own MP4, empty until one exists."""
304
+ try:
305
+ data = client().open_editor_project(job_id)
306
+ except Exception as exc:
307
+ return err(exc)
308
+ payload = publish_kit_payload(data, job_id)
309
+ if not payload.get("error") and not (payload.get("video") or {}).get("url"):
310
+ try:
311
+ job = client().get_job(job_id)
312
+ except Exception:
313
+ job = None
314
+ output = job.get("output") if isinstance(job, dict) and isinstance(job.get("output"), dict) else {}
315
+ if output.get("url"):
316
+ payload["video"] = {"url": output["url"], "source": "original", "note": ""}
317
+ return payload
318
+
319
+ return apps
320
+
321
+
322
+ def _tag_reviews(tool: Any, name: str) -> None:
323
+ """A 428 review result also names the tool that returned it, so the review widget can call it again."""
324
+ original = tool.fn
325
+ if getattr(original, "_cliptude_tagged", False) or getattr(tool, "is_async", False):
326
+ return
327
+
328
+ @functools.wraps(original)
329
+ def tagged(*args: Any, **kwargs: Any) -> Any:
330
+ result = original(*args, **kwargs)
331
+ if isinstance(result, dict) and result.get("status") == 428 and "tool" not in result:
332
+ return {**result, "tool": name}
333
+ return result
334
+
335
+ tagged._cliptude_tagged = True # type: ignore[attr-defined]
336
+ tool.fn = tagged
337
+
338
+
339
+ def bind_existing_tools(mcp: Any) -> list[str]:
340
+ """Stamp `_meta.ui.resourceUri` on the existing tools that have a widget; returns the names bound.
341
+
342
+ The tools are registered by server.py (and creation.py) as before, so their names and parameters do not
343
+ change; a 428 review also says which tool returned it (`tool`).
344
+ """
345
+ manager = getattr(mcp, "_tool_manager", None)
346
+ bound = []
347
+ for name, uri in BOUND_TOOLS.items():
348
+ tool = manager.get_tool(name) if manager is not None else None
349
+ if tool is None:
350
+ continue
351
+ tool.meta = {**(tool.meta or {}), **_ui_meta(uri, name)}
352
+ if name in REVIEW_TOOLS:
353
+ _tag_reviews(tool, name)
354
+ bound.append(name)
355
+ for name in sorted(WIDGET_CALLED_TOOLS - set(BOUND_TOOLS)):
356
+ tool = manager.get_tool(name) if manager is not None else None
357
+ if tool is not None:
358
+ tool.meta = {**(tool.meta or {}), "openai/widgetAccessible": True}
359
+ return bound
360
+
361
+
362
+ def choices_payload(options: Any, format_value: str, field: str) -> dict[str, Any]:
363
+ kind, label = CHOICE_FIELDS[field]
364
+ if not isinstance(options, dict):
365
+ return {"error": "Cliptude returned no template options."}
366
+ if options.get("error"):
367
+ return options
368
+ entry = (options.get("fields") or {}).get(field)
369
+ if not isinstance(entry, dict):
370
+ return {"error": f"{format_value} templates have no {field} setting."}
371
+ details = entry.get("choice_details")
372
+ if not isinstance(details, list): # An older Cliptude server: values only.
373
+ details = [{"value": value, "label": str(value)} for value in entry.get("choices") or []]
374
+ usage = f"Set {field} in create_template settings"
375
+ usage += " (or in the plan's look on an agent-planned video)." if field in _PLAN_LOOK_FIELDS else "."
376
+ if field == "background_music_library_file":
377
+ usage += " With it, set background_music_mode to library; none means no music."
378
+ return {
379
+ "format": format_value,
380
+ "field": field,
381
+ "kind": kind,
382
+ "label": label,
383
+ "description": entry.get("description") or entry.get("note") or "",
384
+ "default": entry.get("default"),
385
+ "current": entry.get("default"),
386
+ "choices": details,
387
+ "usage": usage,
388
+ }
389
+
390
+
391
+ def video_payload(job: Any, job_id: str) -> dict[str, Any]:
392
+ if not isinstance(job, dict):
393
+ return {"error": "Cliptude returned no job."}
394
+ if job.get("error") and not job.get("status"):
395
+ return job
396
+ output = job.get("output") if isinstance(job.get("output"), dict) else {}
397
+ return {
398
+ "job_id": str(job.get("id") or job.get("job_id") or job_id),
399
+ "title": job.get("title") or "",
400
+ "status": job.get("status") or "",
401
+ "progress": job.get("progress"),
402
+ "current_step": job.get("current_step") or "",
403
+ "error": job.get("error") or "",
404
+ "url": output.get("url") or "",
405
+ "path": output.get("path") or "",
406
+ "note": (
407
+ "Saved on this computer: open path." if output.get("path") and not output.get("url") else ""
408
+ ),
409
+ }
410
+
411
+
412
+ def _project_video(project: dict[str, Any]) -> dict[str, Any]:
413
+ """The newest finished export of the editor project, for the publish kit's player."""
414
+ render = project.get("latest_render") if isinstance(project.get("latest_render"), dict) else {}
415
+ url = ""
416
+ if str(render.get("status") or "completed").lower() == "completed":
417
+ url = str(render.get("output_url") or project.get("latest_render_url") or "")
418
+ if url:
419
+ return {"url": url, "source": "export", "note": ""}
420
+ note = "Not rendered yet: render_project makes the MP4." if render.get("status") not in (None, "", "completed") else ""
421
+ return {"url": "", "source": "", "note": note}
422
+
423
+
424
+ def publish_kit_payload(data: Any, job_id: str) -> dict[str, Any]:
425
+ if not isinstance(data, dict):
426
+ return {"error": "Cliptude returned no editor project."}
427
+ if data.get("error"):
428
+ return data
429
+ project = data.get("project") if isinstance(data.get("project"), dict) else data
430
+ meta = project.get("publish_metadata") if isinstance(project.get("publish_metadata"), dict) else {}
431
+ return {
432
+ "job_id": job_id,
433
+ "project_id": project.get("id"),
434
+ "title": project.get("title") or "",
435
+ "video": _project_video(project),
436
+ "thumbnails": project.get("thumbnails") or {"status": "", "items": []},
437
+ "publish_metadata": {
438
+ "title_variants": meta.get("title_variants") or [],
439
+ "description": meta.get("description") or "",
440
+ "chapters": meta.get("chapters") or "",
441
+ "tags": meta.get("tags") or [],
442
+ "downloads": meta.get("downloads") or {},
443
+ },
444
+ }