@reicek/neataptic-ts 0.1.19 → 0.1.21

package/README.md

@@ -5,7 +5,7 @@
   <a href="docs/index.html"><img src="https://img.shields.io/badge/docs-generated-2c3963.svg" alt="Docs"/></a>
 </div>
 
-<img src="https://cdn-images-1.medium.com/max/800/1*THG2__H9YHxYIt2sulzlTw.png" width="480"/>
+<img src="nn.jpg" width="480"/>
 
 > The unofficial modern, typed evolution of **Neataptic**.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reicek/neataptic-ts",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Architecture-free neural network library with genetic algorithm implementations",
   "main": "./dist/neataptic.js",
   "module": "./dist/neataptic.js",
@@ -17,6 +17,9 @@
     "build:ts": "tsc",
     "build:webpack": "webpack --config webpack.config.js",
     "build:ascii-maze": "npx esbuild test/examples/asciiMaze/browser-entry.ts --bundle --outfile=docs/assets/ascii-maze.bundle.js --platform=browser --format=iife --minify --sourcemap --external:fs --external:child_process --external:path",
+    "build:flappy-worker": "npx esbuild test/examples/flappy_bird/flappyEvolution.worker.ts --bundle --outfile=docs/assets/flappy-evolution.worker.bundle.js --platform=browser --format=iife --minify --sourcemap --external:fs --external:child_process --external:path",
+    "build:flappy-bird": "npx esbuild test/examples/flappy_bird/browser-entry/browser-entry.ts --bundle --outfile=docs/assets/flappy-bird.bundle.js --platform=browser --format=iife --minify --sourcemap --external:fs --external:child_process --external:path",
+    "start:local-server": "npx http-server . -p 8080 -c-1",
     "start:ts": "ts-node src/neataptic.ts",
     "test:e2e": "cross-env FORCE_COLOR=true jest e2e.test.ts --no-cache --runInBand",
     "test:e2e:logs": "npx jest e2e.test.ts --verbose --runInBand --no-cache",
@@ -28,7 +31,7 @@
     "prettier": "npm run prettier:tests && npm run prettier:src",
     "prettier:tests": "npx prettier --write test/**/*.ts",
     "prettier:src": "npx prettier --write src/**/*.ts",
-    "docs": "npm run build:ascii-maze && npm run docs:examples && npm run docs:build-scripts && node ./dist-docs/scripts/generate-docs.js && node ./dist-docs/scripts/render-docs-html.js",
+    "docs": "npm run build:ascii-maze && npm run build:flappy-worker && npm run build:flappy-bird && npm run docs:examples && npm run docs:build-scripts && node ./dist-docs/scripts/generate-docs.js && node ./dist-docs/scripts/render-docs-html.js",
     "lint": "eslint src/ test/",
     "lint:fix": "eslint src/ --fix",
     "onnx:export": "node scripts/export-onnx.mjs"

package/plans/Architecture_Primitives_Node_Group_Layer.md

