feat(video): add motion graphics examples and tools

MervinPraison · MervinPraison · commit 3967dd164f81 · 2026-04-19T01:09:50.000+01:00
Introduced several Python scripts demonstrating motion graphics rendering
and GitTools safety features. Includes examples for basic rendering,
Git repository validation, and agent factories. These enhancements aim
to provide a comprehensive toolkit for creating and managing motion
graphics projects efficiently.
diff --git a/examples/python/video/01_motion_graphics_basic_render.py b/examples/python/video/01_motion_graphics_basic_render.py
@@ -0,0 +1,85 @@
+"""Motion Graphics — Basic HTML/GSAP → MP4 render (no LLM required).
+
+This example drives the `HtmlRenderBackend` directly with a hand-authored
+HTML/GSAP composition. It renders to a real MP4 via headless Chromium +
+bundled ffmpeg, with no API keys needed.
+
+Requirements:
+    pip install praisonai-tools[video-motion]
+    playwright install chromium
+
+Verified end-to-end: produces 1920x1080 @ 30fps H.264 MP4 in ~5–10 seconds.
+"""
+
+import asyncio
+from pathlib import Path
+
+from praisonai_tools.video.motion_graphics import HtmlRenderBackend, RenderOpts
+
+
+HTML = """
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js"></script>
+  <style>
+    body { margin:0; padding:0; background:#0f172a; overflow:hidden;
+           font-family: -apple-system, Arial, sans-serif; }
+    #stage { width:1920px; height:1080px; position:relative; }
+    .title { font-size:96px; font-weight:800; color:#f8fafc;
+             position:absolute; top:50%; left:50%;
+             transform:translate(-50%,-50%); opacity:0; }
+    .subtitle { font-size:44px; color:#94a3b8;
+                position:absolute; top:62%; left:50%;
+                transform:translate(-50%,-50%); opacity:0; }
+    .dot { width:32px; height:32px; border-radius:50%; background:#38bdf8;
+           position:absolute; top:78%; left:50%;
+           transform:translate(-50%,-50%); opacity:0; }
+  </style>
+</head>
+<body>
+  <div id="stage" data-duration="4.0">
+    <div class="title">PraisonAI</div>
+    <div class="subtitle">Motion Graphics Pipeline</div>
+    <div class="dot"></div>
+  </div>
+  <script>
+    const tl = gsap.timeline({ paused: true });
+    tl.to(".title",    { duration: 0.8, opacity: 1, y: -30, ease: "power3.out" })
+      .to(".subtitle", { duration: 0.7, opacity: 1, y: -20, ease: "power3.out" }, "-=0.3")
+      .to(".dot",      { duration: 0.5, opacity: 1, scale: 2, ease: "back.out(2)" }, "-=0.2")
+      .to(".dot",      { duration: 0.4, x: 200,  ease: "power2.inOut" })
+      .to(".dot",      { duration: 0.4, x: -200, ease: "power2.inOut" })
+      .to(".dot",      { duration: 0.4, x: 0,    ease: "power2.inOut" })
+      .to([".title",".subtitle",".dot"],
+          { duration: 0.5, opacity: 0, ease: "power2.in" });
+    // Required: export timeline(s) for the render backend to drive.
+    window.__timelines = [tl];
+  </script>
+</body>
+</html>
+"""
+
+
+async def main() -> None:
+    out = Path("/tmp/motion_graphics_demo")
+    out.mkdir(exist_ok=True)
+    (out / "index.html").write_text(HTML)
+
+    backend = HtmlRenderBackend(base_dir=out)
+
+    lint = await backend.lint(out)
+    print(f"Lint:   ok={lint.ok}  messages={lint.messages}")
+
+    opts = RenderOpts(output_name="praisonai_demo.mp4", fps=30, quality="standard")
+    print("Render: ...", flush=True)
+    result = await backend.render(out, opts)
+
+    if result.ok:
+        print(f"Render: OK  path={result.output_path}  size={result.size_kb} KB")
+    else:
+        print(f"Render: FAIL  stderr={result.stderr}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/python/video/02_motion_graphics_git_tools.py b/examples/python/video/02_motion_graphics_git_tools.py
@@ -0,0 +1,52 @@
+"""Motion Graphics — GitTools safety demo (no network required for this demo).
+
+GitTools is the read-only toolkit used by the code-exploration specialist in
+`motion_graphics_team`. It clones repos on demand, validates paths against
+traversal, and restricts to GitHub URLs or `owner/repo` format.
+
+This example exercises the pure-Python safety helpers (URL parsing + file
+path validation). Cloning is network-bound and demonstrated separately.
+
+Requirements:
+    pip install praisonai-tools
+"""
+
+from praisonai_tools.tools.git_tools import GitTools
+
+
+def main() -> None:
+    tools = GitTools(base_dir="/tmp/praison_git_repos_demo")
+
+    print("URL parsing")
+    print("-----------")
+    for repo_input in [
+        "octocat/Hello-World",                         # owner/repo
+        "https://github.com/octocat/Hello-World.git",  # https URL
+        "git@github.com:octocat/Hello-World.git",      # ssh URL
+    ]:
+        try:
+            url, name = tools._parse_repo_input(repo_input)
+            print(f"  {repo_input:<50}  ->  name={name}")
+        except ValueError as exc:
+            print(f"  {repo_input:<50}  ->  REJECTED: {exc}")
+
+    print("\nFile-path validation")
+    print("--------------------")
+    for path in [
+        "README.md",            # safe
+        "src/main.py",          # safe
+        "../etc/passwd",        # traversal
+        "../../secret.txt",     # traversal
+        "/etc/passwd",          # absolute
+    ]:
+        try:
+            safe = tools._validate_file_path(path)
+            print(f"  {path:<30}  ->  SAFE:   {safe}")
+        except ValueError as exc:
+            print(f"  {path:<30}  ->  REJECT: {exc}")
+
+    print("\nListing any previously cloned repos:", tools.list_repos())
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/python/video/03_motion_graphics_agent_factory.py b/examples/python/video/03_motion_graphics_agent_factory.py
@@ -0,0 +1,54 @@
+"""Motion Graphics — single-agent factory (requires praisonaiagents + LLM key).
+
+Creates a single motion-graphics authoring agent that writes HTML/GSAP and
+renders to MP4 via the HTML backend. Good for quick, one-shot prompts.
+
+Requirements:
+    pip install praisonai-tools[video-motion] praisonaiagents[llm]
+    playwright install chromium
+    export ANTHROPIC_API_KEY=...        # or OPENAI_API_KEY, etc.
+
+Set a working model via env (LiteLLM routing):
+    export MOTION_LLM=anthropic/claude-sonnet-4-20250514
+"""
+
+import os
+from pathlib import Path
+
+from praisonai_tools.video.motion_graphics import create_motion_graphics_agent
+
+
+def main() -> None:
+    workspace = Path("/tmp/motion_graphics_agent_demo")
+    workspace.mkdir(exist_ok=True)
+
+    llm = os.getenv("MOTION_LLM", "anthropic/claude-sonnet-4-20250514")
+
+    agent = create_motion_graphics_agent(
+        backend="html",
+        workspace=workspace,
+        max_retries=3,
+        llm=llm,
+    )
+
+    print(f"Agent:     {agent.name}")
+    print(f"Backend:   {agent._motion_graphics_backend.__class__.__name__}")
+    print(f"Workspace: {agent._motion_graphics_workspace}")
+    print(f"Retries:   {agent._motion_graphics_max_retries}")
+    print(f"LLM:       {llm}")
+    print()
+    print("Starting agent...\n")
+
+    agent.start(
+        "Create a 6-second title-card animation with the text 'Hello Motion' "
+        "fading in and a cyan underline drawing across. Save as intro.mp4."
+    )
+
+    print("\nArtifacts in workspace:")
+    for p in sorted(workspace.rglob("*")):
+        if p.is_file():
+            print(f"  {p.relative_to(workspace)}  ({p.stat().st_size} bytes)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/python/video/04_motion_graphics_team.py b/examples/python/video/04_motion_graphics_team.py
@@ -0,0 +1,56 @@
+"""Motion Graphics — full team pipeline (requires praisonaiagents + LLM key).
+
+Runs the coordinator + animator team (optionally with researcher and
+code-explorer specialists) under a hierarchical process, so the coordinator
+validates outputs before marking a render as successful.
+
+Requirements:
+    pip install praisonai-tools[video-motion] praisonaiagents[llm]
+    playwright install chromium
+    export ANTHROPIC_API_KEY=...
+    export MOTION_LLM=anthropic/claude-sonnet-4-20250514
+"""
+
+import os
+import time
+from pathlib import Path
+
+from praisonai_tools.video.motion_graphics import motion_graphics_team
+
+
+def main() -> None:
+    workspace = Path("/tmp/motion_graphics_team_demo")
+    workspace.mkdir(exist_ok=True)
+
+    llm = os.getenv("MOTION_LLM", "anthropic/claude-sonnet-4-20250514")
+
+    print(f"[setup] workspace={workspace}  llm={llm}")
+
+    team = motion_graphics_team(
+        research=False,           # set True to add a web-search researcher
+        code_exploration=False,   # set True to add a GitTools code-explorer
+        workspace=workspace,
+        llm=llm,
+    )
+
+    print(f"[setup] {len(team.agents)} agents: {[a.name for a in team.agents]}")
+
+    prompt = "Animate Dijkstra's algorithm on a small weighted graph, 30s."
+    print(f"[run] prompt: {prompt}")
+
+    t0 = time.time()
+    result = team.start(prompt)
+    elapsed = time.time() - t0
+
+    print(f"[done] elapsed={elapsed:.1f}s")
+    print(f"[result] {result!r}")
+
+    print("\n[artifacts]")
+    for p in sorted(workspace.rglob("*.mp4")):
+        print(f"  mp4  {p}  ({p.stat().st_size} bytes)")
+    for p in sorted(workspace.rglob("*.html")):
+        print(f"  html {p}  ({p.stat().st_size} bytes)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/praisonai-agents/pyproject.toml b/src/praisonai-agents/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "praisonaiagents"
-version = "1.6.13"
+version = "1.6.14"
 description = "Praison AI agents for completing complex tasks with Self Reflection Agents"
 readme = "README.md"
 requires-python = ">=3.10"
diff --git a/src/praisonai-agents/uv.lock b/src/praisonai-agents/uv.lock
diff --git a/src/praisonai/praisonai/cli/features/gateway.py b/src/praisonai/praisonai/cli/features/gateway.py
@@ -8,11 +8,55 @@
 
 import asyncio
 import logging
-from typing import Optional
+import os
+from pathlib import Path
+from typing import Dict, Optional
 
 logger = logging.getLogger(__name__)
 
 
+def _load_praisonai_env_file() -> Dict[str, str]:
+    """Load ``~/.praisonai/.env`` into ``os.environ`` (without overwriting).
+
+    Daemons launched by ``launchd`` / ``systemd`` don't inherit the user's
+    shell env and don't auto-source dotfiles, so secrets written by
+    ``praisonai onboard`` (e.g. ``TELEGRAM_BOT_TOKEN``) are missing when
+    the gateway starts in the background. We load them here so the
+    YAML ``${VAR}`` substitution in ``GatewayServer.load_gateway_config``
+    resolves correctly.
+
+    Existing ``os.environ`` values take precedence (so user-set shell
+    vars always win). Returns the dict of keys we loaded (for logging).
+    """
+    env_path = Path(os.environ.get("PRAISONAI_ENV_FILE")
+                    or (Path.home() / ".praisonai" / ".env"))
+    loaded: Dict[str, str] = {}
+    if not env_path.exists():
+        return loaded
+    try:
+        for raw in env_path.read_text().splitlines():
+            s = raw.strip()
+            if not s or s.startswith("#") or "=" not in s:
+                continue
+            k, v = s.split("=", 1)
+            k = k.strip()
+            v = v.strip().strip('"').strip("'")
+            if not k:
+                continue
+            if k in os.environ:
+                continue  # don't clobber existing env
+            os.environ[k] = v
+            loaded[k] = v
+    except OSError as exc:
+        logger.warning("Could not read %s: %s", env_path, exc)
+    if loaded:
+        logger.info(
+            "Loaded %d env var(s) from %s: %s",
+            len(loaded), env_path, ", ".join(sorted(loaded.keys())),
+        )
+    return loaded
+
+
 class GatewayHandler:
     """Handler for gateway CLI commands."""
     
@@ -34,6 +78,28 @@ def start(
             agent_file: Optional path to agent configuration file
             config_file: Optional path to gateway.yaml for multi-bot mode
         """
+        # Ensure INFO-level logs surface to bot-stdout.log / bot-stderr.log
+        # when running under launchd / systemd. Many key lifecycle events
+        # (bot start, channel routing, scheduler tick, retries) are already
+        # emitted via `logger.info()` — they just weren't visible with the
+        # default WARNING root level. Only configure if nothing is set yet,
+        # so users/embedders keep control.
+        _root = logging.getLogger()
+        if not _root.handlers:
+            logging.basicConfig(
+                level=logging.INFO,
+                format="%(asctime)s %(name)s %(levelname)s %(message)s",
+            )
+        if _root.level > logging.INFO or _root.level == logging.NOTSET:
+            _root.setLevel(logging.INFO)
+
+        # Load ~/.praisonai/.env BEFORE any config parsing or ${VAR}
+        # substitution — daemons don't inherit shell env.
+        _load_praisonai_env_file()
+        logger.info(
+            "Gateway starting (host=%s port=%s config=%s agents=%s)",
+            host, port, config_file or "-", agent_file or "-",
+        )
         try:
             from praisonai.gateway import WebSocketGateway
             from praisonaiagents.gateway import GatewayConfig
diff --git a/src/praisonai/praisonai/gateway/server.py b/src/praisonai/praisonai/gateway/server.py
@@ -1030,15 +1030,26 @@ def _resolve_agent(agent_id):
 
     @staticmethod
     def _substitute_env_vars(value: str) -> str:
-        """Replace ${VAR_NAME} patterns with environment variable values."""
+        """Replace ``${VAR_NAME}`` patterns with environment variable values.
+
+        Previously, missing env vars returned the literal ``${VAR_NAME}`` which
+        caused downstream APIs (e.g. Telegram) to receive a broken token
+        string and fail with opaque 404s. We now substitute missing vars with
+        an **empty string** so the schema validator's required-field checks
+        (e.g. ``token`` must be truthy) trip cleanly instead.
+        """
         if not isinstance(value, str):
             return value
         def _replacer(match):
             var_name = match.group(1)
             env_val = os.environ.get(var_name)
             if env_val is None:
-                logger.warning(f"Environment variable {var_name} not set")
-                return match.group(0)
+                logger.warning(
+                    f"Environment variable {var_name} not set "
+                    f"— substituting empty string. "
+                    f"Run `praisonai onboard` or set it in ~/.praisonai/.env."
+                )
+                return ""
             return env_val
         return re.sub(r'\$\{([^}]+)\}', _replacer, value)
 
diff --git a/src/praisonai/praisonai/scheduler/executor.py b/src/praisonai/praisonai/scheduler/executor.py
