fix(motion-graphics): agent tool wiring + ffmpeg frame clipping (v0.2.26) (#29)

End-to-end agent loop now works with real LLMs (OpenAI gpt-4o-mini
verified). Caught by running the Example 03 agent factory live against
gpt-4o-mini and capturing the full failure chain. Unit tests previously
mocked these paths so the bugs were invisible.

Three real bugs fixed:

1. Tool registration (agent.py)
   Passing class instances (FileTools(), RenderTools()) as tools caused the
   OpenAI adapter to log 'Tool ... not recognized' and the agent to skip
   tool calls entirely. Now we expose individual bound methods:
     - file_tools.read_file / write_file / list_files
     - lint_composition / render_composition  (sync wrappers, see #2)

2. Async tools in sync agent path (agent.py)
   RenderTools.lint_composition / render_composition are async but the
   Agent sync path does not await coroutines. Result:
     'Object of type coroutine is not JSON serializable'
   Fix: wrap each async tool with a local sync function that uses
   asyncio.run(...). Bytes are also stripped from the render_composition
   return (unserializable, and the file already lives at output_path).

3. Odd-height screenshots break libx264 (backend_html.py)
   page.screenshot(full_page=True) captured 1920x1167 for the LLM-authored
   composition (SVG overflowed viewport). libx264 rejects odd height:
     'height not divisible by 2 (1920x1167)'
   Fix: clip to the exact 1920x1080 viewport via
     page.screenshot(clip={x:0,y:0,width:1920,height:1080})

Tests updated (test_motion_graphics_agent.py):
  - MockFileTools now exposes read_file/write_file/list_files methods
  - tool-count assertions updated from 2 class instances to 5 callables

Verification (live, not mocked):

  PRAISONAI_AUTO_APPROVE=true MOTION_LLM=gpt-4o-mini \
    python examples/python/video/03_motion_graphics_agent_factory.py

  Produces:
    index.html  (LLM-authored, 1031 bytes)
    intro.mp4   (1920x1080 H.264 yuv420p, 30fps, 1.5s, 13.5KB)

87/87 unit tests pass. Version bump 0.2.25 -> 0.2.26.

Author: MervinPraison

praisonai_tools/video/motion_graphics/agent.py

@@ -1,5 +1,6 @@
 """Motion graphics agent factory."""
 
+import asyncio
 import tempfile
 from pathlib import Path
 from typing import Union, Any
@@ -193,16 +194,47 @@ def create_motion_graphics_agent(
 Workspace directory: {workspace}
 """
 
-    # Create tools.
-    # FileTools is a utility class with bound methods; pass the instance so the
-    # Agent can register read_file/write_file/list_files as callable tools.
+    # Create tools. Expose bound methods individually so the Agent (which
+    # treats each tool entry as a callable) can register them across all LLM
+    # adapters (OpenAI, Anthropic, LiteLLM). Passing class instances is not
+    # portable — the OpenAI adapter logs "Tool ... not recognized".
     file_tools = FileTools()
     render_tools = RenderTools(render_backend, workspace, max_retries)
-    
+
+    # Sync wrappers around the async render tools — the Agent's sync call path
+    # does not await coroutines automatically and would otherwise fail with
+    # "Object of type coroutine is not JSON serializable".
+    def lint_composition(strict: bool = False) -> dict:
+        """Lint the motion graphics composition for common issues."""
+        return asyncio.run(render_tools.lint_composition(strict=strict))
+
+    def render_composition(
+        output_name: str = "video.mp4",
+        fps: int = 30,
+        quality: str = "standard",
+    ) -> dict:
+        """Render the motion graphics composition to MP4."""
+        result = asyncio.run(
+            render_tools.render_composition(
+                output_name=output_name, fps=fps, quality=quality
+            )
+        )
+        # Strip the raw bytes — they are not JSON-serializable for the next
+        # LLM turn and the file is already on disk at result["output_path"].
+        return {k: v for k, v in result.items() if k != "bytes"}
+
+    tool_callables = [
+        file_tools.read_file,
+        file_tools.write_file,
+        file_tools.list_files,
+        lint_composition,
+        render_composition,
+    ]
+
     # Create agent
     agent = Agent(
         instructions=base_instructions + "\n\n" + MOTION_GRAPHICS_SKILL,
-        tools=[file_tools, render_tools],
+        tools=tool_callables,
         llm=llm,
         **agent_kwargs
     )

praisonai_tools/video/motion_graphics/backend_html.py

@@ -231,9 +231,15 @@ async def _render_with_playwright(self, workspace: Path, opts: RenderOpts) -> Re
                         # Wait a bit for animations to settle
                         await page.wait_for_timeout(50)
 
-                        # Capture frame
+                        # Capture frame. Clip to the fixed 1920x1080 viewport —
+                        # `full_page=True` can produce odd-height images when
+                        # content overflows, which libx264 rejects (height must
+                        # be divisible by 2).
                         frame_path = temp_path / f"frame_{frame:06d}.png"
-                        await page.screenshot(path=str(frame_path), full_page=True)
+                        await page.screenshot(
+                            path=str(frame_path),
+                            clip={"x": 0, "y": 0, "width": 1920, "height": 1080},
+                        )
                         frame_paths.append(frame_path)
 
                     # Encode to MP4 using FFmpeg

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "praisonai-tools"
-version = "0.2.25"
+version = "0.2.26"
 description = "Extended tools for PraisonAI Agents"
 authors = [
     {name = "Mervin Praison"}

tests/unit/video/test_motion_graphics_agent.py

@@ -24,11 +24,24 @@ def __init__(self, instructions="", tools=None, llm="", **kwargs):
 
 
 class MockFileTools:
-    """Mock FileTools for testing."""
-    
+    """Mock FileTools for testing.
+
+    Exposes the same method surface as `praisonaiagents.tools.file_tools.FileTools`
+    so the factory can reference bound methods as tools.
+    """
+
     def __init__(self, base_dir=""):
         self.base_dir = base_dir
 
+    def read_file(self, filepath, encoding="utf-8"):
+        return ""
+
+    def write_file(self, filepath, content, encoding="utf-8"):
+        return True
+
+    def list_files(self, directory=".", pattern="*"):
+        return []
+
 
 class MockBackend:
     """Mock render backend for testing."""
@@ -115,7 +128,13 @@ def test_create_agent_defaults(self):
 
             assert isinstance(agent, MockAgent)
             assert agent.llm == "claude-sonnet-4"
-            assert len(agent.tools) == 2  # FileTools and RenderTools
+            # Tools are now exposed as individual callables (bound methods +
+            # sync render wrappers): read_file, write_file, list_files,
+            # lint_composition, render_composition.
+            assert len(agent.tools) == 5
+            tool_names = {getattr(t, "__name__", "") for t in agent.tools}
+            assert {"read_file", "write_file", "list_files",
+                    "lint_composition", "render_composition"} <= tool_names
             assert "motion graphics specialist" in agent.instructions.lower()
 
     @patch('praisonai_tools.video.motion_graphics.agent.Agent', MockAgent)
@@ -207,14 +226,10 @@ def test_agent_tools_configuration(self):
         with tempfile.TemporaryDirectory() as tmpdir:
             agent = create_motion_graphics_agent(workspace=tmpdir)
 
-            assert len(agent.tools) == 2
-            
-            # Check FileTools
-            file_tools = agent.tools[0]
-            assert isinstance(file_tools, MockFileTools)
-            assert file_tools.base_dir == str(tmpdir)
-            
-            # Check RenderTools
-            render_tools = agent.tools[1]
-            assert isinstance(render_tools, RenderTools)
-            assert render_tools.workspace == Path(tmpdir)
+            # Tools are now exposed as individual callables (bound methods +
+            # sync render wrappers): read_file, write_file, list_files,
+            # lint_composition, render_composition.
+            assert len(agent.tools) == 5
+            tool_names = {getattr(t, "__name__", "") for t in agent.tools}
+            assert {"read_file", "write_file", "list_files",
+                    "lint_composition", "render_composition"} <= tool_names