Math Beauty Agent

数学が苦手・嫌いな人に向けて、数学の美しさや不思議さを視覚的に伝える短い動画を制作するAIエージェント。

これは何ではないか

このプロジェクトは、数学の問題を解けるようにする一般的な教材生成システムではない。 目的は、視聴者に次のような感情を持ってもらうことである。

• 数学は少し面白いかもしれない
• この動きは美しい
• なぜこうなるのか知りたい
• 数式は苦手だが、もう少し見てみたい

中心となる考え方は以下。

数学を分からせる前に、数学を見たくさせる。

数学嫌い向けである理由

学校教育での数学は「解けるようになること」を目的にすることが多く、 そこに苦手意識を持つ人を置き去りにしてきた。このエージェントは解法ではなく 現象の美しさに焦点を当て、専門用語や数式を急がずに提示することで、 数学に対する拒否感（math anxiety）を下げることを狙う。

完成イメージ

テーマ（例:「二次関数の係数a」）を入力すると、以下を経て60秒の縦型動画が生成される。

ユーザーがテーマを入力
        ↓
美しい数学現象を企画 (Wonder Finder)
        ↓
数学嫌い向けに企画を修正 (Anti-Math Editor)
        ↓
動画のシーン構成を作成 (Experience Designer)
        ↓
数学的な正確性を検証 (Math Guardian)
        ↓
Manim用の映像計画を作成 (Visual Director)
        ↓
固定テンプレートを使って動画生成
        ↓
ナレーション・字幕生成 (Narration Writer)
        ↓
動画を合成
        ↓
数学嫌い視点でレビュー (Boredom Judge)
        ↓
人間が公開判断

動作環境

• Python 3.10 以上を推奨（本リポジトリの開発環境では 3.11+ が利用できず 3.10.6 で開発・検証している。3.11+ が利用可能であればそちらを推奨）
• FFmpeg（PATHに通っていること）
• Manim Community（動画レンダリングを行う場合のみ必須。MockProviderのみで企画〜JSON生成までは不要）

セットアップ

python -m venv .venv
. .venv/Scripts/activate   # Windows (bash)
pip install -e ".[dev]"
# 実際に動画レンダリングまで行う場合
pip install -e ".[dev,render]"

cp .env.example .env

.env の MBA_LLM_PROVIDER=mock / MBA_SPEECH_PROVIDER=mock のままであれば、 外部APIキーなしで企画からプレビュー動画生成までを実行できる。 MockLLMProvider には二次関数の係数aについてのデモ企画（Wonder Idea〜FinalReview）が 既定値として登録されており、math-beauty new から math-beauty run までを 実LLM/実TTSなしで一本通しで実行できる。

CLIの使用例

math-beauty new --topic "二次関数の係数a" --audience "数学が苦手な大人" --duration-seconds 60 --format vertical
math-beauty plan PROJECT_ID
math-beauty validate PROJECT_ID
math-beauty render PROJECT_ID
math-beauty narrate PROJECT_ID
math-beauty compose PROJECT_ID
math-beauty review PROJECT_ID
math-beauty run PROJECT_ID
math-beauty status PROJECT_ID

--project-id を省略すると quadratic-a-001 のように自動採番される （採番されたIDは new コマンドの出力に表示される）。

各コマンドは projects/<project_id>/ 配下にJSONと生成物を保存する。 途中で失敗しても、math-beauty run PROJECT_ID は完了済み工程を再利用し、 失敗した工程から再開する。

プロジェクト構成

src/math_beauty_agent/
  agents/       各エージェントの実行関数（プロンプト+入出力スキーマ+検証）
  providers/    LLM/音声プロバイダの抽象化とMock実装
  schemas/      Pydanticモデル
  rendering/    Manim固定テンプレートとレンダラー
  audio/        ナレーション・字幕(SRT)生成
  video/        映像と音声の合成
  pipeline/     工程の実行順序と状態管理
  prompts/      各エージェント用プロンプト
  cli.py        Typer CLI（PipelineRunnerを呼ぶだけ）

knowledge/      Manimパターン・成功例・既知エラー・避けるべき表現の蓄積
projects/       生成物の出力先（プロジェクトIDごとのディレクトリ）
tests/          unit / integration / fixtures
docs/           設計ドキュメントと引き継ぎ資料

パイプラインの説明

詳細は docs/pipeline.md を参照。各工程は独立したJSON入出力を持ち、 個別に再実行できる。パイプラインの状態は projects/<id>/state.json に保存される。

現在の制限

• 対象は二次関数 (y = ax^2 の係数a) のみ
• 動画は約60秒・縦型のみ
• Manimテンプレートは graph_parameter_change のみ実装（point_tracing / expression_graph_transition は未実装）
• 実LLM/実TTS Providerは未実装（MockProviderのみ。デモ企画は固定内容で、 入力テーマの内容に応じて動的に企画が変わるわけではない）
• 開発環境にLaTeXが無いため、Manimの数式表示はMathTex/Texではなく プレーンテキスト(Text)で代替している
• Boredom Judgeの入力はストーリーボードとナレーション文章のみ（プレビュー画像や レンダリングログはMVP後の候補）
• 自動投稿機能なし
• Web UIなし
• 開発環境の制約により Python 3.10 で検証（3.11+推奨だが未検証）

ロードマップ

MVP完成後の候補（詳細は指示書・TASKS.md参照）:

• 実LLM Provider / VOICEVOX等の実TTS連携
• 視覚モデルによる動画レビュー
• レンダリングエラーの自動修正
• 三角関数・円運動・フラクタル・フーリエ級数などへの対象拡大
• Web UI

OSSライセンス

本リポジトリは MIT License の下で公開する（LICENSE 未整備の場合は今後追加）。 Manim Community、MoviePy、Pydantic、Typer など各依存ライブラリのライセンスは それぞれのプロジェクトに従う。

外部API利用時の注意

実際のLLM/TTS APIを利用する場合、APIキーは .env にのみ保存し、コミットしないこと。 生成コストや利用規約は各サービス提供元のポリシーに従うこと。

重要な注意

動画の数学的正確性は、Math Guardianによる自動検証を経てもなお、最終的には人間が確認すること。 本システムの自動投稿機能はなく、公開判断は常に人間が行う。