@@ -0,0 +1,211 @@
+# Architecture Primitives (Node / Group / Layer) Plan
+
+## Purpose
+
+Introduce a **first-class architecture-building API** that lets users construct networks from composable primitives (nodes, groups, layers), while staying compatible with:
+
+- Evolution (topology + weights)
+- Optional gradient fine-tuning
+- Telemetry and reproducibility
+
+This plan focuses on **ergonomic graph construction** and **strong typing**, not on changing the core evolutionary algorithms.
+
+## Why this matters
+
+Many users want to:
+
+- Build a custom graph (including gating/modulatory patterns) before evolving.
+- Swap parts of a network (e.g., replace an encoder) without rewriting controllers.
+- Teach the library “this is input / this is output” without relying on fragile indexing.
+
+A primitives API also becomes the foundation for:
+
+- preconfigured architectures (separate plan)
+- visualization export (separate plan)
+- browser examples (separate plan)
+
+## Goals
+
+- G1: Provide minimal primitives that can express arbitrary directed graphs.
+- G2: Make input/output designation explicit and robust.
+- G3: Ensure primitives can be compiled into the existing `Network` execution model.
+- G4: Preserve current public API; primitives are additive.
+
+## Non-goals
+
+- Replacing the existing `Network` class.
+- Designing a full deep-learning layers DSL (Conv/Attention/etc).
+- Introducing any breaking changes in NEAT controller behavior.
+
+## Proposed primitives
+
+### `NeuronNode` (or `Node`)
+
+A lightweight object that represents a neuron-like unit with:
+
+- id (stable)
+- type (`input` | `hidden` | `output` | `constant`)
+- bias, activation function, optional metadata
+
+### `ConnectionEdge`
+
+A connection between nodes:
+
+- fromId, toId
+- weight
+- enabled flag
+- optional gating/modulation reference
+
+### `NodeGroup`
+
+A collection of nodes with helper operations:
+
+- create N nodes
+- connect to another group with a connection policy
+- gate a set of edges (optional, if supported)
+
+### `Layer`
+
+A specialization of group with explicit `inputNodes` and `outputNodes` to simplify connecting composite blocks.
+
+## API sketch
+
+```ts
+export type NodeRole = 'input' | 'hidden' | 'output' | 'constant';
+
+export interface NodeSpec {
+  role: NodeRole;
+  bias?: number;
+  activation?: Activation;
+  label?: string;
+}
+
+export class GraphNode {
+  readonly id: string;
+  role: NodeRole;
+  bias: number;
+  activation: Activation;
+}
+
+export interface ConnectOptions {
+  weightInit?: WeightInitializer;
+  allowSelf?: boolean;
+  allowRecurrent?: boolean;
+}
+
+export class NodeGroup {
+  readonly nodes: readonly GraphNode[];
+  connect(
+    target: NodeGroup | GraphNode,
+    policy?: ConnectPolicy,
+    options?: ConnectOptions,
+  ): GraphEdge[];
+}
+
+export class Layer extends NodeGroup {
+  readonly inputNodes: readonly GraphNode[];
+  readonly outputNodes: readonly GraphNode[];
+}
+
+export interface GraphBuildResult {
+  network: Network;
+  mapping: {
+    nodeIdToNetworkIndex: Map<string, number>;
+  };
+}
+
+export function constructNetwork(
+  parts: Array<NodeGroup | Layer | GraphNode>,
+  options?: ConstructOptions,
+): GraphBuildResult;
+```
+
+The library should keep naming consistent with existing exports, but the key is:
+
+- stable ids
+- explicit roles
+- a single “construct” function that produces a `Network`.
+
+## Implementation steps
+
+### Step 1 — Define types and minimal classes
+
+- Add new module folder, e.g. `src/architecture/primitives/`.
+- Implement minimal `GraphNode`, `GraphEdge`, `NodeGroup`, and `Layer`.
+
+Acceptance:
+
+- Can create groups and connect them; edges are produced.
+
+### Step 2 — Connection policies
+
+Implement a small set of connection policies:
+
+- `oneToOne`
+- `allToAll`
+- `allToAllForward` (acyclic-by-construction)
+- `allToElse` (exclude same-node connections)
+
+Acceptance:
+
+- Policies are deterministic under seeded RNG/weight initializer.
+
+### Step 3 — Define role inference rules (conservative)
+
+Construction must not guess aggressively.
+
+Rules:
+
+- If any nodes are explicitly marked `input`/`output`, use those.
+- If not, require the user to specify via options.
+- Provide a helper that can infer only when unambiguous, but default to explicit.
+
+Acceptance:
+
+- Ambiguous graphs throw descriptive errors.
+
+### Step 4 — Compile primitives into a `Network`
+
+- Implement `constructNetwork(...)`:
+  - resolve nodes in stable order
+  - create a `Network` with correct input/output sizes
+  - add nodes in the correct order
+  - materialize connections and optional gating references
+
+Acceptance:
+
+- Constructed network activates and produces outputs.
+
+### Step 5 — JSDoc + docs map
+
+- Document the primitives as an educational feature.
+- Provide 2–3 short examples:
+  - MLP via groups
+  - custom graph via nodes
+  - layer chaining
+
+Acceptance:
+
+- Docs generator includes the new APIs cleanly.
+
+## Testing strategy
+
+- Unit tests for policies and construct:
+  - builds correct node counts
+  - preserves explicit input/output roles
+  - rejects ambiguous graphs
+  - deterministic construction under seed
+- Typecheck: `npx tsc --noEmit -p tsconfig.json`
+
+## Risks and mitigations
+
+- Risk: duplicating concepts already in `Network`.
+  - Mitigation: primitives compile _into_ `Network`; do not fork execution.
+- Risk: confusion about "graph" vs "genome" semantics.
+  - Mitigation: docs clarify: primitives are for building initial phenotypes; NEAT still operates on genomes.
+
+## Success criteria
+
+- Users can construct non-trivial architectures without touching internal arrays.
+- The constructed network works with evolution and training flows.
+- No breaking changes to existing imports.

