build: separate core and optional deps

README.md

@@ -63,6 +63,12 @@ pip install -e .
 
 Note: Depending on your platform, a local build may be required.
 
+Optional features (extras)
+- Core install includes only `numpy`.
+- Visualization utils require `graphviz` and the Graphviz system binary: `uv pip install -e .[viz]`.
+- Dataset download progress uses `tqdm`: `uv pip install -e .[datasets]`.
+- Install everything optional: `uv pip install -e .[all]`.
+
 ## Quickstart
 
 Minimal example training MNIST with mini‑batches. Tensor slicing is not available yet, so batching uses NumPy views. See `examples/mnist.py` for a complete script.

cranberry/features/datasets.py

@@ -6,12 +6,28 @@
 import tempfile
 from typing import Optional, Union
 import urllib.request
+import sys
 
 import numpy as np
-from psutil import OSX
-from tqdm import tqdm
 from cranberry import Tensor
 
+# Platform detection without psutil
+OSX = sys.platform == "darwin"
+
+# Optional tqdm progress bar
+try:
+  from tqdm import tqdm as _tqdm  # type: ignore
+  tqdm = _tqdm  # noqa: N802 - keep name compatibility
+except Exception:  # pragma: no cover - fallback path
+  class _NoopTqdm:
+    def __init__(self, *a, **kw):
+      pass
+    def update(self, n: int):
+      pass
+
+  # Keep the same callable interface as tqdm
+  tqdm = _NoopTqdm  # noqa: N802 - keep name compatibility
+
 _cache_dir: str = getenv("XDG_CACHE_HOME", os.path.expanduser("~/Library/Caches" if OSX else "~/.cache"))
 
 

cranberry/features/visualize.py

@@ -1,6 +1,12 @@
-from graphviz import Digraph
 from cranberry import Tensor
 
+# Defer graphviz requirement until used, with a helpful error
+try:
+  from graphviz import Digraph  # type: ignore
+except ImportError as _gv_err:  # pragma: no cover - informative path
+  Digraph = None  # type: ignore
+  _GRAPHVIZ_IMPORT_ERROR = _gv_err
+
 
 def trace(root: Tensor):
   nodes, edges = set(), set()
@@ -27,6 +33,12 @@ def plot_graph(root: Tensor, fmt="svg", rankdir="LR"):
   rankdir: TB (top to bottom graph) | LR (left to right)
   """
   assert rankdir in ["LR", "TB"]
+  if Digraph is None:
+    raise ImportError(
+      "graphviz is required for visualization. Install the extra with '\n"
+      "pip install 'cranberry[viz]'\n"
+      "and ensure the Graphviz system binary is installed (brew/apt/choco)."
+    ) from _GRAPHVIZ_IMPORT_ERROR
   nodes, edges = trace(root)
   dot = Digraph(format=fmt, graph_attr={"rankdir": rankdir})
 

pyproject.toml

@@ -13,8 +13,17 @@ classifiers = [
 ]
 dependencies = [
     "numpy~=2.0",
+]
+
+[project.optional-dependencies]
+viz = [
+    "graphviz>=0.20.3,<0.21",
+]
+datasets = [
+    "tqdm>=4.66.4,<5",
+]
+all = [
     "graphviz>=0.20.3,<0.21",
-    "psutil>=6.0.0,<7",
     "tqdm>=4.66.4,<5",
 ]