@cliptude/cli 0.1.17 → 0.1.18

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.
@@ -48,6 +48,74 @@ def _err(exc: Exception) -> dict[str, Any]:
48
48
  return {"error": str(exc)}
49
49
 
50
50
 
51
+ # Fields that make an MCP result too big to read (a 90 minute-class timeline index, per-word timings,
52
+ # whole-voiceover segment arrays) without helping an agent decide anything.
53
+ _BULKY_OPERATION_KEYS = frozenset({
54
+ "voice_segments", "chunk_alignments", "chunk_durations", "voiceover_chunks", "timing_metadata",
55
+ })
56
+
57
+
58
+ def _compact_operation(operation: Any) -> Any:
59
+ if not isinstance(operation, dict):
60
+ return operation
61
+ out: dict[str, Any] = {}
62
+ for key, value in operation.items():
63
+ if key in _BULKY_OPERATION_KEYS and isinstance(value, (list, dict)):
64
+ out[key] = f"<{len(value)} entries omitted>"
65
+ else:
66
+ out[key] = value
67
+ return out
68
+
69
+
70
+ def _compact_agent_run(data: Any) -> Any:
71
+ """Agent run with the voice-segment arrays of its operations summarised (they repeat in messages)."""
72
+ if not isinstance(data, dict):
73
+ return data
74
+ out = dict(data)
75
+ run = out.get("run")
76
+ if isinstance(run, dict) and isinstance(run.get("applied_operations"), list):
77
+ out["run"] = {**run, "applied_operations": [_compact_operation(op) for op in run["applied_operations"]]}
78
+ messages = out.get("messages")
79
+ if isinstance(messages, list):
80
+ compact_messages = []
81
+ for message in messages:
82
+ if isinstance(message, dict) and isinstance(message.get("metadata"), dict):
83
+ meta = dict(message["metadata"])
84
+ if isinstance(meta.get("operations"), list):
85
+ meta["operations"] = [_compact_operation(op) for op in meta["operations"]]
86
+ message = {**message, "metadata": meta}
87
+ compact_messages.append(message)
88
+ out["messages"] = compact_messages
89
+ return out
90
+
91
+
92
+ def _compact_editor_project(data: Any) -> Any:
93
+ """Editor project without voice_timing.spokenEventIndex (every word of the narration, 100 KB+)."""
94
+ if not isinstance(data, dict):
95
+ return data
96
+ project = data.get("project")
97
+ if not isinstance(project, dict) or not isinstance(project.get("voice_timing"), dict):
98
+ return data
99
+ timing = project["voice_timing"]
100
+ kept = {k: v for k, v in timing.items() if k != "spokenEventIndex"}
101
+ index = timing.get("spokenEventIndex")
102
+ if isinstance(index, dict) and isinstance(index.get("words"), list):
103
+ kept["spoken_words"] = len(index["words"])
104
+ return {**data, "project": {**project, "voice_timing": kept}}
105
+
106
+
107
+ def _compact_narration(data: Any, *, include_words: bool) -> Any:
108
+ """Narration sentences without per-word timings unless asked (they are most of the payload)."""
109
+ if include_words or not isinstance(data, dict) or not isinstance(data.get("sentences"), list):
110
+ return data
111
+ sentences = []
112
+ for sentence in data["sentences"]:
113
+ if isinstance(sentence, dict) and "words" in sentence:
114
+ sentence = {k: v for k, v in sentence.items() if k != "words"}
115
+ sentences.append(sentence)
116
+ return {**data, "sentences": sentences, "words_omitted": True}
117
+
118
+
51
119
  def mcp_allowed_hosts(resource_url: str | None = None) -> list[str]:
52
120
  """Host header values the Streamable HTTP transport should accept.
53
121
 
@@ -141,7 +209,7 @@ def build_server(*, with_http_auth: bool = False):
141
209
  "plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. Before giving the user "
142
210
  "the editor link, open_editor_project and look at EVERY frame with view_scenes (0 to the end): replace "
143
211
  "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 "
212
+ "contradicts the story (a search naming a place can return a namesake elsewhere), near-black frames, clips floating in black bars, broken AI pictures and any picture held over ~8 s, in a free revision, then review again. Generic "
145
213
  "shots of places name the story's setting (\"empty bed mud house\", not \"empty bed dark room\"). True "
146
214
  "stories (real events and people) set sense.true_story and sense.people and never search for people: a "
147
215
  "stranger on screen is taken for the real person (check_plan refuses it, stand_in_person; a dated topic "
@@ -655,7 +723,7 @@ def build_server(*, with_http_auth: bool = False):
655
723
  "Store to search or read from, e.g. acme.com or acme.myshopify.com. Uses the user's connected "
656
724
  "store when it matches."))] = None,
657
725
  ) -> dict[str, Any]:
658
- """Read a store product: title, price, variants, description and its real image URLs, saved as product_id, plus 3 educational YouTube video angles (80% teaching, 20% product). A search that matches several products returns candidates; fetch again with the chosen URL. Show the user the angles before drafting."""
726
+ """Read a store product: title, price, variants, description and its real image URLs, saved as product_id, plus 3 educational YouTube video angles (80% teaching, 20% product). When no angles could be suggested the list is empty with an angles_note: pass your own angle (a title, or {title, problem, hook}) to draft_product_script. A search that matches several products returns candidates; fetch again with the chosen URL. Show the user the angles before drafting."""
659
727
  try:
660
728
  return _client().fetch_product_context(product_url_or_query, store_domain=store_domain)
661
729
  except Exception as exc:
@@ -674,8 +742,9 @@ def build_server(*, with_http_auth: bool = False):
674
742
  "Length: 6-8, 10-12, 18-20, 30-40 or 50-60 (minutes), or a number of minutes from 6 to 60. "
675
743
  "Default 6-8."))] = None,
676
744
  template_id: Annotated[str | None, Field(description=(
677
- "Faceless Documentary template to use (voice, look, music). Omit to use the latest one, or a "
678
- "default Product Explainer template."))] = None,
745
+ "Template to use (voice, look, music): a Faceless Documentary, Top 10 or Avatar Video template "
746
+ "(an Avatar Video one puts the avatar on screen). Omit to use the latest Faceless Documentary one, "
747
+ "or a default Product Explainer template."))] = None,
679
748
  title: Annotated[str | None, Field(description="Video title. Defaults to the angle title.")] = None,
680
749
  discount_code: Annotated[str | None, Field(description="Discount code the merchant gave. Never invent one.")] = None,
681
750
  cta_url: Annotated[str | None, Field(description="Where viewers should go. Defaults to the product page.")] = None,
@@ -810,10 +879,13 @@ def build_server(*, with_http_auth: bool = False):
810
879
  )
811
880
  def get_narration(
812
881
  job_id: Annotated[str, Field(min_length=8, description="Plan job UUID (status plan_ready)")],
882
+ include_words: Annotated[
883
+ bool, Field(description="Add every word's start/end to each sentence (large: about 10 KB a minute). Phrases in a plan are matched server-side, so leave it off unless you need word times.")
884
+ ] = False,
813
885
  ) -> dict[str, Any]:
814
- """The narration you plan against: numbered sentences with start/end seconds and every word's timing, narration_digest (copy it into the plan), suggested chapters, the template's theme and switched-off graphics, pricing (website price, already charged, due at continue), and narration_audio: a url to listen to (check names and borrowed words before you lock) and the API path that downloads the MP3. The sentence text is what the voice said, so a misspoken word shows up there too."""
886
+ """The narration you plan against: numbered sentences with start/end seconds (and every word's timing with include_words), narration_digest (copy it into the plan), suggested chapters, the template's theme and switched-off graphics, pricing (website price, already charged, due at continue), and narration_audio: a url to listen to (check names and borrowed words before you lock) and the API path that downloads the MP3. The sentence text is what the voice said, so a misspoken word shows up there too."""
815
887
  try:
816
- return _client().get_narration(job_id)
888
+ return _compact_narration(_client().get_narration(job_id), include_words=include_words)
817
889
  except Exception as exc:
818
890
  return _err(exc)
819
891
 
@@ -1047,7 +1119,7 @@ def build_server(*, with_http_auth: bool = False):
1047
1119
  ) -> dict[str, Any]:
1048
1120
  """Open (or create) the timeline editor project for a completed video job. Returns project id, revision, a compact timeline (item id, type, start_s, end_s, text) to reference in run_agent, and export_credits_due: what render_project would charge now."""
1049
1121
  try:
1050
- return _client().open_editor_project(job_id)
1122
+ return _compact_editor_project(_client().open_editor_project(job_id))
1051
1123
  except Exception as exc:
1052
1124
  return _err(exc)
1053
1125
 
@@ -1060,7 +1132,7 @@ def build_server(*, with_http_auth: bool = False):
1060
1132
  ) -> dict[str, Any]:
1061
1133
  """Current revision, compact timeline, latest render and export_credits_due (what render_project would charge now) of an editor project."""
1062
1134
  try:
1063
- return _client().get_editor_project(project_id)
1135
+ return _compact_editor_project(_client().get_editor_project(project_id))
1064
1136
  except Exception as exc:
1065
1137
  return _err(exc)
1066
1138
 
@@ -1073,7 +1145,7 @@ def build_server(*, with_http_auth: bool = False):
1073
1145
  start_s: Annotated[float, Field(ge=0, description="First second to show")] = 0.0,
1074
1146
  end_s: Annotated[float | None, Field(description="Stop before this second (default: the end)")] = None,
1075
1147
  ) -> list[str | Image]:
1076
- """See what the timeline shows, without opening any link: numbered contact sheets of every picture, a frame of every clip and each graphic's picture with its words, with the narration under each, plus a legend (tile, item_id, start_s, end_s, words, said, flags). Up to 24 tiles per call; call again from next_start_s. Use it to review a built video yourself (other brands, wrong pictures, repeats, leftover text) before giving the user the editor link, and again after run_agent to check the change."""
1148
+ """See what the timeline shows, without opening any link: numbered contact sheets of every picture, a frame of every clip and each graphic's picture with its words, with the narration under each, plus a legend (tile, item_id, start_s, end_s, words, said, flags: REPEATED PICTURE, HELD, AI STILL, DARK, BARS). Up to 24 tiles per call; call again from next_start_s. Use it to review a built video yourself (other brands, wrong pictures, repeats, leftover text) before giving the user the editor link, and again after run_agent to check the change."""
1077
1149
  try:
1078
1150
  data = _client().view_scenes(project_id, start_s=start_s, end_s=end_s)
1079
1151
  except Exception as exc:
@@ -1097,11 +1169,11 @@ def build_server(*, with_http_auth: bool = False):
1097
1169
  tier: Annotated[str, Field(description="fast or smart")] = "fast",
1098
1170
  chat_id: Annotated[str | None, Field(description="Continue an existing agent chat")] = None,
1099
1171
  ) -> dict[str, Any]:
1100
- """Ask Cliptude Agent to edit the timeline (swap footage, regenerate images or voiceover ranges, music, transitions, text). One kind of change per run: picture swaps and text edits go in separate runs. Several clips can get new pictures in one run: reference them all and describe each one's picture by its item id; a clip with nothing suitable is left unchanged and named in the reply. Swapping a graphic's picture keeps the graphic and its words. Returns a run; poll get_agent_run. Charges agent credits. Then render_project for a new MP4, after view_scenes on the changed range."""
1172
+ """Ask Cliptude Agent to edit the timeline (swap footage, regenerate images or voiceover ranges, music, transitions, text). One kind of change per run: picture swaps and text edits go in separate runs. Several clips can get new pictures in one run: reference them all and describe each one's picture by its item id; a clip with nothing suitable is left unchanged and named in the reply. Swapping a graphic's picture keeps the graphic and its words. To use one exact picture (a product cover, a screenshot), paste its https link in the prompt: it is downloaded and applied as is, not searched for. Returns a run; poll get_agent_run. Charges agent credits. Then render_project for a new MP4, after view_scenes on the changed range."""
1101
1173
  try:
1102
- return _client().run_agent(
1174
+ return _compact_agent_run(_client().run_agent(
1103
1175
  project_id, prompt=prompt, tier=tier, referenced_item_ids=referenced_item_ids, chat_id=chat_id
1104
- )
1176
+ ))
1105
1177
  except Exception as exc:
1106
1178
  return _err(exc)
1107
1179
 
@@ -1115,7 +1187,7 @@ def build_server(*, with_http_auth: bool = False):
1115
1187
  ) -> dict[str, Any]:
1116
1188
  """Status of a Cliptude Agent run plus the agent's messages."""
1117
1189
  try:
1118
- return _client().get_agent_run(project_id, run_id)
1190
+ return _compact_agent_run(_client().get_agent_run(project_id, run_id))
1119
1191
  except Exception as exc:
1120
1192
  return _err(exc)
1121
1193
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.17",
3
+ "version": "0.1.18",
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.17"
7
+ version = "0.1.18"
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"