[ternaus]

Introduce a seeded Generator with independent state, floating distributions, bounded integers, and caller-owned output buffers. State and fills are serialized per instance. Generation is scalar, and normal sampling uses host libm.

This introduces a new public API and remains a separate, lower-priority review.

Refs #299.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

6 open issues

• These NK_PUBLIC functions are defined in a public header, which will typically produce… · New
• The GIL is released while fill(...) mutates generator->generator.state. If the same Generator… · New
• This example assertion is likely incorrect/ambiguous: == for array/tensor-like objects is often… · New
• The stubs indicate size is optional for uniform/normal/integers (defaulting to ...), but… · New
• Generator.integers parses low/high strictly as signed int64 regardless of dtype. This… · New
• The error message format here is non-standard for Python call errors. For consistency with typical… · New

What changed in this PR

Adds a stateful nk.Generator(seed=...) API to provide independent, reproducible random generation from Python (with optional out= support and dtype/shape controls), backed by new native RNG utilities.

Changes:

• Introduces native RNG core (include/numkong/random.h) and Python bindings (python/random.c/.h) for Generator methods (random, uniform, normal, standard_normal, integers) and state.
• Exposes the new Generator type from the extension module and adds typing stubs + Python documentation.
• Adds a dedicated pytest suite covering determinism, state restore, dtype/shape/bounds, and out= behavior.

File	Description
test/​test_random.py	Adds tests for determinism, state independence/restore, out= validation, and argument errors.
setup.py	Adds python/random.c to the extension build sources.
python/​random.h	Declares the new RandomGeneratorType for module registration.
python/​random.c	Implements numkong.Generator Python C-extension type and distribution methods (GIL-releasing fills).
python/​numkong/​__init__.pyi	Adds typing stubs for the new Generator API.
python/​numkong.c	Registers the Generator type with the extension module.
python/​README.md	Documents nk.Generator usage and out= semantics.
include/​numkong/​random.h	Adds the native RNG generator struct and RNG/distribution functions.
include/​numkong/​numkong.h	Re-exports the new RNG header from the umbrella include.

_{Review effort: Lite}