Math-To-Manim：数学推論から解説動画への変換アーキテクチャ

Math-To-Manim は、数学や物理学に関する深刻なプロンプトを、Manim による解説動画とそれらを作成するための再利用可能なアーティファクトに変換するプロジェクトです。単なる動画生成ではなく、「質問 → 理解 → アニメーション」に至る全ての過程を検査可能（inspect）にする設計思想を持っています。

💡 プロジェクトの背景と理念

開発のきっかけ

• 2025 年 1 月 20 日、ドナルド・トランプ大統領の第 2 回就任式直前に始動。
• Hugging Face にリリースされた DeepSeek の R1 モデルを契機に、数学推論（Math Reasoning）への焦点が寄せられた。
• 「スプートニク式」のシグナルとして、地政学的な事実となった open reasoning モデルの扱いを検証した。

核となる理念（デザイン原則）

「物語が記号より優先され、幾何学が代数より優先され、アーティファクトが副作用（side effects）より優先される。」

M2M2パイプラインの役割

• 入力： 短い質問、レッスンのアイデア、技術メモなど。
• 出力：
  • 概念と教育順序。
  • 不足する前提知識の特定。
  • スクリーンビート（映像演出）と Manim コード。
  • オプションでレンダリングされた MP4 動画。
• 価値：
  • 4〜5 分間の解説動画のための強力なファーストパス。
  • 装飾的な擬似数学ではなく、実際の数学的および物理的な記号（LaTeX）を使用。
  • 出力バンドル自体が重要な資産：デバッグ、エージェント間引き継ぎ、強化学習環境での利用が可能。

次のステップ：再帰的編集

• 目標： 完成した動画と実行バンドルを、エージェントが検査して改正できる「環境」として扱う（Recurrent Language Models の発想）。
• 具体例： 「カメラの傾きを調整して方程式が見やすくする」リクエストに対し、シーンプランと Manim コードを再計算し、検証後、再度レンダリング。

🏗️ 逆推論パイプライン（Reverse Reasoning Pipeline）

通常のデモが「リクエスト → Python コード」と直接ジャンプするのに対し、Math-To-Manim は意図的に以下の長道を経由します。 最終的な概念 ← 前提知識 ← 教育順序 ← 視覚的シーケンス → コード生成

エージェントのチェーン

AnimationPipeline.generate()

intent.json

knowledge_graph.json

curriculum.json

math_packet.json

storyboard.json

scene_spec.json

generated_scene.py

実行バンドルの構成要素

全ての出力には「記憶（メモリ）」が与えられます。

• JSON コンパクトデータ（意向、知識グラフなど）
• 生成されたコード
• レンダリング結果と証拠
• レビューノート
• マニフェスト

これにより、単なる動画ではなく、質問から理解に至る検査可能な道筋そのものが得られます。

🤖 Prime Intellect RL リペアループ

Math-To-Manim は同時に Prime Intellect 強化学習環境としても発展しています。

シナリオと目的

• ターゲット： 「1 つのショットで全体動画を作る」ことではない。リペア（修復） の動きが重要。
• 入力データ： 失敗したアニメーションコード、タイピングされたシーンプラン、静的検証レポート、レンダリング/回復の証拠。
• 出力要求： モデルは厳密に 「GeneratedCode JSON ブロック」 を一つ返す必要があります。

検証器（Verifiers）による報酬チェック

提案されたコードに対し、以下の条件を満たすか確認します。

1. パース可能であること。
2. 予想される Manim シーンを定義していること。
3. 不安全なインポートや呼び出しを行っていないこと。
4. 期待される数学用語を保持していること。
5. テキスト/レイアウトの混雑危険性を減少させていること。

アーキテクチャフロー

graph LR
    A[generated_scene.py + scene_spec<br>+ validation/render evidence] --> B(Prime Intellect Verifiers environment)
    B --> C{Model proposes corrected<br>GeneratedCode JSON}
    C -->|Strict Output| D(static reward checks parseability, scene shape, safety, terms, layout)
    D --> E(hosted RL updates the repair policy)
    E --> F(corrected, renderable Manim Python flows back into M2M2 recovery)

ハウススタイルの学習

RL ループにより、モデルは以下の「ハウススタイル」を学びます。

• シネマティックでありながら読みやすいシーン。
• スパース（簡潔）な式。
• セグメント化されたキャプション。
• 安全な Manim コード。
• 最初の回復試行で直ちにレンダリング可能なスクリプト。

🚀 クローンして実行する方法

1. リポジトリのクローンと環境構築

Windows PowerShell:

git clone https://github.com/HarleyCoops/Math-To-Manim.git
cd Math-To-Manim
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[dev]"
python -m pytest

macOS / Linux / WSL:

git clone https://github.com/HarleyCoops/Math-To-Manim.git
cd Math-To-Manim
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
python -m pytest

2. API なしでのスモークテスト

モデル時間やレンダリング時間を消費する前に、CLI と検証器の接続を確認します。

