precisionai-agrieval 0.1.0.dev0__py3-none-any.whl

precisionai/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0

precisionai/agrieval/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0

precisionai/agrieval/api/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0

precisionai/agrieval/api/app.py

@@ -0,0 +1,103 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0
+
+"""Unified FastAPI application factory and CLI entry point for all AgriEval wirings."""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+import uvicorn
+from fastapi import FastAPI
+
+from precisionai.agrieval.emb.api.routes.evaluate import router as emb_router
+from precisionai.agrieval.seg.api.routes.evaluate import router as seg_router
+
+_DESCRIPTION = """
+Precision AI AgriEval — evaluation framework for agricultural computer vision models.
+
+## Embedding evaluation
+
+Benchmark how well image embeddings cluster by L1/L2 crop-class hierarchy.
+
+```
+POST /v1/embeddings/evaluate/image2image
+POST /v1/embeddings/evaluate/plant2image
+POST /v1/embeddings/evaluate/plant2plant
+```
+
+## Segmentation evaluation
+
+Evaluate predicted colour-coded masks against ground-truth masks.  Returns
+per-class IoU, Dice/F1, accuracy, mIoU, mAcc, and FWIoU.
+
+```
+POST /v1/segmentation/evaluate
+```
+
+## Path resolution
+
+All path arguments (``pred_dir``, ``masks_dir``, ``classes_path``, etc.) are
+resolved against the ``dataset_root`` field in the request body, which falls
+back to the ``PAI_DATASET_ROOT`` environment variable and then ``"dataset"``.
+Absolute paths bypass ``dataset_root`` entirely.
+"""
+
+app = FastAPI(
+    title="precisionai-agrieval",
+    description=_DESCRIPTION,
+    version="0.1.0",
+)
+
+app.include_router(emb_router, prefix="/v1")
+app.include_router(seg_router, prefix="/v1")
+
+
+def main() -> None:
+    """Parse CLI arguments and start the uvicorn ASGI server.
+
+    Recognised arguments
+    --------------------
+    --dataset-root : str
+        Default dataset root used when a request does not supply one.  Also
+        settable via the ``PAI_DATASET_ROOT`` environment variable.  Defaults
+        to ``"dataset"``.
+    --host : str
+        Bind address for the server.  Defaults to ``"0.0.0.0"``.
+    --port : int
+        TCP port to listen on.  Defaults to ``8000``.
+    --no-reload : flag
+        Disable uvicorn auto-reload (recommended in production).
+    """
+    parser = argparse.ArgumentParser(description="precisionai-agrieval unified API server")
+    parser.add_argument(
+        "--dataset-root",
+        default="dataset",
+        metavar="PATH",
+        help="Default dataset root used when the request omits dataset_root. "
+        "Can also be set via PAI_DATASET_ROOT env var. (default: dataset)",
+    )
+    parser.add_argument("--host", default="0.0.0.0", metavar="HOST")
+    parser.add_argument("--port", type=int, default=8000, metavar="PORT")
+    parser.add_argument(
+        "--no-reload",
+        dest="reload",
+        action="store_false",
+        default=True,
+        help="Disable auto-reload (recommended in production)",
+    )
+    args = parser.parse_args()
+
+    os.environ.setdefault("PAI_DATASET_ROOT", args.dataset_root)
+
+    uvicorn.run(
+        "precisionai.agrieval.api.app:app",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+    )
+
+
+if __name__ == "__main__":
+    main()

precisionai/agrieval/api/config.py

@@ -0,0 +1,31 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared runtime configuration resolved from environment variables.
+
+``PAI_DATASET_ROOT`` — default dataset root used when a request does not
+supply ``dataset_root``.  Set by the ``--dataset-root`` CLI argument before
+uvicorn spawns worker processes so the value is inherited.
+
+Defaults to ``"dataset"`` so a repository checked out next to a ``dataset/``
+directory works out of the box.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def get_dataset_root() -> str:
+    """Return the server-level default dataset root.
+
+    The value is read from the ``PAI_DATASET_ROOT`` environment variable at
+    request time so that it reflects any changes made after server start.
+
+    Returns
+    -------
+    str
+        Dataset root path, defaulting to ``"dataset"`` when the environment
+        variable is not set.
+    """
+    return os.environ.get("PAI_DATASET_ROOT", "dataset")

precisionai/agrieval/emb/__init__.py

