feat(backend): API FastAPI de conteo con modo standby

Implementa el backend del MVP: configuración por entorno, esquemas Pydantic, dominio de detección, métricas, adaptador de inferencia agnóstico (YOLO26/RF-DETR vía ONNX) y endpoints /api/status y /api/count. El conteo arranca en standby (COUNTING_ENABLED=false) y responde 503 hasta publicar el modelo.

backend/__init__.py

@@ -0,0 +1 @@
+"""Paquete backend del MVP de AgroVisión (gateway FastAPI + inferencia de conteo)."""

backend/api/__init__.py

@@ -0,0 +1 @@
+"""Rutas HTTP del backend del MVP (healthcheck y conteo)."""

backend/api/count.py

@@ -0,0 +1,139 @@
+"""
+Archivo: count.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Define las rutas HTTP del MVP: el healthcheck `/api/status` y el conteo síncrono
+`/api/count`. El conteo respeta el modo **standby**: mientras `COUNTING_ENABLED`
+sea falso o el modelo no esté cargado, responde 503 con un mensaje claro en vez
+de intentar inferir.
+
+Acciones Principales:
+    - Expone `/api/status` (estado + bandera de conteo).
+    - Expone `/api/count` (inferencia síncrona, gateada por standby).
+
+Estructura Interna:
+    - `router`: APIRouter con las rutas del MVP.
+    - `_draw_overlay`: dibuja las cajas detectadas sobre la imagen.
+
+Entradas / Dependencias:
+    - `fastapi`, `numpy`, `opencv-python`, `backend.config`, `backend.core.*`, `backend.schemas`.
+
+Salidas / Efectos:
+    - Ninguno persistente; la respuesta es efímera (overlay en base64).
+
+Integración UI:
+    - Este router es montado por `backend.main:app`.
+    - La UI Shiny consume `/api/status` y `/api/count` vía HTTPS.
+"""
+
+from __future__ import annotations
+
+import base64
+
+import cv2
+import numpy as np
+from fastapi import APIRouter, File, Form, HTTPException, Request, UploadFile, status
+
+from backend.config import get_settings
+from backend.core.detection import CLASS_PLANT, Detection
+from backend.core.metrics import compute_metrics
+from backend.schemas import CountResponse, StatusResponse
+
+router = APIRouter()
+
+_OVERLAY_COLOR_BGR: tuple[int, int, int] = (61, 128, 21)  # verde Deep Canopy (#15803D) en BGR
+_OVERLAY_THICKNESS: int = 2
+
+
+def _draw_overlay(image_bgr: np.ndarray, detections: list[Detection]) -> str:
+    """
+    Dibuja las cajas detectadas sobre la imagen y la codifica como PNG en base64.
+
+    Args:
+        image_bgr (np.ndarray): Imagen original en formato BGR.
+        detections (list[Detection]): Detecciones a superponer.
+
+    Returns:
+        str: Imagen anotada (PNG) codificada en base64.
+    """
+    overlay = image_bgr.copy()
+    for detection in detections:
+        top_left = (int(detection.x1), int(detection.y1))
+        bottom_right = (int(detection.x2), int(detection.y2))
+        cv2.rectangle(overlay, top_left, bottom_right, _OVERLAY_COLOR_BGR, _OVERLAY_THICKNESS)
+    _, buffer = cv2.imencode(".png", overlay)
+    return base64.b64encode(buffer.tobytes()).decode("ascii")
+
+
+@router.get("/api/status", response_model=StatusResponse)
+def get_status() -> StatusResponse:
+    """
+    Devuelve el estado del backend y si el módulo de conteo está activo.
+
+    Returns:
+        StatusResponse: Estado, nombre/versión del modelo y bandera de conteo.
+    """
+    settings = get_settings()
+    return StatusResponse(
+        status="ok",
+        model="agrovision-plantcount",
+        version=settings.model_version,
+        counting_enabled=settings.counting_enabled,
+    )
+
+
+@router.post("/api/count", response_model=CountResponse)
+async def post_count(
+    request: Request,
+    file: UploadFile = File(...),
+    area_ha: float = Form(default=1.0),
+) -> CountResponse:
+    """
+    Ejecuta el conteo síncrono sobre un ortomosaico, respetando el modo standby.
+
+    Args:
+        request (Request): Petición; expone el adaptador en `request.app.state`.
+        file (UploadFile): Ortomosaico RGB en formato JPG/PNG/TIFF.
+        area_ha (float): Área del lote en hectáreas para calcular densidad.
+
+    Returns:
+        CountResponse: Conteo, densidad, malezas, fallas, confianza y overlay.
+
+    Raises:
+        HTTPException: 503 si el conteo está en standby; 400 si la imagen es inválida.
+    """
+    settings = get_settings()
+    adapter = getattr(request.app.state, "adapter", None)
+
+    if not settings.counting_enabled or adapter is None:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=(
+                "Módulo de conteo en standby: el modelo aún no está disponible. "
+                "Se activará cuando el repo del modelo publique el artefacto."
+            ),
+        )
+
+    raw_bytes = await file.read()
+    image_bgr = cv2.imdecode(np.frombuffer(raw_bytes, np.uint8), cv2.IMREAD_COLOR)
+    if image_bgr is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No se pudo decodificar la imagen. Use JPG, PNG o TIFF válido.",
+        )
+
+    detections = adapter.predict(image_bgr, confidence=settings.confidence_threshold)
+    metrics = compute_metrics(detections, area_ha=area_ha)
+    plant_detections = [d for d in detections if d.class_id == CLASS_PLANT]
+    overlay_b64 = _draw_overlay(image_bgr, plant_detections)
+
+    return CountResponse(
+        count=metrics["count"],
+        density=metrics["density"],
+        weeds=metrics["weeds"],
+        failures=metrics["failures"],
+        confidence=metrics["confidence"],
+        overlay_b64=overlay_b64,
+    )

