{"id":19379573,"url":"https://github.com/we-gold/tinyneat","last_synced_at":"2025-04-23T19:32:53.120Z","repository":{"id":185588694,"uuid":"671611100","full_name":"We-Gold/tinyneat","owner":"We-Gold","description":"TinyNEAT is a simple and extensible NEAT (NeuroEvolution of Augmenting Topologies) implementation in TypeScript.","archived":false,"fork":false,"pushed_at":"2023-08-09T10:51:30.000Z","size":986,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T19:22:09.237Z","etag":null,"topics":["genetic-algorithm","machine-learning","neat","neat-algorithm","neural-network","neuroevolution","p5js","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/tinyneat","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/We-Gold.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-27T18:06:20.000Z","updated_at":"2024-12-10T13:56:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"9aa8ab18-d8c6-44e2-84e6-67878156aa1a","html_url":"https://github.com/We-Gold/tinyneat","commit_stats":null,"previous_names":["we-gold/tinyneat"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/We-Gold%2Ftinyneat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/We-Gold%2Ftinyneat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/We-Gold%2Ftinyneat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/We-Gold%2Ftinyneat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/We-Gold","download_url":"https://codeload.github.com/We-Gold/tinyneat/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250499924,"owners_count":21440715,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["genetic-algorithm","machine-learning","neat","neat-algorithm","neural-network","neuroevolution","p5js","typescript"],"created_at":"2024-11-10T09:10:34.931Z","updated_at":"2025-04-23T19:32:52.726Z","avatar_url":"https://github.com/We-Gold.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GitHub package.json version (branch)](https://img.shields.io/github/package-json/v/We-Gold/tinyneat/main?label=npm%20version\u0026color=green\u0026link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2Ftinyneat)\n![npm bundle size](https://img.shields.io/bundlephobia/min/tinyneat?color=green)\n[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/We-Gold/tinyneat/issues)\n![CI](https://github.com/We-Gold/tinyneat/actions/workflows/ci.yaml/badge.svg)\n![ViewCount](https://views.whatilearened.today/views/github/We-Gold/tinyneat.svg)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n![NPM Downloads](https://img.shields.io/npm/dw/tinyneat)\n\n## What is TinyNEAT?\n\nTinyNEAT is a simple and extensible NEAT (NeuroEvolution of Augmenting Topologies) implementation in JavaScript.\n\n_[Skip To Documentation](#documentation)_\n\n#### Motivation\n\nWith many websites and web-based games being written in JavaScript, having a solid starting place for using NEAT to train AI agents seems pretty useful.\n\nThe goal is that this library is able to fit into any particular use case, and that the implementation of the environment is entirely up to the user.\n\n#### Features\n\n-   Tiny Size (less than 20 KB!)\n-   Plugin System\n    -   Neural Networks\n    -   Logging\n-   Examples Provided\n-   Fully Configurable\n-   Complete TypeScript Support\n\n## Basic Example\n\n### Installation\n\n```bash\nnpm i tinyneat\n```\n\nor\n\n```html\n\u003c!-- Import using CDN, no types included --\u003e\n\u003cscript\n\ttype=\"module\"\n\tsrc=\"https://cdn.jsdelivr.net/npm/tinyneat/dist/index.js\"\n\u003e\u003c/script\u003e\n```\n\n### Example Usage (inspired by OpenAI gym)\n\n```js\nimport { TinyNEAT } from \"tinyneat\"\n\nconst tn = TinyNEAT(config)\n\n// Loop until the configured fitness or generation threshold has been met.\n// Will never end if neither is configured.\nwhile (!tn.complete()) {\n\tconst populationIndexed = tn.getPopulationIndexed()\n\n\t// Reset the environment for a new generation\n\tenv.reset(populationIndexed.length)\n\n\t// Environment loop for one generation\n\tfor (let step = 0; step \u003c maxGenerationSteps; step++) {\n\t\tfor (const [i, genome] of populationIndexed) {\n\t\t\tconst inputs = env.getInputs(i)\n\n\t\t\tconst outputs = genome.process(inputs)\n\n\t\t\t// Environment either supports outputs or takes argmax action\n\t\t\tconst stepFitness = env.receiveAgentAction(i, outputs)\n\n\t\t\t// Fitness is either calculated at the end of the generation\n\t\t\t// or iteratively throughout.\n\t\t\tgenome.fitness += stepFitness\n\t\t}\n\t}\n\n\t// Run evolution to produce the next generation\n\ttn.evolve()\n}\n\n// Reset the environment for a testing round\nenv.reset(1)\n\n// Test the best genome in a round\nconst bestGenome = tn.getBestGenomes()[0]\n\nfor (let step = 0; step \u003c maxGenerationSteps; step++) {\n\t// Get the inputs for the singular agent\n\tconst inputs = env.getInputs(0)\n\n\tconst outputs = bestGenome.process(inputs)\n\n\tbestGenome.fitness += env.receiveAgentAction(i, outputs)\n}\n\nconsole.log(`Best fitness: ${tn.getBestGenomes()[0].fitness}`)\n```\n\n## NEAT Demos\n\n[Racing](https://wegold.me/tinyneat/examples/racing/): An adaptation of a very old project of mine that trains agents to drive around race tracks.\n\n## Environment Recommendations\n\nEnvironments are not managed by TinyNEAT. We do recommend one of two environment structures. One, is an OpenAI gym-type environment, where each agent has their own environment. The other is an environment that manages each agent individually inside a single environment.\n\nEnvironments are expected to iterate automatically, manage agents, and calculate fitness values. After each generation, TinyNEAT will handle the rest, as long as fitness values have been calculated for each genome (they are initialized to 0). TinyNEAT will build neural networks and provide evaluate methods.\n\n## Documentation\n\nSee our reference documentation [here](https://wegold.me/tinyneat/docs).\n\n### Configuration\n\nThe following is the default configuration of TinyNEAT. For any changes, for example the number of inputs to the networks, pass an object with these updated properties to the `TinyNEAT` method.\n\n```js\n// Closely based on parameters of the original NEAT paper\nexport const defaultConfig = {\n\tinitialPopulationSize: 50, // Number of networks in the population\n\ttargetSpecies: 10, // Desired number of species to maintain\n\tmaxGenerations: 100, // Stopping point for evolution\n\n\tmaximumStagnation: 15, // Maximum number of generations a species is allowed to stay the same fitness before it is removed\n\texcessCoefficient: 2.0, // Coefficient representing how important excess genes are in measuring compatibility\n\tdisjointCoefficient: 2.0, // Coefficient for disjoint genes\n\tweightDifferenceCoefficient: 1.0, // Coefficient for average weight difference (highly recommended for tuning)\n\tcompatibilityThreshold: 6.0, // Threshold for speciation (highly recommended for tuning)\n\tcompatibilityModifier: 0.3, // Rate to change the compatibility threshold at when target species count is not met\n\tsurvivalThreshold: 0.2, // Percentage of each species allowed to reproduce\n\tmutateOnlyProbability: 0.25, // Probability that a reproduction will only result from mutation and not crossover\n\tmateOnlyProbability: 0.2, // Probability an offspring will be created only through crossover without mutation\n\taddNodeProbability: 0.03, // Probability a new node gene will be added to the genome\n\taddLinkProbability: 0.05, // Probability a new connection will be added\n\tmutateWeightProbability: 0.3, // Probability a weight will be mutated\n\tinterspeciesMatingRate: 0.01, // Percentage of crossovers allowed to occur between parents of different species\n\tmateByChoosingProbability: 0.6, // Probability that genes will be chosen one at a time from either parent during crossover\n\tmateByAveragingProbability: 0.4, // Probability that matching genes will be averaged during crossover\n\treenableConnectionProbability: 0.01, // Probability that a connection is randomly reenabled during crossover\n\n\tfitnessSort: \"max\",\n\n\tlargeNetworkSize: 20, // A network with this many genes is considered to be large\n\tminimumSpeciesSize: 1, // The minimum number of offspring a species can have\n\n\thallOfFameSize: 10, // The number of top-performing individuals to store\n\n\tinputSize: 1, // The number of inputs to each neural network\n\toutputSize: 1, // The number of outputs of each neural network\n\n\t// Plugin for the specific type of neural network (ANN, RNN, etc)\n\tnnPlugin: ANNPlugin(),\n\n\t// Plugins for logging data\n\tloggingPlugins: [ConsoleLogger()],\n}\n```\n\n### Usage vs. Plugin Development\n\nTinyNEAT supports both standard usage and plugins that add custom functionality. Certain plugins are built-in, such as the standard feedforward neural network and a few default loggers.\n\nThere are only two external entry points to the library. See below:\n\n```js\nimport { TinyNEAT, plugins } from \"tinyneat\"\n```\n\nThe `TinyNEAT` method (with configuration) creates and manages the population of NEAT individuals and provides all necessary methods. See [Basic Example](#basic-example) for what this looks like.\n\nThis was done so that multiple NEAT instances can be created with no conflicts.\n\n**Besides the `TinyNEAT` method and `plugins`, nearly all other items in the documentation are internal.** These are only applicable for building plugins.\n\n## Plugin Development\n\nTinyNEAT currently supports two types of plugins: Neural Network Plugins and Logging Plugins.\n\n### Neural Network Plugins\n\nThese plugins extend TinyNEAT's capabilities, enabling any type of neural network desired. While a only a standard ANN\nplugin is provided, additional plugins can be developed. See the documentation (`NNPlugin`) for the proper interface, and see the configuration section for how to include a Neural Network Plugin.\n\nA plugin could even use Tensorflow.js, Brain.js, or another neural network library, as long as it works in conjunction with NEAT.\n\n### Logging Plugins\n\nThese plugins enable custom logging features. TinyNEAT emits two events, one when the initial population is created, and one on each evolution. For more specific information, see the `Logger` interface in the documentation.\n\nAlso, see `consolelogger.ts` for a basic example.\n\n## Library Development\n\nIf you are interested in contributing to the library, or have public plugin code you would like linked on this page, create an issue or pull request.\n\nFor local installation, simply clone the repository and run `npm i` to install all of the development dependencies.\n\nAll scripts are listed in `package.json`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwe-gold%2Ftinyneat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwe-gold%2Ftinyneat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwe-gold%2Ftinyneat/lists"}