Metadata-Version: 2.4
Name: beatoven
Version: 0.5.0
Summary: Compose hierarchical animation/simulation plans, generate full library-backed code, play and inline-edit AnimationObjects
Author: Ephraim Hallford
License: MIT
Project-URL: Homepage, https://github.com/ehallford11714/beatoven
Project-URL: Documentation, https://github.com/ehallford11714/beatoven/blob/main/docs/INDEX.md
Project-URL: Repository, https://github.com/ehallford11714/beatoven
Project-URL: Issues, https://github.com/ehallford11714/beatoven/issues
Keywords: animation,simulation,gsap,threejs,manim,blueprint,slm,hierarchy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pillow>=10.0
Requires-Dist: moviepy>=1.0.3
Requires-Dist: imageio-ffmpeg>=0.4
Requires-Dist: openai>=1.0
Requires-Dist: anthropic>=0.20
Requires-Dist: torch>=2.0
Requires-Dist: transformers>=4.36
Requires-Dist: accelerate>=0.27
Requires-Dist: huggingface_hub>=0.20
Provides-Extra: play
Requires-Dist: pillow>=10.0; extra == "play"
Provides-Extra: video
Requires-Dist: moviepy>=1.0.3; extra == "video"
Requires-Dist: imageio-ffmpeg>=0.4; extra == "video"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: local
Requires-Dist: torch>=2.0; extra == "local"
Requires-Dist: transformers>=4.36; extra == "local"
Requires-Dist: accelerate>=0.27; extra == "local"
Requires-Dist: huggingface_hub>=0.20; extra == "local"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: all
Requires-Dist: beatoven[dev]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="assets/beatoven-logo.png" alt="Beatoven — painting a portrait" width="220"/>
</p>

# Beatoven

