murali-kit 0.1.0__tar.gz

murali_kit-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+rendered_output/

murali_kit-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: murali-kit
+Version: 0.1.0
+Summary: Free Python authoring kit and add-ons for Murali Engine.
+Project-URL: Homepage, https://github.com/murali-engine/murali-kit
+Project-URL: Repository, https://github.com/murali-engine/murali-kit
+Project-URL: Engine, https://github.com/murali-engine/murali
+Author: Murali Engine
+License: MIT OR Apache-2.0
+Keywords: ai,animation,education,math,visualization
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Education
+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 :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: murali-engine<0.3.0,>=0.2.5
+Description-Content-Type: text/markdown
+
+# Murali Kit
+
+Free Python authoring components and add-ons for Murali Engine.
+
+This repository is the free companion package for higher-level Murali visuals, examples, and
+education-focused helpers. The core runtime and PyO3 engine bindings live in the
+[`murali-engine/murali`](https://github.com/murali-engine/murali) repository.
+
+## Boundary
+
+- `murali-engine`: Rust engine, renderer, scene graph, timelines, preview/export, and Python
+  bindings for the core runtime.
+- `murali-kit`: Python add-ons built on top of `murali-engine`.
+
+The current split is non-destructive. Existing Rust collection code remains in the engine repo until
+each add-on surface has a Python equivalent and a stable engine contract.
+
+See [docs/SPLIT_PLAN.md](docs/SPLIT_PLAN.md) for the migration plan.
+
+## First Component
+
+`murali-kit` now includes a small `TitleCard` composition:
+
+```python
+from murali_engine import Scene
+from murali_kit.collection import TitleCard
+
+scene = Scene()
+handles = TitleCard("Murali Kit", "Python add-ons for Murali Engine").add_to_scene(scene)
+```
+
+`murali-kit` depends on the `murali-engine` Python package:
+
+```bash
+python3 -m pip install murali-kit==0.1.0
+```
+
+During local development, create a virtual environment inside this repo and install the adjacent
+engine checkout plus this kit package:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -r requirements-local.txt
+```
+
+Activate the environment:
+
+```bash
+source .venv/bin/activate
+```
+
+Run the examples:
+
+```bash
+python examples/core_surfaces.py
+python examples/hello_shapes.py
+python examples/shapes_and_layout.py
+python examples/three_d_scene.py
+python examples/title_card.py
+```
+
+By default these open the preview window. To export a single PNG frame instead:
+
+```bash
+python examples/core_surfaces.py --png
+python examples/hello_shapes.py --png
+python examples/shapes_and_layout.py --png
+python examples/three_d_scene.py --png
+python examples/title_card.py --png
+```
+
+To try every Python example one by one:
+
+```bash
+python preview_all.py
+```
+
+For a non-window export pass:
+
+```bash
+python preview_all.py --png
+```
+
+You can also run them without activation:
+
+```bash
+.venv/bin/python examples/core_surfaces.py
+.venv/bin/python examples/hello_shapes.py
+.venv/bin/python examples/shapes_and_layout.py
+.venv/bin/python examples/three_d_scene.py
+.venv/bin/python examples/title_card.py
+```
+
+See [RUNNING_EXAMPLES.md](RUNNING_EXAMPLES.md) for the full local workflow.

murali_kit-0.1.0/README.md

@@ -0,0 +1,94 @@
+# Murali Kit
+
+Free Python authoring components and add-ons for Murali Engine.
+
+This repository is the free companion package for higher-level Murali visuals, examples, and
+education-focused helpers. The core runtime and PyO3 engine bindings live in the
+[`murali-engine/murali`](https://github.com/murali-engine/murali) repository.
+
+## Boundary
+
+- `murali-engine`: Rust engine, renderer, scene graph, timelines, preview/export, and Python
+  bindings for the core runtime.
+- `murali-kit`: Python add-ons built on top of `murali-engine`.
+
+The current split is non-destructive. Existing Rust collection code remains in the engine repo until
+each add-on surface has a Python equivalent and a stable engine contract.
+
+See [docs/SPLIT_PLAN.md](docs/SPLIT_PLAN.md) for the migration plan.
+
+## First Component
+
+`murali-kit` now includes a small `TitleCard` composition:
+
+```python
+from murali_engine import Scene
+from murali_kit.collection import TitleCard
+
+scene = Scene()
+handles = TitleCard("Murali Kit", "Python add-ons for Murali Engine").add_to_scene(scene)
+```
+
+`murali-kit` depends on the `murali-engine` Python package:
+
+```bash
+python3 -m pip install murali-kit==0.1.0
+```
+
+During local development, create a virtual environment inside this repo and install the adjacent
+engine checkout plus this kit package:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -r requirements-local.txt
+```
+
+Activate the environment:
+
+```bash
+source .venv/bin/activate
+```
+
+Run the examples:
+
+```bash
+python examples/core_surfaces.py
+python examples/hello_shapes.py
+python examples/shapes_and_layout.py
+python examples/three_d_scene.py
+python examples/title_card.py
+```
+
+By default these open the preview window. To export a single PNG frame instead:
+
+```bash
+python examples/core_surfaces.py --png
+python examples/hello_shapes.py --png
+python examples/shapes_and_layout.py --png
+python examples/three_d_scene.py --png
+python examples/title_card.py --png
+```
+
+To try every Python example one by one:
+
+```bash
+python preview_all.py
+```
+
+For a non-window export pass:
+
+```bash
+python preview_all.py --png
+```
+
+You can also run them without activation:
+
+```bash
+.venv/bin/python examples/core_surfaces.py
+.venv/bin/python examples/hello_shapes.py
+.venv/bin/python examples/shapes_and_layout.py
+.venv/bin/python examples/three_d_scene.py
+.venv/bin/python examples/title_card.py
+```
+
+See [RUNNING_EXAMPLES.md](RUNNING_EXAMPLES.md) for the full local workflow.

murali_kit-0.1.0/RUNNING_EXAMPLES.md

@@ -0,0 +1,113 @@
+# Running Examples
+
+## Rust Examples
+
+Rust examples still run from the engine repo:
+
+```bash
+cd ../murali
+cargo run --example hello_shapes
+```
+
+Experimental linear-algebra Rust examples need the feature enabled:
+
+```bash
+cargo run --features experimental --example linear_algebra_vectors
+```
+
+The helper scripts in the engine repo can preview or export tagged Rust example groups:
+
+```bash
+./preview_all.sh --tag linear-algebra --auto
+./export_all.sh --tag linear-algebra --release
+```
+
+## Python Examples
+
+Python examples require the `murali-engine` Python package. For local development, create a virtual
+environment in this kit repo and install both the adjacent engine checkout and this kit package:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -r requirements-local.txt
+```
+
+To install `murali-engine` from GitHub instead of the adjacent checkout:
+
+```bash
+.venv/bin/python -m pip install -r requirements-git.txt
+```
+
+Then activate the environment and run examples from `murali-kit`:
+
+```bash
+source .venv/bin/activate
+python examples/core_surfaces.py
+python examples/hello_shapes.py
+python examples/shapes_and_layout.py
+python examples/three_d_scene.py
+python examples/title_card.py
+```
+
+By default these open the preview window. To export a single PNG frame instead:
+
+```bash
+python examples/core_surfaces.py --png
+python examples/hello_shapes.py --png
+python examples/shapes_and_layout.py --png
+python examples/three_d_scene.py --png
+python examples/title_card.py --png
+```
+
+Or run them without activation:
+
+```bash
+.venv/bin/python examples/core_surfaces.py
+.venv/bin/python examples/hello_shapes.py
+.venv/bin/python examples/shapes_and_layout.py
+.venv/bin/python examples/three_d_scene.py
+.venv/bin/python examples/title_card.py
+```
+
+Run every Python example one by one:
+
+```bash
+python preview_all.py
+```
+
+For an export-only pass:
+
+```bash
+python preview_all.py --png
+```
+
+Useful filters:
+
+```bash
+python preview_all.py --list
+python preview_all.py --match title
+python preview_all.py --png --continue-on-error
+```
+
+## Where To Write Examples
+
+New Python examples should be written in:
+
+```text
+examples/
+```
+
+Rust examples remain in:
+
+```text
+../murali/examples/
+```
+
+The copied Rust examples are reference material only:
+
+```text
+rust-reference/examples/
+```
+
+Those Rust examples do not run as Python yet. We will port them one by one into
+`murali-kit/examples` as Python equivalents.

murali_kit-0.1.0/docs/SPLIT_PLAN.md

@@ -0,0 +1,73 @@
+# Murali Library Split Plan
+
+Murali is splitting into a core engine repo and a free Python kit repo.
+
+This pass is intentionally non-destructive: no Rust collection code is removed from the engine repo.
+Rust components stay where they are until the PyO3 engine surface exists and each Python add-on has
+real examples and compatibility checks.
+
+## Repositories
+
+### murali-engine/murali
+
+Owns the core runtime:
+
+- Rust scene graph and tattva lifecycle
+- timeline, animation, easing, and playback
+- renderer, preview, export, capture, and resources
+- primitive geometry needed by most scenes
+- PyO3 bindings for the core authoring surface
+- stable contracts that add-ons can depend on
+
+### murali-engine/murali-kit
+
+Owns free Python add-ons:
+
+- education-focused authoring helpers
+- Python collection components
+- AI visualization components
+- maths and linear algebra helpers
+- examples that exercise the public Python surface
+
+## Package Names
+
+- PyPI package for the engine: `murali-engine`
+- Python import for the engine: `murali_engine`
+- PyPI package for the free kit: `murali-kit`
+- Python import for the free kit: `murali_kit`
+
+## Initial Python Namespaces
+
+```text
+murali_kit
+  collection
+  maths
+    linear_algebra
+  ai
+```
+
+More namespaces should be added only when they have at least one real component and one example.
+
+## Migration Order
+
+1. Keep Rust code in the engine repo.
+2. Copy the current add-on-facing Rust sources into `murali-kit/rust-reference`.
+3. Add PyO3 bindings for a small engine slice: scene, timeline, labels, shapes, preview, and export.
+4. Add compatibility metadata to `murali-kit` against the engine package.
+5. Translate one small component into Python and add one example. The first component is
+   `murali_kit.collection.TitleCard`.
+6. Translate components incrementally, keeping visual examples close to each new public API.
+7. Add contract checks once the first real engine API exists.
+8. Only then decide whether any Rust collection code should move, remain as examples, or become
+   internal engine tests.
+
+## Contract Strategy
+
+The first contract should be programmatic but small:
+
+- import availability checks for required engine symbols
+- signature checks for constructors and methods used by kit components
+- smoke examples that render or export through the installed engine package
+- version bounds in package metadata
+
+Documentation remains useful, but docs alone should not be treated as the compatibility contract.

murali_kit-0.1.0/examples/MIGRATION.md

@@ -0,0 +1,82 @@
+# Example Migration
+
+The long-term goal is to port the Rust reference examples from `murali/examples` into Python
+examples here when the `murali_engine` Python API exposes the needed surface.
+
+## Current Python Examples
+
+- `core_surfaces.py`
+- `hello_shapes.py`
+- `shapes_and_layout.py`
+- `three_d_scene.py`
+- `title_card.py`
+
+## Porting Rule
+
+- Keep Rust reference examples in `murali/examples`.
+- Put runnable Python ports in `murali-kit/examples`.
+- Keep `murali-kit/rust-reference/examples` as reference material only.
+- Prefer 1:1 teaching intent over mechanical line-by-line translation when the Python API is more
+  ergonomic.
+
+## Rust Examples To Port
+
+The current Python API supports basic shapes, paths, labels, code blocks, LaTeX, Typst, axes,
+number planes, tables, camera controls, 3D axes, named 3D curves, named parametric surfaces,
+SceneView, prop asset loading, timelines, preview, and PNG export. Examples that need arbitrary
+Python callbacks for curves/surfaces, advanced graph helpers, tensors, or AI composites need more
+`murali_engine` bindings before they can be ported cleanly.
+
+```text
+chat_input_box.rs
+code_blocks.rs
+context_window.rs
+curves_3d.rs
+equation_and_matrix_animation.rs
+force_fields.rs
+fourier_formula_trace.rs
+graphs_2d.rs
+hello_shapes.rs
+kavriq_opening.rs
+kv_cache.rs
+latex_and_typst.rs
+layout_and_groups.rs
+linear_algebra_basis_change.rs
+linear_algebra_column_combination.rs
+linear_algebra_composition.rs
+linear_algebra_determinant.rs
+linear_algebra_dot_product.rs
+linear_algebra_matrix_transform.rs
+linear_algebra_matrix_vector.rs
+linear_algebra_span.rs
+linear_algebra_transform_order_scene_view.rs
+linear_algebra_vectors.rs
+map_projection_morph.rs
+model_inspector.rs
+motion_basics.rs
+murali_logo.rs
+murali_logo_transparent.rs
+neural_networks.rs
+next_token_distribution.rs
+normalization.rs
+opening_scene_view.rs
+particles.rs
+portrait_video.rs
+prop3d_glb.rs
+prop3d_gltf.rs
+scene_view.rs
+self_attention_lesson.rs
+stepwise_storytelling.rs
+streamlines.rs
+style_and_paths.rs
+surfaces_3d.rs
+tables.rs
+tensor_operations.rs
+tensor_semantics.rs
+tensor_slicing.rs
+text_animation.rs
+textured_surface.rs
+traced_paths.rs
+transformer_attention.rs
+wireframe_surfaces.rs
+```

murali_kit-0.1.0/examples/README.md

@@ -0,0 +1,57 @@
+# Examples
+
+Examples use the `murali_engine` Python package and installed editable `murali_kit` source.
+
+One-time local setup from this kit repo:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -r requirements-local.txt
+```
+
+This installs `murali-engine` from the adjacent `../murali` checkout and installs `murali-kit`
+editable. To install the engine from GitHub instead:
+
+```bash
+.venv/bin/python -m pip install -r requirements-git.txt
+```
+
+Run examples from this repo:
+
+```bash
+source .venv/bin/activate
+python examples/core_surfaces.py
+python examples/hello_shapes.py
+python examples/shapes_and_layout.py
+python examples/three_d_scene.py
+python examples/title_card.py
+```
+
+By default these open the preview window. To export a single PNG frame instead:
+
+```bash
+python examples/core_surfaces.py --png
+python examples/hello_shapes.py --png
+python examples/shapes_and_layout.py --png
+python examples/three_d_scene.py --png
+python examples/title_card.py --png
+```
+
+Or run without activation:
+
+```bash
+.venv/bin/python examples/core_surfaces.py
+.venv/bin/python examples/hello_shapes.py
+.venv/bin/python examples/shapes_and_layout.py
+.venv/bin/python examples/three_d_scene.py
+.venv/bin/python examples/title_card.py
+```
+
+Run every Python example one by one from the repo root:
+
+```bash
+python preview_all.py
+```
+
+Write new Python examples in this folder. The copied Rust examples in `rust-reference/examples`
+are only migration references until we port them.

murali_kit-0.1.0/examples/_runner.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+
+from murali_engine import Scene
+
+
+def run_example(build_scene: Callable[[], Scene], default_png: str) -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--png",
+        action="store_true",
+        help="export one PNG frame instead of opening the preview window",
+    )
+    parser.add_argument("--output", default=default_png, help="PNG path for --png")
+    parser.add_argument("--width", type=int, default=960, help="PNG width for --png")
+    args = parser.parse_args()
+
+    scene = build_scene()
+    print(scene.tattva_count())
+
+    if args.png:
+        scene.save_png(args.output, width=args.width, fps=1, duration=0.0)
+    else:
+        scene.preview()

