Metadata-Version: 2.4
Name: ManimGenAI
Version: 0.1.0
Summary: Generate Manim videos from natural-language prompts using OpenAI Responses API.
Author: ManimGenAI contributors
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.108.1
Requires-Dist: pydantic>=2.11.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Provides-Extra: packaging
Requires-Dist: pyinstaller>=6.0.0; extra == "packaging"

# ManimGenAI

Turn natural-language prompts into rendered [Manim](https://www.manim.community/) videos using OpenAI.

ManimGenAI is designed to work in two modes:

- as a **CLI tool** for quickly generating videos from prompts
- as a **Python API** that another script, agent, or AI system can call programmatically

The core pipeline is:

```text
prompt + optional local assets
-> structured video plan
-> Manim Python code
-> AST validation
-> render
-> automatic repair loop on failure
-> final MP4
```

ManimGenAI is designed to be agent-friendly: it can be used as a tool inside larger AI systems.

## Highlights

- Uses the **OpenAI Responses API** instead of legacy chat completions.
  (Other providers soon)
- Separates **planning**, **code generation**, and **repair** into distinct stages with custom AI pipelines.
- Renders through `python -m manim render`, so it does not rely on `manim` being globally available in `PATH`.
- Stores (by default) full execution artifacts for each run: prompt, plan, generated code, validation output, logs, and render errors.
- Exposes both a CLI and an importable Python API.
- Supports local assets like images, SVGs, fonts, and simple data files.

## Status

This project is already functional end-to-end:

- package structure in place
- CLI and Python API implemented
- OpenAI planning/codegen/repair client implemented
- real local Manim render path verified
- unit tests passing

Current defaults are optimized by stage:

- `best` -> `gpt-5.4` across planner, codegen, and repair
- `balanced` -> `gpt-5.4` for planner and `gpt-5.4-mini` for codegen and repair
- `fast` -> `gpt-5.4-mini` across the pipeline

## Installation

### Base install

```bash
python -m pip install -e .
```

### Development extras

```bash
python -m pip install -e .[dev]
```

### Optional packaging extras

```bash
python -m pip install -e .[packaging]
```

## Requirements

You need:

- Python 3.11+
- Manim installed in the environment you will use
- FFmpeg available on the machine
- an OpenAI API key

## Configuration

Copy `.env.example` to `.env` and fill in the values you want.

Minimal setup:

```bash
OPENAI_API_KEY=your_key_here
MANIMGENAI_MODEL_PLANNER_BALANCED=gpt-5.4
MANIMGENAI_MODEL_CODEGEN_BALANCED=gpt-5.4-mini
MANIMGENAI_MODEL_REPAIR_BALANCED=gpt-5.4-mini
```

Important defaults:

- `balanced` is the recommended everyday profile.
- model fallback is disabled by default.
- artifacts are kept by default.
- final videos are written to `artifacts/output` unless you override the output directory.

## CLI Usage

### Render a video from a prompt

```bash
manimgenai render "Create a 10-second elegant animation explaining the dot product with vectors and projection." --quality balanced --output-name dot_product
```

### Render from a prompt file

```bash
manimgenai render --prompt-file prompt.txt --quality balanced --output-name lesson_01
```

### Use local assets

```bash
manimgenai render \
  "Animate this SVG logo and turn it into a graph scene" \
  --asset assets/logo.svg \
  --asset assets/chart.png \
  --output-name branded_scene
```

### Open the final video automatically

```bash
manimgenai render "Explain eigenvectors visually" --open
```

### Emit machine-readable JSON

```bash
manimgenai render "Explain the unit circle" --json
```

### Inspect environment health

```bash
manimgenai doctor
```

### Show prompt templates

```bash
manimgenai prompt-template --style pro
manimgenai prompt-template --style short
manimgenai prompt-template --system all
```

### Build an optional Windows executable

```bash
manimgenai build-exe --name manimgenai
```

## Python API

```python
from manimgenai import RenderRequest, render_video

request = RenderRequest(
    prompt="Explain the chain rule with a clean educational style.",
    output_name="chain_rule",
)

result = render_video(request)
print(result.status)
print(result.video_path)
```

## How Prompting Works

ManimGenAI uses two prompt layers.

### 1. Internal system prompts

These are built into the tool:

- `planner`: transforms the free-form request into a structured video plan
- `coder`: turns the plan into one Manim Python module
- `repair`: fixes failed generations using validation messages or traceback output

You can inspect them with:

```bash
manimgenai prompt-template --system all
```

### 2. User prompt

This is the prompt you send to the tool. Better prompt structure usually gives better videos.

Recommended high-quality template:

```text
Goal:
Audience:
Core concept or story:
Visual style and mood:
Approx duration in seconds:
Aspect ratio or output format:
Camera movement notes:
Objects, graphs, formulas, or text that must appear:
Scene progression beat by beat:
Assets to use (optional):
Non-negotiable constraints:
Things to avoid:
```

Compact version:

```text
Goal:
Audience:
Visual style:
Approx duration:
Camera or motion:
Important elements to show:
Things to avoid:
Assets to use (optional):
```

## Safety Model

Generated code is validated before execution.

By default, ManimGenAI blocks dangerous imports and calls such as:

- `subprocess`
- `socket`
- `requests`
- `httpx`
- `eval`
- `exec`
- `open`

Unsafe mode can be enabled explicitly, but the intended default is safe generation.

## Artifacts

Each run stores a full artifact bundle under:

```text
<output_dir>/_artifacts/<timestamp>-<job-name>/
```

That folder includes:

- the original prompt
- the structured plan JSON
- each generated code attempt
- validation results
- render error messages
- Manim logs

This makes debugging and prompt iteration much easier.

## Project Structure

```text
manimgenai/
  cli.py
  config.py
  schemas.py
  prompts.py
  client.py
  planner.py
  codegen.py
  validator.py
  renderer.py
  pipeline.py
  doctor.py
tests/
main.py
pyproject.toml
README.md
```

## Testing

Run unit tests:

```bash
python -m pytest
```

Run integration tests that render with local Manim:

```bash
python -m pytest -m integration
```

## Example Outputs

### `manimgenai doctor`

Example:

```text
Python: C:\Users\you\anaconda3\python.exe
[OK] openai: openai 1.108.1
[OK] manim: manim 0.19.0
[OK] ffmpeg: C:\Program Files\ffmpeg\bin\ffmpeg.exe
[OK] manim_cli: Manim Community v0.19.0
[OK] openai_api_key: configured
```

### `manimgenai render "..."`

Human-readable example:

```text
Video generated: artifacts\output\trigonometry_demo.mp4
Scene: UnitCircleTrigonometryScene
Artifacts: artifacts\output\_artifacts\20260410-163616-trigonometry_demo
```

### `manimgenai render "..." --json`

Machine-readable example:

```json
{
  "status": "success",
  "video_path": "artifacts\\output\\trigonometry_demo.mp4",
  "scene_name": "UnitCircleTrigonometryScene",
  "attempt_count": 1,
  "artifacts_dir": "artifacts\\output\\_artifacts\\20260410-163616-trigonometry_demo",
  "generated_code_path": "artifacts\\output\\_artifacts\\20260410-163616-trigonometry_demo\\attempts\\attempt-1.py",
  "logs_path": "artifacts\\output\\_artifacts\\20260410-163616-trigonometry_demo\\logs\\attempt-1_UnitCircleTrigonometryScene.log",
  "errors": [],
  "timings": {
    "planning_seconds": 11.94,
    "initial_codegen_seconds": 107.86,
    "render_attempt_1_seconds": 17.26
  }
}
```

### `manimgenai prompt-template --system all`

Example:

```text
{
  "planner": "...system prompt for structured planning...",
  "coder": "...system prompt for Manim code generation...",
  "repair": "...system prompt for fixing validation or render failures..."
}
```

## Notes

- The current implementation is already usable, but it can still be improved in prompt tuning and UTF-8 handling.

## Disclaimer

ManimGenAI uses AI models to generate video plans and Python code.

While the system includes validation and safety checks, the generated content may:
- contain inaccuracies or conceptual mistakes
- produce inefficient, unexpected, or non-idiomatic code
- fail to render correctly
- include unintended behaviors due to model limitations

Executing AI-generated code may lead to unexpected side effects depending on the environment.

All generated outputs should be reviewed before execution and before being used in production, educational material, or public-facing content.

The user is responsible for verifying the correctness, safety, and appropriateness of any generated video or code, as well as any consequences derived from executing it.

ManimGenAI does not guarantee correctness, reliability, or fitness for a particular purpose.

## License

MIT


