vector-engine 1.0.0__py3-none-any.whl

vector_engine/__init__.py

@@ -0,0 +1,16 @@
+"""Vector Engine public API."""
+
+__version__ = "1.0.0"
+
+from .array import VectorArray
+from .index import VectorIndex
+from .metric import Metric
+from .results import SearchResult
+
+__all__ = [
+    "__version__",
+    "Metric",
+    "SearchResult",
+    "VectorArray",
+    "VectorIndex",
+]

vector_engine/array.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Sequence
+
+import numpy as np
+
+
+def _normalize_l2(x: np.ndarray) -> np.ndarray:
+    norms = np.linalg.norm(x, axis=1, keepdims=True)
+    norms = np.where(norms == 0, 1.0, norms)
+    return x / norms
+
+
+@dataclass(frozen=True)
+class VectorArray:
+    """Canonical vector container with IDs and metadata."""
+
+    values: np.ndarray
+    ids: np.ndarray
+    metadata: list[dict[str, Any]] | None = None
+    source_framework: str = "numpy"
+    source_device: str = "cpu"
+    _id_to_row: dict[int | str, int] | None = None
+
+    def __post_init__(self) -> None:
+        values = np.ascontiguousarray(self.values, dtype=np.float32)
+        if values.ndim != 2:
+            raise ValueError("vector_array_error: values must be a 2D array with shape (n, d)")
+        if values.shape[0] == 0 or values.shape[1] == 0:
+            raise ValueError("vector_array_error: values must have at least one row and one column")
+        if len(self.ids) != values.shape[0]:
+            raise ValueError("vector_array_error: ids length must match number of rows")
+        if self.metadata is not None and len(self.metadata) != values.shape[0]:
+            raise ValueError("vector_array_error: metadata length must match number of rows")
+        id_to_row: dict[int | str, int] = {}
+        for i, raw in enumerate(self.ids.tolist()):
+            if not isinstance(raw, (int, str, np.integer)):
+                raise TypeError("vector_array_error: ids must contain only int or str values")
+            if isinstance(raw, np.integer):
+                raw = int(raw)
+            if raw in id_to_row:
+                raise ValueError(f"vector_array_error: duplicate id found: {raw}")
+            id_to_row[raw] = i
+
+        object.__setattr__(self, "values", values)
+        object.__setattr__(self, "_id_to_row", id_to_row)
+
+    @classmethod
+    def from_numpy(
+        cls,
+        x: np.ndarray,
+        *,
+        ids: Sequence[int | str] | None = None,
+        metadata: Sequence[Mapping[str, Any]] | None = None,
+        normalize: bool = False,
+    ) -> "VectorArray":
+        arr = np.asarray(x, dtype=np.float32)
+        if arr.ndim != 2:
+            raise ValueError("vector_array_error: input numpy array must be shape (n, d)")
+        arr = np.ascontiguousarray(arr)
+        if normalize:
+            arr = _normalize_l2(arr)
+        if ids is None:
+            ids_array = np.arange(arr.shape[0], dtype=np.int64)
+        else:
+            ids_list = list(ids)
+            if len(ids_list) != arr.shape[0]:
+                raise ValueError("vector_array_error: ids length must match number of rows")
+            ids_array = np.asarray(ids_list, dtype=object)
+        md = [dict(item) for item in metadata] if metadata is not None else None
+        return cls(values=arr, ids=ids_array, metadata=md, source_framework="numpy")
+
+    @classmethod
+    def from_torch(
+        cls,
+        x: "torch.Tensor",  # type: ignore[name-defined]
+        *,
+        ids: Sequence[int | str] | None = None,
+        metadata: Sequence[Mapping[str, Any]] | None = None,
+        to_numpy: bool = True,
+        normalize: bool = False,
+    ) -> "VectorArray":
+        if not to_numpy:
+            raise ValueError("vector_array_error: v0.1 requires to_numpy=True for torch inputs")
+        import torch
+
+        if not isinstance(x, torch.Tensor):
+            raise TypeError("vector_array_error: x must be a torch.Tensor")
+        device = str(x.device)
+        arr = x.detach().to("cpu").numpy()
+        out = cls.from_numpy(arr, ids=ids, metadata=metadata, normalize=normalize)
+        return cls(
+            values=out.values,
+            ids=out.ids,
+            metadata=out.metadata,
+            source_framework="torch",
+            source_device=device,
+        )
+
+    @classmethod
+    def from_jax(
+        cls,
+        x: "jax.Array",  # type: ignore[name-defined]
+        *,
+        ids: Sequence[int | str] | None = None,
+        metadata: Sequence[Mapping[str, Any]] | None = None,
+        to_numpy: bool = True,
+        normalize: bool = False,
+    ) -> "VectorArray":
+        if not to_numpy:
+            raise ValueError("vector_array_error: v0.1 requires to_numpy=True for jax inputs")
+        import jax.numpy as jnp
+
+        arr = np.asarray(jnp.asarray(x), dtype=np.float32)
+        out = cls.from_numpy(arr, ids=ids, metadata=metadata, normalize=normalize)
+        return cls(
+            values=out.values,
+            ids=out.ids,
+            metadata=out.metadata,
+            source_framework="jax",
+            source_device="device",
+        )
+
+    def to_numpy(self, *, dtype: np.dtype = np.float32, copy: bool = False) -> np.ndarray:
+        arr = self.values.astype(dtype, copy=False)
+        if copy:
+            return np.array(arr, copy=True)
+        return arr
+
+    def subset(self, ids: Sequence[int | str]) -> "VectorArray":
+        assert self._id_to_row is not None
+        rows = []
+        for id_ in ids:
+            if id_ not in self._id_to_row:
+                raise KeyError(f"vector_array_error: unknown id in subset(): {id_}")
+            rows.append(self._id_to_row[id_])
+        values = self.values[rows]
+        out_ids = np.asarray(list(ids), dtype=object)
+        out_meta = None
+        if self.metadata is not None:
+            out_meta = [self.metadata[i] for i in rows]
+        return VectorArray(
+            values=values,
+            ids=out_ids,
+            metadata=out_meta,
+            source_framework=self.source_framework,
+            source_device=self.source_device,
+        )
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        return self.values.shape