backend/config.py

@@ -0,0 +1,98 @@
+"""
+Archivo: config.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Centraliza la configuración del backend del MVP leyéndola de variables de
+entorno, evitando valores mágicos dispersos por el código y facilitando el
+despliegue en distintos entornos (local, Render).
+
+Acciones Principales:
+    - Expone `get_settings`, que construye y cachea la configuración del entorno.
+
+Estructura Interna:
+    - `Settings`: dataclass inmutable con los parámetros del backend.
+    - `get_settings`: lee el entorno y devuelve la configuración cacheada.
+
+Entradas / Dependencias:
+    - Variables de entorno: APP_ENV, MODEL_PATH, MODEL_VERSION, MODEL_ARCHITECTURE,
+      ALLOWED_ORIGINS, COUNTING_ENABLED, MAX_UPLOAD_MB, CONFIDENCE_THRESHOLD.
+
+Salidas / Efectos:
+    - No genera efectos secundarios; únicamente lee variables de entorno.
+
+Ejemplo de Integración:
+    from backend.config import get_settings
+    settings = get_settings()
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+
+from dotenv import load_dotenv
+
+load_dotenv()  # carga variables desde .env en desarrollo local (no sobreescribe el entorno real)
+
+DEFAULT_CONFIDENCE_THRESHOLD: float = 0.25
+DEFAULT_MAX_UPLOAD_MB: int = 50
+DEFAULT_MODEL_PATH: str = "./models/agrovision-plantcount-v2.0.0.onnx"
+DEFAULT_MODEL_VERSION: str = "2.0.0"
+DEFAULT_MODEL_ARCHITECTURE: str = "yolo26n"
+
+
+def _parse_bool(raw: str | None, default: bool = False) -> bool:
+    """
+    Convierte una variable de entorno textual en un booleano.
+
+    Args:
+        raw (str | None): Valor crudo de la variable de entorno.
+        default (bool, opcional): Valor a devolver si `raw` es None. Por defecto False.
+
+    Returns:
+        bool: True si el texto representa un valor verdadero ('1', 'true', 'yes', 'on').
+    """
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Configuración inmutable del backend del MVP, derivada del entorno."""
+
+    app_env: str
+    model_path: str
+    model_version: str
+    model_architecture: str
+    allowed_origins: tuple[str, ...]
+    counting_enabled: bool
+    max_upload_mb: int
+    confidence_threshold: float
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """
+    Construye la configuración del backend a partir de variables de entorno.
+
+    Returns:
+        Settings: Instancia cacheada con la configuración activa del backend.
+    """
+    origins_raw = os.getenv("ALLOWED_ORIGINS", "http://localhost:8001")
+    origins = tuple(origin.strip() for origin in origins_raw.split(",") if origin.strip())
+    return Settings(
+        app_env=os.getenv("APP_ENV", "development"),
+        model_path=os.getenv("MODEL_PATH", DEFAULT_MODEL_PATH),
+        model_version=os.getenv("MODEL_VERSION", DEFAULT_MODEL_VERSION),
+        model_architecture=os.getenv("MODEL_ARCHITECTURE", DEFAULT_MODEL_ARCHITECTURE),
+        allowed_origins=origins,
+        counting_enabled=_parse_bool(os.getenv("COUNTING_ENABLED"), default=False),
+        max_upload_mb=int(os.getenv("MAX_UPLOAD_MB", str(DEFAULT_MAX_UPLOAD_MB))),
+        confidence_threshold=float(
+            os.getenv("CONFIDENCE_THRESHOLD", str(DEFAULT_CONFIDENCE_THRESHOLD))
+        ),
+    )