package/plans/Browser_Build_and_CDN_Distribution.md

@@ -0,0 +1,158 @@
+# Browser Build + CDN Distribution Plan
+
+## Purpose
+
+Make NeatapticTS effortless to use in the browser:
+
+- Provide **official browser bundles** (ESM + IIFE) with a stable public surface.
+- Enable **copy/paste quickstarts** for demos, education, and interactive docs.
+- Preserve Node-first correctness and determinism.
+
+This plan is strictly about packaging, compatibility, and documentation—not new algorithms.
+
+## Why this matters
+
+A library can be technically excellent and still lose adoption if the first run experience is hard. Browser support unlocks:
+
+- Interactive documentation and “try it live” examples.
+- Lightweight playgrounds for evolution experiments.
+- Classroom use (no Node install, no build pipeline).
+
+## Goals
+
+- G1: Produce a **browser ESM build** that works with modern bundlers and native ESM.
+- G2: Produce a **single-file IIFE build** for `<script>` usage.
+- G3: Ensure the browser build has a clearly defined public API entry (no deep imports).
+- G4: Keep Node builds unchanged and fully supported.
+
+## Non-goals
+
+- Implementing new NEAT features (tracked elsewhere).
+- Supporting legacy browsers requiring heavy polyfills.
+- Guaranteeing identical performance characteristics vs Node.
+
+## Compatibility target
+
+- Modern evergreen browsers (Chromium, Firefox, Safari) with ES2023-ish features.
+- If a feature requires Node-only APIs (fs, worker_threads), it must be:
+  - compiled out of the browser bundle, or
+  - behind a runtime capability check with a clear error.
+
+## Public API (browser)
+
+Provide a stable top-level namespace export.
+
+Proposed browser entry exports:
+
+- `Neat`
+- `Network`
+- `Architect` (if present)
+- `methods` / activations / cost functions (where applicable)
+- Optional: `version`
+
+Avoid exporting internal/private helpers.
+
+## Build artifacts
+
+Add/standardize these artifacts under `dist/`:
+
+- `dist/neataptic.browser.esm.js` (ESM)
+- `dist/neataptic.browser.iife.js` (IIFE)
+- `dist/neataptic.browser.iife.min.js` (minified)
+- Source maps for all where practical
+
+Naming can be adjusted to fit current conventions; the key is that we ship both ESM and IIFE.
+
+## Implementation steps
+
+### Step 1 — Define browser entry module
+
+- Create a dedicated browser entry file (example name):
+  - `src/browser-entry.ts`
+- Re-export only supported browser-safe symbols.
+- Ensure no Node-only modules are imported transitively.
+
+Acceptance:
+
+- A simple `import { Neat } from './dist/neataptic.browser.esm.js'` works.
+
+### Step 2 — Split Node-only concerns behind environment adapters
+
+- Introduce “environment adapter” modules so imports are browser-safe:
+  - `src/env/node/*`
+  - `src/env/browser/*`
+  - `src/env/index.ts` that chooses by build target (compile-time), not runtime.
+
+Notes:
+
+- If runtime selection is needed, use capability checks, not user-agent sniffing.
+
+Acceptance:
+
+- Browser bundle has no references to Node built-ins (`fs`, `path`, `worker_threads`).
+
+### Step 3 — Add explicit bundling pipeline
+
+Use existing tooling already present in repo:
+
+- Keep `webpack.config.js` for main dist build if desired.
+- Add a small `esbuild`/webpack target for browser artifacts.
+
+Add scripts (names illustrative):
+
+- `npm run build:browser`
+- `npm run build:browser:min`
+
+Acceptance:
+
+- `npm run build` continues to work.
+- `npm run build:browser` produces the expected dist files.
+
+### Step 4 — Document browser usage
+
+Add a dedicated docs page:
+
+- `docs/` content or a `README` section describing:
+  - script tag IIFE usage
+  - ESM usage
+  - limitations (threads, filesystem, perf)
+
+Acceptance:
+
+- A user can run a minimal evolve loop in the browser with 10–20 lines.
+
+### Step 5 — Add a CI smoke check
+
+Without introducing heavy browser testing:
+
+- Add a small build-time smoke check that:
+  - imports the browser ESM output
+  - runs a trivial activation on a toy network
+
+Acceptance:
+
+- Build fails if the browser bundle is broken.
+
+## Testing strategy
+
+- TypeScript: `npx tsc --noEmit -p tsconfig.json`
+- Build: `npm run build` and `npm run build:browser`
+- Minimal runtime smoke:
+  - Node loads `dist/neataptic.browser.esm.js` (as ESM) and runs a simple call.
+  - Optional: a headless browser run (Puppeteer exists in dev deps) for a single-page smoke.
+
+## Risks and mitigations
+
+- Risk: accidental Node-only transitive imports.
+  - Mitigation: keep browser entry small; use env adapters.
+- Risk: tree-shaking breaks side-effect assumptions.
+  - Mitigation: mark side-effectful modules clearly; add smoke tests.
+- Risk: bundle size grows.
+  - Mitigation: export only essentials; avoid large optional modules by default.
+
+## Success criteria
+
+- `npm run build:browser` produces ESM + IIFE outputs.
+- A minimal browser example works without bundlers.
+- Node build remains unchanged.
+- Documentation includes at least one runnable browser example.