murali_kit-0.1.0/examples/core_surfaces.py

@@ -0,0 +1,89 @@
+from murali_engine import (
+    BLUE_D,
+    GOLD_C,
+    GRAY_A,
+    GRAY_B,
+    GREEN_D,
+    TEAL_D,
+    WHITE,
+    Axes,
+    CodeBlock,
+    Label,
+    Latex,
+    NumberPlane,
+    Path,
+    Scene,
+    Table,
+    Timeline,
+    Typst,
+)
+
+try:
+    from _runner import run_example
+except ModuleNotFoundError as exc:
+    if exc.name != "_runner":
+        raise
+    from examples._runner import run_example
+
+
+def build_scene() -> Scene:
+    scene = Scene(frame="landscape")
+
+    title = scene.add(Label("Core Surfaces", height=0.34, color=WHITE))
+    scene.to_edge(title, "up", margin=0.65)
+
+    subtitle = scene.add(
+        Label("Paths, code, math, axes, planes, and tables from Python", height=0.17, color=GRAY_B)
+    )
+    scene.next_to(subtitle, title, "down", padding=0.24)
+
+    curve = Path(color=GOLD_C, thickness=0.045)
+    curve.move_to((-2.2, -0.15))
+    curve.cubic_to((-1.4, 1.0), (-0.5, -1.0), (0.25, 0.15))
+    curve.cubic_to((0.75, 0.9), (1.45, -0.45), (2.1, 0.25))
+    curve_id = scene.add(curve, at=(-3.45, 0.2, 0.0))
+
+    plane = NumberPlane(x_range=(-2.2, 2.2), y_range=(-1.4, 1.4), step=0.7)
+    plane_id = scene.add(plane, at=(-3.45, 0.2, 0.0))
+
+    axes = Axes(x_range=(-2.2, 2.2), y_range=(-1.4, 1.4), color=GRAY_A)
+    axes.with_step(0.7)
+    axes.with_thickness(0.018)
+    axes_id = scene.add(axes, at=(-3.45, 0.2, 0.0))
+
+    code = CodeBlock(
+        "scene = Scene()\\npath = Path(color=GOLD_C)\\nscene.add(path)",
+        language="python",
+        font_size=0.16,
+    )
+    code.with_title("example.py")
+    code.with_surface("dark")
+    code_id = scene.add(code, at=(2.55, 1.0, 0.0))
+
+    latex_id = scene.add(Latex(r"\\nabla f(x, y)", height=0.28, color=GREEN_D), at=(2.55, -0.55, 0.0))
+    typst_id = scene.add(Typst("$A x = b$", height=0.26, color=TEAL_D), at=(2.55, -1.05, 0.0))
+
+    table = Table([["Surface", "Status"], ["Path", "bound"], ["Table", "bound"]])
+    table.with_title("Python API")
+    table.with_text_color(WHITE)
+    table.with_line_color(BLUE_D)
+    table.with_text_height(0.15)
+    table_id = scene.add(table, at=(2.55, -2.35, 0.0))
+
+    timeline = Timeline()
+    timeline.animate(title).at(0.0).for_duration(0.6).typewrite_text().spawn()
+    timeline.animate(subtitle).at(0.25).for_duration(0.8).reveal_text().spawn()
+    timeline.animate(plane_id).at(0.8).for_duration(0.45).appear().spawn()
+    timeline.animate(axes_id).at(1.05).for_duration(0.55).draw().spawn()
+    timeline.animate(curve_id).at(1.45).for_duration(0.85).draw().spawn()
+    timeline.animate(code_id).at(1.8).for_duration(0.75).reveal_text().spawn()
+    timeline.animate(latex_id).at(2.35).for_duration(0.55).reveal_text().spawn()
+    timeline.animate(typst_id).at(2.65).for_duration(0.55).reveal_text().spawn()
+    timeline.animate(table_id).at(3.0).for_duration(0.8).write_table().spawn()
+    scene.play(timeline)
+
+    return scene
+
+
+if __name__ == "__main__":
+    run_example(build_scene, "rendered_output/core_surfaces.png")