math-to-manim generate "Explain why derivatives are slopes" --deterministic --no-render

モジュール形式でも可能です：

python -m math_to_manim.cli generate "Explain why derivatives are slopes" --deterministic --no-render

3. モデル呼び出しによる生成

OpenAI キーを設定し、必要に応じてモデルを選択します。

Bash/シェル:

export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4.1"
math-to-manim generate "Explain Fourier epicycles as rotating vectors" --no-render

PowerShell:

$env:OPENAI_API_KEY = "sk-..."
$env:OPENAI_MODEL = "gpt-4.1"
math-to-manim generate "Explain Fourier epicycles as rotating vectors" --no-render

4. MP4 出力用のレンダリング環境設定

Python レンダリング依存項のインストール:

python -m pip install -e ".[dev,render]"

システム側のレンダリング依存項（Debian/Ubuntu/WSL）： FFmpeg と LaTeX for MathTex が必要です。

./scripts/bootstrap-render.sh

必要なパッケージリストは

requirements-system.txt

5. Codex CLI を経由したコード生成

プランニング段階はタイピングされたアダプター（通常のモデル）に留め、生成とリペアのみを Codex CLI で行う「部分的な移行」が可能です。

Codex の確認:

codex --version
codex exec "Say ready from inside this repo"

コード生成の設定:

math-to-manim generate "Explain derivatives as slopes with a cinematic tangent-line reveal" \
  --codegen-provider codex-cli \
  --codex-full-auto \
  --style cinematic \
  --quality l

💾 ディスク上の保存構造

生成は自己完結型の実行バンドルとして保存されます。ディレクトリ

runs/<run_id>/

• 入力・計画:

  • request.json

    ,

    intent.json

  • knowledge_graph.json

    ,

    curriculum.json

  • math_packet.json

    ,

    storyboard.json

    ,

    scene_spec.json

• 生成・検証:

  • generated_code.json

  • generated_scene.py

    (編集対象)

  • validation_report.json

    ,

    render_result.json

  • review_report.json

• 追跡・資産:

  • trace.jsonl

    （有効な場合のステージ境界イベント）

  • recovery_manifest.json

    （リカバー後のもの）

  • draft_review/

    (ドラフトレビュー用)

    • draft_review.md

      ,

      contact_sheet.png

      ,

      frames/

• メタデータ:

  • animation_package.json

    ,

    manifest.json

回復パスの実行

generated_scene.py

math-to-manim recover-render runs/<run_id> --quality l

このコマンドは、上流のプランニングアーティファクトを再生成せずに、検証・レンダリング・レビュー資産を更新します。

パッケージ構成

• math_to_manim/agents/

  : ステージアダプター。

• math_to_manim/schemas/

  : バージョン化されたアーティファクト契約。

• math_to_manim/tools/

  : グラフ、検証、レンダリングなどのヘルパー。

• math_to_manim/pipeline/

  : オーケストレーションとリペアループ。

• math_to_manim/rendering/

  : Manim と FFmpeg ラッパー。

• math_to_manim/review/

  : 静的および視覚的レビュー処理。

👩‍💻 Hermes エージェント（コントリビューター用）

Hermes は、このリポジトリの運用や貢献を行うためのエージェントです。

• 独立性: Math-To-Manim コアに埋め込まれておらず、ランタイム依存関係もありません。
• 機能: 開発者が行う作業を自動化・支援：ファイル読み込み、コード検索、パッチ適用、ターミナルチェック、アーティファクト検査、TODO 追跡など。
• スタンス: 逆推論パイプラインの維持には有用ですが、パイプラインの一部になるわけではありません。
• スキルの場所:

  hermes/skills/

Hermes セッションでの検証対象:

• AGENTS.md

  ,

  pyproject.toml

  , スキーマ、テスト、

  runs/<run_id>/

  バンドル。
• pytest、CLI スモークコマンド、Manim、FFmpeg、git チェックの実行。
• ドキュメントやメディアがアーティファクト契約に合致するかの確認。

関連ドキュメント:

• コントリビューターガイドライン:

  AGENTS.md

• 起動ノート:

  docs/HERMES_LEARNS_MANIM.md

🎬 モーションショーケース

目標: Math-To-Manim の視覚的説明に対するアートディレクションの目標を定めた、16 のカイアード GIF が

docs/showcase/assets/

• 詳細なギャラリーと説明文：

  docs/showcase/README.md

GIF からのレンダリング作成

MP4 ファイルから特定の授業ビートをキャプチャして GIF を作成します。

MP4="media/videos/your_scene/480p15/YourScene.mp4"

ffmpeg -y -ss 95 -t 24 -i "$MP4" \
  -vf "fps=12,scale=720:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=96[p];[s1][p]paletteuse=dither=bayer:bayer_scale=5" \
  docs/showcase/assets/your-clip.gif

ヒント:

-ss

-t

📄 ライセンス

MIT