backend/core/__init__.py

@@ -0,0 +1 @@
+"""Lógica núcleo del backend: dominio de detección, métricas e inferencia."""

backend/core/detection.py

@@ -0,0 +1,47 @@
+"""
+Archivo: detection.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Define el tipo de dominio `Detection` y las constantes de clases del modelo de
+conteo. Es un módulo puro (sin dependencias pesadas) compartido por la inferencia
+y por el cálculo de métricas, evitando importaciones circulares.
+
+Acciones Principales:
+    - Provee la estructura inmutable de una detección y el catálogo de clases.
+
+Estructura Interna:
+    - `Detection`: dataclass con caja, confianza y clase de una detección.
+    - Constantes `CLASS_*` y `CLASS_NAMES`: catálogo de clases del modelo.
+
+Entradas / Dependencias:
+    - Solo librería estándar.
+
+Salidas / Efectos:
+    - Ninguno; expone tipos y constantes.
+
+Ejemplo de Integración:
+    from backend.core.detection import Detection, CLASS_PLANT
+    deteccion = Detection(0, 0, 10, 10, 0.9, CLASS_PLANT)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+CLASS_PLANT: int = 0
+CLASS_WEED: int = 1
+CLASS_NAMES: dict[int, str] = {CLASS_PLANT: "planta", CLASS_WEED: "maleza"}
+
+
+@dataclass(frozen=True)
+class Detection:
+    """Detección individual con caja delimitadora, confianza y clase."""
+
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+    confidence: float
+    class_id: int

backend/core/inference.py

@@ -0,0 +1,144 @@
+"""
+Archivo: inference.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Adaptador de inferencia **agnóstico a la arquitectura**. Carga el artefacto ONNX
+del modelo de conteo con onnxruntime y delega el decode según la arquitectura
+declarada (YOLO26 o RF-DETR), manteniendo la app desacoplada del modelo concreto
+publicado por el repo del modelo. En el MVP el conteo está en standby, por lo que
+el decode permanece como contrato pendiente hasta que el modelo se publique.
+
+Sustentación Científica: [Opcional]
+Los detectores objetivo (YOLO26, RF-DETR) son NMS-free, por lo que el conteo
+equivale al número de detecciones que superan el umbral de confianza.
+
+Acciones Principales:
+    - Carga un modelo ONNX y expone `predict` para obtener detecciones.
+
+Estructura Interna:
+    - `ModelNotAvailableError`: error cuando el modelo no está disponible.
+    - `InferenceAdapter`: envuelve la sesión ONNX y despacha el decode por arquitectura.
+    - `load_adapter`: valida la ruta y construye el adaptador.
+
+Entradas / Dependencias:
+    - `numpy`, `onnxruntime` (import diferido), `backend.core.detection.Detection`.
+
+Salidas / Efectos:
+    - Ninguno persistente; ejecuta inferencia en memoria.
+
+Ejemplo de Integración:
+    from backend.core.inference import load_adapter
+    adapter = load_adapter("models/agrovision-plantcount-v2.0.0.onnx", "yolo26n")
+    detecciones = adapter.predict(imagen_bgr, confidence=0.25)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from backend.core.detection import Detection
+
+SUPPORTED_ARCHITECTURES: frozenset[str] = frozenset({"yolo26n", "rfdetr_nano"})
+
+
+class ModelNotAvailableError(RuntimeError):
+    """Se lanza cuando el modelo de conteo no está disponible (standby o archivo ausente)."""
+
+
+class InferenceAdapter:
+    """
+    Adaptador de inferencia agnóstico a la arquitectura del modelo de conteo.
+
+    Envuelve una sesión de onnxruntime y traduce su salida a una lista de
+    `Detection`, delegando en el decode específico de cada arquitectura soportada.
+    """
+
+    def __init__(self, model_path: str, architecture: str) -> None:
+        """
+        Inicializa la sesión ONNX para el modelo indicado.
+
+        Args:
+            model_path (str): Ruta al artefacto `.onnx` del modelo de conteo.
+            architecture (str): Arquitectura del modelo ('yolo26n' o 'rfdetr_nano').
+
+        Raises:
+            ModelNotAvailableError: Si la arquitectura no está soportada.
+        """
+        if architecture not in SUPPORTED_ARCHITECTURES:
+            raise ModelNotAvailableError(
+                f"Arquitectura no soportada: {architecture}. "
+                f"Soportadas: {sorted(SUPPORTED_ARCHITECTURES)}."
+            )
+        import onnxruntime as ort  # import diferido: onnxruntime no se exige en modo standby
+
+        self._architecture = architecture
+        self._session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
+
+    def predict(self, image_bgr: np.ndarray, confidence: float) -> list[Detection]:
+        """
+        Ejecuta la inferencia sobre una imagen y devuelve las detecciones.
+
+        Args:
+            image_bgr (np.ndarray): Imagen RGB/BGR como arreglo de NumPy.
+            confidence (float): Umbral mínimo de confianza para conservar detecciones.
+
+        Returns:
+            list[Detection]: Detecciones que superan el umbral (sin NMS, modelos NMS-free).
+        """
+        if self._architecture == "yolo26n":
+            return self._decode_yolo(image_bgr, confidence)
+        return self._decode_detr(image_bgr, confidence)
+
+    def _decode_yolo(self, image_bgr: np.ndarray, confidence: float) -> list[Detection]:
+        """
+        Decodifica la salida de un modelo YOLO26 a una lista de detecciones.
+
+        Nota: el decode concreto se implementa cuando el repo del modelo publique el
+        artefacto YOLO26 y se conozca el layout exacto del tensor de salida.
+
+        Raises:
+            NotImplementedError: Mientras el modelo de conteo esté en standby.
+        """
+        raise NotImplementedError(
+            "Decode YOLO26 pendiente: se implementa al publicar el modelo de conteo."
+        )
+
+    def _decode_detr(self, image_bgr: np.ndarray, confidence: float) -> list[Detection]:
+        """
+        Decodifica la salida de un modelo RF-DETR a una lista de detecciones.
+
+        Nota: el decode concreto se implementa cuando el repo del modelo publique el
+        artefacto RF-DETR y se conozca el layout exacto del tensor de salida.
+
+        Raises:
+            NotImplementedError: Mientras el modelo de conteo esté en standby.
+        """
+        raise NotImplementedError(
+            "Decode RF-DETR pendiente: se implementa al publicar el modelo de conteo."
+        )
+
+
+def load_adapter(model_path: str, architecture: str) -> InferenceAdapter:
+    """
+    Valida la existencia del artefacto y construye el adaptador de inferencia.
+
+    Args:
+        model_path (str): Ruta al artefacto `.onnx` del modelo de conteo.
+        architecture (str): Arquitectura del modelo ('yolo26n' o 'rfdetr_nano').
+
+    Returns:
+        InferenceAdapter: Adaptador listo para inferir.
+
+    Raises:
+        ModelNotAvailableError: Si el archivo del modelo no existe en `model_path`.
+    """
+    if not Path(model_path).exists():
+        raise ModelNotAvailableError(
+            f"Modelo no encontrado en {model_path}. Se descarga de Hugging Face Hub "
+            "en el build cuando el repo del modelo publique el artefacto."
+        )
+    return InferenceAdapter(model_path, architecture)