murali_kit-0.1.0/examples/hello_shapes.py

@@ -0,0 +1,34 @@
+from murali_engine import BLUE, GREEN, WHITE, Circle, Label, Rectangle, Scene, Square, Timeline
+
+try:
+    from _runner import run_example
+except ModuleNotFoundError as exc:
+    if exc.name != "_runner":
+        raise
+    from examples._runner import run_example
+
+
+def build_scene() -> Scene:
+    scene = Scene()
+
+    title = scene.add(Label("Hello from Murali Kit", height=0.3, color=WHITE), at=(0.0, 1.0, 0.0))
+
+    circle = Circle(radius=0.5, color=GREEN, segments=32)
+    circle.with_stroke(0.03, WHITE)
+    moving_circle = scene.add(circle, at=(-1.0, 0.0, 0.0))
+
+    scene.add(Square(size=0.6, color=BLUE), at=(1.0, 0.0, 0.0))
+    scene.add(Rectangle(width=1.2, height=0.4, color=WHITE), at=(0.0, -1.0, 0.0))
+
+    timeline = Timeline()
+    timeline.animate(title).at(0.0).for_duration(0.4).typewrite_text().spawn()
+    timeline.animate(moving_circle).at(0.2).for_duration(0.8).ease("out_cubic").move_to(
+        (0.0, -0.2, 0.0)
+    ).spawn()
+    scene.play(timeline)
+
+    return scene
+
+
+if __name__ == "__main__":
+    run_example(build_scene, "rendered_output/hello_shapes.png")