Metadata-Version: 2.4
Name: northcel
Version: 0.3.1
Summary: NorthCel (.ncel) — the open drawing language for AI-drawn video: reference parser, validator, formatter and CPU renderer, plus the one-command CLI that runs the native MoonBit + Bend/HVM2 + GLSL runtime when the platform supports it.
Author: NorthCel contributors
License-Expression: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/syver777/northcel
Project-URL: Documentation, https://github.com/syver777/northcel/tree/main/docs
Project-URL: Repository, https://github.com/syver777/northcel
Project-URL: Changelog, https://github.com/syver777/northcel/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/syver777/northcel/issues
Project-URL: Language specification, https://github.com/syver777/northcel/blob/main/docs/spec/SPEC-0.2.0-draft.md
Keywords: northcel,ncel,ai-drawn-video,animation,hand-drawn,moonbit,bend,glsl,dsl
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
Requires-Dist: numpy>=1.24
Requires-Dist: Pillow>=10.0
Requires-Dist: northcel-native==0.3.1; sys_platform == "linux" and platform_machine == "x86_64"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# `northcel` — the reference implementation and the one-command CLI

This directory is one Python distribution: the **normative reference implementation**
(parser, semantic validator, formatter, CPU renderer) *and* the **launcher** that
runs the native runtime whenever the platform supports it.

```
pip install northcel        # installs this package + the northcel-native bundle
northcel doctor             # stages, exact versions, platform verdict
northcel verify             # real renders + determinism, from bundled fixtures
ncel doctor                 # short alias, same program
```

## Two implementations, one command

`northcel` dispatches, in this order:

1. **Native runtime** — MoonBit parses the typed scene/film AST, decodes every
   contour chain, expands `def`/`use`, applies frame deltas and the deterministic
   boil hash; **Bend 0.2.38 / HVM 2.0.22** evaluates every `bend_swarm` agent;
   **GLSL 4.30**, compiled by the **Mesa/EGL** driver (llvmpipe, no GPU),
   rasterises the normative `aa×aa` even-odd integration.
2. **Python reference** — this package's own renderer, used only where the native
   stages cannot run. It prints one line to stderr and labels the result
   `python-reference`. Nothing is ever silently substituted.
3. **`check` only:** the zero-dependency JS pre-check in the npm package, clearly
   labelled `PARTIAL`. It never reports a document as valid.

## Install and use

```
pip install northcel
northcel render scene.ncel -o frame.png --frame 0 --json
northcel film   film.ncel -o out/ --frames 0..5 --mp4 out.mp4 --json
northcel check  scene.ncel --json
northcel info   scene.ncel --json
northcel fmt    scene.ncel --check
northcel guide                      # offline authoring guide
northcel doctor --json              # machine-readable stage report
northcel toolchain status|install   # MoonBit compiler, only needed to rebuild
```

`--json` receipts from the native runtime include `language`, `northcel_version`,
`spec_version`, size/fps/frames, source bytes, per-frame `sha256`, stage timings,
geometry, swarm counts and `"stage": "MoonBit+Bend+GLSL"`.

## Platforms

Supported natively today: **Linux x86_64**, glibc ≥ 2.39, Mesa `libegl1` +
`libgl1` + `mesa-libgallium` (Ubuntu 24.04+, Debian 13, Fedora 40+, RHEL 10).

Everything else installs and is honest: macOS (Apple's OpenGL caps at 4.1; the
4.30 shader cannot compile there — macOS needs Vulkan/MoltenVK or a tested GL 4.1
path), Windows and non-x86_64 Linux get `northcel doctor` exit 3 with the exact
reason, and `render`/`film`/`check` run the Python reference, marked
`python-reference` — never "native".

## What `doctor` prints

```
northcel 0.3.1  (native runtime 0.2.0, spec 0.2.0-draft, native)
platform      linux-x86_64 glibc 2.39
supported     yes
native        0.2.0  (bundle checksums 13 verified, stage MoonBit+Bend+GLSL)
  MoonBit       stage present: yes  binary ncel-ast  compiled with MoonBit 0.1.20261102 (ea07287 2026-11-02)
  Bend          bend-lang 0.2.38  …/bin/bend
  HVM2          hvm 2.0.22  …/bin/hvm
  GL runtime    4.5 (Core Profile) Mesa 25.2.8  llvmpipe (LLVM 20.1.2, 256 bits)  GLSL 4.50
  GLSL          draw430 14829a3cbb6c… compiles  draw410 fe4d0c4fe4e0… compiles
  ffmpeg        present (optional, --mp4)
```

## What `verify` proves

- a starter scene renders to a 320×180 PNG;
- the shower `f0001` frame reproduces the pinned conformance hash (`be0eb036…`),
  which the Python reference reproduces pixel-for-pixel;
- a 6-frame film renders 6 distinct frames;
- both renders repeat with identical sha256 (determinism).

## Toolchain notes

A runtime needs no downloads: the MoonBit-compiled stage, Bend and HVM2 ship inside
`northcel-native`, with every file sha256-pinned in `bundle-manifest.json` and
checked against `native/toolchain.lock`. The **MoonBit compiler** (101 MB) is only
needed to rebuild the native tree — `northcel toolchain install` fetches and
verifies it into `~/.local/share/ncel/toolchain` (the directory name is historical).

GLSL is not installed; it is compiled by the GL driver. That is why the installer
provisions the **Mesa/EGL runtime**, and why `doctor` compiles and links both
shaders as proof.

## Python API

```python
from northcel import parse_ncel, validate_document, format_document
from northcel.renderer import render_document_frame, render_film_frames

doc = parse_ncel(open("scene.ncel").read())
print([d.format() for d in validate_document(doc) if d.level == "error"])
rgb = render_document_frame(doc, frame_index=0)      # numpy uint8 (H, W, 3)
```

## Uninstall

```
pip uninstall northcel northcel-native
rm -rf ~/.local/share/ncel        # only if you ran `northcel toolchain install`
```

## Licence

Dual licensed under MIT OR Apache-2.0 — see `LICENSE-MIT` and `LICENSE-APACHE` in
the repository root.
