verianim 0.1.0

Local Blender scene and animation generation harness for VeriAnim experiments

VeriAnim Animation Harness

This repository is a local Blender scene and animation generation harness. It does not use the discontinued cloud service flow from the reference codebase. The active entry points are:

python -m harness.runner --text "a cup on a wooden table in a small kitchen"
python -m harness.tui

The harness targets Blender 4.5.4 LTS and uses LiteLLM-compatible models for planning, Blender Python generation, refinement, visual verification, and video verification.

What It Adds

• Structured scene and animation IR v0.2.
• Planner, coder, refiner, visual verifier, and video verifier agents.
• Deterministic Blender validation plus screenshot/video verification gates.
• Two-stage animation generation: validate the static scene first, then add animation while preserving the baseline scene.
• Blender addon socket server with scene inspection, validation, screenshot, and animation sampling commands.
• Optional material texture search and vision approval.
• Interactive Textual TUI for multi-turn scene editing.

Requirements

• Python 3.12 recommended.
• Blender 4.5.4 LTS.
• An LLM provider supported by LiteLLM.
• A multimodal model for visual verification if VERIANIM_TUI_SKIP_VISION=false or runner visual verification is enabled.
• A video-capable model if animation video verification is enabled.

Install Python dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

On Windows, activate the environment with:

.\.venv\Scripts\activate

Configuration

Copy the example environment file and fill the provider keys/models you use:

cp .env.example .env

The most common settings are:

OPENAI_API_KEY=
DASHSCOPE_API_KEY=

VERIANIM_PLANNER_MODEL=openai/gpt-4.1
VERIANIM_CODER_MODEL=openai/gpt-4.1
VERIANIM_REFINER_MODEL=openai/gpt-4.1
VERIANIM_VISION_MODEL=openai/gpt-4.1
VERIANIM_VIDEO_MODEL=dashscope/qwen-omni-turbo

VERIANIM_BLENDER_HOST=localhost
VERIANIM_BLENDER_PORT=8888
VERIANIM_RUNS_DIR=runs

All LLM calls go through LiteLLM. You can route all agents through a shared OpenAI-compatible gateway with LITELLM_API_BASE and LITELLM_API_KEY, or set agent-specific keys such as VERIANIM_CODER_API_KEY and VERIANIM_VISION_API_KEY.

Start Blender

Open Blender 4.5.4, install blender/addon.py, enable the "VeriAnim Blender" addon, then use the 3D View sidebar:

N panel > VeriAnim > Start VeriAnim Server

The default server port is 8888, matching VERIANIM_BLENDER_PORT.

You can also start the server from Blender's command line:

blender --background --python scripts/start_verianim_server.py

For a GUI Blender process:

blender --python scripts/start_verianim_server_gui.py

Run The Harness

Generate a static scene:

python -m harness.runner --text "a wooden chair beside a small round table"

Generate a scene with animation:

python -m harness.runner --text "a red ball rolls into a cardboard box" --animation

Run from an existing IR file:

python -m harness.runner --ir examples/animation_ir/translate_ball_to_box.json --animation

Skip model-based visual or video verification when debugging provider setup:

python -m harness.runner --text "a blue mug on a shelf" --skip-vision --skip-video

Use the interactive TUI:

python -m harness.tui

In the TUI, the first prompt creates a new scene. Later prompts modify the current scene and script. Useful commands are /animation, /vision, /video, /clear, and /quit.

Outputs

Each run writes artifacts under runs/, including:

• ir.json and stage-specific IR snapshots.
• Generated/refined Blender Python under code/.
• Execution logs under logs/.
• Deterministic and model verifier reports under reports/.
• Screenshot and animation previews under screenshots/ and animation/.
• Selected texture assets under textures/ when texture search is enabled.

Showcase Showroom

Curated examples live under showcase/. Generate a scan-friendly static gallery for talks or demos with:

make showroom

This writes showroom/index.html and copies preview media into showroom/assets/. Deploy the whole showroom/ directory with any static file host, or open the HTML file locally for a quick check.

Validation And Tests

Run the current unit tests with:

make test

Quickly check whether the default Blender socket port can bind inside Blender:

blender --background --python scripts/blender_socket_bind_smoke.py

Run local non-Blender checks with:

make check

The runner also performs startup checks before a normal run. To check only configuration and Blender connectivity:

python -m harness.runner --text "a blue mug" --preflight-only

Troubleshooting

• If the runner cannot connect to Blender, verify the addon server is running on localhost:8888 or set VERIANIM_BLENDER_PORT consistently in .env.
• If you intentionally use a custom local LLM gateway or a nonstandard provider setup, pass --skip-preflight after verifying the configuration yourself.
• If LiteLLM reports missing credentials, fill the provider key for the model prefix you selected in .env.
• If a provider rejects streaming or JSON response format, set the affected VERIANIM_*_STREAM=false or choose a model/gateway that supports structured JSON.
• If rendering is slow, lower VERIANIM_RENDER_WIDTH, VERIANIM_RENDER_HEIGHT, or set VERIANIM_RENDER_GIF_EACH_ROUND=false.
• Validation renders default to Workbench to keep transparent or reflective surfaces from hiding interior geometry from vision checks.
• If external texture lookup is not needed, set VERIANIM_TEXTURE_SEARCH_ENABLED=false.

More implementation details are in docs/harness.md, and the IR format is documented in docs/ir.md.