R14-ASQ-E1: qualitative evidence structured-output recovery

core/qualitative_engine.py

@@ -272,37 +272,138 @@ Rules:
 {schema}
 """
 
+    def _qualitative_packet_validation_error(self, data, *, has_user_data):
+        """Return a bounded local validation reason, or an empty string when safe.
+
+        This pre-freeze validator mirrors the existing fatal packet gates so a
+        malformed/incomplete model response can be regenerated once before any
+        study fact or quotation becomes authoritative. It never repairs JSON or
+        mutates model output.
+        """
+        if not isinstance(data, dict):
+            return "packet_not_json_object"
+
+        facts = data.get("study_facts") or {}
+        evidence = data.get("evidence") or data.get("quotes") or []
+        if not isinstance(facts, dict) or not isinstance(evidence, list):
+            return "invalid_packet_schema"
+
+        for key in ("participant_count", "interview_count"):
+            value = facts.get(key)
+            if value is not None and (not isinstance(value, int) or value <= 0):
+                return f"invalid_{key}"
+
+        seen_quotes = set()
+        theme_keys = set()
+        retained = 0
+        has_deviant = False
+        for item in evidence[:15]:
+            if not isinstance(item, dict):
+                continue
+            quote = self._clean_cell(item.get("quote"), "").replace('"', "'")
+            normalized_quote = re.sub(r"\s+", " ", quote).strip().casefold()
+            if not quote or len(quote.split()) < 4 or normalized_quote in seen_quotes:
+                continue
+            seen_quotes.add(normalized_quote)
+            retained += 1
+            theme = self._clean_cell(item.get("theme"), "Emergent pattern")
+            theme_keys.add(re.sub(r"\s+", " ", theme).strip().casefold())
+            if str(item.get("evidence_role") or "typical").strip().lower() == "deviant":
+                has_deviant = True
+
+        validation = APP_CONFIG.get("manuscript_validation", {})
+        minimum_themes = int(validation.get("minimum_qualitative_themes", 3))
+        minimum_quotes = int(validation.get("minimum_qualitative_quotes", 8))
+        if len(theme_keys) < minimum_themes or retained < minimum_quotes:
+            return f"incomplete_packet_themes_{len(theme_keys)}_quotes_{retained}"
+        if not has_user_data and not has_deviant:
+            return "generated_packet_missing_deviant_evidence"
+        return ""
+
+    def _generate_qualitative_packet(self, topic, keywords, raw_interviews, *, has_user_data):
+        """Generate and validate one evidence packet with one bounded fresh retry."""
+        system_prompt = (
+            "You are a rigorous qualitative research analyst. "
+            "Evidence fidelity has priority over narrative completeness."
+        )
+        base_prompt = self._build_request(topic, keywords, raw_interviews)
+        last_reason = "packet_not_json_object"
+
+        for local_attempt in range(2):
+            # API/auth/balance/cancellation/transport failures remain owned by
+            # the model client and are deliberately not converted into local
+            # content retries here. Only a completed but locally invalid packet
+            # reaches the second attempt.
+            if local_attempt == 0:
+                response = "".join(
+                    str(chunk or "")
+                    for chunk in self.agent.stream_deepseek(
+                        system_prompt,
+                        base_prompt,
+                        model_role="reasoning",
+                        thinking=True,
+                        allow_fallback=False,
+                    )
+                )
+            else:
+                retry_prompt = base_prompt + (
+                    "\n\nLOCAL VALIDATION RETRY: The previous completed response failed local "
+                    "JSON/schema/content validation. Generate a fresh complete qualitative evidence "
+                    "packet from the ORIGINAL inputs above. Do not repair, continue, quote, or rely on "
+                    "the previous response. Return exactly one complete JSON object matching the required "
+                    "schema, with no Markdown or explanatory prose. Preserve every evidence-fidelity rule "
+                    "from the original request, including verbatim quotation requirements when user material "
+                    "was supplied."
+                )
+                response = self.agent.call_deepseek(
+                    system_prompt,
+                    retry_prompt,
+                    max_tokens=8000,
+                    temp=0.0,
+                    model_role="reasoning",
+                    thinking=False,
+                    allow_fallback=False,
+                    response_format={"type": "json_object"},
+                )
+
+            response = re.sub(
+                r"<think>.*?</think>",
+                "",
+                str(response or ""),
+                flags=re.DOTALL,
+            ).strip()
+            data = self.agent._extract_json_from_text(response)
+            last_reason = self._qualitative_packet_validation_error(
+                data,
+                has_user_data=has_user_data,
+            )
+            if not last_reason:
+                return data
+            if local_attempt == 0:
+                logging.warning(
+                    "Qualitative evidence structured-output local retry | attempt=1/2 | reason=%s",
+                    last_reason,
+                )
+
+        if last_reason == "packet_not_json_object":
+            raise RuntimeError("Qualitative evidence packet could not be parsed safely.")
+        if last_reason == "invalid_packet_schema":
+            raise RuntimeError("Qualitative evidence packet has an invalid schema.")
+        raise RuntimeError(
+            "Qualitative evidence packet failed local validation after one bounded regeneration: "
+            f"{last_reason}."
+        )
+
     def resolve_qualitative_data(self, topic, keywords, raw_interviews=""):
         has_user_data = bool(raw_interviews and len(raw_interviews) > 100)
-        prompt = self._build_request(topic, keywords, raw_interviews)
         # R3-Free engine code is headless. Streamlit rendering belongs to app.py;
         # this method only produces frozen evidence + metadata.
-        response = "".join(
-            str(chunk or "")
-            for chunk in self.agent.stream_deepseek(
-                "You are a rigorous qualitative research analyst. Evidence fidelity has priority over narrative completeness.",
-                prompt,
-                model_role="reasoning",
-                thinking=True,
-                allow_fallback=False,
-            )
+        data = self._generate_qualitative_packet(
+            topic, keywords, raw_interviews, has_user_data=has_user_data
         )
 
-        response = re.sub(
-            r"<think>.*?</think>",
-            "",
-            response,
-            flags=re.DOTALL,
-        ).strip()
-        data = self.agent._extract_json_from_text(response)
-
-        if not isinstance(data, dict):
-            raise RuntimeError("Qualitative evidence packet could not be parsed safely.")
-
         facts = data.get("study_facts") or {}
         evidence = data.get("evidence") or data.get("quotes") or []
-        if not isinstance(facts, dict) or not isinstance(evidence, list):
-            raise RuntimeError("Qualitative evidence packet has an invalid schema.")
 
         data_sources = facts.get("data_sources") or ["Not specified"]
         if not isinstance(data_sources, list):