vector_engine/backends/__init__.py

@@ -0,0 +1,13 @@
+from .bruteforce import BruteForceBackend
+from .faiss_backend import FaissBackend
+from .registry import get_backend, register_backend
+
+register_backend("bruteforce", BruteForceBackend)
+register_backend("faiss", FaissBackend)
+
+__all__ = [
+    "BruteForceBackend",
+    "FaissBackend",
+    "get_backend",
+    "register_backend",
+]

vector_engine/backends/base.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+import numpy as np
+
+from vector_engine.metric import Metric
+
+
+class BaseBackend(Protocol):
+    name: str
+    capabilities: dict[str, bool]
+
+    def build(self, xb: np.ndarray, metric: Metric, config: dict) -> None:
+        ...
+
+    def add(self, xb: np.ndarray) -> np.ndarray:
+        ...
+
+    def search(self, xq: np.ndarray, k: int) -> tuple[np.ndarray, np.ndarray]:
+        ...
+
+    def save(self, path: str) -> None:
+        ...
+
+    @classmethod
+    def load(cls, path: str) -> "BaseBackend":
+        ...

vector_engine/backends/bruteforce.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from vector_engine.metric import Metric
+
+
+def _normalize_l2(x: np.ndarray) -> np.ndarray:
+    norms = np.linalg.norm(x, axis=1, keepdims=True)
+    norms = np.where(norms == 0, 1.0, norms)
+    return x / norms
+
+
+@dataclass
+class BruteForceBackend:
+    name: str = "bruteforce"
+    capabilities: dict[str, bool] = field(
+        default_factory=lambda: {
+            "supports_delete": False,
+            "supports_custom_metric": True,
+            "supports_persistence": True,
+        }
+    )
+    xb: np.ndarray | None = None
+    metric: Metric | None = None
+
+    def build(self, xb: np.ndarray, metric: Metric, config: dict) -> None:
+        arr = np.ascontiguousarray(xb, dtype=np.float32)
+        self.metric = metric
+        if metric.name == "cosine":
+            arr = _normalize_l2(arr)
+        self.xb = arr
+
+    def add(self, xb: np.ndarray) -> np.ndarray:
+        if self.xb is None or self.metric is None:
+            raise RuntimeError("backend is not built")
+        arr = np.ascontiguousarray(xb, dtype=np.float32)
+        if self.metric.name == "cosine":
+            arr = _normalize_l2(arr)
+        start = self.xb.shape[0]
+        self.xb = np.vstack([self.xb, arr])
+        return np.arange(start, start + arr.shape[0], dtype=np.int64)
+
+    def search(self, xq: np.ndarray, k: int) -> tuple[np.ndarray, np.ndarray]:
+        if self.xb is None or self.metric is None:
+            raise RuntimeError("backend is not built")
+        queries = np.ascontiguousarray(xq, dtype=np.float32)
+        if self.metric.name == "cosine":
+            queries = _normalize_l2(queries)
+
+        if self.metric.fn is not None:
+            # Metric fn returns pairwise matrix, shape (n_queries, n_db).
+            scores = self.metric.fn(queries, self.xb)
+        elif self.metric.name == "ip" or self.metric.name == "cosine":
+            scores = queries @ self.xb.T
+        elif self.metric.name == "l2":
+            diff = queries[:, None, :] - self.xb[None, :, :]
+            scores = np.sum(diff * diff, axis=2)
+        else:
+            raise ValueError(f"unsupported metric for brute force: {self.metric.name}")
+
+        k = min(k, self.xb.shape[0])
+        if self.metric.higher_is_better:
+            idx = np.argpartition(-scores, kth=k - 1, axis=1)[:, :k]
+            row = np.arange(scores.shape[0])[:, None]
+            val = scores[row, idx]
+            order = np.argsort(-val, axis=1)
+        else:
+            idx = np.argpartition(scores, kth=k - 1, axis=1)[:, :k]
+            row = np.arange(scores.shape[0])[:, None]
+            val = scores[row, idx]
+            order = np.argsort(val, axis=1)
+        sorted_idx = np.take_along_axis(idx, order, axis=1)
+        sorted_scores = np.take_along_axis(scores, sorted_idx, axis=1)
+        return sorted_scores, sorted_idx.astype(np.int64)
+
+    def save(self, path: str) -> None:
+        if self.xb is None or self.metric is None:
+            raise RuntimeError("backend is not built")
+        os.makedirs(path, exist_ok=True)
+        np.save(os.path.join(path, "vectors.npy"), self.xb)
+        with open(os.path.join(path, "backend_meta.json"), "w", encoding="utf-8") as f:
+            json.dump(
+                {
+                    "name": self.name,
+                    "metric_name": self.metric.name,
+                    "higher_is_better": self.metric.higher_is_better,
+                    "has_custom_metric": self.metric.fn is not None,
+                },
+                f,
+            )
+
+    @classmethod
+    def load(cls, path: str) -> "BruteForceBackend":
+        with open(os.path.join(path, "backend_meta.json"), "r", encoding="utf-8") as f:
+            meta = json.load(f)
+        if meta["has_custom_metric"]:
+            raise ValueError("cannot load custom brute force metric without explicit code hook")
+        xb = np.load(os.path.join(path, "vectors.npy"))
+        backend = cls()
+        backend.metric = Metric(name=meta["metric_name"], higher_is_better=meta["higher_is_better"])
+        backend.xb = xb
+        return backend

