feat: make numpy an optional dependency

docs/docs/api/models/Embedder.md

@@ -1,5 +1,8 @@
 # dspy.Embedder
 
+!!! note "Requires numpy"
+    `dspy.Embedder` requires numpy. Install it with `pip install dspy[numpy]`.
+
 <!-- START_API_REF -->
 ::: dspy.Embedder
     handler: python

docs/docs/api/optimizers/KNN.md

@@ -1,5 +1,8 @@
 # dspy.KNN
 
+!!! note "Requires numpy"
+    `dspy.KNN` requires numpy. Install it with `pip install dspy[numpy]`.
+
 <!-- START_API_REF -->
 ::: dspy.KNN
     handler: python

docs/docs/api/optimizers/KNNFewShot.md

@@ -1,5 +1,8 @@
 # dspy.KNNFewShot
 
+!!! note "Requires numpy"
+    `dspy.KNNFewShot` requires numpy. Install it with `pip install dspy[numpy]`.
+
 <!-- START_API_REF -->
 ::: dspy.KNNFewShot
     handler: python

docs/docs/api/optimizers/SIMBA.md

@@ -1,5 +1,8 @@
 # dspy.SIMBA
 
+!!! note "Requires numpy"
+    `dspy.SIMBA` requires numpy. Install it with `pip install dspy[numpy]`.
+
 <!-- START_API_REF -->
 ::: dspy.SIMBA
     handler: python

docs/docs/api/tools/Embeddings.md

@@ -1,5 +1,8 @@
 # dspy.retrievers.Embeddings
 
+!!! note "Requires numpy"
+    `dspy.retrievers.Embeddings` requires numpy. Install it with `pip install dspy[numpy]`.
+
 <!-- START_API_REF -->
 ::: dspy.Embeddings
     handler: python

docs/docs/tutorials/rag/index.ipynb

@@ -8,7 +8,7 @@
     "\n",
     "Let's walk through a quick example of **basic question answering** with and without **retrieval-augmented generation** (RAG) in DSPy. Specifically, let's build **a system for answering Tech questions**, e.g. about Linux or iPhone apps.\n",
     "\n",
-    "Install the latest DSPy via `pip install -U dspy` and follow along. If you're looking instead for a conceptual overview of DSPy, this [recent lecture](https://www.youtube.com/live/JEMYuzrKLUw) is a good place to start. You also need to run `pip install datasets`."
+    "Install the latest DSPy via `pip install -U dspy` and follow along. If you're looking instead for a conceptual overview of DSPy, this [recent lecture](https://www.youtube.com/live/JEMYuzrKLUw) is a good place to start. You also need to run `pip install datasets`. This tutorial uses `dspy.Embedder` and `dspy.retrievers.Embeddings`, which require numpy: `pip install dspy[numpy]`."
    ]
   },
   {

docs/docs/tutorials/tool_use/index.ipynb

@@ -8,7 +8,7 @@
     "\n",
     "Let's walk through a quick example of building and prompt-optimizing a DSPy agent for advanced tool use. We'll do this for the challenging task [ToolHop](https://arxiv.org/abs/2501.02506) but with an even stricter evaluation criteria.\n",
     "\n",
-    "Install the latest DSPy via `pip install -U dspy` and follow along. You will also need to `pip install func_timeout datasets`."
+    "Install the latest DSPy via `pip install -U dspy` and follow along. You will also need to `pip install func_timeout datasets`. This tutorial uses `dspy.SIMBA`, which requires numpy: `pip install dspy[numpy]`."
    ]
   },
   {

dspy/clients/embedding.py

@@ -1,10 +1,13 @@
+from __future__ import annotations
+
 from typing import Any, Callable
 
 import litellm
-import numpy as np
 
 from dspy.clients.cache import request_cache
+from dspy.utils.lazy_import import require
 
+np = require("numpy")
 
 class Embedder:
     """DSPy embedding class.

dspy/predict/knn.py

@@ -1,7 +1,8 @@
-import numpy as np
-
 from dspy.clients import Embedder
 from dspy.primitives import Example
+from dspy.utils.lazy_import import require
+
+np = require("numpy")
 
 
 class KNN:

dspy/retrievers/embeddings.py

@@ -1,11 +1,14 @@
+from __future__ import annotations
+
 import json
 import os
 from typing import Any
 
-import numpy as np
-
+from dspy.utils.lazy_import import require
 from dspy.utils.unbatchify import Unbatchify
 
+np = require("numpy")
+
 
 class Embeddings:
     """DSPy Embeddings retriever.

dspy/teleprompt/copro_optimizer.py

@@ -1,4 +1,5 @@
 import logging
+import statistics
 from collections import defaultdict
 
 import dspy
@@ -142,9 +143,6 @@ def compile(self, student, *, trainset, eval_kwargs):
             id(p): {"depth": [], "max": [], "average": [], "min": [], "std": []} for p in module.predictors()
         }
 
