# -*- coding: utf-8 -*- """Qualitative evidence preparation for SmartPaper's ASQ-oriented track.""" from __future__ import annotations import hashlib import logging import re from config import APP_CONFIG class QualitativeEngine: ALLOWED_ANALYTIC_DESIGNS = { "Process analysis", "Comparative case analysis", "Grounded theory", "Gioia-style inductive coding", "Longitudinal qualitative analysis", "Iterative thematic/process analysis", } def __init__(self, agent): self.agent = agent @staticmethod def _clean_cell(value, default="Not specified"): cleaned = str(value or default).replace("\n", " ").strip() return cleaned or default @classmethod def _normalize_analytic_design(cls, value): cleaned = re.sub(r"\s+", " ", str(value or "")).strip() if not cleaned: return "Iterative thematic/process analysis" lookup = {item.lower(): item for item in cls.ALLOWED_ANALYTIC_DESIGNS} return lookup.get(cleaned.lower(), "Iterative thematic/process analysis") @classmethod def _normalize_string_list(cls, values): if values is None: return [] if not isinstance(values, list): values = [values] out = [] for value in values: cleaned = cls._clean_cell(value, "") if cleaned and cleaned.casefold() != "not specified" and cleaned not in out: out.append(cleaned) return out @classmethod def _normalize_data_source_roles(cls, values): rows = [] for item in values or []: if not isinstance(item, dict): continue actor_role = cls._clean_cell(item.get("actor_role"), "") data_source = cls._clean_cell(item.get("data_source"), "") count = item.get("count") if not actor_role or not data_source: continue if count is not None and (not isinstance(count, int) or count <= 0): continue row = {"actor_role": actor_role, "data_source": data_source, "count": count} if row not in rows: rows.append(row) return rows @classmethod def build_scoped_evidence_md( cls, metadata, *, include_themes=True, theme_titles=None, assigned_evidence=None, include_quotes=False, include_quote_ids=True, ): """Render the minimum qualitative evidence needed by one drafting unit. Study facts/theme summaries are an internal empirical channel. Verbatim quotations are a separate channel and are exposed only to their owning Findings unit (or the final appendix when explicitly requested by the caller). This prevents a quotation visible in one unit from being opportunistically reused elsewhere and keeps external literature from becoming evidence for this study's own facts. """ metadata = metadata or {} facts = metadata.get("study_facts") or {} sources = facts.get("data_sources") or ["Not specified"] if not isinstance(sources, list): sources = [sources] clean_sources = [cls._clean_cell(item) for item in sources] participants = facts.get("participant_count") interviews = facts.get("interview_count") analytic_design = cls._normalize_analytic_design( facts.get("analytic_design") or facts.get("analysis_method") ) analytic_logic = cls._clean_cell( facts.get("analytic_logic"), "Iteratively compare empirical observations to refine a process/mechanism explanation.", ) temporal_structure = cls._clean_cell(facts.get("temporal_structure")) case_structure = cls._clean_cell(facts.get("case_structure")) setting = cls._clean_cell(facts.get("research_setting")) data_source_roles = cls._normalize_data_source_roles(facts.get("data_source_roles") or []) trustworthiness = cls._normalize_string_list(facts.get("trustworthiness_procedures")) ethics = cls._normalize_string_list(facts.get("ethics_procedures")) reflexivity = cls._normalize_string_list(facts.get("reflexivity_procedures")) lines = [ "### Frozen Qualitative Study Facts", "| Field | Frozen value |", "| :--- | :--- |", f"| Research setting | {setting} |", f"| Data sources | {', '.join(clean_sources)} |", f"| Participants | {participants if participants is not None else 'Not specified'} |", f"| Interviews | {interviews if interviews is not None else 'Not specified'} |", f"| Analytic design | {analytic_design} |", f"| Analytic logic | {analytic_logic} |", f"| Temporal structure | {temporal_structure} |", f"| Case structure | {case_structure} |", f"| Trustworthiness procedures | {'; '.join(trustworthiness) if trustworthiness else 'Not specified'} |", f"| Ethics procedures | {'; '.join(ethics) if ethics else 'Not specified'} |", f"| Reflexivity procedures | {'; '.join(reflexivity) if reflexivity else 'Not specified'} |", ] if data_source_roles: lines.extend([ "", "### Frozen Actor / Data-Source Relations", "| Actor role | Data source | Count |", "| :--- | :--- | :--- |", ]) lines.extend( f"| {row['actor_role']} | {row['data_source']} | {row['count'] if row['count'] is not None else 'Not specified'} |" for row in data_source_roles ) lines.extend([ "", "[QUALITATIVE EVIDENCE CHANNELS]", "1. STUDY FACTS and THEME SUMMARIES below are this study's internal empirical evidence. Never attach an external [CITE-XX] tag to a sentence merely because it reports or interprets these frozen facts.", "2. External literature may support only prior-theory, prior-evidence, or methodological-rationale claims. Keep those claims in distinct sentences from this study's setting, sample, data, events, quotations, and findings.", "3. ASSIGNED QUOTATIONS, when present, are analysis-only verbatim evidence owned by the current stable theme. Do not reproduce the verbatim wording or any internal quotation identifier in generated prose; the Executor renders frozen quotations deterministically after narrative QA.", "4. Study-owned trustworthiness, ethics, reflexivity, recruitment, consent, observation, or audit procedures may be stated as performed only when explicitly frozen above. Never convert general methodological best practice into a fact about this study.", ]) allowed_theme_titles = None if theme_titles: allowed_theme_titles = { re.sub(r"\s+", " ", str(item or "")).strip().casefold() for item in theme_titles if str(item or "").strip() } if include_themes: theme_rows = [] for theme in metadata.get("themes") or []: if not isinstance(theme, dict): continue title = cls._clean_cell(theme.get("title"), "Emergent pattern") if allowed_theme_titles is not None and title.casefold() not in allowed_theme_titles: continue concepts = ", ".join( cls._clean_cell(item, "") for item in (theme.get("concepts") or []) if cls._clean_cell(item, "") ) or "Not specified" stages = ", ".join( cls._clean_cell(item, "") for item in (theme.get("stages") or []) if cls._clean_cell(item, "") and cls._clean_cell(item, "") != "Not specified" ) or "Not specified" deviant = "yes" if theme.get("has_deviant_evidence") else "no" theme_rows.append((title, concepts, stages, deviant)) if theme_rows: lines.extend([ "", "### Frozen Qualitative Theme Summary", "| Higher-order Theme | Empirical Concepts | Process Stages | Deviant/Boundary Evidence Present |", "| :--- | :--- | :--- | :--- |", ]) lines.extend( f"| {title} | {concepts} | {stages} | {deviant} |" for title, concepts, stages, deviant in theme_rows ) if include_quotes: evidence_items = assigned_evidence if evidence_items is None: evidence_items = metadata.get("evidence") or [] quote_rows = [] for item in evidence_items or []: if not isinstance(item, dict): continue tag = cls._clean_cell(item.get("tag"), "") quote = cls._clean_cell(item.get("quote"), "").replace('"', "'") if not tag or not quote: continue stage = cls._clean_cell(item.get("stage")) case_label = cls._clean_cell(item.get("case_label")) evidence_role = str(item.get("evidence_role") or "typical").strip().lower() if evidence_role not in {"typical", "deviant"}: evidence_role = "typical" quote_rows.append((tag, stage, case_label, evidence_role, quote)) if quote_rows: lines.extend(["", "### Assigned Qualitative Quotations"]) if include_quote_ids: lines.extend([ "| Tag | Process Stage | Case/Actor | Evidence Role | Verbatim Quote |", "| :--- | :--- | :--- | :--- | :--- |", ]) lines.extend( f'| {tag} | {stage} | {case_label} | {role} | "{quote}" |' for tag, stage, case_label, role, quote in quote_rows ) else: lines.extend([ "| Process Stage | Case/Actor | Evidence Role | Verbatim Quote |", "| :--- | :--- | :--- | :--- |", ]) lines.extend( f'| {stage} | {case_label} | {role} | "{quote}" |' for _tag, stage, case_label, role, quote in quote_rows ) return "\n".join(lines).strip() @classmethod def build_appendix_evidence_md(cls, metadata): """Render the reader-facing qualitative evidence appendix deterministically. Internal QUOTE identifiers are deliberately omitted. The same frozen quotation literals are reused by the translation ledger, so Findings and Appendix share one target-language rendering per quote. """ metadata = metadata or {} def cell(value, default="Not specified"): return cls._clean_cell(value, default).replace("|", r"\|") lines = [ "| Higher-order Theme | Empirical Concept | Process Stage | Case/Actor | Evidence Role | Representative Quote |", "| :--- | :--- | :--- | :--- | :--- | :--- |", ] for item in metadata.get("evidence") or []: if not isinstance(item, dict): continue quote = cls._clean_cell(item.get("quote"), "").replace('"', "'") if not quote: continue lines.append( "| {theme} | {concept} | {stage} | {case_label} | {role} | \"{quote}\" |".format( theme=cell(item.get("theme"), "Emergent pattern"), concept=cell(item.get("concept"), "Empirical observation"), stage=cell(item.get("stage")), case_label=cell(item.get("case_label")), role=cell(str(item.get("evidence_role") or "typical").strip().lower(), "typical"), quote=quote.replace("|", r"\|"), ) ) return "\n".join(lines).strip() def _build_request(self, topic, keywords, raw_interviews): schema = """Return ONLY one valid JSON object with this schema: { "study_facts": { "research_setting": "string or Not specified", "data_sources": ["string"], "data_source_roles": [{"actor_role":"string", "data_source":"string", "count":integer or null}], "participant_count": integer or null, "interview_count": integer or null, "trustworthiness_procedures": ["explicitly supported/frozen procedure"], "ethics_procedures": ["explicitly supported/frozen procedure"], "reflexivity_procedures": ["explicitly supported/frozen procedure"], "analytic_design": "one allowed design", "analytic_logic": "one concise sentence", "temporal_structure": "string or Not specified", "case_structure": "string or Not specified" }, "evidence": [ { "theme": "higher-order pattern/theme", "concept": "empirical concept", "quote": "verbatim quotation", "stage": "temporal/process stage or Not specified", "case_label": "generic case/actor label or Not specified", "evidence_role": "typical or deviant" } ] } Allowed analytic designs: Process analysis; Comparative case analysis; Grounded theory; Gioia-style inductive coding; Longitudinal qualitative analysis; Iterative thematic/process analysis. """ if raw_interviews and len(raw_interviews) > 100: return f"""Topic: {topic} Keywords: {keywords} Analyze the supplied interview or field material for an ASQ-oriented qualitative manuscript. Rules: 1. Treat the supplied material as the only source of study facts. Use null, empty arrays, or "Not specified" for any setting, sample, count, date, case, actor/data-source relation, trustworthiness procedure, ethics procedure, reflexivity procedure, or data source not explicitly supported by the material. 2. Extract 8-15 representative quotations VERBATIM. Never repair, paraphrase, translate, combine, or invent a quotation. 3. Choose the analytic design that best fits the actual material. Do NOT default to Gioia. Use Gioia-style coding only if the evidence structure genuinely warrants it. 4. Organize evidence around a central organizational puzzle and, when the material supports it, preserve temporal stages, actor/case contrasts, process transitions, and at least one deviant or boundary observation. 5. Do not manufacture a longitudinal sequence when the material is cross-sectional, and do not manufacture multiple cases when only one is present. 6. Freeze actor-to-data-source relations explicitly in data_source_roles whenever the material supports them (for example extension officers -> interviews; farmers -> focus groups). Never infer that an actor participated in a data source not supported by the material. The study_facts object and quotations will become the frozen single source of truth for the entire manuscript. {schema} {raw_interviews[:30000]} """ return f"""Topic: {topic} Keywords: {keywords} Construct one internally coherent qualitative evidence packet for a complete ASQ-oriented manuscript because no interview material was supplied. Rules: 1. Choose one generic organizational research setting directly relevant to the topic and keep it fixed. Do not name a real organization, institution, or identifiable person. 2. Freeze one participant count, interview count, data-source set, actor-to-data-source relation map, analytic design, temporal/case structure, and analytic logic. Keep them internally consistent. Every actor/data-source relationship later stated in the paper must be represented in data_source_roles. 3. Produce exactly 12 natural representative quotations distributed across at least three higher-order themes. Quotations must sound like distinct participants rather than repeated template variants. 4. Choose the analytic design that best fits the constructed evidence; do NOT default to Gioia. Use process, comparative-case, grounded-theory, longitudinal, or Gioia-style logic only when the packet supports it. 5. Include at least one clearly labelled deviant/boundary observation so the eventual theory is not built only from confirming examples. 6. The evidence should support a process/mechanism explanation, not merely descriptive topic categories. 7. Freeze concise, internally coherent trustworthiness, ethics, and reflexivity procedures in their typed arrays so later Methods prose has an explicit study-owned source. Do not name a real ethics board, institution, vendor, approval number, or identifiable organization. 8. The study_facts object and evidence packet will become the frozen single source of truth for the entire manuscript. 9. Avoid decorative language, generic AI phrasing, and repetitive quotation patterns. {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}" raw_relations = facts.get("data_source_roles") or [] if raw_relations and not isinstance(raw_relations, list): return "invalid_data_source_roles" declared_sources = [ re.sub(r"\s+", " ", str(item or "")).strip().casefold() for item in (facts.get("data_sources") or []) if str(item or "").strip() ] for item in raw_relations: if not isinstance(item, dict) or not str(item.get("actor_role") or "").strip() or not str(item.get("data_source") or "").strip(): return "invalid_data_source_role_item" count = item.get("count") if count is not None and (not isinstance(count, int) or count <= 0): return "invalid_data_source_role_count" relation_source = re.sub(r"\s+", " ", str(item.get("data_source") or "")).strip().casefold() if declared_sources and not any( relation_source == source or relation_source in source or source in relation_source for source in declared_sources ): return "data_source_role_not_in_declared_sources" for key in ("trustworthiness_procedures", "ethics_procedures", "reflexivity_procedures"): value = facts.get(key) or [] if not isinstance(value, list): return f"invalid_{key}" if any(not str(item or "").strip() for item in value): return f"invalid_{key}" if not has_user_data: if not raw_relations: return "generated_packet_missing_data_source_roles" for key in ("trustworthiness_procedures", "ethics_procedures", "reflexivity_procedures"): if not (facts.get(key) or []): return f"generated_packet_missing_{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 = self.agent.call_deepseek( system_prompt + "\n\nDIRECT OUTPUT MODE: Produce the complete evidence packet directly without extended hidden reasoning.", base_prompt, max_tokens=8000, temp=0.0, model_role="reasoning", thinking=False, allow_fallback=False, response_format={"type": "json_object"}, ) 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".*?", "", 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) # R3-Free engine code is headless. Streamlit rendering belongs to app.py; # this method only produces frozen evidence + metadata. data = self._generate_qualitative_packet( topic, keywords, raw_interviews, has_user_data=has_user_data ) facts = data.get("study_facts") or {} evidence = data.get("evidence") or data.get("quotes") or [] data_sources = facts.get("data_sources") or ["Not specified"] if not isinstance(data_sources, list): data_sources = [data_sources] setting = self._clean_cell(facts.get("research_setting")) clean_sources = [self._clean_cell(item) for item in data_sources] sources = ", ".join(clean_sources) data_source_roles = self._normalize_data_source_roles(facts.get("data_source_roles") or []) trustworthiness = self._normalize_string_list(facts.get("trustworthiness_procedures")) ethics = self._normalize_string_list(facts.get("ethics_procedures")) reflexivity = self._normalize_string_list(facts.get("reflexivity_procedures")) participants = facts.get("participant_count") interviews = facts.get("interview_count") analytic_design = self._normalize_analytic_design( facts.get("analytic_design") or facts.get("analysis_method") ) analytic_logic = self._clean_cell( facts.get("analytic_logic"), "Iteratively compare empirical observations to refine a process/mechanism explanation.", ) temporal_structure = self._clean_cell(facts.get("temporal_structure")) case_structure = self._clean_cell(facts.get("case_structure")) for value, label in ((participants, "participant_count"), (interviews, "interview_count")): if value is not None and (not isinstance(value, int) or value <= 0): raise RuntimeError(f"Qualitative evidence packet has invalid {label}.") md = ( "### Frozen Qualitative Study Design\n" "| Field | Frozen value |\n" "| :--- | :--- |\n" f"| Research setting | {setting} |\n" f"| Data sources | {sources} |\n" f"| Participants | {participants if participants is not None else 'Not specified'} |\n" f"| Interviews | {interviews if interviews is not None else 'Not specified'} |\n" f"| Analytic design | {analytic_design} |\n" f"| Analytic logic | {analytic_logic} |\n" f"| Temporal structure | {temporal_structure} |\n" f"| Case structure | {case_structure} |\n" f"| Trustworthiness procedures | {'; '.join(trustworthiness) if trustworthiness else 'Not specified'} |\n" f"| Ethics procedures | {'; '.join(ethics) if ethics else 'Not specified'} |\n" f"| Reflexivity procedures | {'; '.join(reflexivity) if reflexivity else 'Not specified'} |\n\n" "[QUALITATIVE EVIDENCE CONTRACT]\n" "Use the frozen design summary and tagged evidence below as the only source of this study's empirical facts. " "Do not change the setting, sample, interview count, data sources, actor/data-source relations, analytic design, temporal structure, cases, procedures, or quotations. " "Do not infer an event sequence, actor comparison, trustworthiness/ethics/reflexivity procedure, negative case, or quotation that is absent from this packet.\n\n" "### Table: Qualitative Evidence Structure\n" "| Higher-order Theme | Empirical Concept | Process Stage | Case/Actor | Evidence Role | Representative Quote |\n" "| :--- | :--- | :--- | :--- | :--- | :--- |\n" ) if data_source_roles: md += ( "### Frozen Actor / Data-Source Relations\n" "| Actor role | Data source | Count |\n" "| :--- | :--- | :--- |\n" ) for row in data_source_roles: md += f"| {row['actor_role']} | {row['data_source']} | {row['count'] if row['count'] is not None else 'Not specified'} |\n" md += "\n" clean_evidence = [] seen_quotes = set() for item in evidence[:15]: if not isinstance(item, dict): continue quote = self._clean_cell(item.get("quote"), "").replace('"', "'") concept = self._clean_cell(item.get("concept"), "Empirical observation") theme = self._clean_cell(item.get("theme"), "Emergent pattern") stage = self._clean_cell(item.get("stage")) case_label = self._clean_cell(item.get("case_label")) evidence_role = str(item.get("evidence_role") or "typical").strip().lower() if evidence_role not in {"typical", "deviant"}: evidence_role = "typical" normalized_quote = re.sub(r"\s+", " ", quote).strip().lower() if not quote or len(quote.split()) < 4 or normalized_quote in seen_quotes: continue seen_quotes.add(normalized_quote) tag = f"QUOTE-{len(clean_evidence) + 1:02d}" md += ( f'| {theme} | {concept} | {stage} | {case_label} | {evidence_role} | ' f'"{quote}" [{tag}] |\n' ) clean_evidence.append( { "theme": theme, "concept": concept, "quote": quote, "quote_hash": hashlib.sha256(re.sub(r"\s+", " ", quote).strip().encode("utf-8")).hexdigest(), "tag": tag, "stage": stage, "case_label": case_label, "evidence_role": evidence_role, } ) theme_map = {} theme_ids = {} for item in clean_evidence: theme_key = re.sub(r"\s+", " ", item["theme"]).strip().casefold() theme_id = theme_ids.setdefault(theme_key, f"THEME-{len(theme_ids) + 1:02d}") item["theme_id"] = theme_id theme_entry = theme_map.setdefault( item["theme"], { "theme_id": theme_id, "title": item["theme"], "concepts": [], "evidence": [], "stages": [], "has_deviant_evidence": False, }, ) if item["concept"] not in theme_entry["concepts"]: theme_entry["concepts"].append(item["concept"]) if item["stage"] != "Not specified" and item["stage"] not in theme_entry["stages"]: theme_entry["stages"].append(item["stage"]) if item["evidence_role"] == "deviant": theme_entry["has_deviant_evidence"] = True theme_entry["evidence"].append( { "theme_id": item["theme_id"], "tag": item["tag"], "quote": item["quote"], "quote_hash": item["quote_hash"], "stage": item["stage"], "case_label": item["case_label"], "evidence_role": item["evidence_role"], } ) themes = list(theme_map.values()) 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(themes) < minimum_themes or len(clean_evidence) < minimum_quotes: raise RuntimeError( "Qualitative evidence packet is incomplete: " f"themes={len(themes)}, quotes={len(clean_evidence)}; " f"required themes>={minimum_themes}, quotes>={minimum_quotes}." ) if not has_user_data and not any(item["evidence_role"] == "deviant" for item in clean_evidence): raise RuntimeError("Generated qualitative evidence packet lacks a deviant/boundary observation.") metadata = { "mode": "qualitative", "source_type": ( "user_provided" if has_user_data else "system_generated" ), "disclosure_required": not has_user_data, "study_facts": { "research_setting": setting, "data_sources": clean_sources, "data_source_roles": data_source_roles, "participant_count": participants, "interview_count": interviews, "trustworthiness_procedures": trustworthiness, "ethics_procedures": ethics, "reflexivity_procedures": reflexivity, "analytic_design": analytic_design, "analysis_method": analytic_design, "analytic_logic": analytic_logic, "temporal_structure": temporal_structure, "case_structure": case_structure, }, "evidence_count": len(clean_evidence), "generation_parameters": { "analytic_design": analytic_design, "requested_quote_count_when_generated": 12, "maximum_retained_quotes": 15, "minimum_themes": minimum_themes, "minimum_quotes": minimum_quotes, "requires_generated_deviant_evidence": not has_user_data, "consistency_constraints": [ "one frozen research setting", "one frozen participant count", "one frozen interview count", "one frozen data-source set", "one frozen analytic design", "no unsupported temporal or case structure", "quotation tags must remain unique", ], }, "evidence": clean_evidence, "themes": themes, } status_message = "✅ 定性研究事实、分析设计与证据结构已冻结。" return md, status_message, metadata def get_qualitative_engine(agent): return QualitativeEngine(agent)