[![PyPI](https://img.shields.io/pypi/v/beatoven.svg)](https://pypi.org/project/beatoven/)
[![Python](https://img.shields.io/pypi/pyversions/beatoven.svg)](https://pypi.org/project/beatoven/)

**Compose hierarchical animation & simulation plans, generate full library-backed code, play it back, and inline-edit with `.edit`.**

Beatoven turns a prompt into a playable `AnimationObject`:

- Imports **full capability surfaces** for GSAP, Anime.js, Motion, Theatre.js, Typed.js, Three.js, Lottie, Manim, MoviePy, Textual, Bevy, Unity, libGDX, and more
- **SLM / cloud guided compose** binds real library APIs (not a tiny subset) via heuristic, local Qwen, or OpenAI/Claude/Grok
- Builds a **hierarchy plan**: scene → acts → shots → layers → tracks → keyframes
- Supports **draft → finalize** and **Deep Mode** cinematic enhancement
- Returns **runnable code** (not stubs) plus a built-in web player
- **`anim.edit(...)`** / **`anim.deep(...)`** for inline revisions and capability-max enhancements
- Optional **Hugging Face SLM** (hardware-sized Qwen) or **cloud** providers when API keys are set

## Install

### From PyPI (recommended)

`pip install beatoven` pulls the **full dependency stack** — play (Pillow), video (MoviePy / imageio-ffmpeg), cloud clients (OpenAI + Anthropic), and local SLM (torch / transformers / accelerate / huggingface_hub):

```powershell
pip install beatoven
```

```powershell
pip install -U beatoven
beatoven --help
python -c "from beatoven import compose; print(compose('Type Hi', provider='heuristic').summary())"
```

```powershell
pip install "beatoven[dev]"   # pytest, ruff, build, twine
```

Package: [https://pypi.org/project/beatoven/](https://pypi.org/project/beatoven/)

### From source (development)

```powershell
git clone https://github.com/ehallford11714/beatoven.git
cd beatoven
python -m venv .venv
.\.venv\Scripts\pip install -e ".[dev]"
python -m pytest -q
```

## Quick start

```python
from beatoven import compose

anim = compose(
    "Type 'Beatoven' letter-by-letter, then drop a rubber ball in a Three.js room",
    languages=["javascript", "python"],
    provider="heuristic",  # or auto / local / openai / claude / grok
)

print(anim.plan.summary())
print(anim.code["javascript"][:400])

anim.play()  # opens browser player

anim.edit("make the title blue and stagger faster")
anim.edit(path="scene/act1/shot1/title", props={"text": "Beatoven Live"})
anim.export("out/index.html")
```

### Draft + edit

```python
anim = compose("Type 'Draft Scene' + bouncing ball", draft=True)
anim.edit("use Typed.js style typing; title color cyan")
anim.finalize()
anim.play()
```

### Grounded iterative satisfaction

Compose now **verifies** the plan/code against the prompt using a documentation contract (libraries, physics, engines, typing) and **iteratively repairs** gaps until the threshold is met (default on):

```python
anim = compose(
    "Type 'Nova' then drop a rubber ball in a Babylon physics room",
    provider="heuristic",
    grounded=True,              # default
    max_ground_iters=3,
    satisfaction_threshold=0.85,
)
print(anim.verify().summary())  # [PASS] score=...
anim.ground(max_iters=2)        # force another grounded repair loop
```

### Direct object playback (`showWhenDone`)

Playback is no longer HTML-only. You get a live Python / JS / IR player object:

```python
anim = compose("Type 'Beatoven' then bounce a ball", provider="heuristic")

# Python player object — samples IR, shows native window when done
player = anim.play(runtime="python", show_when_done=True)
print(player.sample(1.0))

# JavaScript-facing object (dict) for hosts / notebooks
js = anim.to_js_object(show_when_done=True)
print(js["type"], js["duration"])

# Force classic HTML file preview
anim.play(runtime="web", object_playback=False, show_when_done=True)
```

### Deep Mode + multicascade

Deep Mode expands capability coverage. **Cascade** runs multi-pass SLM/heuristic refinement (structure → physics → cinematography → detail → engine bind) for Babylon / Unity / Bevy / Three complex scenes:

```python
anim = compose(
    "Babylon physics room with stacked boxes and a bouncing ball",
    provider="auto",
    cascade=True,
    cascade_passes=4,
)
print(anim.plan.enhancements["cascade"])
anim.play(runtime="python", show_when_done=True)

anim.deep("more cinematic camera and bloom")
anim.cascade("richer multi-body physics", passes=3)
```

## CLI

```powershell
python -m beatoven compose --prompt "Type 'Hello' then bounce a ball" --lang javascript,python --play
python -m beatoven compose --prompt "..." --deep --play
python -m beatoven compose --prompt "Babylon physics stack" --cascade --cascade-passes 4 --play
python -m beatoven compose --prompt "..." --draft --out out
python -m beatoven edit out/beat.json --instruction "make the title blue and stagger faster"
python -m beatoven deep out/beat.json --instruction "cinematic bloom + dolly" --play
python -m beatoven cascade out/beat.json --passes 4 --play
python -m beatoven play out/beat.json --runtime python
python -m beatoven play out/beat.json --runtime web --html
python -m beatoven export out/beat.json --out out/clip.html
python -m beatoven catalog --domain text_ui
python -m beatoven probe
```

## Providers

| Value | Behavior |
|-------|----------|
| `auto` | Cloud if API key present → else local Qwen when configured → else heuristic |
| `openai` / `claude` / `grok` | Cloud APIs |
| `openai_compatible` | `BEATOVEN_LLM_BASE_URL` + key + model |
| `local` | On-device Qwen/HF sized via hardware probe |
| `heuristic` | Offline catalog + hierarchy planner |

Environment: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `XAI_API_KEY` / `GROK_API_KEY`, `BEATOVEN_LLM_API_KEY`, `BEATOVEN_LLM_BASE_URL`, `BEATOVEN_LLM_MODEL`, `BEATOVEN_PROVIDER`, `BEATOVEN_LOCAL_MODEL`.

## Documentation

| Doc | Description |
|-----|-------------|
| [docs/INDEX.md](docs/INDEX.md) | Docs home |
| [docs/TUTORIAL.md](docs/TUTORIAL.md) | Step-by-step tutorial |
| [docs/API.md](docs/API.md) | Public API reference |
| [docs/COMPONENTS.md](docs/COMPONENTS.md) | Every module explained |
| [docs/CLI.md](docs/CLI.md) | CLI reference |
| [docs/LIBRARIES.md](docs/LIBRARIES.md) | Capability pack catalog |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Pipeline & Deep Mode |

## Example prompts

See [`examples/prompts.md`](examples/prompts.md). Runnable scripts:

- `examples/text_typing_web.py`
- `examples/draft_and_edit.py`
- `examples/threejs_physics_scene.py`
- `examples/deep_mode_demo.py`

## Layout

```
src/beatoven/     # library
  capabilities/   # full API surfaces per library
  generators/     # JS / Python / Rust / C# / Java
  runtime/        # play + export
  providers/      # heuristic / local / cloud
tests/
examples/
docs/             # tutorial, API, components, CLI, libraries
```

## License

MIT