package/plans/Construct_From_Parts_Graph_Assembly.md

@@ -0,0 +1,164 @@
+# Construct From Parts (Deterministic Graph Assembly) Plan
+
+## Purpose
+
+Provide a deterministic, validated way to build a runnable `Network` from user-defined parts (nodes/groups/layers), with:
+
+- explicit input/output handling
+- a stable activation schedule
+- clear error messages for ambiguous/invalid graphs
+
+This is the correctness backbone for the primitives API and preconfigured architectures.
+
+## Goals
+
+- G1: Deterministic construction (same parts + seed ⇒ same built network).
+- G2: Robust validation (fail fast, descriptive errors).
+- G3: Stable activation ordering for acyclic graphs; well-defined handling for recurrence.
+- G4: Constructed networks seamlessly work with evolution/training.
+
+## Non-goals
+
+- Replacing NEAT genome operators.
+- Fully general static scheduling for arbitrary cyclic graphs without explicit recurrence semantics.
+
+## Key design decisions
+
+### 1) Input/output nodes must be explicit by default
+
+We should not silently guess I/O roles from degree heuristics except behind an explicit opt-in flag.
+
+### 2) Two construction modes
+
+- **Acyclic mode** (default):
+  - require that edges can be topologically sorted
+  - compute a stable activation order
+- **Recurrent mode** (opt-in):
+  - allow cycles
+  - define recurrence handling policy and state reset policy
+
+### 3) Stable node identity
+
+Construction uses stable node ids (string/number). Internal network indices are derived deterministically.
+
+## API sketch
+
+```ts
+export interface ConstructOptions {
+  mode?: 'acyclic' | 'recurrent';
+  inputNodes?: string[];
+  outputNodes?: string[];
+  allowIsolatedHiddenNodes?: boolean;
+  validate?: {
+    forbidDuplicateEdges?: boolean;
+    forbidSelfEdges?: boolean;
+  };
+}
+
+export interface ConstructDiagnostics {
+  nodeCount: number;
+  edgeCount: number;
+  detectedCycles: boolean;
+  activationOrder: number[]; // network indices
+}
+
+export function constructNetwork(
+  parts: Array<GraphNode | NodeGroup | Layer>,
+  options?: ConstructOptions,
+): { network: Network; diagnostics: ConstructDiagnostics };
+```
+
+## Implementation steps
+
+### Step 1 — Canonical graph extraction
+
+- Flatten parts into canonical sets:
+  - nodes (unique by id)
+  - edges (unique by (fromId,toId,kind))
+- Resolve conflicts deterministically:
+  - same node id with differing specs ⇒ error (unless exact-equal)
+
+Acceptance:
+
+- A graph can be built from mixed inputs (nodes + groups + layers).
+
+### Step 2 — Validation layer
+
+Implement validations with high-quality errors:
+
+- missing nodes referenced by edges
+- duplicate edges (optional)
+- self edges (policy-controlled)
+- acyclic mode: detect cycles and explain a minimal cycle path
+- input/output constraints:
+  - at least one input and output
+  - inputs cannot have incoming edges (optional rule)
+  - outputs cannot have outgoing edges (optional rule)
+
+Acceptance:
+
+- Invalid graphs produce errors that tell users what to change.
+
+### Step 3 — Activation scheduling
+
+**Acyclic mode**
+
+- Determine activation order by stable topological sort.
+- Tie-breaker must be deterministic (e.g., by node id).
+
+**Recurrent mode**
+
+- Require explicit `mode:'recurrent'`.
+- Define a policy:
+  - either use a fixed order that is stable but not a topological order
+  - and define how many “passes” per activation call (usually 1)
+
+Acceptance:
+
+- Acyclic graphs run with a proper topo order.
+- Recurrent graphs run deterministically given the same initial state.
+
+### Step 4 — Materialize into `Network`
+
+- Create `Network` with correct input/output sizes.
+- Map node ids to network indices.
+- Add nodes to `Network` with role, bias, activation.
+- Create connections with correct weights and enabled flags.
+
+Acceptance:
+
+- Built networks activate and return the expected output length.
+
+### Step 5 — Diagnostics + developer tools
+
+Add optional diagnostics to help users debug:
+
+- export a compact graph JSON
+- print a human-readable summary (counts, I/O ids, cycle info)
+
+Acceptance:
+
+- Users can introspect why a graph failed.
+
+## Testing strategy
+
+- Unit tests:
+  - stable topo order (same ids ⇒ same order)
+  - cycle detection yields a helpful cycle path
+  - recurrent mode requires explicit opt-in
+  - deterministic mapping from ids → indices
+- Property tests (optional):
+  - generate DAGs, ensure schedule covers all nodes
+
+## Risks and mitigations
+
+- Risk: scheduling semantics for recurrent networks confuse users.
+  - Mitigation: require explicit mode, document state/clear behavior.
+- Risk: graph builder becomes a second “Network”.
+  - Mitigation: builder only compiles into `Network`; no parallel runtime.
+
+## Success criteria
+
+- Users can assemble networks safely and deterministically.
+- Activation order is stable and correct for DAGs.
+- Recurrent graphs are supported with explicit, documented semantics.