@@ -0,0 +1,28 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0
+
+from precisionai.agrieval.emb.schemas.evaluate import MetadataGroup
+from precisionai.agrieval.emb.services.evaluate import (
+    run_image2image_eval,
+    run_plant2image_eval,
+    run_plant2plant_eval,
+)
+from precisionai.agrieval.emb.services.reporting import (
+    plot_cosine_similarity,
+    plot_knn_confusion,
+    plot_lle,
+    plot_tsne,
+    print_result,
+)
+
+__all__ = [
+    "MetadataGroup",
+    "plot_cosine_similarity",
+    "plot_knn_confusion",
+    "plot_lle",
+    "plot_tsne",
+    "print_result",
+    "run_image2image_eval",
+    "run_plant2image_eval",
+    "run_plant2plant_eval",
+]

precisionai/agrieval/emb/api/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0

precisionai/agrieval/emb/api/app.py

@@ -0,0 +1,114 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0
+
+"""FastAPI application factory and entry point."""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+import uvicorn
+from fastapi import FastAPI
+
+from precisionai.agrieval.emb.api.routes.evaluate import router as evaluate_router
+
+_DESCRIPTION = """
+Evaluate the quality of image model embeddings — how well they cluster by L1/L2 cluster.
+
+## Usage
+
+Send a single JSON object with your embeddings dict to **POST /v1/embeddings/evaluate/image2image**.
+Everything else is optional.
+
+```json
+{
+  "embeddings": {
+    "images/A1/pai-abc123.png": [0.12, -0.31, 0.27, ...],
+    "images/A2/pai-def456.png": [0.11, -0.30, 0.26, ...],
+    "images/D1/pai-ghi789.png": [-0.45, 0.18, -0.09, ...]
+  }
+}
+```
+
+**Embedding requirements**
+- Flat 1-D array (length = `embedding_dim`)
+- L2-normalised float32 (`‖v‖₂ = 1.0 ± 0.001`)
+- All vectors must share the same length
+- Minimum 2 embeddings per request
+
+**Path convention**
+
+The L1 cluster label is extracted automatically from the L2 folder name:
+```
+images / A1 / pai-abc123.png
+         ^^
+         L2 folder  →  L1 = "A"  (leading letters)
+```
+
+Supply a `metadata` dict to enable graded nDCG and per-attribute KPIs based on
+the explicit L1/L2 cluster structure (see `image2image.json` in the dataset root).
+
+**Response**
+
+Returns a fixed JSON report with a `global_metrics` summary and a
+`per_class` breakdown for every detected L1 cluster.
+"""
+
+app = FastAPI(
+    title="precisionai-agrieval",
+    description=_DESCRIPTION,
+    version="0.1.0",
+)
+
+app.include_router(evaluate_router, prefix="/v1")
+
+
+def main() -> None:
+    """Parse CLI arguments and start the uvicorn ASGI server.
+
+    Recognised arguments
+    --------------------
+    --dataset-root : str
+        Default dataset root passed to the evaluation service when a request
+        does not supply one.  Also settable via the ``PAI_DATASET_ROOT``
+        environment variable.  Defaults to ``"dataset"``.
+    --host : str
+        Bind address for the server.  Defaults to ``"0.0.0.0"``.
+    --port : int
+        TCP port to listen on.  Defaults to ``8000``.
+    --no-reload : flag
+        Disable uvicorn auto-reload (recommended in production).
+    """
+    parser = argparse.ArgumentParser(description="precisionai-agrieval API server")
+    parser.add_argument(
+        "--dataset-root",
+        default="dataset",
+        metavar="PATH",
+        help="Default dataset root used when the request omits dataset_root. "
+        "Can also be set via PAI_DATASET_ROOT env var. (default: dataset)",
+    )
+    parser.add_argument("--host", default="0.0.0.0", metavar="HOST")
+    parser.add_argument("--port", type=int, default=8000, metavar="PORT")
+    parser.add_argument(
+        "--no-reload",
+        dest="reload",
+        action="store_false",
+        default=True,
+        help="Disable auto-reload (recommended in production)",
+    )
+    args = parser.parse_args()
+
+    # Propagate to child worker processes via env var before uvicorn forks.
+    os.environ.setdefault("PAI_DATASET_ROOT", args.dataset_root)
+
+    uvicorn.run(
+        "precisionai.agrieval.emb.api.app:app",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+    )
+
+
+if __name__ == "__main__":
+    main()

precisionai/agrieval/emb/api/config.py

@@ -0,0 +1,8 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0
+
+"""Re-export of the shared dataset-root configuration for the emb sub-package."""
+
+from precisionai.agrieval.api.config import get_dataset_root
+
+__all__ = ["get_dataset_root"]

precisionai/agrieval/emb/api/routes/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0

precisionai/agrieval/emb/api/routes/evaluate.py

