Metadata-Version: 2.4
Name: ember-edu
Version: 0.2.0
Summary: Lightweight educational simulation library for AI-generated visual lessons
License-Expression: MIT
Project-URL: Repository, https://github.com/hegdeadithyak/ember
Keywords: education,simulation,visualization,AI,STEM
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: Pillow>=10.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# ember

`ember` is a small educational simulation library.

The main goal is simple: an AI or teacher should be able to make a clear visual
simulation without writing hundreds of lines. The code should focus on the idea,
not on drawing everything manually.

It is useful for:

- explaining science and maths concepts
- making small interactive lessons
- generating GIF/PNG style visual explanations
- testing how LLMs can create better teaching simulations

This is not a game engine in the big sense and it is not a console emulator. It
is a lightweight sandbox for educational visuals.

## What Is Inside

- A C11 core library in `src/` and `include/`
- Python bindings in `python/ember/`
- A high-level education API in `python/ember/edu.py`
- Example simulations in `examples/` and `games/`
- Plain text mission files in `missions/`
- Documentation in `docs/`

The most important API for AI-generated lessons is `ember.edu`.

## Example Gallery

These previews are regenerated into `docs/gallery/` so changes in the visual
library are visible in the README. The small examples show the target style:
AI writes one clear mechanism in roughly 40-50 lines instead of making a large
custom app.

Regenerate the gallery after visual/library changes:

```bash
make gallery
```

| Concept | Source | Render |
| --- | --- | --- |
| Fajan's rule | [examples/fajan_sim_test.py](examples/fajan_sim_test.py) - 47 lines | ![Fajan rule preview](docs/gallery/fajan_sim_test.png) |
| Faraday's law | [examples/faraday_sim_test.py](examples/faraday_sim_test.py) - 62 lines | ![Faraday law preview](docs/gallery/faraday_sim_test.png) |
| Hybridisation | [examples/hybridisation_sim.py](examples/hybridisation_sim.py) - 64 lines | ![sp3 hybridisation preview](docs/gallery/hybridisation_sim.png) |
| Heart function | [games/heart_sim.py](games/heart_sim.py) - richer demo | ![Heart function animation](docs/gallery/heart_function.gif) |
| Transformer attention | [games/transformer_sim.py](games/transformer_sim.py) - richer demo | ![Transformer attention animation](docs/gallery/transformer_attention.gif) |

## Run Examples

From the repo root:

```bash
PYTHONPATH=python python3 examples/hybridisation_sim.py
PYTHONPATH=python python3 games/heart_sim.py
PYTHONPATH=python python3 games/transformer_sim.py
```

Many examples also add the local `python/` path themselves, so they can be run
directly with `python3`.

## Build And Test

```bash
make all
make test
make python-test
```

Run the default C mission:

```bash
make run
```

This writes frames into `build/`.

## For AI Agents

Before generating a simulation, read the prompt contract:

```python
import ember
print(ember.prompt)
```

The same guide is available here:

[docs/AI_SIMULATION_GUIDE.md](docs/AI_SIMULATION_GUIDE.md)

Important rules for AI-generated simulations:

- Ask what exact mechanism the user wants to understand.
- Websearch for factual topics unless the user provides source material.
- Show one clear cause and effect.
- Prefer concrete scenes over abstract variable animation.
- Keep the code small.
- Use only existing public APIs.
- Do not edit the library unless the user asks for library work.

For most visual lessons, use `Lesson` plus `Sketch`:

```python
from ember.edu import Lesson, Sketch

def draw(canvas, state):
    canvas.text("main idea", 0, -0.8)

lesson = Lesson("My Lesson", theme="neon")
lesson.show_hud = False
lesson.state.params["_time"] = 0.0
lesson.rate("_time", lambda s: 1.0)
lesson.show(Sketch(draw, "one-line visual legend"))
lesson.explain("One sentence takeaway.")
lesson.run()
```

## Useful Docs

- [docs/AI_SIMULATION_GUIDE.md](docs/AI_SIMULATION_GUIDE.md): system prompt for AI agents
- [docs/EDU_LIBRARY.md](docs/EDU_LIBRARY.md): high-level education API
- [docs/GRAPHICS_API.md](docs/GRAPHICS_API.md): lower-level graphics helpers
- [docs/PYTHON_BINDINGS.md](docs/PYTHON_BINDINGS.md): Python API
- [docs/MISSION_FORMAT.md](docs/MISSION_FORMAT.md): text mission format
- [docs/CAR_PHYSICS.md](docs/CAR_PHYSICS.md): car physics lesson

## Project Layout

```text
include/          C public headers
src/              C implementation
python/ember/     Python package
examples/         small concept examples
games/            richer interactive lessons
missions/         text mission files
docs/             documentation
tests/            C and Python tests
```

## Notes

The project is still evolving. The important direction is to make the library
more general and easier for smaller models also. If a generated sim needs too
much drawing code, that is a sign the library needs a better primitive.