vector_engine/backends/faiss_backend.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from vector_engine.metric import Metric
+
+
+def _normalize_l2(x: np.ndarray) -> np.ndarray:
+    norms = np.linalg.norm(x, axis=1, keepdims=True)
+    norms = np.where(norms == 0, 1.0, norms)
+    return x / norms
+
+
+@dataclass
+class FaissBackend:
+    name: str = "faiss"
+    capabilities: dict[str, bool] = field(
+        default_factory=lambda: {
+            "supports_delete": False,
+            "supports_custom_metric": False,
+            "supports_persistence": True,
+        }
+    )
+    _index: object | None = None
+    _metric: Metric | None = None
+    _count: int = 0
+    _config: dict | None = None
+
+    def _faiss(self) -> object:
+        try:
+            import faiss  # type: ignore
+        except Exception as exc:  # pragma: no cover - import path depends on env
+            raise ImportError(
+                "Faiss backend requested but faiss is not installed. "
+                "Install with `pip install faiss-cpu`."
+            ) from exc
+        return faiss
+
+    def build(self, xb: np.ndarray, metric: Metric, config: dict) -> None:
+        if metric.fn is not None:
+            raise ValueError("faiss backend does not support custom metric functions")
+        faiss = self._faiss()
+        arr = np.ascontiguousarray(xb, dtype=np.float32)
+        if metric.name == "cosine":
+            arr = _normalize_l2(arr)
+            metric_for_faiss = "ip"
+        else:
+            metric_for_faiss = metric.name
+
+        index_factory = config.get("index_factory", "Flat")
+        if metric_for_faiss == "l2":
+            index = faiss.index_factory(arr.shape[1], index_factory, faiss.METRIC_L2)
+        elif metric_for_faiss == "ip":
+            index = faiss.index_factory(arr.shape[1], index_factory, faiss.METRIC_INNER_PRODUCT)
+        else:
+            raise ValueError(f"unsupported metric for faiss: {metric.name}")
+
+        if hasattr(index, "train") and not index.is_trained:
+            index.train(arr)
+        index.add(arr)
+
+        nprobe = config.get("nprobe")
+        if nprobe is not None and hasattr(index, "nprobe"):
+            index.nprobe = int(nprobe)
+
+        self._index = index
+        self._metric = metric
+        self._count = arr.shape[0]
+        self._config = dict(config)
+
+    def add(self, xb: np.ndarray) -> np.ndarray:
+        if self._index is None or self._metric is None:
+            raise RuntimeError("backend is not built")
+        arr = np.ascontiguousarray(xb, dtype=np.float32)
+        if self._metric.name == "cosine":
+            arr = _normalize_l2(arr)
+        start = self._count
+        self._index.add(arr)
+        self._count += arr.shape[0]
+        return np.arange(start, self._count, dtype=np.int64)
+
+    def search(self, xq: np.ndarray, k: int) -> tuple[np.ndarray, np.ndarray]:
+        if self._index is None or self._metric is None:
+            raise RuntimeError("backend is not built")
+        queries = np.ascontiguousarray(xq, dtype=np.float32)
+        if self._metric.name == "cosine":
+            queries = _normalize_l2(queries)
+        scores, internal_ids = self._index.search(queries, k)
+        return scores, internal_ids.astype(np.int64)
+
+    def save(self, path: str) -> None:
+        if self._index is None or self._metric is None:
+            raise RuntimeError("backend is not built")
+        faiss = self._faiss()
+        os.makedirs(path, exist_ok=True)
+        faiss.write_index(self._index, os.path.join(path, "faiss.index"))
+        with open(os.path.join(path, "backend_meta.json"), "w", encoding="utf-8") as f:
+            json.dump(
+                {
+                    "name": self.name,
+                    "metric_name": self._metric.name,
+                    "higher_is_better": self._metric.higher_is_better,
+                    "config": self._config or {},
+                    "count": self._count,
+                },
+                f,
+            )
+
+    @classmethod
+    def load(cls, path: str) -> "FaissBackend":
+        backend = cls()
+        faiss = backend._faiss()
+        with open(os.path.join(path, "backend_meta.json"), "r", encoding="utf-8") as f:
+            meta = json.load(f)
+        backend._index = faiss.read_index(os.path.join(path, "faiss.index"))
+        backend._metric = Metric(name=meta["metric_name"], higher_is_better=meta["higher_is_better"])
+        backend._config = meta.get("config", {})
+        backend._count = int(meta.get("count", 0))
+        return backend

