strategy-genome 0.1.0__tar.gz

strategy_genome-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.venv/
+checkpoints/

strategy_genome-0.1.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-11-15
+
+First release. Carved out of [srfm-lab](https://github.com/Mattbusel/srfm-lab)
+`ml/genetic` at commit `8cbfcb0` (MIT). See `docs/provenance.md`.
+
+### Added
+- `evolve(fitness, space, population, generations, seed, ...)`: GA over a
+  user-supplied fitness function returning a float or a tuple of floats,
+  with `direction` / `directions` (maximize or minimize per objective).
+- `strategy_genome.space`: `Float`, `Int`, `LogFloat`, `Categorical`, `Bool`
+  and shorthand dict spaces.
+- `EvolutionResult` gains `best_params`, `best_value(s)`,
+  `diversity_history`, `best_fitness_history`, `n_failed_evaluations`,
+  `directions` and `to_dict()`.
+- `CallableFitness`: failed or NaN evaluations score `-inf` and are counted
+  instead of aborting the run (opt out with `raise_errors=True`).
+- `strategy_genome.optuna.GeneticStrategySampler`: steady-state GA as an
+  `optuna.samplers.BaseSampler` (single and multi-objective), plus
+  `space_to_distributions` / `distribution_to_param_range`. Works with
+  freqtrade hyperopt via `HyperOpt.generate_estimator`.
+- `n_jobs` thread-pool evaluation; `callback` can stop a run early;
+  `initial` seeds generation 0; `multi_run` repeats a run over seeds.
+- `GPEngine(terminal_names=..., function_names=...)`.
+- `strategy-genome demo` CLI.
+- Tests: numeric reference checks for metrics and hypervolume, GA
+  convergence and reproducibility, Optuna integration (tested on Optuna 3.4
+  and 5.0), trading examples, CLI; plus the 108 upstream GP tests.
+- `contrib/optunahub/strategy_genome`: OptunaHub registry wrapper (not yet
+  submitted).
+
+### Changed
+- Fitness is user-supplied. The hard-wired toy backtester, co-evolution and
+  meta-reward code moved to the opt-in `strategy_genome.trading` package.
+- Return-series metrics moved to `strategy_genome.metrics`, Pareto indicators
+  to `strategy_genome.pareto`, GP to `strategy_genome.gp`.
+- Checkpoint files are opt-in (`checkpoint_interval=0` by default) and
+  `verbose` defaults to `False`.
+- Multi-objective parent selection uses NSGA-II crowded comparison.
+
+### Fixed (relative to srfm-lab)
+- `StrategyGenome.clone()` was called but never defined, so the GA loop
+  raised `AttributeError`.
+- Seeded runs were not reproducible (unseeded diversity sampler and operator
+  selection; genome ids drawn from the global RNG).
+- `Population.__repr__` raised `ValueError`.
+- Two-point crossover raised `IndexError` on single-gene chromosomes.
+- `ParetoAnalysis.knee_point` returned an extreme point instead of the knee.
+- `ParamRange.step` was ignored.
+- Island mode did not advance the generation counter and left padded
+  members unevaluated.
+
+### Removed
+- `visualization.py` (matplotlib dashboards) and the multiprocessing worker
+  that never ran in parallel.
+
+[0.1.0]: https://github.com/Mattbusel/strategy-genome/releases/tag/v0.1.0

strategy_genome-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Busel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

strategy_genome-0.1.0/NOTICE

@@ -0,0 +1,11 @@
+strategy-genome
+Copyright (c) 2026 Matthew Busel
+
+This package was carved out of srfm-lab (https://github.com/Mattbusel/srfm-lab),
+directory ml/genetic, at commit 8cbfcb0551d44e3ed1c20bdae9dc805d61521c62.
+srfm-lab is released under the MIT License, copyright (c) 2026 Matthew Busel.
+
+Most modules under src/strategy_genome/ (genome, population, operators,
+evolution, gp/, trading/) are derived from that code; docs/provenance.md maps
+each file to its origin and lists the changes made. tests/test_gp.py is the
+upstream test suite with only its import paths changed.

strategy_genome-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: strategy-genome
+Version: 0.1.0
+Summary: Typed genetic-algorithm / genetic-programming optimizer (NSGA-II, island model, adaptive operators) with an Optuna sampler. Carved out of srfm-lab.
+Project-URL: Homepage, https://github.com/Mattbusel/strategy-genome
+Project-URL: Repository, https://github.com/Mattbusel/strategy-genome
+Project-URL: Documentation, https://github.com/Mattbusel/strategy-genome/tree/main/docs
+Project-URL: Changelog, https://github.com/Mattbusel/strategy-genome/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Mattbusel/strategy-genome/issues
+Project-URL: Upstream (srfm-lab), https://github.com/Mattbusel/srfm-lab
+Author: Matthew Busel
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: evolutionary-algorithm,freqtrade,genetic-algorithm,genetic-programming,hyperopt,hyperparameter-optimization,multi-objective-optimization,nsga-ii,optuna,quantitative-finance,sampler,trading-strategy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.22
+Provides-Extra: optuna
+Requires-Dist: optuna>=3.4; extra == 'optuna'
+Provides-Extra: scipy
+Requires-Dist: scipy>=1.8; extra == 'scipy'
+Provides-Extra: test
+Requires-Dist: optuna>=3.4; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# strategy-genome
+
+A typed genetic algorithm (GA) and genetic programming (GP) optimizer for
+Python, with an Optuna sampler so any Optuna study can use it.
+
+- **You bring the fitness function.** `evolve(fitness, space)` calls
+  `fitness(genome)` and expects a float, or a tuple of floats for
+  multi-objective runs. Nothing about trading is built in.
+- **Mixed search spaces:** floats (optionally on a step grid), integers,
+  log-scale floats, categoricals and booleans.
+- **Real GA machinery:** elitism, tournament selection, SBX / arithmetic /
+  uniform / one- and two-point crossover, gaussian / polynomial / creep /
+  boundary mutation, adaptive mutation rate and adaptive operator choice,
+  NSGA-II for multiple objectives, an island model, stagnation restarts, and a
+  hall of fame.
+- **Reproducible:** the same seed and the same fitness give the same run.
+- **Light:** the GA core is pure standard-library Python. numpy is used by
+  the GP submodule and the trading examples. Optuna is an optional extra.
+
+Carved out of [srfm-lab](https://github.com/Mattbusel/srfm-lab)
+(`ml/genetic`), MIT licensed. See [provenance](https://github.com/Mattbusel/strategy-genome/blob/main/docs/provenance.md) for what was
+changed and which upstream bugs were fixed on the way out.
+
+## Install
+
+```bash
+pip install strategy-genome            # GA core + GP (numpy)
+pip install "strategy-genome[optuna]"  # adds the Optuna sampler
+```
+
+Python 3.10 or newer.
+
+## Quickstart
+
+```python
+from strategy_genome import evolve, space as sp
+
+def fitness(g):
+    # g["name"] reads one parameter; g.params is the whole dict
+    return (g["x"] - 3.0) ** 2 + (g["y"] + 1.0) ** 2
+
+result = evolve(
+    fitness,
+    {"x": sp.Float(-10, 10), "y": sp.Float(-10, 10)},
+    population=40,
+    generations=80,
+    seed=7,
+    direction="minimize",
+)
+
+result.best_params        # {'x': 3.00..., 'y': -0.99...}
+result.best_value         # what your function returned for the best genome
+result.hall_of_fame       # best unique genomes seen, best first
+result.diversity_history  # mean pairwise parameter distance per generation
+```
+
+### Search spaces
+
+```python
+space = {
+    "fast":  sp.Int(2, 50),
+    "slow":  sp.Int(10, 200, step=5),
+    "stop":  sp.Float(0.005, 0.10),
+    "lr":    sp.LogFloat(1e-5, 1e-1),
+    "kind":  sp.Categorical(["ema", "sma", "wma"]),
+    "short": sp.Bool(),
+}
+```
+
+Shorthand also works: `(0, 10)` is an integer range, `(0.0, 1.0)` a float
+range, and a list is a categorical.
+
+### Several objectives
+
+Return a tuple and give one direction per objective. The run switches to
+NSGA-II and `result.pareto_front` holds the non-dominated genomes.
+
+```python
+def fitness(g):
+    returns = backtest(g.params)
+    return sharpe(returns), max_drawdown(returns)
+
+result = evolve(fitness, space, population=60, generations=100, seed=1,
+                directions=["maximize", "minimize"])
+for g in result.pareto_front:
+    print(g.values, g.params)
+```
+
+### Failures
+
+If `fitness` raises or returns NaN, that genome scores `-inf` and the run
+continues. `result.n_failed_evaluations` counts them. Pass
+`raise_errors=True` to stop on the first error instead.
+
+## Use it from Optuna (and freqtrade)
+
+```python
+import optuna
+from strategy_genome.optuna import GeneticStrategySampler
+
+study = optuna.create_study(sampler=GeneticStrategySampler(population_size=30, seed=1))
+study.optimize(objective, n_trials=500)
+```
+
+freqtrade's hyperopt runs on Optuna and lets a strategy return any
+`optuna.samplers.BaseSampler` from `HyperOpt.generate_estimator`, so the
+sampler drops straight in. See [Optuna and freqtrade](https://github.com/Mattbusel/strategy-genome/blob/main/docs/optuna-and-freqtrade.md),
+including a benchmark against Random, NSGA-II and TPE.
+
+## More
+
+- [API reference](https://github.com/Mattbusel/strategy-genome/blob/main/docs/api.md)
+- [Optuna and freqtrade](https://github.com/Mattbusel/strategy-genome/blob/main/docs/optuna-and-freqtrade.md)
+- [Genetic programming (`strategy_genome.gp`)](https://github.com/Mattbusel/strategy-genome/blob/main/docs/gp.md)
+- [Trading examples (`strategy_genome.trading`)](https://github.com/Mattbusel/strategy-genome/blob/main/docs/trading-examples.md)
+- [Provenance and upstream fixes](https://github.com/Mattbusel/strategy-genome/blob/main/docs/provenance.md)
+- [Ecosystem plan (OptunaHub)](https://github.com/Mattbusel/strategy-genome/blob/main/docs/ecosystem.md)
+- Examples: [`examples/`](https://github.com/Mattbusel/strategy-genome/tree/main/examples)
+
+## License
+
+MIT. Copyright (c) 2026 Matthew Busel. See `LICENSE` and `NOTICE`.

strategy_genome-0.1.0/contrib/optunahub/strategy_genome/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Busel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

strategy_genome-0.1.0/docs/api.md

@@ -0,0 +1,109 @@
+# API reference
+
+Everything below is importable from `strategy_genome` unless a submodule is
+named.
+
+## `evolve`
+
+```python
+evolve(
+    fitness,                 # fn(genome) -> float | tuple[float, ...]
+    space,                   # {name: ParamRange} | shorthand dict | [ParamRange]
+    population=50,
+    generations=100,
+    seed=None,
+    *,
+    direction=None,          # "maximize" (default) | "minimize"
+    directions=None,         # one per objective, for multi-objective runs
+    initial=None,            # list of param dicts to seed generation 0
+    n_jobs=1,                # threads for fitness evaluation
+    callback=None,           # callback(gen, population, stats); return False to stop
+    raise_errors=False,
+    verbose=False,
+    **config,                # any EvolutionConfig field
+) -> EvolutionResult
+```
+
+Useful `**config` fields (see `EvolutionConfig` for all of them):
+
+| field | default | meaning |
+|---|---|---|
+| `elite_fraction` | 0.10 | share of the population copied unchanged each generation |
+| `tournament_size` | 5 | tournament size for parent selection |
+| `crossover_rate` | 0.80 | starting crossover probability (cosine-annealed) |
+| `initial_mutation_rate` | 0.10 | starting per-gene mutation probability |
+| `use_adaptive_mutation` | True | adapt the mutation rate to progress and diversity |
+| `use_adaptive_operators` | True | sample crossover/mutation operators by weight |
+| `mutation_method` / `crossover_method` | gaussian / uniform | used when adaptive operators are off |
+| `use_island_model`, `n_islands`, `migration_interval` | False, 4, 20 | island model (single objective) |
+| `stagnation_patience`, `max_restarts`, `restart_method` | 30, 5, partial | restarts when progress stalls |
+| `convergence_patience` | 50 | generations without improvement before stopping |
+| `use_fitness_sharing`, `sharing_sigma` | False, 0.15 | niching |
+| `checkpoint_interval`, `checkpoint_dir` | 0, ./checkpoints | write best-genome JSON every N generations (0 = off) |
+
+## `EvolutionResult`
+
+| attribute | meaning |
+|---|---|
+| `best_genome` | best genome seen (hall-of-fame head) |
+| `best_params` | its parameters as a dict |
+| `best_value` / `best_values` | what your fitness returned for it |
+| `hall_of_fame` | best unique genomes, best first |
+| `pareto_front` | non-dominated genomes (multi-objective runs) |
+| `stats_history` | `PopulationStats` per generation |
+| `diversity_history` | mean pairwise distance in normalized parameter space, per generation |
+| `best_fitness_history` | best internal fitness per generation |
+| `n_generations_run`, `n_evaluations`, `n_failed_evaluations`, `n_restarts` | counters |
+| `converged`, `convergence_reason` | why the run stopped |
+| `directions` | the direction of each objective |
+| `to_dict()` | JSON-friendly summary |
+| `summary()` | printable summary |
+
+Internally every objective is maximized: `genome.fitness` and
+`genome.objectives` are sign-adjusted. `genome.value` / `genome.values` are
+always your function's raw output.
+
+## Genomes
+
+`Genome` (alias of `StrategyGenome`) is what your fitness function receives.
+
+- `g["name"]`, `g.get("name", default)`, `g.params`
+- `g.value`, `g.values`, `g.fitness`, `g.objectives`
+- `g.clone()`, `g.mutate(rate, method=...)`, `StrategyGenome.crossover(a, b, method=...)`
+- `g.dominates(other)` (Pareto dominance on `objectives`)
+
+`GenomeFactory.from_space(space, seed=...)` builds random, default or
+dict-specified genomes and serializes them to JSON-compatible dicts.
+
+## Search space (`strategy_genome.space`)
+
+`Float(low, high, step=None)`, `Int(low, high, step=1)`,
+`LogFloat(low, high)`, `Categorical(choices)`, `Bool()`, and
+`normalize_space(space)` which turns any accepted form into a list of named
+`ParamRange`.
+
+## Lower-level pieces
+
+- `GeneticAlgorithm(config, factory, evaluator)`: the loop itself. The
+  evaluator is any object with `evaluate(genome) -> genome` that sets
+  `genome.fitness` (higher is better). `CallableFitness` wraps a function.
+- `Population`, `HallOfFame`, `SelectionOperator` (tournament, roulette,
+  rank, SUS, lexicase), `FitnessSharing`, `DiversityMetrics`.
+- `MutationOperator`, `CrossoverOperator`: the operators, usable on their own.
+- `AdaptiveMutationRate`, `AdaptiveOperatorSelection`, `NichePreservation`
+  (deterministic crowding, clearing, restricted mating), `IslandModel`,
+  `RestartStrategy`.
+- `ParetoAnalysis`: hypervolume (exact in 2-D, Monte Carlo above), spacing,
+  knee point.
+- `metrics`: `compute_sharpe`, `compute_sortino`, `compute_calmar`,
+  `compute_max_drawdown`, `compute_profit_factor`, `compute_win_rate`,
+  `compute_omega_ratio`, `compute_var`, `compute_cvar`,
+  `compute_information_ratio`. Ratios with a zero denominator return capped
+  sentinels (for example 10.0) rather than infinity, as upstream did.
+- `multi_run(fitness, space, n_runs=5, ...)`: repeat a run over seeds to see
+  whether a result is robust or a lucky seed.
+
+## CLI
+
+`strategy-genome demo [--strategy momentum] [--prices prices.csv] [--json out.json]`
+runs the GA against the toy backtester so you can watch it work.

strategy_genome-0.1.0/docs/ecosystem.md

@@ -0,0 +1,29 @@
+# Ecosystem plan
+
+Where this package can plug into existing tools, and the status of each.
+
+## freqtrade: no merge needed
+
+freqtrade hyperopt runs on Optuna and accepts any `BaseSampler` instance
+from a strategy's `HyperOpt.generate_estimator`. The integration is a
+user-side snippet, documented in [Optuna and freqtrade](optuna-and-freqtrade.md)
+and `examples/freqtrade_strategy.py`. Verified against freqtrade's
+`docs/advanced-hyperopt.md` and `freqtrade/optimize/hyperopt/hyperopt_optimizer.py`
+on `develop` (release 2026.10).
+
+## OptunaHub sampler: prepared, not submitted
+
+OptunaHub (`optuna/optunahub-registry`) hosts community samplers under
+`package/samplers/<name>/`. A package there is a thin wrapper that imports
+this library. `contrib/optunahub/strategy_genome/` holds the wrapper
+(`__init__.py`, `_sampler.py`, `example.py`, `LICENSE`, `requirements.txt`), matching the layout of existing registry packages such as `auto_sampler`.
+
+Not submitted yet: the registry requires a `README.md` inside the package
+directory, and that file is not written here.
+
+## OptunaHub benchmark: proposed
+
+OptunaHub's benchmark list has no financial problem. A walk-forward
+strategy-overfitting benchmark (optimize on one window, score on the next,
+report the gap) would be a new category. It would be built on this package
+and a walk-forward splitter, and has the same `README.md` requirement.

strategy_genome-0.1.0/docs/gp.md

@@ -0,0 +1,52 @@
+# Genetic programming: `strategy_genome.gp`
+
+An opt-in submodule that evolves symbolic expression trees, for example
+candidate alpha signals built from feature arrays. Needs numpy. scipy is used
+for Spearman rank correlation when installed, with a numpy fallback.
+
+```python
+import numpy as np
+from strategy_genome.gp import GPConfig, GPEngine, SignalValidator
+
+rng = np.random.default_rng(0)
+n = 500
+data = {
+    "close": rng.standard_normal(n).cumsum() + 100.0,
+    "volume": rng.uniform(1e5, 1e7, n),
+    "mom_5d": rng.standard_normal(n),
+    "mom_20d": rng.standard_normal(n),
+}
+forward_returns = rng.standard_normal(n) * 0.01
+
+engine = GPEngine(seed=1, terminal_names=list(data))
+pareto = engine.run(data, forward_returns,
+                    GPConfig(population_size=200, max_generations=20, verbosity=0))
+
+best = pareto[0]
+print(engine.export_best(best)["expression"], best.fitness_scores)
+```
+
+What is inside:
+
+- `ExpressionTree`, `ExpressionNode`, `TreeGenerator`: trees over unary and
+  binary functions (arithmetic with protected division, EMA, rolling
+  statistics, ranks, lags and more; see `ALL_FUNCTION_NAMES`), simplification,
+  depth and size introspection.
+- `gp_operators`: subtree crossover, point / subtree / hoist mutation,
+  tournament, fitness-proportional and lexicase selection.
+- `GPEngine`: ramped half-and-half initialization, tournament + lexicase
+  parent selection, elitism, parsimony pressure, early stopping, and a Pareto
+  front over information coefficient (IC) and ICIR.
+- `SignalValidator`: IC and ICIR checks, a look-ahead test, stability across
+  sub-periods, correlation against an existing signal library, and
+  out-of-sample validation.
+
+Notes:
+
+- `terminal_names` defaults to the srfm-lab signal library
+  (`ALL_TERMINALS`). Pass the keys of your own data dict, as above, or trees
+  will reference names you do not have (those evaluate to 0).
+- `GPEngine(seed=...)` seeds Python's and numpy's global RNGs, as upstream
+  did.
+- The 108 upstream tests for this subsystem ship unchanged in
+  `tests/test_gp.py` and all pass.

strategy_genome-0.1.0/docs/index.md

@@ -0,0 +1,122 @@
+# strategy-genome
+
+A typed genetic algorithm (GA) and genetic programming (GP) optimizer for
+Python, with an Optuna sampler so any Optuna study can use it.
+
+- **You bring the fitness function.** `evolve(fitness, space)` calls
+  `fitness(genome)` and expects a float, or a tuple of floats for
+  multi-objective runs. Nothing about trading is built in.
+- **Mixed search spaces:** floats (optionally on a step grid), integers,
+  log-scale floats, categoricals and booleans.
+- **Real GA machinery:** elitism, tournament selection, SBX / arithmetic /
+  uniform / one- and two-point crossover, gaussian / polynomial / creep /
+  boundary mutation, adaptive mutation rate and adaptive operator choice,
+  NSGA-II for multiple objectives, an island model, stagnation restarts, and a
+  hall of fame.
+- **Reproducible:** the same seed and the same fitness give the same run.
+- **Light:** the GA core is pure standard-library Python. numpy is used by
+  the GP submodule and the trading examples. Optuna is an optional extra.
+
+Carved out of [srfm-lab](https://github.com/Mattbusel/srfm-lab)
+(`ml/genetic`), MIT licensed. See [provenance](https://github.com/Mattbusel/strategy-genome/blob/main/docs/provenance.md) for what was
+changed and which upstream bugs were fixed on the way out.
+
+## Install
+
+```bash
+pip install strategy-genome            # GA core + GP (numpy)
+pip install "strategy-genome[optuna]"  # adds the Optuna sampler
+```
+
+Python 3.10 or newer.
+
+## Quickstart
+
+```python
+from strategy_genome import evolve, space as sp
+
+def fitness(g):
+    # g["name"] reads one parameter; g.params is the whole dict
+    return (g["x"] - 3.0) ** 2 + (g["y"] + 1.0) ** 2
+
+result = evolve(
+    fitness,
+    {"x": sp.Float(-10, 10), "y": sp.Float(-10, 10)},
+    population=40,
+    generations=80,
+    seed=7,
+    direction="minimize",
+)
+
+result.best_params        # {'x': 3.00..., 'y': -0.99...}
+result.best_value         # what your function returned for the best genome
+result.hall_of_fame       # best unique genomes seen, best first
+result.diversity_history  # mean pairwise parameter distance per generation
+```
+
+### Search spaces
+
+```python
+space = {
+    "fast":  sp.Int(2, 50),
+    "slow":  sp.Int(10, 200, step=5),
+    "stop":  sp.Float(0.005, 0.10),
+    "lr":    sp.LogFloat(1e-5, 1e-1),
+    "kind":  sp.Categorical(["ema", "sma", "wma"]),
+    "short": sp.Bool(),
+}
+```
+
+Shorthand also works: `(0, 10)` is an integer range, `(0.0, 1.0)` a float
+range, and a list is a categorical.
+
+### Several objectives
+
+Return a tuple and give one direction per objective. The run switches to
+NSGA-II and `result.pareto_front` holds the non-dominated genomes.
+
+```python
+def fitness(g):
+    returns = backtest(g.params)
+    return sharpe(returns), max_drawdown(returns)
+
+result = evolve(fitness, space, population=60, generations=100, seed=1,
+                directions=["maximize", "minimize"])
+for g in result.pareto_front:
+    print(g.values, g.params)
+```
+
+### Failures
+
+If `fitness` raises or returns NaN, that genome scores `-inf` and the run
+continues. `result.n_failed_evaluations` counts them. Pass
+`raise_errors=True` to stop on the first error instead.
+
+## Use it from Optuna (and freqtrade)
+
+```python
+import optuna
+from strategy_genome.optuna import GeneticStrategySampler
+
+study = optuna.create_study(sampler=GeneticStrategySampler(population_size=30, seed=1))
+study.optimize(objective, n_trials=500)
+```
+
+freqtrade's hyperopt runs on Optuna and lets a strategy return any
+`optuna.samplers.BaseSampler` from `HyperOpt.generate_estimator`, so the
+sampler drops straight in. See [Optuna and freqtrade](https://github.com/Mattbusel/strategy-genome/blob/main/docs/optuna-and-freqtrade.md),
+including a benchmark against Random, NSGA-II and TPE.
+
+## More
+
+- [API reference](https://github.com/Mattbusel/strategy-genome/blob/main/docs/api.md)
+- [Optuna and freqtrade](https://github.com/Mattbusel/strategy-genome/blob/main/docs/optuna-and-freqtrade.md)
+- [Genetic programming (`strategy_genome.gp`)](https://github.com/Mattbusel/strategy-genome/blob/main/docs/gp.md)
+- [Trading examples (`strategy_genome.trading`)](https://github.com/Mattbusel/strategy-genome/blob/main/docs/trading-examples.md)
+- [Provenance and upstream fixes](https://github.com/Mattbusel/strategy-genome/blob/main/docs/provenance.md)
+- [Ecosystem plan (OptunaHub)](https://github.com/Mattbusel/strategy-genome/blob/main/docs/ecosystem.md)
+- Examples: [`examples/`](https://github.com/Mattbusel/strategy-genome/tree/main/examples)
+
+## License
+
+MIT. Copyright (c) 2026 Matthew Busel. See `LICENSE` and `NOTICE`.