-        if self.track_stats:
-            import numpy as np
-
         candidates = {}
         evaluated_candidates = defaultdict(dict)
 
@@ -254,7 +252,7 @@ def compile(self, student, *, trainset, eval_kwargs):
                     results_latest[id(p_old)]["max"].append(max(latest_scores))
                     results_latest[id(p_old)]["average"].append(sum(latest_scores) / len(latest_scores))
                     results_latest[id(p_old)]["min"].append(min(latest_scores))
-                    results_latest[id(p_old)]["std"].append(np.std(latest_scores))
+                    results_latest[id(p_old)]["std"].append(statistics.pstdev(latest_scores))
 
                 # Now that we've evaluated the candidates, set this predictor to the best performing version
                 # to ensure the next round of scores reflect the best possible version
@@ -296,7 +294,7 @@ def compile(self, student, *, trainset, eval_kwargs):
                     results_best[id(p_base)]["max"].append(max(scores))
                     results_best[id(p_base)]["average"].append(sum(scores) / len(scores))
                     results_best[id(p_base)]["min"].append(min(scores))
-                    results_best[id(p_base)]["std"].append(np.std(scores))
+                    results_best[id(p_base)]["std"].append(statistics.pstdev(scores))
 
                 for i in range(shortest_len - 1, -1, -1):
                     # breakpoint()
@@ -341,7 +339,7 @@ def compile(self, student, *, trainset, eval_kwargs):
                 results_best[id(predictor)]["max"].append(max(scores))
                 results_best[id(predictor)]["average"].append(sum(scores) / len(scores))
                 results_best[id(predictor)]["min"].append(min(scores))
-                results_best[id(predictor)]["std"].append(np.std(scores))
+                results_best[id(predictor)]["std"].append(statistics.pstdev(scores))
 
         candidates.sort(key=lambda x: x["score"], reverse=True)
 

dspy/teleprompt/gepa/gepa.py

@@ -1,5 +1,6 @@
 import inspect
 import logging
+import math
 import random
 from dataclasses import dataclass
 from typing import Any, Literal, Optional, Protocol, Union
