Metadata-Version: 2.2
Name: verianim
Version: 0.1.0
Summary: Local Blender scene and animation generation harness for VeriAnim experiments
License: # DEMONSTRATION LICENSE AGREEMENT
        
        This Demonstration License Agreement (“**Agreement**”), effective as of Customer’s acceptance of the terms of this Agreement (the “**Effective Date**”) is between the person or party accepting the terms of this Agreement (“**Customer**”); and [Threedle at the University of Chicago] (“**Licensor**”). BY ACCESSING OR USING THE SOFTWARE IN ANY WAY, INCLUDING, WITHOUT LIMITATION, BY CLICKING “I ACCEPT” WHEN PRESENTED WITH THIS AGREEMENT IN CONNECTION WITH THE SOFTWARE, CUSTOMER AGREES TO BE BOUND BY THIS AGREEMENT. IF CUSTOMER DOES NOT ACCEPT ANY OF THE TERMS OF THIS AGREEMENT AND/OR DOES NOT MEET OR COMPLY WITH ITS PROVISIONS, CUSTOMER MAY NOT USE THE SOFTWARE.
        
        **WHEREAS**, Customer wishes to use and access Licensor’s VeriAnim software, further described at https://threedle.github.io/verianim/ (the “Software”), solely for non-commercial academic and evaluation purposes (collectively, the “**Purpose**”).
        
        **WHEREAS**, Licensor is willing to permit such access under the terms and conditions contained herein;
        
        **NOW, THEREFORE**, in consideration of the mutual promises contained herein and for other good and valuable consideration, the receipt and sufficiency of which are hereby acknowledged, Customer and Licensor agree as follows:
        
        ## 1. License; Restrictions; Proprietary Rights.
        
        ### 1.1. Limited License.
        
        Solely on the condition that Customer accepts the terms of Section 1.4 below, Licensor hereby grants to Customer a royalty-free, non-exclusive, non-transferable, non-sublicensable license during the Term to install and use the Software solely for the Purpose and in accordance with the terms of the GNU Affero General Public License 3.0. All provisions in such license referring to "the Program" shall be deemed to apply to the Software.
        
        ### 1.2. Restrictions.
        
        Customer shall not use the Software for any purpose other than the Purpose. Without limiting the foregoing, Customer may not: (a) modify, translate, alter, reverse engineer, disassemble, decrypt, decompile, or otherwise manipulate the Software, in whole or in part; (b) use the Software to create any competing product or service; (c) sell, resell, rent, lease, loan, or sublicense the Software or any portion thereof to third parties, (d) otherwise make available the Software to any third party, including in any commercial time share or service bureau arrangement; (e) disable or circumvent any security features of the Software; (f) interfere with or disrupt the integrity or performance of the Software or the data contained therein; (g) attempt to gain unauthorized access to the Software or its related systems or networks; or (h) use the Software for any commercial or business purpose. Licensor may, in its sole discretion, suspend Customer's access to the Software if it determines that Customer has violated or is likely to violate the provisions of this Section 1.2.
        
        ### 1.3. Proprietary Rights.
        
        All rights not expressly granted to Customer herein are reserved to Licensor. Except as set forth in this Agreement (including the open source licenses incorporated hereunder), nothing in this Agreement shall be construed, by implication or otherwise, to grant any right or license to Customer under any patent, trademark, invention, copyright, or any other intellectual property right or trade secret, now or hereafter owned or controlled by Licensor.
        
        ### 1.4. Outputs.
        
        Customer acknowledges and agrees that any asset, information, or other output generated by the Software (each, an "Output") shall be considered Adapated Material, as defined by the Creative Commons Attribution 4.0 International Public License, and Customer acknowledges and agrees that it shall comply with the terms thereof with respect to its use and disclosure of any Output. Without limiting the foregoing, Customer shall credit Licensor, including a link to the Software, and prominently disclose that the Output was generated using Software.
        
        ### 2. Term; Termination.
        
        Unless sooner terminated by either party upon written notification to the other party, this Agreement commence upon the Effective Date and shall remain in effect until terminated pursuant to the terms of this Agreement (the "Term"). Customer may terminate this Agreement at any time by immediately discontinuing all access to the Software. Termination or cancellation of the Agreement will not affect any right or relief to which Licensor may be entitled at law or in equity. Licensor reserves the right to terminate this Agreement or Customer's access to the Software at any time and for any reason upon prior notice to Customer.
        
        ### 3. Fees.
        
        Each party shall perform its obligations hereunder at no charge to the other party.
        
        ### 4. Confidentiality.
        
        Each party shall retain in confidence and shall not, without the prior written consent of the other party (the "Disclosing Party"), disclose in any manner or use, except in performance of its obligations or enjoyment of its rights under this Agreement, any information disclosed to a party (the "Receiving Party") by the Disclosing Party and either marked at the time of disclosure as being confidential or identified in writing by the Disclosing Party as being confidential, or which would be understood by a reasonable person to be confidential ("Confidential Information"). This Section shall impose no obligation upon the Receiving Party with respect to any information that: (a) is publicly available at the time received by Receiving Party; (b) becomes publicly available other than by breach of the Receiving Party's obligations hereunder; (c) is known to the Receiving Party prior to receipt from the Disclosing Party; (d) is received by Receiving Party from a third party that was not subject to a confidentiality obligation; or (e) is required to be disclosed by law, provided that in such case the Receiving Party shall notify the Disclosing Party of any such required disclosure so that the Disclosing Party may contest any such required disclosure.
        
        ## 5. Representations and Warranties.
        
        ### 5.1. Compliance with Laws.
        
        Each party represents and warrants that it shall comply with all applicable federal, state and local laws and regulations, as well as any applicable self-regulatory guidelines.
        
        ### 5.2. Warranty Disclaimer.
        
        Licensor does not make any representation or warranty, express or implied, with respect to the accuracy or completeness of any Software provided hereunder. Moreover, Licensor does not guarantee that the functions and features of the Software will meet Customer's requirements. TO THE MAXIMUM EXTENT ALLOWED BY LAW AND EXCEPT AS UNAMBIGUOUSLY AND EXPRESSLY SET FORTH IN THIS SECTION 5.2 OF THE AGREEMENT, LICENSOR AND ITS AFFILIATES AND ITS THIRD PARTY PROVIDERS, LICENSORS, DISTRIBUTORS AND SUPPLIERS MAKE NO WARRANTY, EXPRESS OR IMPLIED, ABOUT THE SOFTWARE. THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, OR FITNESS FOR A PARTICULAR PURPOSE (EVEN IF THAT PURPOSE IS KNOWN TO LICENSOR), OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. LICENSOR DOES NOT REPRESENT OR WARRANT THAT THE SOFTWARE IS COMPLETE OR FREE FROM ERRORS OR OMISSIONS OR WILL BE UNINTERRUPTED, AND DOES NOT ASSUME, AND EXPRESSLY DISCLAIMS, ANY LIABILITY TO ANY PERSON OR ENTITY FOR ANY LOSS OR DAMAGE CAUSED BY ERRORS OR OMISSIONS IN, OR THE UNAVAILABILITY OF, THE SOFTWARE, WHETHER SUCH ERRORS OR OMISSIONS OR UNAVAILABILITY RESULT FROM NEGLIGENCE, ACCIDENT, OR OTHER CAUSE. LICENSOR AND ITS AFFILIATES AND SUPPLIERS MAKE NO REPRESENTATIONS OR WARRANTIES ABOUT THE LEGALITY OR PROPRIETY OF THE USE OF THE SERVICES FOR ANY SPECIFIC PURPOSES.
        
        ## 6. Limitations of Liability and Indemnity.
        
        ### 6.1 Indemnity.
        
        CUSTOMER SHALL INDEMNIFY, DEFEND AND HOLD LICENSOR AND ITS REPRESENTATIVES, SUBSIDIARIES AND AFFILIATES HARMLESS FROM AND AGAINST ANY AND ALL LIABILITIES, DAMAGES, LOSSES, CLAIMS, COSTS, FEES AND EXPENSES (INCLUDING REASONABLE ATTORNEYS' FEES) ARISING OUT OF OR RELATED TO (A) CUSTOMER'S MISAPPROPRIATION OR INFRINGEMENT OF ANY LICENSOR INTELLECTUAL PROPERTY (INCLUDING WITHOUT LIMITATION THE SOFTWARE AND ALL CONTENT CONTAINED THEREIN); (B) CUSTOMER'S BREACH OF THIS AGREEMENT; (C) CUSTOMER'S GROSS NEGLIGENCE OR WILLFUL MISCONDUCT; OR (D) CUSTOMER'S VIOLATION OF LAW.
        
        ### 6.2 Waiver of Indirect Damages.
        
        IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY CONSEQUENTIAL INCIDENTAL INDIRECT, SPECIAL, OR PUNITIVE DAMAGES INCURRED BY CUSTOMER AND ARISING OUT OF THE PERFORMANCE OF THIS AGREEMENT, INCLUDING BUT NOT LIMITED TO LOSS OF GOOD WILL AND LOST PROFITS OR REVENUE, WHETHER OR NOT SUCH LOSS OR DAMAGE IS BASED IN CONTRACT, WARRANTY, TORT, NEGLIGENCE, STRICT LIABILITY, INDEMNITY, OR OTHERWISE, EVEN IF SUCH PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THESE LIMITATIONS SHALL APPLY NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY.
        
        ### 6.3 Limitation of Liability.
        
        IN NO EVENT SHALL LICENSOR'S LIABILITY UNDER THIS AGREEMENT, WHETHER FOR DIRECT, INDIRECT, CONSEQUENTIAL OR OTHER DAMAGES OF ANY NATURE, AND REGARDLESS OF LEGAL THEORY, EXCEED ACTUAL DIRECT DAMAGES INCURRED OR $1,000, WHICHEVER AMOUNT IS LESS.
        
        ## 7. General.
        
        ### 7.1. Amendments.
        
        Licensor revise and update this Agreement from time to time, and will post the updated Agreement to the Software. UNLESS OTHERWISE STATED IN THE AMENDED VERSION OF THIS AGREEMENT, ANY CHANGES TO THIS AGREEMENT WILL APPLY IMMEDIATELY UPON POSTING. Although Licensor is not obligated to provide Customer with notice of any changes, any changes to this Agreement will not apply retroactively to events that occurred prior to such changes. Customer's continued use of the Software will constitute agreement to any new or revised provisions within the Agreement.
        
        ### 7.2. Assignment.
        
        This Agreement may not be assigned, or otherwise be transferred, in whole or in part, by Customer without the prior written consent of Licensor.
        
        ### 7.3. Construction.
        
        The headings contained herein are for directory purposes only, do not constitute a part of this Agreement, and shall not be employed in interpreting this Agreement. All references in this Agreement to the singular shall include the plural where applicable.
        
        ### 7.4. Entire Agreement.
        
        This Agreement constitutes the entire agreement between the parties hereto and supersedes all previous agreements and understandings, whether oral or written, express or implied, with respect to the subject matter hereof.
        
        ### 7.5. Force Majeure.
        
        Neither party shall be liable to the other for failure to perform, or delay in performance, under this Agreement if, and to the extent, such failure or delay is caused by conditions beyond its reasonable control and which, by the exercise of reasonable diligence, the delayed party is unable to prevent or provide against. Such conditions include, but are not limited to, acts of God; strikes, boycotts or other concerted acts of workmen; laws, regulations or other orders of public authorities; military action, terrorism, state of war or other national emergency; fire or flood.
        
        ### 7.6. Governing Law.
        
        This Agreement shall be governed by and construed in accordance with the laws of the State of New York, without giving effect to its principles of conflicts of law. Any litigation arising out of this Agreement shall be brought by either party in a court of competent jurisdiction located in New York County, New York, and each party hereby waives any defenses it may have before such courts based on a lack of personal jurisdiction or inconvenient forum.
        
        ### 7.7. No Other Relationship.
        
        This Agreement shall not be construed to establish any partnership, agency or joint venture of any kind between Licensor and Customer, nor shall constitute either party as the agent, employee, or legal representative of the other. Neither Customer nor Licensor has any authority to make any representation on behalf of the other, nor to incur any expense on behalf of the other party, nor to otherwise bind or commit the other to any obligation without the prior written agreement of such other party.
        
        ### 7.8. Notices.
        
        Any notice required to be sent under this Agreement, may be delivered in person; confirmed facsimile transmission; confirmed electronic-mail transmission; via nationally-recognized overnight courier; or mail, postage pre-paid, certified, return receipt requested, to the address of the receiving party first set forth above. Either party may notify the other of an address change in accordance with this paragraph.
        
        ### 7.9. Severability.
        
        If any term or provision of this Agreement is held by a court of competent jurisdiction to be invalid, void, or unenforceable, the remainder of the provisions shall remain in full force and effect and shall in no way be affected, impaired or invalidated.
        
        ### 7.10. Survival.
        
        Sections 1.3, 1.4, 4, 5, 6, and 7 shall survive any termination or expiration of this Agreement.
        
        ### 7.11 Waivers.
        
        No failure or successive failures on the part of either party, its respective successors or permitted assigns, to enforce any covenant or agreement, and no waiver or successive waivers on its or their part of any condition of this Agreement shall operate as a discharge of such covenant, agreement, or condition, or render the same invalid, or impair the right of either party, its respective successors and permitted assigns, to enforce the same in the event of any subsequent breach or breaches by the other party, its successors or permitted assigns.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=10.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: litellm>=1.65.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: requests==2.32.3
Requires-Dist: textual>=0.89.1
Provides-Extra: dev
Requires-Dist: ruff>=0.8.0; extra == "dev"
Provides-Extra: slides
Requires-Dist: playwright>=1.45.0; extra == "slides"

# 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:

```bash
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:

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

On Windows, activate the environment with:

```powershell
.\.venv\Scripts\activate
```

## Configuration

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

```bash
cp .env.example .env
```

The most common settings are:

```env
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:

```text
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:

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

For a GUI Blender process:

```bash
blender --python scripts/start_verianim_server_gui.py
```

## Run The Harness

Generate a static scene:

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

Generate a scene with animation:

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

Run from an existing IR file:

```bash
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:

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

Use the interactive TUI:

```bash
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:

```bash
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:

```bash
make test
```

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

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

Run local non-Blender checks with:

```bash
make check
```

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

```bash
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`.