backend/core/metrics.py

@@ -0,0 +1,80 @@
+"""
+Archivo: metrics.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Convierte el resultado crudo de la detección (lista de cajas) en los indicadores
+agronómicos de negocio: conteo de plantas, densidad por hectárea, número de
+malezas, porcentaje de fallas de siembra y confianza media. Se mantiene aislado
+de la inferencia para poder probarlo de forma determinista.
+
+Acciones Principales:
+    - Calcula las métricas de negocio a partir de una lista de detecciones.
+
+Estructura Interna:
+    - `compute_metrics`: agrega las detecciones en métricas de negocio.
+    - `_estimate_failures`: heurística de fallas de siembra (placeholder del MVP).
+
+Entradas / Dependencias:
+    - `backend.core.detection.Detection`.
+
+Salidas / Efectos:
+    - Ninguno; función pura que retorna un diccionario de métricas.
+
+Ejemplo de Integración:
+    from backend.core.metrics import compute_metrics
+    metricas = compute_metrics(detecciones, area_ha=1.0)
+"""
+
+from __future__ import annotations
+
+from backend.core.detection import CLASS_PLANT, CLASS_WEED, Detection
+
+SQUARE_METERS_PER_HECTARE: int = 10_000
+
+
+def _estimate_failures(plant_count: int) -> float:
+    """
+    Estima el porcentaje de fallas de siembra (huecos en hilera).
+
+    Nota: en el MVP devuelve 0.0 como marcador. La heurística real (detección de
+    huecos en hileras) se incorpora cuando el modelo de conteo esté publicado y se
+    disponga de la disposición espacial de las plantas.
+
+    Args:
+        plant_count (int): Número de plantas detectadas.
+
+    Returns:
+        float: Porcentaje estimado de fallas de siembra en el rango [0, 100].
+    """
+    return 0.0
+
+
+def compute_metrics(detections: list[Detection], area_ha: float) -> dict[str, float]:
+    """
+    Agrega una lista de detecciones en los indicadores agronómicos de negocio.
+
+    Args:
+        detections (list[Detection]): Detecciones producidas por el modelo.
+        area_ha (float): Área del lote en hectáreas, usada para la densidad.
+
+    Returns:
+        dict[str, float]: Diccionario con las claves 'count', 'weeds', 'density',
+        'failures' y 'confidence'.
+    """
+    plant_count = sum(1 for detection in detections if detection.class_id == CLASS_PLANT)
+    weed_count = sum(1 for detection in detections if detection.class_id == CLASS_WEED)
+
+    confidences = [detection.confidence for detection in detections]
+    mean_confidence = round(sum(confidences) / len(confidences), 2) if confidences else 0.0
+
+    density = round(plant_count / area_ha, 1) if area_ha > 0 else 0.0
+
+    return {
+        "count": plant_count,
+        "weeds": weed_count,
+        "density": density,
+        "failures": _estimate_failures(plant_count),
+        "confidence": mean_confidence,
+    }