@@ -443,9 +444,7 @@ def __init__(
     def auto_budget(
         self, num_preds, num_candidates, valset_size: int, minibatch_size: int = 35, full_eval_steps: int = 5
     ) -> int:
-        import numpy as np
-
-        num_trials = int(max(2 * (num_preds * 2) * np.log2(num_candidates), 1.5 * num_candidates))
+        num_trials = int(max(2 * (num_preds * 2) * math.log2(num_candidates), 1.5 * num_candidates))
         if num_trials < 0 or valset_size < 0 or minibatch_size < 0:
             raise ValueError("num_trials, valset_size, and minibatch_size must be >= 0.")
         if full_eval_steps < 1:

dspy/teleprompt/infer_rules.py

@@ -1,8 +1,7 @@
 import logging
+import math
 import random
 
-import numpy as np
-
 import dspy
 from dspy.evaluate.evaluate import Evaluate
 from dspy.teleprompt import BootstrapFewShot
@@ -32,7 +31,7 @@ def compile(self, student, *, teacher=None, trainset, valset=None):
         all_predictors = [p for p in original_program.predictors() if hasattr(p, "signature")]
         instructions_list = [p.signature.instructions for p in all_predictors]
 
-        best_score = -np.inf
+        best_score = -math.inf
         best_program = None
 
         for candidate_idx in range(self.num_candidates):

dspy/teleprompt/mipro_optimizer_v2.py

@@ -1,10 +1,9 @@
 import logging
+import math
 import random
 from collections import defaultdict
 from typing import TYPE_CHECKING, Any, Callable, Literal
 
-import numpy as np
-
 import dspy
 from dspy.evaluate.evaluate import Evaluate
 from dspy.propose import GroundedProposer
@@ -277,14 +276,13 @@ def compile(
 
     def _set_random_seeds(self, seed):
         self.rng = random.Random(seed)
-        np.random.seed(seed)
 
     def _set_num_trials_from_num_candidates(self, program, zeroshot_opt, num_candidates):
         num_vars = len(program.predictors())
         if not zeroshot_opt:
             num_vars *= 2  # Account for few-shot examples + instruction variables
         # Trials = MAX(c*M*log(N), c=2, 3/2*N)
-        num_trials = int(max(2 * num_vars * np.log2(num_candidates), 1.5 * num_candidates))
+        num_trials = int(max(2 * num_vars * math.log2(num_candidates), 1.5 * num_candidates))
 
         return num_trials
 

dspy/teleprompt/simba.py

@@ -4,11 +4,12 @@
 import random
 from typing import Any, Callable
 
-import numpy as np
-
 import dspy
 from dspy.teleprompt.simba_utils import append_a_demo, append_a_rule, prepare_models_for_resampling, wrap_program
 from dspy.teleprompt.teleprompt import Teleprompter
+from dspy.utils.lazy_import import require
+
+np = require("numpy")
 
 logger = logging.getLogger(__name__)
 

dspy/teleprompt/utils.py

@@ -6,8 +6,6 @@
 import shutil
 import sys
 
-import numpy as np
-
 try:
     from IPython.core.magics.code import extract_symbols
 except ImportError:
@@ -121,8 +119,8 @@ def get_program_with_highest_avg_score(param_score_dict, fully_evaled_param_comb
     # Calculate the mean for each combination of categorical parameters, based on past trials
     results = []
     for key, values in param_score_dict.items():
-        scores = np.array([v[0] for v in values])
-        mean = np.average(scores)
+        scores = [v[0] for v in values]
+        mean = sum(scores) / len(scores)
         program = values[0][1]
         params = values[0][2]
         results.append((key, mean, program, params))
@@ -284,9 +282,8 @@ def get_token_usage(model) -> tuple[int, int]:
         input_tokens.append(_input_tokens)
         output_tokens.append(_output_tokens)
 
-    total_input_tokens = int(np.sum(input_tokens))
-    total_output_tokens = int(np.sum(output_tokens))
-
+    total_input_tokens = sum(input_tokens)
+    total_output_tokens = sum(output_tokens)
     return total_input_tokens, total_output_tokens
 
 

dspy/utils/dummies.py

@@ -1,13 +1,16 @@
+from __future__ import annotations
+
 import random
 from collections import defaultdict
 from typing import Any
 
-import numpy as np
-
 from dspy.adapters.chat_adapter import FieldInfoWithName, field_header_pattern
 from dspy.clients.base_lm import BaseLM
 from dspy.dsp.utils.utils import dotdict
 from dspy.signatures.field import OutputField
+from dspy.utils.lazy_import import require
+
+np = require("numpy")
 
 
 class DummyLM(BaseLM):