@cliptude/cli 0.1.16 → 0.1.17

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.
@@ -15,6 +15,48 @@ def _print(payload) -> None:
15
15
  sys.stdout.write("\n")
16
16
 
17
17
 
18
+ def _add_review_args(parser) -> None:
19
+ parser.add_argument("--review-token", default="", help="Token from the job review (shown when you run without it)")
20
+ parser.add_argument(
21
+ "--acknowledge", action="append", default=[],
22
+ help="An item from acknowledgements_required the user approved, e.g. no_general_web_content (repeatable)",
23
+ )
24
+
25
+
26
+ def _create_reviewed(client: CliptudeClient, args, **kwargs):
27
+ """create_job behind the job review: in a terminal, show it and ask; otherwise print it and stop.
28
+
29
+ Cliptude answers a job without a review_token with the review (HTTP 428) and creates nothing.
30
+ """
31
+ token = (getattr(args, "review_token", "") or "").strip() or None
32
+ acks = [a.strip() for raw in (getattr(args, "acknowledge", None) or []) for a in raw.split(",") if a.strip()]
33
+ try:
34
+ return client.create_job(review_token=token, acknowledge=acks or None, **kwargs)
35
+ except CliptudeApiError as exc:
36
+ detail = exc.payload if isinstance(exc.payload, dict) else {}
37
+ if exc.status != 428 or "review" not in detail or not sys.stdin.isatty():
38
+ raise
39
+ review = detail["review"]
40
+ out = sys.stderr
41
+ out.write("\nReview this video before it is created:\n")
42
+ for item in review.get("settings") or []:
43
+ out.write(f" {item.get('label')}: {item.get('value')}\n")
44
+ credits = review.get("credits") or {}
45
+ if credits.get("credits_required") is not None:
46
+ out.write(f" Credits: about {credits['credits_required']} (you have {credits.get('credits_available')})\n")
47
+ for warning in review.get("warnings") or []:
48
+ out.write(f" ! {warning}\n")
49
+ approved = []
50
+ for ack in review.get("acknowledgements_required") or []:
51
+ out.write(f"\n {ack['message']}\n")
52
+ if input(f" Approve ({ack['id']})? [y/N] ").strip().lower() != "y":
53
+ raise CliptudeApiError("Not created: change the template and run again.")
54
+ approved.append(ack["id"])
55
+ if input("\nCreate this video? [y/N] ").strip().lower() != "y":
56
+ raise CliptudeApiError("Not created.")
57
+ return client.create_job(review_token=detail["review_token"], acknowledge=approved or None, **kwargs)
58
+
59
+
18
60
  def _die(exc: Exception, code: int = 1) -> None:
19
61
  if isinstance(exc, CliptudeApiError):
20
62
  _print({"error": str(exc), "status": exc.status, "detail": exc.payload})
@@ -543,6 +585,8 @@ def main(argv: list[str] | None = None) -> None:
543
585
  c = sub.add_parser("cancel", help="Cancel a job")
544
586
  c.add_argument("job_id")
545
587
 
588
+ for job_parser in (g, sc, vo, pj):
589
+ _add_review_args(job_parser)
546
590
  args = parser.parse_args(argv)
547
591
  if args.cmd == "auth":
548
592
  _run_auth(args.auth_cmd)
@@ -624,7 +668,7 @@ def main(argv: list[str] | None = None) -> None:
624
668
  "Provide --prompt, --script / --script-file, --voiceover, or --talking-head."
625
669
  )
626
670
  template_id = _resolve_template_id(client, args.template)