backend/main.py

@@ -0,0 +1,102 @@
+"""
+Archivo: main.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Punto de entrada del backend FastAPI del MVP. Configura CORS, carga el modelo de
+conteo en el `lifespan` (si está habilitado y disponible) y monta las rutas del
+MVP. Soporta el modo **standby**: si el conteo está deshabilitado o el modelo no
+existe, el backend arranca igual y el endpoint de conteo responde 503.
+
+Acciones Principales:
+    - Crea la app FastAPI, configura CORS y carga (opcionalmente) el modelo.
+
+Estructura Interna:
+    - `lifespan`: gestiona la carga/descarga del adaptador de inferencia.
+    - `create_app`: construye y configura la instancia de FastAPI.
+    - `app`: instancia ASGI servida por uvicorn.
+
+Entradas / Dependencias:
+    - `fastapi`, `backend.config`, `backend.core.inference`, `backend.api.count`.
+
+Salidas / Efectos:
+    - Expone un servicio ASGI en el puerto configurado.
+
+Ejecución:
+    uv run uvicorn backend.main:app --host 0.0.0.0 --port 8000
+
+Ejemplo de Uso:
+    uv run uvicorn backend.main:app --reload --port 8000
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from backend.api.count import router as count_router
+from backend.config import get_settings
+from backend.core.inference import ModelNotAvailableError, load_adapter
+
+_logger = logging.getLogger("agrovision.backend")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """
+    Carga el adaptador de inferencia al iniciar y lo libera al terminar.
+
+    En modo standby (conteo deshabilitado o modelo ausente) deja el adaptador en
+    None y registra el motivo, permitiendo que el backend arranque de todas formas.
+
+    Args:
+        app (FastAPI): Instancia de la aplicación cuyo estado se inicializa.
+
+    Yields:
+        None: Cede el control mientras la app está en ejecución.
+    """
+    settings = get_settings()
+    app.state.adapter = None
+
+    if settings.counting_enabled:
+        try:
+            app.state.adapter = load_adapter(settings.model_path, settings.model_architecture)
+            _logger.info("Modelo de conteo cargado: %s", settings.model_architecture)
+        except ModelNotAvailableError as error:
+            _logger.warning("Conteo en standby (modelo no disponible): %s", error)
+    else:
+        _logger.info("Conteo en standby (COUNTING_ENABLED=false).")
+
+    yield
+    app.state.adapter = None
+
+
+def create_app() -> FastAPI:
+    """
+    Construye y configura la instancia de FastAPI del MVP.
+
+    Returns:
+        FastAPI: Aplicación con CORS y rutas montadas.
+    """
+    settings = get_settings()
+    app = FastAPI(
+        title="AgroVisión MVP — Backend",
+        version=settings.model_version,
+        lifespan=lifespan,
+    )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=list(settings.allowed_origins),
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    app.include_router(count_router)
+    return app
+
+
+app = create_app()

backend/schemas.py

@@ -0,0 +1,71 @@
+"""
+Archivo: schemas.py
+Fecha de modificación: 03/06/2026
+Autor: Equipo AgroVisión
+
+Descripción:
+Define los contratos de datos (Pydantic) que entran y salen de la API del MVP.
+Validan los límites del sistema, documentan el acuerdo UI↔backend y rechazan
+payloads inválidos antes de que contaminen la lógica.
+
+Acciones Principales:
+    - Declara los esquemas de respuesta del healthcheck y del conteo.
+
+Estructura Interna:
+    - `StatusResponse`: respuesta del endpoint de salud.
+    - `CountResponse`: respuesta del endpoint de conteo.
+
+Entradas / Dependencias:
+    - `pydantic`.
+
+Salidas / Efectos:
+    - Ninguno; expone modelos de validación/serialización.
+
+Ejemplo de Integración:
+    from backend.schemas import CountResponse
+    respuesta = CountResponse(count=124, density=72400, weeds=12,
+                              failures=1.2, confidence=0.91, overlay_b64="...")
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class StatusResponse(BaseModel):
+    """Respuesta del healthcheck del backend, incluye el estado del módulo de conteo."""
+
+    status: str = Field(default="ok")
+    model: str = Field(description="Nombre de marca del modelo de conteo")
+    version: str = Field(description="Versión semántica del modelo predeterminado")
+    counting_enabled: bool = Field(description="Indica si el conteo está activo o en standby")
+
+
+class CountResponse(BaseModel):
+    """Resultado del conteo de plantas sobre un ortomosaico RGB."""
+
+    count: int = Field(ge=0, description="Total de plantas/arbustos detectados")
+    density: float = Field(ge=0, description="Plantas por hectárea")
+    weeds: int = Field(ge=0, description="Número de malezas detectadas")
+    failures: float = Field(ge=0, le=100, description="Porcentaje de fallas de siembra")
+    confidence: float = Field(ge=0, le=1, description="Confianza media de las detecciones")
+    overlay_b64: str = Field(description="Imagen anotada (PNG) codificada en base64")
+
+    @field_validator("confidence")
+    @classmethod
+    def _validar_confianza(cls, value: float) -> float:
+        """
+        Verifica que la confianza media esté estrictamente en el rango [0, 1].
+
+        Args:
+            value (float): Confianza media propuesta.
+
+        Returns:
+            float: La misma confianza si es válida.
+
+        Raises:
+            ValueError: Si la confianza queda fuera del rango [0, 1].
+        """
+        if not 0.0 <= value <= 1.0:
+            raise ValueError("La confianza debe estar en el rango [0, 1].")
+        return value