@@ -0,0 +1,126 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0
+
+"""Embedding evaluation routes.
+
+Three named endpoints cover the full agricultural retrieval taxonomy:
+
+- ``POST /evaluate/image2image`` — Image→Image (full field image vs. full field image)
+- ``POST /evaluate/plant2image`` — Plant→Image (instance crop vs. full field image)
+- ``POST /evaluate/plant2plant`` — Plant→Plant (instance crop vs. instance crop)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+
+from precisionai.agrieval.emb.api.config import get_dataset_root
+from precisionai.agrieval.emb.schemas.evaluate import (
+    EmbeddingEvaluateRequest,
+    EmbeddingEvaluateResponse,
+    Plant2ImageRequest,
+    Plant2PlantRequest,
+)
+from precisionai.agrieval.emb.services.evaluate import (
+    run_image2image_eval,
+    run_plant2image_eval,
+    run_plant2plant_eval,
+)
+
+router = APIRouter(prefix="/embeddings", tags=["evaluate"])
+
+
+def _resolve_dataset_root(dataset_root: str | None) -> str:
+    """Use the configured server default when a request omits dataset_root."""
+    return dataset_root if dataset_root is not None else get_dataset_root()
+
+
+def _run_or_400(func: Callable[..., dict[str, Any]], /, **kwargs: Any) -> EmbeddingEvaluateResponse:
+    """Convert service-layer ValueError exceptions into 400 responses."""
+    try:
+        result = func(**kwargs)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    return EmbeddingEvaluateResponse(**result)
+
+
+@router.post("/evaluate/image2image", response_model=EmbeddingEvaluateResponse)
+def evaluate_image2image(request: EmbeddingEvaluateRequest) -> EmbeddingEvaluateResponse:
+    """Evaluate embedding quality for the Image→Image retrieval scenario.
+
+    Given a complete agricultural field image, retrieve visually and
+    agronomically similar full field images.  Similarity can be coarse
+    (crop type, soil, growth stage) or fine (disease symptoms, weed pressure).
+
+    Pass a dict of ``image_path → embedding`` vectors.  When ``metadata`` is
+    omitted the L1 class label is inferred from the folder name of each path
+    (e.g. ``images/A1/img.png`` → ``A``).  Supply ``metadata`` to enable
+    explicit-positive groups, graded nDCG (0-3 by L2/L1 hierarchy and
+    ``plants`` overlap), and per-attribute KPIs.
+
+    **Only ``embeddings`` is required** — all other fields use server defaults.
+
+    Returns a fixed JSON report with:
+    - **global_metrics** — pairwise similarity stats, intra/inter class gap,
+      KNN label purity, effective rank, centroid similarity, duplicate counts.
+    - **per_class** — the same metrics broken down per crop class.
+    """
+    return _run_or_400(
+        run_image2image_eval,
+        image_embeddings=request.embeddings,
+        k_values=request.k_values,
+        dataset_root=_resolve_dataset_root(request.dataset_root),
+        sample_pairs=request.sample_pairs,
+        metadata=request.metadata,
+    )
+
+
+@router.post("/evaluate/plant2image", response_model=EmbeddingEvaluateResponse)
+def evaluate_plant2image(request: Plant2ImageRequest) -> EmbeddingEvaluateResponse:
+    """Evaluate embedding quality for the Plant→Image retrieval scenario.
+
+    Pass a mixed corpus of full-field image embeddings and per-plant instance
+    crop embeddings together with an ``instance_to_image`` mapping that
+    declares which instances were cropped from which parent image.
+
+    The mapping is the explicit-positive ground truth: when an instance is the
+    query its parent full image is the grade-3 positive; when a full image is
+    the query all its instances are grade-3 positives.  Items that share the
+    same class label (inferred from the parent's folder name) are grade-2
+    positives across groups.
+
+    Returns the same fixed JSON report as ``POST /v1/embeddings/evaluate``
+    with metadata-aware KPIs enabled (``knn_metadata_precision``,
+    ``knn_metadata_ndcg``, ``alignment``, etc.).
+    """
+    return _run_or_400(
+        run_plant2image_eval,
+        embeddings=request.embeddings,
+        instance_to_image=request.instance_to_image,
+        k_values=request.k_values,
+        dataset_root=_resolve_dataset_root(request.dataset_root),
+        sample_pairs=request.sample_pairs,
+    )
+
+
+@router.post("/evaluate/plant2plant", response_model=EmbeddingEvaluateResponse)
+def evaluate_plant2plant(request: Plant2PlantRequest) -> EmbeddingEvaluateResponse:
+    """Evaluate embedding quality for the Plant→Plant retrieval scenario.
+
+    Pass per-plant instance crop embeddings with an ``instance_labels`` mapping
+    that assigns each instance its crop or weed class.  All instances sharing
+    the same class label are treated as mutual explicit positives.
+
+    Returns the same fixed JSON report as ``POST /v1/embeddings/evaluate``
+    with metadata-aware KPIs enabled.
+    """
+    return _run_or_400(
+        run_plant2plant_eval,
+        embeddings=request.embeddings,
+        instance_labels=request.instance_labels,
+        k_values=request.k_values,
+        sample_pairs=request.sample_pairs,
+    )

precisionai/agrieval/emb/metrics/__init__.py

@@ -0,0 +1,115 @@
+# Copyright 2026 Precision AI
+# SPDX-License-Identifier: Apache-2.0
+
+from precisionai.agrieval.emb.metrics.analysis import analyze_embedding_space, compare_embedding_spaces
+from precisionai.agrieval.emb.metrics.cross_model import (
+    knn_jaccard_at_k,
+    knn_overlap_at_k,
+    pairwise_similarity_correlation,
+    per_item_neighbor_disagreement,
+)
+from precisionai.agrieval.emb.metrics.duplicates import (
+    duplicate_groups_at_threshold,
+    duplicate_pairs_at_threshold,
+)
+from precisionai.agrieval.emb.metrics.geometry import (
+    alignment,
+    anisotropy_summary,
+    centroid_similarity_stats,
+    effective_rank,
+    pca_explained_variance,
+    uniformity,
+)
+from precisionai.agrieval.emb.metrics.label_aware import (
+    ImageItem,
+    intra_inter_similarity_gap,
+    knn_confusion_matrix,
+    knn_label_mrr_at_k,
+    knn_label_ndcg_at_k,
+    knn_label_purity_at_k,
+    knn_label_r_precision,
+    knn_map_at_k,
+    knn_metadata_map_at_k,
+    knn_metadata_mrr_at_k,
+    knn_metadata_ndcg_at_k,
+    knn_metadata_precision_at_k,
+    knn_metadata_r_precision,
+    knn_per_attribute_ndcg_at_k,
+    relevance_grade,
+)
+from precisionai.agrieval.emb.metrics.neighbors import (
+    gini_coefficient,
+    hubness_at_k,
+    knn_radius_at_k,
+    mean_top_k_similarity,
+    outlier_score_at_k,
+)
+from precisionai.agrieval.emb.metrics.ranking import (
+    average_precision_at_k,
+    dcg_at_k,
+    l2_normalize,
+    ndcg_at_k,
+    normalize_ks,
+    precision_at_k,
+    r_precision,
+    recall_at_k,
+    reciprocal_rank,
+    safe_mean,
+)
+from precisionai.agrieval.emb.metrics.similarity import (
+    cosine_similarity_matrix,
+    pairwise_similarity_stats,
+    similarity_threshold_counts,
+    top_k_neighbors,
+)
+
+__all__ = [
+    "ImageItem",
+    "alignment",
+    "analyze_embedding_space",
+    "anisotropy_summary",
+    "average_precision_at_k",
+    "centroid_similarity_stats",
+    "compare_embedding_spaces",
+    "cosine_similarity_matrix",
+    "dcg_at_k",
+    "duplicate_groups_at_threshold",
+    "duplicate_pairs_at_threshold",
+    "effective_rank",
+    "gini_coefficient",
+    "hubness_at_k",
+    "intra_inter_similarity_gap",
+    "knn_confusion_matrix",
+    "knn_jaccard_at_k",
+    "knn_label_mrr_at_k",
+    "knn_label_ndcg_at_k",
+    "knn_label_purity_at_k",
+    "knn_label_r_precision",
+    "knn_map_at_k",
+    "knn_metadata_map_at_k",
+    "knn_metadata_mrr_at_k",
+    "knn_metadata_ndcg_at_k",
+    "knn_metadata_precision_at_k",
+    "knn_metadata_r_precision",
+    "knn_overlap_at_k",
+    "knn_per_attribute_ndcg_at_k",
+    "knn_radius_at_k",
+    "l2_normalize",
+    "mean_top_k_similarity",
+    "ndcg_at_k",
+    "normalize_ks",
+    "outlier_score_at_k",
+    "pairwise_similarity_correlation",
+    "pairwise_similarity_stats",
+    "pca_explained_variance",
+    "per_item_neighbor_disagreement",
+    "precision_at_k",
+    "r_precision",
+    "recall_at_k",
+    "reciprocal_rank",
+    "relevance_grade",
+    "safe_mean",
+    "similarity_threshold_counts",
+    "top_k_neighbors",
+    "uniformity",
+]