📦 Split heavy deps into optional extras and slim the wheel

CHANGELOG.md

@@ -17,10 +17,21 @@ the set of symbols exported from `devol.__all__`; anything else is internal.
 - `py.typed` marker so downstream type checkers pick up `devol`'s inline hints.
 - `CONTRIBUTING.md` with minimum expectations for patches.
 - This changelog.
+- CI matrix covering Python 3.11, 3.12, and 3.13 with separate lint, typecheck, test, and build jobs.
+- `examples`, `benchmark`, `dev`, and `all` optional dependency groups.
+- `src/devol` is now strictly typed end-to-end (`mypy --strict` clean).
+- Installation section in the README explaining the new extras.
 
 ### Changed
 
 - Moved `pytest` from required dependencies to the `dev` extra.
+- Moved `torch`, `torchvision`, `gymnasium`, and `matplotlib` out of required dependencies. Installing `devol` now pulls only `numpy`, `pydantic`, and `pydantic-yaml`; the heavy deps live under the `examples` extra.
+- Dropped unused `pydantic-settings` from dependencies.
+- Wheel contents narrowed to `src/devol` only — `examples/` and `benchmark/` stay in the repo but are no longer shipped.
+
+### Fixed
+
+- `DiffusionEvolution.run()` no longer requires `initial_population`; calling `algo.run()` now initializes a population automatically, matching the documented Quick Start usage and unblocking the `devol` CLI entry point.
 
 ## [0.1.0]
 

README.md

@@ -12,6 +12,21 @@ This reframing gives us an algorithm that naturally transitions from broad explo
 
 **The intuition**: Imagine you're in a foggy room full of people, each standing at a different elevation. You can only see your immediate neighbors through the fog. To find the highest point, you don't just copy the person next to you - you look at everyone nearby, weight them by height, and move toward the weighted average. As the fog clears (denoising), your steps become smaller and more precise.
 
+## Installation
+
+```bash
+pip install devol
+```
+
+Devol's core has a tiny footprint (numpy + pydantic + pydantic-yaml). Optional extras install the dependencies needed for demos and benchmarks:
+
+```bash
+pip install "devol[examples]"   # cartpole, MNIST, two-peaks (adds torch, gymnasium, matplotlib)
+pip install "devol[benchmark]"  # grid-search benchmarks (adds matplotlib, rich, tqdm)
+pip install "devol[dev]"        # contributor tooling (pytest, ruff, mypy, twine)
+pip install "devol[all]"        # everything above
+```
+
 ## Quick Start
 
 ```python

pyproject.toml

@@ -30,14 +30,9 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "gymnasium[classic-control]>=1.2.1",
-    "matplotlib>=3.10.7",
     "numpy>=1.26.0",
     "pydantic>=2.0.0",
-    "pydantic-settings>=2.0.0",
     "pydantic-yaml>=1.6.0",
-    "torch>=2.9.0",
-    "torchvision>=0.24.0",
 ]
 
 [project.urls]
@@ -51,16 +46,22 @@ dev = [
     "ruff>=0.1.0",
     "mypy>=1.7.0",
     "pytest>=8.0.0",
+    "twine>=5.0.0",
 ]
 examples = [
     "matplotlib>=3.8.0",
-    "gymnasium>=0.29.0",
+    "gymnasium[classic-control]>=1.2.1",
+    "torch>=2.9.0",
+    "torchvision>=0.24.0",
 ]
 benchmark = [
     "matplotlib>=3.8.0",
     "rich>=13.0.0",
     "tqdm>=4.65.0",
 ]
+all = [
+    "devol[dev,examples,benchmark]",
+]
 
 [project.scripts]
 devol = "devol.cli:main"
@@ -70,7 +71,7 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/devol", "examples"]
+packages = ["src/devol"]
 
 [tool.ruff]
 line-length = 120
@@ -88,3 +89,7 @@ warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
 files = ["src/devol"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]