1  """
  2  Output Formatters for AI Consumption
  3  
  4  Transforms hierarchy descriptions into formats optimized for AI context windows.
  5  """
  6  
  7  import json
  8  
  9  
 10  def format_json(hierarchy_result):
 11      """
 12      Format hierarchy result as JSON string.
 13  
 14      Args:
 15          hierarchy_result: dict from describe_hierarchy()
 16  
 17      Returns:
 18          JSON string
 19      """
 20      return json.dumps(hierarchy_result, indent=2)
 21  
 22  
 23  def format_markdown(hierarchy_result):
 24      """
 25      Format hierarchy result as markdown for AI context.
 26  
 27      Produces a tree-like structure that's easy to scan and understand.
 28  
 29      Args:
 30          hierarchy_result: dict from describe_hierarchy()
 31  
 32      Returns:
 33          Markdown string
 34      """
 35      lines = []
 36  
 37      # Header
 38      doc_name = hierarchy_result.get("document_name", "Untitled")
 39      lines.append(f"# Scene: {doc_name}")
 40      lines.append("")
 41  
 42      # Summary
 43      lines.append(f"**{hierarchy_result.get('summary', 'No objects')}**")
 44      lines.append("")
 45  
 46      # Object tree
 47      if hierarchy_result.get("objects"):
 48          lines.append("## Hierarchy")
 49          lines.append("")
 50          lines.append("```")
 51  
 52          for obj in hierarchy_result["objects"]:
 53              lines.extend(_format_object_tree(obj, prefix="", is_last=True))
 54  
 55          lines.append("```")
 56          lines.append("")
 57  
 58      # Stats
 59      stats = hierarchy_result.get("stats", {})
 60      if stats:
 61          lines.append("## Stats")
 62          lines.append("")
 63          lines.append(f"- Total objects: {stats.get('total_objects', 0)}")
 64          if stats.get("custom_objects"):
 65              lines.append(f"- CustomObjects: {stats['custom_objects']}")
 66          if stats.get("line_objects"):
 67              lines.append(f"- LineObjects: {stats['line_objects']}")
 68          if stats.get("solid_objects"):
 69              lines.append(f"- SolidObjects: {stats['solid_objects']}")
 70          lines.append(f"- Max depth: {stats.get('max_depth', 0)}")
 71  
 72      return "\n".join(lines)
 73  
 74  
 75  def _format_object_tree(obj, prefix="", is_last=True):
 76      """
 77      Recursively format an object and its children as a tree.
 78  
 79      Args:
 80          obj: object description dict
 81          prefix: current line prefix for indentation
 82          is_last: whether this is the last sibling
 83  
 84      Returns:
 85          list of formatted lines
 86      """
 87      lines = []
 88  
 89      # Build the connector
 90      connector = "└── " if is_last else "├── "
 91  
 92      # Build object description line
 93      name = obj.get("name", "Unknown")
 94      obj_type = obj.get("type", "Unknown")
 95  
 96      # Start with name and type
 97      desc_parts = [f"{name} ({obj_type})"]
 98  
 99      # Add position if not at origin