vector_engine/backends/registry.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Any
+
+BACKENDS: dict[str, type[Any]] = {}
+
+
+def register_backend(name: str, backend_cls: type[Any]) -> None:
+    BACKENDS[name] = backend_cls
+
+
+def get_backend(name: str) -> type[Any]:
+    if name not in BACKENDS:
+        raise ValueError(f"unknown backend: {name}")
+    return BACKENDS[name]

vector_engine/eval/__init__.py

@@ -0,0 +1,17 @@
+from .retrieval import (
+    batch_metrics_summary,
+    ndcg_at_k,
+    precision_at_k,
+    recall_at_k,
+    retrieval_report,
+    retrieval_report_detailed,
+)
+
+__all__ = [
+    "batch_metrics_summary",
+    "ndcg_at_k",
+    "precision_at_k",
+    "recall_at_k",
+    "retrieval_report",
+    "retrieval_report_detailed",
+]

vector_engine/eval/retrieval.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import math
+from typing import Iterable, Sequence
+
+import numpy as np
+
+
+def _normalize_ground_truth(
+    ground_truth_ids: np.ndarray | Iterable[Iterable[object]],
+    n_queries: int,
+) -> list[set[object]]:
+    if isinstance(ground_truth_ids, np.ndarray):
+        if ground_truth_ids.ndim == 2:
+            rows = [ground_truth_ids[i].tolist() for i in range(ground_truth_ids.shape[0])]
+        elif ground_truth_ids.ndim == 1:
+            rows = ground_truth_ids.tolist()
+        else:
+            raise ValueError("eval_error: ground_truth_ids must be 1D or 2D")
+    else:
+        rows = list(ground_truth_ids)
+
+    if len(rows) != n_queries:
+        raise ValueError("eval_error: retrieved_ids and ground_truth_ids must have same number of queries")
+
+    normalized: list[set[object]] = []
+    for i, row in enumerate(rows):
+        if isinstance(row, (str, bytes)) or not isinstance(row, Iterable):
+            raise TypeError(f"eval_error: ground_truth_ids row {i} must be an iterable of IDs")
+        normalized.append(set(row))
+    return normalized
+
+
+def _ensure_2d(name: str, value: np.ndarray) -> np.ndarray:
+    arr = np.asarray(value, dtype=object)
+    if arr.ndim != 2:
+        raise ValueError(f"eval_error: {name} must be a 2D array")
+    if arr.shape[0] == 0:
+        raise ValueError(f"eval_error: {name} cannot be empty")
+    return arr
+
+
+def _validate_inputs(
+    retrieved_ids: np.ndarray,
+    ground_truth_ids: np.ndarray | Iterable[Iterable[object]],
+    k: int,
+) -> tuple[np.ndarray, list[set[object]]]:
+    if not isinstance(k, int):
+        raise TypeError("eval_error: k must be an int")
+    if k <= 0:
+        raise ValueError("eval_error: k must be > 0")
+    retrieved = _ensure_2d("retrieved_ids", retrieved_ids)
+    if k > retrieved.shape[1]:
+        raise ValueError("eval_error: k cannot exceed retrieved_ids width")
+    return retrieved, _normalize_ground_truth(ground_truth_ids, n_queries=retrieved.shape[0])
+
+
+def _per_query_precision(retrieved_row: Sequence[object], gt_row: set[object], k: int) -> float:
+    hit = sum(1 for item in list(retrieved_row)[:k] if item in gt_row)
+    return hit / float(k)
+
+
+def _per_query_recall(retrieved_row: Sequence[object], gt_row: set[object], k: int) -> float:
+    if len(gt_row) == 0:
+        return 0.0
+    hit = sum(1 for item in list(retrieved_row)[:k] if item in gt_row)
+    return hit / float(len(gt_row))
+
+
+def _per_query_ndcg(retrieved_row: Sequence[object], gt_row: set[object], k: int) -> float:
+    dcg = 0.0
+    for rank, item in enumerate(list(retrieved_row)[:k], start=1):
+        rel = 1.0 if item in gt_row else 0.0
+        dcg += rel / math.log2(rank + 1)
+    ideal_hits = min(k, len(gt_row))
+    idcg = sum(1.0 / math.log2(rank + 1) for rank in range(1, ideal_hits + 1))
+    return 0.0 if idcg == 0 else dcg / idcg
+
+
+def precision_at_k(
+    retrieved_ids: np.ndarray,
+    ground_truth_ids: np.ndarray | Iterable[Iterable[object]],
+    k: int,
+) -> float:
+    retrieved, gt = _validate_inputs(retrieved_ids, ground_truth_ids, k)
+    vals = [_per_query_precision(retrieved[i].tolist(), gt[i], k) for i in range(retrieved.shape[0])]
+    return float(np.mean(np.asarray(vals, dtype=np.float64)))
+
+
+def recall_at_k(
+    retrieved_ids: np.ndarray,
+    ground_truth_ids: np.ndarray | Iterable[Iterable[object]],
+    k: int,
+) -> float:
+    retrieved, gt = _validate_inputs(retrieved_ids, ground_truth_ids, k)
+    vals = [_per_query_recall(retrieved[i].tolist(), gt[i], k) for i in range(retrieved.shape[0])]
+    return float(np.mean(np.asarray(vals, dtype=np.float64)))
+
+
+def ndcg_at_k(
+    retrieved_ids: np.ndarray,
+    ground_truth_ids: np.ndarray | Iterable[Iterable[object]],
+    k: int,
+) -> float:
+    retrieved, gt = _validate_inputs(retrieved_ids, ground_truth_ids, k)
+    vals = [_per_query_ndcg(retrieved[i].tolist(), gt[i], k) for i in range(retrieved.shape[0])]
+    return float(np.mean(np.asarray(vals, dtype=np.float64)))
+
+
+def retrieval_report(
+    retrieved_ids: np.ndarray,
+    ground_truth_ids: np.ndarray | Iterable[Iterable[object]],
+    ks: Sequence[int] = (1, 5, 10),
+) -> dict[str, float]:
+    """Compute retrieval metrics for multiple k values."""
+    if len(ks) == 0:
+        raise ValueError("eval_error: ks cannot be empty")
+    report: dict[str, float] = {}
+    for k in ks:
+        if k <= 0:
+            raise ValueError("eval_error: each k must be > 0")
+        report[f"precision@{k}"] = precision_at_k(retrieved_ids, ground_truth_ids, k)
+        report[f"recall@{k}"] = recall_at_k(retrieved_ids, ground_truth_ids, k)
+        report[f"ndcg@{k}"] = ndcg_at_k(retrieved_ids, ground_truth_ids, k)
+    return report
+
+
+def retrieval_report_detailed(
+    retrieved_ids: np.ndarray,
+    ground_truth_ids: np.ndarray | Iterable[Iterable[object]],
+    ks: Sequence[int] = (1, 5, 10),
+    *,
+    include_per_query: bool = True,
+) -> dict[str, object]:
+    """Compute aggregate and per-query retrieval metrics."""
+    retrieved = _ensure_2d("retrieved_ids", retrieved_ids)
+    summary = retrieval_report(retrieved_ids, ground_truth_ids, ks=ks)
+    payload: dict[str, object] = {"summary": summary}
+    if include_per_query:
+        per_query: list[dict[str, float]] = []
+        gt = _normalize_ground_truth(ground_truth_ids, n_queries=retrieved.shape[0])
+        for i in range(retrieved.shape[0]):
+            row: dict[str, float] = {}
+            for k in ks:
+                row[f"precision@{k}"] = _per_query_precision(retrieved[i].tolist(), gt[i], k)
+                row[f"recall@{k}"] = _per_query_recall(retrieved[i].tolist(), gt[i], k)
+                row[f"ndcg@{k}"] = _per_query_ndcg(retrieved[i].tolist(), gt[i], k)
+            per_query.append(row)
+        payload["per_query"] = per_query
+    return payload
+
+
+def batch_metrics_summary(
+    reports: Sequence[dict[str, float]],
+    *,
+    include_std: bool = False,
+) -> dict[str, float]:
+    """Aggregate multiple retrieval reports into macro means."""
+    if len(reports) == 0:
+        raise ValueError("eval_error: reports cannot be empty")
+    keys = sorted(reports[0].keys())
+    for r in reports:
+        if sorted(r.keys()) != keys:
+            raise ValueError("eval_error: all reports must contain identical metric keys")
+    summary: dict[str, float] = {}
+    for key in keys:
+        vals = [float(r[key]) for r in reports]
+        arr = np.asarray(vals, dtype=np.float64)
+        summary[key] = float(np.mean(arr))
+        if include_std:
+            summary[f"{key}_std"] = float(np.std(arr))
+    summary["num_reports"] = float(len(reports))
+    return summary