feat: make numpy an optional dependency

[isaacbmiller]

Summary

Move numpy from a required runtime dependency to an optional extra.

numpy-dependent features (KNN, Embeddings, SIMBA, MIPROv2, InferRules, DummyVectorizer, Embedder post-processing, etc.) raise a clear ImportError pointing at pip install dspy[numpy] only when actually invoked.

Changes

• Created dspy/utils/_numpy.py with require_numpy() lazy import helper
• Converted all top-level import numpy as np to lazy require_numpy() calls inside method bodies
• Replaced numpy with stdlib where possible:
  • math.log2 in mipro_optimizer_v2, gepa
  • math.inf in infer_rules
  • statistics.pstdev in copro_optimizer
  • sum()/len() in teleprompt/utils
  • Removed dead np.random.seed() in mipro (optuna uses its own seed param)
• Added early require_numpy() in SIMBA.__init__ for fast failure
• Moved numpy to [project.optional-dependencies] with numpy extra
• Added numpy to dev and test_extras so CI still gets it

Notes

• import dspy works without numpy installed
• Users who want numpy-backed features install via pip install dspy[numpy]
• Upstream PR: feat: make numpy an optional dependency stanfordnlp/dspy#9659

[greptile-apps]

Greptile Summary

This PR makes numpy an optional dependency by introducing a require_optional() lazy-import helper and converting all top-level import numpy as np calls to per-method guarded imports, replacing trivial numpy usage with stdlib equivalents where possible.

• dspy/utils/_optional.py adds the require_optional() helper that raises a clear ImportError with a pip install dspy[numpy] hint when numpy is absent.
• pyproject.toml moves numpy>=1.26.0 to [project.optional-dependencies] and keeps it in dev/test_extras so CI is unaffected.
• One missed stdlib replacement remains in get_program_with_highest_avg_score (teleprompt/utils.py), where np.array + np.average could be replaced with sum()/len(), eliminating the numpy requirement on MIPROv2's minibatch path.

Confidence Score: 4/5

Safe to merge after fixing the remaining numpy call in get_program_with_highest_avg_score; all other conversions are correct.

One function in teleprompt/utils.py still calls require_optional('numpy') to compute a simple mean using np.array + np.average on a plain Python list, forcing numpy to be installed for MIPROv2's minibatch optimization path even though no numpy-specific functionality is needed.

dspy/teleprompt/utils.py — get_program_with_highest_avg_score still has a numpy call that should be replaced with stdlib sum()/len().

Important Files Changed

Filename	Overview
dspy/utils/_optional.py	New lazy-import helper for optional dependencies; clean implementation with a helpful install hint in the ImportError message.
dspy/teleprompt/utils.py	Converted np.sum to stdlib sum() in get_token_usage, but get_program_with_highest_avg_score still calls require_optional("numpy") for np.array+np.average, which are easily replaced with sum()/len().
dspy/teleprompt/mipro_optimizer_v2.py	Replaced np.log2 with math.log2 and removed np.random.seed; no remaining numpy usage in the file itself.
dspy/teleprompt/simba.py	require_optional("numpy") placed at the top of compile() correctly gates all np.percentile/np.exp/rng_np usage; np captured by closure for nested softmax_sample.
dspy/teleprompt/infer_rules.py	np.inf replaced with math.inf; numpy dependency fully removed from this file.
dspy/clients/embedding.py	require_optional("numpy") added inside _postprocess; TYPE_CHECKING guard used for annotation-only np import.
dspy/predict/knn.py	require_optional("numpy") added at the start of init and call; correct lazy-init pattern.
dspy/retrievers/embeddings.py	require_optional("numpy") added at the top of each method that uses np; TYPE_CHECKING guard correctly handles np.ndarray annotations.
dspy/utils/dummies.py	require_optional("numpy") added inside DummyVectorizer.call; TYPE_CHECKING guard used for np.ndarray annotation in return type.
pyproject.toml	numpy moved from required dependencies to [project.optional-dependencies]; added to dev and test_extras so CI continues to receive it.

Comments Outside Diff (1)

1. dspy/teleprompt/utils.py, line 120-125 (link)

   get_program_with_highest_avg_score calls require_optional("numpy") solely to compute an array mean with np.array + np.average. Both operations are trivially replicated with stdlib sum()/len(), which the PR already applies in get_token_usage. As written, any caller of MIPROv2's minibatch path must have numpy installed even though no actual numpy computation is needed — the same class of issue that was fixed in mipro_optimizer_v2.py (math.log2) and infer_rules.py (math.inf).

_{Reviews (6): Last reviewed commit: "refactor(_optional): centralize dspy-ext..." | Re-trigger Greptile}