627
- _print(client.create_job(
671
+ _print(_create_reviewed(client, args,
628
672
  template_id=template_id,
629
673
  title=args.title,
630
674
  prompt=args.prompt or None,
@@ -652,7 +696,7 @@ def main(argv: list[str] | None = None) -> None:
652
696
  if not (args.prompt or "").strip():
653
697
  raise CliptudeApiError("Provide --prompt.")
654
698
  template_id = _resolve_template_id(client, args.template)
655
- _print(client.create_job(
699
+ _print(_create_reviewed(client, args,
656
700
  template_id=template_id,
657
701
  title=args.title,
658
702
  prompt=args.prompt,
@@ -666,7 +710,7 @@ def main(argv: list[str] | None = None) -> None:
666
710
  if not (args.prompt or "").strip() and not (script or "").strip():
667
711
  raise CliptudeApiError("Provide --prompt or --script / --script-file.")
668
712
  template_id = _resolve_template_id(client, args.template)
669
- _print(client.create_job(
713
+ _print(_create_reviewed(client, args,
670
714
  template_id=template_id,
671
715
  title=args.title,
672
716
  prompt=args.prompt or None,
@@ -683,7 +727,7 @@ def main(argv: list[str] | None = None) -> None:
683
727
  if not (args.prompt or "").strip() and not (script or "").strip() and not voiceover and not voiceover_url:
684
728
  raise CliptudeApiError("Provide --prompt, --script / --script-file, --voiceover or --voiceover-url.")
685
729
  template_id = _resolve_template_id(client, args.template)
686
- _print(client.create_job(
730
+ _print(_create_reviewed(client, args,
687
731
  template_id=template_id,
688
732
  title=args.title,
689
733
  prompt=args.prompt or None,
@@ -149,6 +149,19 @@ def _avatar_job_fields(
149
149
  return fields
150
150
 
151
151
 
152
+ def _review_job_fields(review_token: str | None, acknowledge: list[str] | None, review_only: bool | None,
153
+ *, as_strings: bool = False) -> dict[str, Any]:
154
+ """The job review: Cliptude answers a job without a review_token with the review (HTTP 428)."""
155
+ out: dict[str, Any] = {}
156
+ if review_token:
157
+ out["review_token"] = str(review_token)
158
+ if acknowledge:
159
+ out["acknowledge"] = ",".join(acknowledge) if as_strings else list(acknowledge)
160
+ if review_only:
161
+ out["review_only"] = "true" if as_strings else True
162
+ return out
163
+
164
+
152
165
  def _thumbnail_job_field(thumbnail: dict[str, str] | None, *, as_string: bool = False) -> dict[str, Any]:
153
166
  """create_job's per-job thumbnail ({custom_prompt} or {reference_url}); multipart sends it as JSON text."""
154
167
  cleaned = {k: str(v).strip() for k, v in (thumbnail or {}).items() if v is not None and str(v).strip()}
@@ -309,6 +322,9 @@ class CliptudeClient:
309
322
  vector_character_id: str | None = None,
310
323
  vector_reveal_mode: str | None = None,
311
324
  pronunciations: list[dict[str, str]] | None = None,
325
+ review_token: str | None = None,
326
+ acknowledge: list[str] | None = None,
327
+ review_only: bool | None = None,
312
328
  ) -> Any:
313
329
  if voiceover_path and voiceover_url:
314
330
  raise CliptudeApiError("Give voiceover_path or voiceover_url, not both.")
@@ -369,6 +385,7 @@ class CliptudeClient:
369
385
  excluded_animation_types=excluded_animation_types,
370
386
  excluded_transition_kinds=excluded_transition_kinds,
371
387
  thumbnail=thumbnail,
388
+ review=_review_job_fields(review_token, acknowledge, review_only),
372
389
  )
373
390
  if vo_path:
374
391
  extra_data = {
@@ -383,6 +400,7 @@ class CliptudeClient:
383
400
  **({"vector_character_id": str(vector_character_id)} if vector_character_id else {}),
384
401
  **({"vector_reveal_mode": str(vector_reveal_mode)} if vector_reveal_mode else {}),
385
402
  **({"pronunciations": json.dumps(pronunciations)} if pronunciations is not None else {}),
403
+ **_review_job_fields(review_token, acknowledge, review_only, as_strings=True),
386
404
  }
387
405
  return self._create_job_multipart(
388
406
  template_id=template_id,
@@ -419,6 +437,7 @@ class CliptudeClient:
419
437
  body["vector_reveal_mode"] = str(vector_reveal_mode)
420
438
  if pronunciations is not None:
421
439
  body["pronunciations"] = pronunciations
440
+ body.update(_review_job_fields(review_token, acknowledge, review_only))
422
441
  return self.request("POST", "/api/v1/jobs", json_body=body)
423
442
 
424
443
  def _raise_http(self, resp, *, payload=None) -> None:
@@ -515,7 +534,11 @@ class CliptudeClient:
515
534
  excluded_animation_types: list[str] | None = None,
516
535
  excluded_transition_kinds: list[str] | None = None,
517
536
  thumbnail: dict[str, str] | None = None,
537
+ review: dict[str, Any] | None = None,
518
538
  ) -> Any:
539
+ review = review or {}
540
+ review_strings = {k: (",".join(v) if isinstance(v, list) else ("true" if v is True else v))
541
+ for k, v in review.items()}
519
542
  motion_extra = _motion_control_job_fields(
520
543
  disable_animations=disable_animations,
521
544
  disable_overlays=disable_overlays,
@@ -549,6 +572,7 @@ class CliptudeClient:
549
572
  **_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
550
573
  **motion_extra,
551
574
  **_thumbnail_job_field(thumbnail, as_string=True),
575
+ **review_strings,
552
576
  }
553
577
  return self._create_job_multipart(
554
578
  template_id=template_id,
@@ -567,6 +591,7 @@ class CliptudeClient:
567
591
  **_avatar_job_fields(avatar_intro_only, avatar_ai_footage, as_strings=True),
568
592
  **motion_extra,
569
593
  **_thumbnail_job_field(thumbnail, as_string=True),
594
+ **review_strings,
570
595
  }
571
596
  return self._create_job_multipart(
572
597
  template_id=template_id,
@@ -605,6 +630,7 @@ class CliptudeClient:
605
630
  excluded_transition_kinds=excluded_transition_kinds,
606
631
  )
607
632
  )
633
+ body.update(review)
608
634
  return self.request("POST", "/api/v1/jobs", json_body=body)
609
635
 
610
636
  def _upload_talking_head_parts(self, path: Path, init: dict[str, Any]) -> None:
@@ -127,15 +127,33 @@ def build_server(*, with_http_auth: bool = False):
127
127
  "Avatar Video templates may include avatar_intro_only "
128
128
  "(Avatar Intro Only) and avatar_ai_footage (AI Image + AI Video); pass those "
129
129
  "on create_job to override the template, or omit them to keep the template. "
130
+ "REVIEW BEFORE EVERY JOB: create_job, create_plan_job, create_script and create_voiceover first return "
131
+ "a review (status 428, detail.review) and create nothing. Show the user every setting in it in plain "
132
+ "words (voice, model tier, media sources incl. general web crawling, animations/motion graphics, charts, "
133
+ "overlays, transitions, sound effects, music, A-roll) plus every warning and the credits, and ask them to "
134
+ "confirm. Then call the same tool again with the same arguments and review_token. For each item in "
135
+ "detail.review.acknowledgements_required (no_general_web_content: no YouTube or general web content, which "
136
+ "can lower video quality a lot; no_video_footage; no_motion_graphics) tell the user what it costs and pass "
137
+ "its id in acknowledge only after they explicitly approve; otherwise fix the template. "
130
138
  "AGENT-PLANNED VIDEOS (Faceless Documentary, Top 10, Avatar Video): you plan every visual "
131
139
  "and Cliptude only voices, sources and renders. create_plan_job, poll get_job until "
132
140
  "plan_ready, get_narration (numbered sentences), get_kind_catalog (compact first), write the "
133
- "plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. See the "
141
+ "plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. Before giving the user "
142
+ "the editor link, open_editor_project and look at EVERY frame with view_scenes (0 to the end): replace "
143
+ "any dead body or gore, other brands, logos, game or album art, title cards, pictures whose place or era "
144
+ "contradicts the story, and any picture held over ~8 s, in a free revision, then review again. Generic "
145
+ "shots of places name the story's setting (\"empty bed mud house\", not \"empty bed dark room\"). True "
146
+ "stories (real events and people) set sense.true_story and sense.people and never search for people: a "
147
+ "stranger on screen is taken for the real person (check_plan refuses it, stand_in_person; a dated topic "
148
+ "naming people counts as true unless true_story is false, and its year is the default era). See the "
134
149
  "cliptude-plan skill. Avatar Video and Talking Head plans never show the presenter only in "
135
150
  "full screen: make about one in four presenter_windows split_left/split_right with collage_media and "
136
151
  "put a speaker board (talking_head_*, dual_metric_talking_head) in most full-screen windows; check_plan "
137
152
  "refuses all-full-screen windows (presenter_only_full_screen). Treat presenter_no_speaker_boards, "
138
153
  "presenter_no_splits, kind_overused, over_cap and few_board_pictures warnings as must-fix. "
154
+ "On footage videos also fix query_too_long, query_style_words and same_subject_searches (write each "
155
+ "query as 2-5 words naming the subject, as clips are titled, and put the shot in intent), and on "
156
+ "video_needs_web_crawling ask the user to turn on General Web Crawling before building. "
139
157
  "PRODUCT VIDEOS (the user's connected store, or a product page from a store they sell for): "
140
158
  "fetch_product_context, show the user the 3 angles, draft_product_script with their pick and a "
141
159
  "duration (6-8 to 50-60 minutes), poll get_product_video_status until script_ready, let the user "
@@ -221,7 +239,10 @@ def build_server(*, with_http_auth: bool = False):
221
239
  Field(
222
240
  description=(
223
241
  "Wizard settings: voice_id, voice_name, voice_provider plus any field from "
224
- "get_template_options (unset fields take the wizard defaults). "
242
+ "get_template_options (unset fields take the wizard defaults). Set only what the user asked for: "
243
+ "each field's description says what turning it on or off does, and the source and graphics "
244
+ "switches (source_general_web_crawling, enable_broll_stock_footage, enable_animations, ...) "
245
+ "decide whether the video can have real footage and boards at all. "
225
246
  "Avatar Video: avatar_profile_id from list_avatars (gender must match the voice). "
226
247
  "Vector Explainer: vector_character_id from get_template_options (vector_character.choices: "
227
248
  "a built-in id such as nova, or one of the user's uploaded figures); omit it for no character. "
@@ -232,7 +253,7 @@ def build_server(*, with_http_auth: bool = False):
232
253
  ),
233
254
  ],
234
255
  ) -> dict[str, Any]:
235
- """Create a ready-to-use template without the create wizard. Values are validated like the wizard; returns the template (use its id in create_job)."""
256
+ """Create a ready-to-use template without the create wizard. Values are validated like the wizard; returns the template (use its id in create_job) and `warnings`: choices that will change what the video can show (no footage, AI stills, no graphics). Tell the user every warning in plain words and fix the ones they did not ask for before making a video."""
236
257
  try:
237
258
  return _client().create_template(name=name, format=format, settings=settings)
238
259
  except Exception as exc:
@@ -477,6 +498,14 @@ def build_server(*, with_http_auth: bool = False):
477
498
  list[dict[str, str]] | None,
478
499
  Field(description='How the voice says hard words (ElevenLabs voices): [{"word": "Gmay", "alias": "guh-MAY"}] or [{"word": "Ordnung", "phoneme": "ˈɔɹt.nʊŋ", "alphabet": "ipa"}]. Script, captions and searches keep the real spelling. Replaces the template\'s list for this video; omit to keep it.'),
479
500
  ] = None,
501
+ review_token: Annotated[
502
+ str | None,
503
+ Field(description="From the review this tool returned when called without it (status 428, detail.review_token). Only send it after showing the user every setting and warning in detail.review and getting their confirmation."),
504
+ ] = None,
505
+ acknowledge: Annotated[
506
+ list[str] | None,
507
+ Field(description="Ids from detail.review.acknowledgements_required (e.g. no_general_web_content) that the user explicitly approved after you explained each one. Never fill these in yourself."),
508
+ ] = None,
480
509
  ) -> dict[str, Any]:
481
510
  """Start generation and return a job id immediately. Do not wait for the MP4. Poll get_job. Provide prompt, script, voiceover_path, or talking_head_path. Never copy the title into prompt; for a topic-only request write a spoken script after web search and pass script. Uploaded audio or talking-head video is transcribed. Avatar Video: optional avatar_intro_only and avatar_ai_footage override the template. Any format: optional disable_animations/disable_overlays/disable_effects/disable_transitions and excluded_animation_types/excluded_transition_kinds override the template's motion & effects settings."""
482
511
  try:
@@ -496,6 +525,8 @@ def build_server(*, with_http_auth: bool = False):
496
525
  )
497
526
  }
498
527
  return _client().create_job(
528
+ review_token=review_token,
529
+ acknowledge=acknowledge,
499
530
  template_id=template_id,
500
531
  title=title,
501
532
  prompt=prompt,
@@ -534,10 +565,20 @@ def build_server(*, with_http_auth: bool = False):
534
565
  str | None,
535
566
  Field(description="Wizard duration bucket such as 3-4 or 6-8. Omit to use the template."),
536
567
  ] = None,
568
+ review_token: Annotated[
569
+ str | None,
570
+ Field(description="From the review this tool returned when called without it (status 428, detail.review_token). Only send it after showing the user every setting and warning in detail.review and getting their confirmation."),
571
+ ] = None,
572
+ acknowledge: Annotated[
573
+ list[str] | None,
574
+ Field(description="Ids from detail.review.acknowledgements_required (e.g. no_general_web_content) that the user explicitly approved after you explained each one. Never fill these in yourself."),
575
+ ] = None,
537
576
  ) -> dict[str, Any]:
538
577
  """Start a script-only job (no MP4). Returns a job id immediately. Poll get_job until completed; read script. Do not use create_job."""
539
578
  try:
540
579
  return _client().create_job(
580
+ review_token=review_token,
581
+ acknowledge=acknowledge,
541
582
  template_id=template_id,
542
583
  title=title,
543
584
  prompt=prompt,
@@ -560,12 +601,22 @@ def build_server(*, with_http_auth: bool = False):
560
601
  str | None,
561
602
  Field(description="Wizard duration bucket such as 3-4 or 6-8. Omit to use the template (or estimate from script)."),
562
603
  ] = None,
604
+ review_token: Annotated[
605
+ str | None,
606
+ Field(description="From the review this tool returned when called without it (status 428, detail.review_token). Only send it after showing the user every setting and warning in detail.review and getting their confirmation."),
607
+ ] = None,
608
+ acknowledge: Annotated[
609
+ list[str] | None,
610
+ Field(description="Ids from detail.review.acknowledgements_required (e.g. no_general_web_content) that the user explicitly approved after you explained each one. Never fill these in yourself."),
611
+ ] = None,
563
612
  ) -> dict[str, Any]:
564
613
  """Start a TTS-only job (no MP4). Returns a job id immediately. Poll get_job until completed; read voiceover.url. Provide prompt or script."""
565
614
  try:
566
615
  if not (prompt or "").strip() and not (script or "").strip():
567
616
  return {"error": "Provide prompt or script."}
568
617
  return _client().create_job(
618
+ review_token=review_token,
619
+ acknowledge=acknowledge,
569
620
  template_id=template_id,
570
621
  title=title,
571
622
  prompt=prompt,
@@ -597,7 +648,8 @@ def build_server(*, with_http_auth: bool = False):
597
648
  def fetch_product_context(
598
649
  product_url_or_query: Annotated[str, Field(min_length=1, description=(
599
650
  "A product page URL from the user's own store (Shopify, e.g. https://store.com/products/handle; "
600
- "WooCommerce or Etsy work through the page's structured data), a connected store's "
651
+ "WooCommerce, e.g. https://store.com/product/name/, is read through its Store API; Etsy and others "
652
+ "work through the page's structured data), a connected store's "
601
653
  "product id/handle, or a search term together with store_domain."))],
602
654
  store_domain: Annotated[str | None, Field(description=(
603
655
  "Store to search or read from, e.g. acme.com or acme.myshopify.com. Uses the user's connected "
@@ -717,12 +769,22 @@ def build_server(*, with_http_auth: bool = False):
717
769
  list[dict[str, str]] | None,
718
770
  Field(description='How the voice says hard words (ElevenLabs voices): [{"word": "Gmay", "alias": "guh-MAY"}] or [{"word": "Ordnung", "phoneme": "ˈɔɹt.nʊŋ", "alphabet": "ipa"}]. Script, captions and searches keep the real spelling. Replaces the template\'s list for this video; omit to keep it.'),
719
771
  ] = None,
772
+ review_token: Annotated[
773
+ str | None,
774
+ Field(description="From the review this tool returned when called without it (status 428, detail.review_token). Only send it after showing the user every setting and warning in detail.review and getting their confirmation."),
775
+ ] = None,
776
+ acknowledge: Annotated[
777
+ list[str] | None,
778
+ Field(description="Ids from detail.review.acknowledgements_required (e.g. no_general_web_content) that the user explicitly approved after you explained each one. Never fill these in yourself."),
779
+ ] = None,
720
780
  ) -> dict[str, Any]:
721
781
  """Start a job whose visuals YOU plan. Cliptude writes (if needed) and voices the narration, then stops at status plan_ready. It needs the full website price in credits but charges only the narration now; the rest is charged when the video completes, and the total equals the website price. Poll get_job until plan_ready, then get_narration."""
722
782
  try:
723
783
  if not (prompt or "").strip() and not (script or "").strip() and not voiceover_path and not voiceover_url:
724
784
  return {"error": "Provide prompt, script, voiceover_path or voiceover_url."}
725
785
  return _client().create_job(
786
+ review_token=review_token,
787
+ acknowledge=acknowledge,
726
788
  template_id=template_id,
727
789
  title=title,
728
790
  prompt=prompt,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.16",
3
+ "version": "0.1.17",
4
4
  "description": "Cliptude CLI — generate videos from saved templates.",
5
5
  "homepage": "https://github.com/cliptude/cliptude#readme",
6
6
  "bin": {
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "cliptude-mcp"
7
- version = "0.1.16"
7
+ version = "0.1.17"
8
8
  description = "Cliptude jobs CLI and MCP server (thin client of /api/v1)."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"