100      pos = obj.get("position", {})
101      if pos.get("x", 0) != 0 or pos.get("y", 0) != 0 or pos.get("z", 0) != 0:
102          desc_parts.append(f"@ ({pos.get('x', 0)}, {pos.get('y', 0)}, {pos.get('z', 0)})")
103  
104      # Add color
105      if obj.get("color"):
106          desc_parts.append(f"[{obj['color']}]")
107  
108      # Add creation progress
109      if obj.get("creation") is not None:
110          desc_parts.append(f"creation:{obj['creation']}%")
111  
112      # Add draw progress
113      if obj.get("draw") is not None and obj.get("draw") != 100:
114          desc_parts.append(f"draw:{obj['draw']}%")
115  
116      # Add scale if non-default
117      if obj.get("scale") and obj["scale"] != 1:
118          desc_parts.append(f"scale:{obj['scale']}")
119  
120      line = prefix + connector + " ".join(desc_parts)
121      lines.append(line)
122  
123      # Process children
124      children = obj.get("children", [])
125      if children:
126          # Update prefix for children
127          child_prefix = prefix + ("    " if is_last else "│   ")
128  
129          for i, child in enumerate(children):
130              child_is_last = (i == len(children) - 1)
131              lines.extend(_format_object_tree(child, child_prefix, child_is_last))
132  
133      return lines
134  
135  
136  def format_for_ai(hierarchy_result, format_type="markdown"):
137      """
138      Format hierarchy result for AI consumption.
139  
140      Args:
141          hierarchy_result: dict from describe_hierarchy()
142          format_type: "markdown" or "json"
143  
144      Returns:
145          Formatted string
146      """
147      if format_type == "json":
148          return format_json(hierarchy_result)
149      else:
150          return format_markdown(hierarchy_result)
151  
152  
153  def format_compact(hierarchy_result):
154      """
155      Format as a compact single-line summary.
156  
157      Useful for quick status checks.
158  
159      Args:
160          hierarchy_result: dict from describe_hierarchy()
161  
162      Returns:
163          Single line summary string
164      """
165      stats = hierarchy_result.get("stats", {})
166      doc_name = hierarchy_result.get("document_name", "Untitled")
167  
168      parts = [f"Scene: {doc_name}"]
169      parts.append(f"{stats.get('total_objects', 0)} objects")
170  
171      type_counts = []
172      if stats.get("custom_objects"):
173          type_counts.append(f"{stats['custom_objects']}C")
174      if stats.get("line_objects"):
175          type_counts.append(f"{stats['line_objects']}L")
176      if stats.get("solid_objects"):
177          type_counts.append(f"{stats['solid_objects']}S")
178  
179      if type_counts:
180          parts.append(f"({'/'.join(type_counts)})")
181  
182      return " | ".join(parts)
183  
184  
185  def format_inspect_object(result):
186      """
187      Format inspect_object result as markdown.
188  
189      Args:
190          result: dict from inspect_object()
191  
192      Returns:
193          Markdown string
194      """
195      if "error" in result:
196          return f"**Error:** {result['error']}"
197  
198      lines = []
199      lines.append(f"# Object: {result['name']}")
200      lines.append("")
201      lines.append(f"**Type:** {result['type']} ({result.get('c4d_type', 'Unknown')})")
202      lines.append("")
203  
204      # Transform
205      t = result.get("transform", {})
206      pos = t.get("position", {})
207      rot = t.get("rotation", {})
208      scale = t.get("scale", {})
209      lines.append("## Transform")
210      lines.append(f"- Position: ({pos.get('x', 0)}, {pos.get('y', 0)}, {pos.get('z', 0)})")
211      lines.append(f"- Rotation: ({rot.get('h', 0)}°, {rot.get('p', 0)}°, {rot.get('b', 0)}°)")
212      lines.append(f"- Scale: ({scale.get('x', 1)}, {scale.get('y', 1)}, {scale.get('z', 1)})")
213      lines.append("")
214  
215      # Hierarchy
216      if result.get("parent") or result.get("children"):
217          lines.append("## Hierarchy")
218          if result.get("parent"):
219              lines.append(f"- Parent: {result['parent']}")
220          if result.get("children"):
221              lines.append(f"- Children: {', '.join(result['children'])}")
222          lines.append("")
223  
224      # Color
225      if result.get("color"):
226          c = result["color"]
227          lines.append("## Color")
228          lines.append(f"- Name: {c.get('name', 'Unknown')}")
229          rgb = c.get("rgb", {})
230          lines.append(f"- RGB: ({rgb.get('r', 0)}, {rgb.get('g', 0)}, {rgb.get('b', 0)})")
231          lines.append("")
232  
233      # Userdata
234      if result.get("userdata"):
235          lines.append("## Parameters")
236          for group, params in result["userdata"].items():
237              lines.append(f"### {group}")
238              for name, value in params.items():
239                  if isinstance(value, dict):
240                      value = f"({value.get('x', 0)}, {value.get('y', 0)}, {value.get('z', 0)})"
241                  elif isinstance(value, float):
242                      value = round(value, 3)
243                  lines.append(f"- {name}: {value}")
244          lines.append("")
245  
246      # Tags
247      if result.get("tags"):
248          lines.append("## Tags")
249          for tag in result["tags"]:
250              tag_line = f"- {tag['type']}"
251              if tag.get("material"):
252                  tag_line += f" → {tag['material']}"
253              lines.append(tag_line)
254          lines.append("")
255  
256      # Bounding box
257      if result.get("bounding_box"):
258          bb = result["bounding_box"]
259          lines.append("## Bounding Box")
260          lines.append(f"- Size: {bb.get('width', 0)} × {bb.get('height', 0)} × {bb.get('depth', 0)}")
261  
262      return "\n".join(lines)
263  
264  
265  def format_inspect_materials(result):
266      """
267      Format inspect_materials result as markdown.
268  
269      Args:
270          result: dict from inspect_materials()
271  
272      Returns:
273          Markdown string
274      """
275      lines = []
276      lines.append(f"# Materials ({result.get('count', 0)})")
277      lines.append("")
278      lines.append(f"**{result.get('summary', 'No materials')}**")
279      lines.append("")
280  
281      for mat in result.get("materials", []):
282          lines.append(f"## {mat['name']}")
283          lines.append(f"- Type: {mat.get('type', 'Unknown')}")
284  
285          if mat.get("color"):
286              c = mat["color"]
287              lines.append(f"- Color: {c.get('name', 'Unknown')}")
288  
289          if mat.get("has_transparency"):
290              lines.append("- Has transparency")
291          if mat.get("has_luminance"):
292              lines.append("- Has luminance/glow")
293  
294          if mat.get("used_by"):
295              lines.append(f"- Used by: {', '.join(mat['used_by'])}")
296          else:
297              lines.append("- **Not used**")
298  
299          lines.append("")
300  
301      return "\n".join(lines)
302  
303  
304  def format_inspect_animation(result):
305      """
306      Format inspect_animation result as markdown.
307  
308      Args:
309          result: dict from inspect_animation()
310  
311      Returns:
312          Markdown string
313      """
314      lines = []
315      fr = result.get("frame_range", {})
316      lines.append(f"# Animation: Frames {fr.get('start', 0)} - {fr.get('end', 0)}")
317      lines.append("")
318      lines.append(f"**{result.get('summary', 'No animation')}**")
319      lines.append("")
320      lines.append(f"- FPS: {result.get('fps', 30)}")
321      lines.append(f"- Duration: {result.get('duration_seconds', 0)}s")
322      lines.append("")
323  
324      for obj in result.get("animated_objects", []):
325          lines.append(f"## {obj['name']} ({obj.get('type', 'Unknown')})")
326          for track in obj.get("tracks", []):
327              param = track.get("parameter", "Unknown")
328              keyframes = track.get("keyframes", [])
329              if keyframes:
330                  kf_summary = ", ".join([f"f{kf['frame']}={kf['value']}" for kf in keyframes[:5]])
331                  if len(keyframes) > 5:
332                      kf_summary += f" ... (+{len(keyframes) - 5} more)"
333                  lines.append(f"- {param}: {kf_summary}")
334          lines.append("")
335  
336      return "\n".join(lines)
337  
338  
339  def format_validate_scene(result):
340      """
341      Format validate_scene result as markdown.
342  
343      Args:
344          result: dict from validate_scene()
345  
346      Returns:
347          Markdown string
348      """
349      lines = []
350      status = "✅ PASSED" if result.get("valid") else "❌ FAILED"
351      lines.append(f"# Scene Validation: {status}")
352      lines.append("")
353      lines.append(f"**{result.get('summary', 'No validation')}**")
354      lines.append("")
355  
356      if result.get("issues"):
357          lines.append("## Issues (must fix)")
358          for issue in result["issues"]:
359              lines.append(f"- ❌ {issue}")
360          lines.append("")
361  
362      if result.get("warnings"):
363          lines.append("## Warnings")
364          for warning in result["warnings"]:
365              lines.append(f"- ⚠️ {warning}")
366          lines.append("")
367  
368      if result.get("info"):
369          lines.append("## Info")
370          for info in result["info"]:
371              lines.append(f"- ℹ️ {info}")
372          lines.append("")
373  
374      stats = result.get("stats", {})
375      if stats:
376          lines.append("## Stats")
377          lines.append(f"- Materials: {stats.get('material_count', 0)}")
378          if stats.get("unused_materials"):
379              lines.append(f"- Unused materials: {stats['unused_materials']}")
380  
381      return "\n".join(lines)
382  
383  
384  def format_describe_scene(result):
385      """
386      Format describe_scene result as markdown.
387  
388      Universal formatter for the consolidated introspection tool.
389  
390      Args:
391          result: dict from describe_scene()
392  
393      Returns:
394          Markdown string
395      """
396      lines = []
397  
398      # Header with scene name and frame info
399      doc_name = result.get("document_name", "Untitled")
400      frame = result.get("frame", {})
401      lines.append(f"# Scene: {doc_name}")
402      lines.append(f"Frame {frame.get('current', 0)}/{frame.get('end', 0)} @ {frame.get('fps', 30)}fps")
403      lines.append("")
404  
405      # Changes section (most important - at top)
406      changes = result.get("changes")
407      if changes:
408          lines.append("## Changes Detected")
409          lines.append("")
410          _format_changes(changes, lines)
411          lines.append("")
412      elif result.get("changes") is None:
413          lines.append("*First inspection - baseline captured for change detection*")
414          lines.append("")
415  
416      # Hierarchy
417      hierarchy = result.get("hierarchy", {})
418      if hierarchy.get("objects"):
419          lines.append("## Hierarchy")
420          lines.append(f"*{hierarchy.get('summary', '')}*")
421          lines.append("")
422          for obj in hierarchy["objects"]:
423              _format_object_compact(obj, lines, indent=0)
424          lines.append("")
425  
426      # Materials (compact)
427      materials = result.get("materials", {})
428      mat_list = materials.get("materials", [])
429      if mat_list:
430          lines.append(f"## Materials ({len(mat_list)})")
431          for mat in mat_list:
432              mat_line = f"- **{mat['name']}**"
433              if mat.get("color"):
434                  mat_line += f" [{mat['color'].get('name', '')}]"
435              if mat.get("used_by"):
436                  mat_line += f" → {', '.join(mat['used_by'])}"
437              else:
438                  mat_line += " (unused)"
439              lines.append(mat_line)
440          lines.append("")
441  
442      # Animation (compact)
443      animation = result.get("animation", {})
444      animated = animation.get("animated_objects", [])
445      if animated:
446          lines.append(f"## Animation")
447          lines.append(f"*{animation.get('summary', '')}*")
448          for obj in animated:
449              tracks_summary = ", ".join([t.get("parameter", "?") for t in obj.get("tracks", [])])
450              lines.append(f"- {obj['name']}: {tracks_summary}")
451          lines.append("")
452  
453      # Validation warnings (compact)
454      validation = result.get("validation", {})
455      warnings = validation.get("warnings", [])
456      issues = validation.get("issues", [])
457      if warnings or issues:
458          lines.append("## Validation")
459          for issue in issues:
460              lines.append(f"- ❌ {issue}")
461          for warning in warnings:
462              lines.append(f"- ⚠️ {warning}")
463          lines.append("")
464  
465      # Console output delta (only if there are new messages)
466      console = result.get("console", {})
467      if console.get("has_new"):
468          lines.append("## Console Output")
469          if console.get("truncated"):
470              lines.append("*Output truncated for safety*")
471          for msg in console.get("messages", []):
472              text = msg.get("text", "")
473              count = msg.get("count", 1)
474              # Format with repetition count if repeated
475              if count > 1:
476                  lines.append(f"- `{text}` (×{count})")
477              else:
478                  lines.append(f"- `{text}`")
479          lines.append("")
480  
481      return "\n".join(lines)
482  
483  
484  def _format_changes(changes_result, lines):
485      """Format change detection results.
486  
487      Handles both DreamTalk param changes and native C4D param changes.
488      Native changes include the DescID for direct use in code.
489      """
490      changes = changes_result.get("changes", {})
491  
492      # Object changes
493      obj_changes = changes.get("objects", {})
494  
495      # DreamTalk param changes (userdata, transforms, etc.)
496      if obj_changes.get("dreamtalk_modified"):
497          for obj_name, params in obj_changes["dreamtalk_modified"].items():
498              for param, vals in params.items():
499                  old_val = vals.get('old')
500                  new_val = vals.get('new')
501                  # Format values nicely
502                  if isinstance(old_val, float):
503                      old_val = round(old_val, 3)
504                  if isinstance(new_val, float):
505                      new_val = round(new_val, 3)
506                  lines.append(f"- **{obj_name}**.{param}: `{old_val}` → `{new_val}`")
507  
508      # Native C4D param changes (only shown when changed)
509      if obj_changes.get("native_modified"):
510          for obj_name, params in obj_changes["native_modified"].items():
511              for desc_id_str, vals in params.items():
512                  old_val = vals.get('old')
513                  new_val = vals.get('new')
514                  param_name = vals.get('name', '')
515                  ident = vals.get('ident', '')
516                  old_label = vals.get('old_label')
517                  new_label = vals.get('new_label')
518  
519                  # Format values nicely
520                  if isinstance(old_val, float):
521                      old_val = round(old_val, 3)
522                  if isinstance(new_val, float):
523                      new_val = round(new_val, 3)
524  
525                  # Build the change description
526                  # If we have labels (dropdown/enum), show "Label (value)"
527                  if old_label and new_label:
528                      old_display = f"{old_label} ({old_val})"
529                      new_display = f"{new_label} ({new_val})"
530                  else:
531                      old_display = str(old_val)
532                      new_display = str(new_val)
533  
534                  # Build parameter identifier: "Name" or "Name (ID_CONSTANT)"
535                  if param_name and ident:
536                      param_display = f"{param_name} ({ident})"
537                  elif param_name:
538                      param_display = param_name
539                  elif ident:
540                      param_display = ident
541                  else:
542                      param_display = f"DescID {desc_id_str}"
543  
544                  lines.append(f"- **{obj_name}**.{param_display}: `{old_display}` → `{new_display}`")
545  
546      # Tag param changes
547      if obj_changes.get("tags_modified"):
548          for obj_name, params in obj_changes["tags_modified"].items():
549              for param_key, vals in params.items():
550                  old_val = vals.get('old')
551                  new_val = vals.get('new')
552                  tag_name = vals.get('tag', '')
553                  param_name = vals.get('name', '')
554                  ident = vals.get('ident', '')
555                  old_label = vals.get('old_label')
556                  new_label = vals.get('new_label')
557  
558                  if isinstance(old_val, float):
559                      old_val = round(old_val, 3)
560                  if isinstance(new_val, float):
561                      new_val = round(new_val, 3)
562  
563                  if old_label and new_label:
564                      old_display = f"{old_label} ({old_val})"
565                      new_display = f"{new_label} ({new_val})"
566                  else:
567                      old_display = str(old_val)
568                      new_display = str(new_val)
569  
570                  if param_name and ident:
571                      param_display = f"{param_name} ({ident})"
572                  elif param_name:
573                      param_display = param_name
574                  elif ident:
575                      param_display = ident
576                  else:
577                      param_display = param_key
578  
579                  lines.append(f"- **{obj_name}** tag **{tag_name}**.{param_display}: `{old_display}` → `{new_display}`")
580  
581      # Added/removed objects
582      if obj_changes.get("added"):
583          for name in obj_changes["added"]:
584              lines.append(f"- **+ Added**: {name}")
585  
586      if obj_changes.get("removed"):
587          for name in obj_changes["removed"]:
588              lines.append(f"- **- Removed**: {name}")
589  
590      # Material changes
591      mat_changes = changes.get("materials", {})
592      if mat_changes.get("modified"):
593          for mat_name, params in mat_changes["modified"].items():
594              for param, vals in params.items():
595                  lines.append(f"- Material **{mat_name}**.{param}: `{vals.get('old')}` → `{vals.get('new')}`")
596  
597      if mat_changes.get("added"):
598          for name in mat_changes["added"]:
599              lines.append(f"- **+ Added Material**: {name}")
600  
601      if mat_changes.get("removed"):
602          for name in mat_changes["removed"]:
603              lines.append(f"- **- Removed Material**: {name}")
604  
605  
606  def _format_object_compact(obj, lines, indent=0):
607      """Format a single object compactly with its key parameters."""
608      prefix = "  " * indent
609  
610      # Build object line
611      name = obj.get("name", "Unknown")
612      obj_type = obj.get("type", "Unknown")
613  
614      parts = [f"{name} ({obj_type})"]
615  
616      # Position (only if non-zero)
617      pos = obj.get("position", {})
618      if pos.get("x", 0) != 0 or pos.get("y", 0) != 0 or pos.get("z", 0) != 0:
619          parts.append(f"@ ({pos.get('x', 0)}, {pos.get('y', 0)}, {pos.get('z', 0)})")
620  
621      # Key DreamTalk params
622      if obj.get("creation") is not None:
623          parts.append(f"creation:{obj['creation']}%")
624      if obj.get("draw") is not None and obj.get("draw") != 100:
625          parts.append(f"draw:{obj['draw']}%")
626      if obj.get("color"):
627          parts.append(f"[{obj['color']}]")
628  
629      lines.append(f"{prefix}- {' '.join(parts)}")
630  
631      # Recurse children
632      for child in obj.get("children", []):
633          _format_object_compact(child, lines, indent + 1)