NeatapticTS

A modern TypeScript NEAT library built to be read, tested, and extended.

NeatapticTS is a documentation-first evolution of Neataptic for people who want more than a black-box experiment runner. It combines typed neural-network primitives, NEAT-style topology evolution, reproducible runs, and educational examples that explain the architecture instead of hiding it.

This page is intentionally short. It is the entry map. The detailed API and subsystem documentation live in the generated docs and the focused READMEs throughout the repo.

Why this exists

Many neuroevolution libraries are either convenient but opaque, or educational but too small to trust as a real reference. NeatapticTS is built to close that gap.

The project aims to give you:

• readable internals instead of magic,
• deterministic seeds and telemetry for reproducible experiments,
• modern TypeScript and ES2023+ ergonomics,
• examples that behave like reference systems rather than toy snippets.

If you want a library you can inspect, modify, and learn from while still running serious experiments, this is the point of the repo.

Start here

Reading paths

If you are new to the repo

1. Read docs/index.html.
2. Read src/README.md.
3. Open one example:
   • examples/flappy_bird/README.md
   • examples/asciiMaze/README.md

If you want runnable source first

• examples/flappy_bird for the clearest full-system example.
• examples/asciiMaze for evolution orchestration, telemetry, and visualization.

If you want library internals

• src/neat/README.md
• src/architecture/network/README.md
• src/architecture/network/onnx/README.md
• src/multithreading/README.md

Examples worth opening first

Flappy Bird

examples/flappy_bird is the best single example if you want to understand how NeatapticTS feels in a real project.

It combines:

• deterministic environment stepping,
• evaluation designed to reduce lucky-rollout bias,
• worker-backed browser playback,
• live network inspection,
• a modular architecture with explicit boundaries.

ASCII Maze

examples/asciiMaze is the best companion example if you want to study curriculum progression, compact observations, reward shaping, and browser plus terminal visualization.

Install

Runtime requirement: Node 22+.

npm install @reicek/neataptic-ts

Minimal example:

import { Neat } from '@reicek/neataptic-ts';

const fitness = (network) => {
	const output = network.activate([1])[0];
	return -(output - 2) ** 2;
};

const neat = new Neat(1, 1, fitness, {
	popsize: 30,
	seed: 42,
	fastMode: true,
});

await neat.evaluate();
await neat.evolve();

console.log(neat.getBest()?.score);

For options, telemetry, and subsystem details, continue in docs/index.html.

Repo map

Contributing

This repo treats documentation as part of the product. If you change behavior, examples, or public API shape, update the documentation surface that teaches that boundary.

Primary contribution entry points:

• CONTRIBUTING.md
• STYLEGUIDE.md
• plans/src-no-explicit-any-cleanup.plans.md
• RELEASE.md

License

MIT.