UPDATE

rag/services/water_need_prediction.py

@@ -14,6 +14,7 @@ from rag.chat import (
     build_rag_context,
 )
 from rag.config import RAGConfig, get_service_config, load_rag_config
+from rag.failure_contract import RAGServiceError
 
 logger = logging.getLogger(__name__)
 
@@ -38,18 +39,47 @@ def _clean_json(raw: str) -> dict[str, Any]:
             cleaned = cleaned[4:]
         cleaned = cleaned.strip()
     if not cleaned:
-        return {}
+        raise RAGServiceError(
+            error_code="empty_response",
+            message="Water need prediction LLM response was empty.",
+            source="llm",
+            retriable=True,
+            details={"service_id": SERVICE_ID},
+            http_status=502,
+        )
     try:
-        return json.loads(cleaned)
-    except (json.JSONDecodeError, ValueError):
+        parsed = json.loads(cleaned)
+    except (json.JSONDecodeError, ValueError) as exc:
         logger.warning("Invalid JSON returned by water_need_prediction LLM: %s", cleaned[:500])
-        return {}
+        raise RAGServiceError(
+            error_code="invalid_json",
+            message="Water need prediction LLM response was not valid JSON.",
+            source="llm",
+            retriable=True,
+            details={"service_id": SERVICE_ID},
+            http_status=502,
+        ) from exc
+    if not isinstance(parsed, dict):
+        raise RAGServiceError(
+            error_code="invalid_schema",
+            message="Water need prediction LLM response root must be a JSON object.",
+            source="llm",
+            details={"service_id": SERVICE_ID},
+            http_status=502,
+        )
+    return parsed
 
 
 def _load_farm_or_error(farm_uuid: str) -> dict[str, Any]:
     farm_details = get_farm_details(farm_uuid)
     if farm_details is None:
-        raise ValueError("farm_uuid نامعتبر است یا اطلاعات مزرعه پیدا نشد.")
+        raise RAGServiceError(
+            error_code="farm_not_found",
+            message="farm_uuid نامعتبر است یا اطلاعات مزرعه پیدا نشد.",
+            source="farm_data",
+            details={"farm_uuid": farm_uuid},
+            http_status=404,
+        )
     return farm_details
 
 
@@ -78,9 +108,12 @@ def _validate_prediction_insight(parsed: dict[str, Any]) -> dict[str, Any]:
     }
     missing = [key for key in required_keys if key not in parsed]
     if missing:
-        raise ValueError(
-            "Water need prediction insight response is missing required fields: "
-            + ", ".join(missing)
+        raise RAGServiceError(
+            error_code="invalid_schema",
+            message="Water need prediction insight response is missing required fields: " + ", ".join(missing),
+            source="llm",
+            details={"missing_fields": missing, "service_id": SERVICE_ID},
+            http_status=502,
         )
     return parsed
 
@@ -154,12 +187,25 @@ def get_water_need_prediction_insight(
         raw = response.choices[0].message.content.strip()
         parsed = _clean_json(raw)
         _complete_audit_log(audit_log, raw)
+    except RAGServiceError as exc:
+        logger.error("Water need prediction insight failed for %s: %s", farm_uuid, exc)
+        _fail_audit_log(audit_log, str(exc))
+        raise
     except Exception as exc:
         logger.error("Water need prediction insight failed for %s: %s", farm_uuid, exc)
         _fail_audit_log(audit_log, str(exc))
-        raise RuntimeError(f"Water need prediction insight failed for farm {farm_uuid}.") from exc
+        raise RAGServiceError(
+            error_code="upstream_failure",
+            message=f"Water need prediction insight failed for farm {farm_uuid}.",
+            source="llm",
+            retriable=True,
+            details={"farm_uuid": farm_uuid, "service_id": SERVICE_ID},
+            http_status=503,
+        ) from exc
 
     parsed = _validate_prediction_insight(parsed)
+    parsed["status"] = "success"
+    parsed["source"] = "llm"
     parsed["farm_uuid"] = farm_uuid
     parsed["raw_response"] = raw
     return parsed