1034 lines
44 KiB
Python
1034 lines
44 KiB
Python
"""Adaptive RAG mixin module."""
|
||
from __future__ import annotations
|
||
|
||
from app.schemas.project_operating_context import ExecutionRecipe, ProjectFitBrief, ProjectOperatingContext
|
||
|
||
from .shared import *
|
||
from .shared_utils import _env_bool
|
||
from .internal_query_context import (
|
||
internal_context_block_reason,
|
||
internal_context_operation_contract,
|
||
internal_context_query_plan,
|
||
)
|
||
|
||
|
||
class AdaptiveRAGAnswerPayloadMixin:
|
||
_SOURCE_PRIORITY_MAP: dict[str, int] = {
|
||
"pmflow": 100,
|
||
"db": 90,
|
||
"graph": 80,
|
||
"doc": 70,
|
||
"mcp_search": 68,
|
||
"url": 65,
|
||
"feishu": 60,
|
||
"system": 10,
|
||
}
|
||
_INTERNAL_SOURCE_TYPES = {"db", "graph", "doc", "pmflow", "feishu"}
|
||
_EXTERNAL_RETRIEVAL_STATUSES = {
|
||
"evidence_found",
|
||
"verifier_blocked",
|
||
"no_relevant_results",
|
||
"retrieval_failed",
|
||
}
|
||
_EXTERNAL_IMPACT_STATUSES = {
|
||
"direct_match",
|
||
"indirect_only",
|
||
"no_direct_impact",
|
||
}
|
||
_ENV_ENABLE_DEFAULT_PLAN_HANDOFF_RENDERING = "PMFLOW_ENABLE_DEFAULT_PLAN_HANDOFF_RENDERING"
|
||
|
||
@staticmethod
|
||
def _normalize_project_operating_context(payload: Optional[dict[str, Any]]) -> dict[str, Any]:
|
||
if not isinstance(payload, dict):
|
||
return {}
|
||
try:
|
||
return ProjectOperatingContext.model_validate(payload).model_dump()
|
||
except Exception:
|
||
return {}
|
||
|
||
@staticmethod
|
||
def _normalize_execution_recipe(payload: Optional[dict[str, Any]]) -> dict[str, Any]:
|
||
if not isinstance(payload, dict):
|
||
return {}
|
||
try:
|
||
return ExecutionRecipe.model_validate(payload).model_dump()
|
||
except Exception:
|
||
return {}
|
||
|
||
@staticmethod
|
||
def _normalize_fit_brief(payload: Optional[dict[str, Any]]) -> dict[str, Any]:
|
||
if not isinstance(payload, dict) or not payload:
|
||
return {}
|
||
try:
|
||
return ProjectFitBrief.model_validate(payload).model_dump()
|
||
except Exception:
|
||
return {}
|
||
|
||
@classmethod
|
||
def _normalize_external_recommendation(cls, payload: Optional[dict[str, Any]]) -> dict[str, Any]:
|
||
if not isinstance(payload, dict) or not payload:
|
||
return {}
|
||
retrieval_status = str(payload.get("retrieval_status") or "").strip().lower()
|
||
impact_status = str(payload.get("impact_status") or "").strip().lower()
|
||
if retrieval_status not in cls._EXTERNAL_RETRIEVAL_STATUSES:
|
||
retrieval_status = "retrieval_failed"
|
||
if impact_status not in cls._EXTERNAL_IMPACT_STATUSES:
|
||
impact_status = "no_direct_impact"
|
||
return {
|
||
"retrieval_status": retrieval_status,
|
||
"impact_status": impact_status,
|
||
"external_summary": str(payload.get("external_summary") or "").strip(),
|
||
"external_impact": str(payload.get("external_impact") or "").strip(),
|
||
"affected_signal_sources": [
|
||
str(item).strip()
|
||
for item in list(payload.get("affected_signal_sources") or [])
|
||
if str(item).strip()
|
||
][:6],
|
||
"external_action": str(payload.get("external_action") or "").strip(),
|
||
}
|
||
|
||
@classmethod
|
||
def _normalize_external_anchor_text(cls, value: Any) -> str:
|
||
raw = str(value or "").strip().lower()
|
||
if not raw:
|
||
return ""
|
||
chars: list[str] = []
|
||
for char in raw:
|
||
if char.isalnum() or "\u4e00" <= char <= "\u9fff":
|
||
chars.append(char)
|
||
return "".join(chars)
|
||
|
||
@classmethod
|
||
def _derive_external_retrieval_status(cls, packet: Optional[dict[str, Any]]) -> str:
|
||
normalized = packet if isinstance(packet, dict) else {}
|
||
explicit = str(normalized.get("retrieval_status") or "").strip().lower()
|
||
if explicit in cls._EXTERNAL_RETRIEVAL_STATUSES:
|
||
return explicit
|
||
|
||
verifier = normalized.get("verifier") if isinstance(normalized.get("verifier"), dict) else {}
|
||
verified_evidence = list(normalized.get("verified_evidence") or [])
|
||
if verified_evidence and bool(verifier.get("ok")):
|
||
return "evidence_found"
|
||
if verified_evidence and not bool(verifier.get("ok")):
|
||
return "verifier_blocked"
|
||
|
||
attempts = [item for item in list(normalized.get("adapter_attempts") or []) if isinstance(item, dict)]
|
||
if any(int(item.get("evidence_count") or 0) > 0 and not bool(item.get("verifier_ok")) for item in attempts):
|
||
return "verifier_blocked"
|
||
statuses = {
|
||
str(item.get("status") or "").strip().lower()
|
||
for item in attempts
|
||
if str(item.get("status") or "").strip()
|
||
}
|
||
if any(status in {"success", "empty"} for status in statuses):
|
||
return "no_relevant_results"
|
||
return "retrieval_failed"
|
||
|
||
@classmethod
|
||
def _collect_fit_brief_signal_source_anchors(cls, fit_brief: Optional[dict[str, Any]]) -> list[str]:
|
||
normalized_fit_brief = cls._normalize_fit_brief(fit_brief)
|
||
anchors: list[str] = []
|
||
for item in list(normalized_fit_brief.get("signal_source_anchors") or []):
|
||
normalized = str(item or "").strip()
|
||
compact = cls._normalize_external_anchor_text(normalized)
|
||
if len(compact) >= 2 and normalized not in anchors:
|
||
anchors.append(normalized)
|
||
return anchors[:6]
|
||
|
||
@classmethod
|
||
def _collect_external_evidence_texts(cls, packet: Optional[dict[str, Any]]) -> list[str]:
|
||
normalized = packet if isinstance(packet, dict) else {}
|
||
texts: list[str] = []
|
||
for item in list(normalized.get("verified_evidence") or []):
|
||
if not isinstance(item, dict):
|
||
continue
|
||
for value in (
|
||
item.get("source_label"),
|
||
item.get("title"),
|
||
item.get("snippet"),
|
||
item.get("target_url"),
|
||
):
|
||
text = str(value or "").strip()
|
||
if text:
|
||
texts.append(text)
|
||
return texts
|
||
|
||
@classmethod
|
||
def _build_external_recommendation(
|
||
cls,
|
||
*,
|
||
external_context_packet: Optional[dict[str, Any]],
|
||
fit_brief: Optional[dict[str, Any]],
|
||
) -> dict[str, Any]:
|
||
packet = dict(external_context_packet or {}) if isinstance(external_context_packet, dict) else {}
|
||
retrieval_status = cls._derive_external_retrieval_status(packet)
|
||
if retrieval_status != "evidence_found":
|
||
return {
|
||
"retrieval_status": retrieval_status,
|
||
"impact_status": "no_direct_impact",
|
||
"external_summary": "",
|
||
"external_impact": "",
|
||
"affected_signal_sources": [],
|
||
"external_action": "",
|
||
}
|
||
|
||
anchors = cls._collect_fit_brief_signal_source_anchors(fit_brief)
|
||
evidence_texts = [cls._normalize_external_anchor_text(item) for item in cls._collect_external_evidence_texts(packet)]
|
||
affected_signal_sources: list[str] = []
|
||
for anchor in anchors:
|
||
compact_anchor = cls._normalize_external_anchor_text(anchor)
|
||
if len(compact_anchor) < 2:
|
||
continue
|
||
if any(compact_anchor in text for text in evidence_texts if text):
|
||
affected_signal_sources.append(anchor)
|
||
|
||
first_evidence = next(
|
||
(item for item in list(packet.get("verified_evidence") or []) if isinstance(item, dict)),
|
||
{},
|
||
)
|
||
external_summary = str(
|
||
first_evidence.get("snippet")
|
||
or first_evidence.get("title")
|
||
or first_evidence.get("source_label")
|
||
or ""
|
||
).strip()[:240]
|
||
if affected_signal_sources:
|
||
return {
|
||
"retrieval_status": "evidence_found",
|
||
"impact_status": "direct_match",
|
||
"external_summary": external_summary,
|
||
"external_impact": f"外部证据已和当前项目对象建立直接映射：{'、'.join(affected_signal_sources[:3])}",
|
||
"affected_signal_sources": affected_signal_sources[:6],
|
||
"external_action": "先做映射验证，再决定是否把这条外部变化正式纳入当前项目计划。",
|
||
}
|
||
|
||
return {
|
||
"retrieval_status": "evidence_found",
|
||
"impact_status": "indirect_only",
|
||
"external_summary": external_summary,
|
||
"external_impact": "当前外部证据只支持背景相关性，暂不能直接映射到当前项目对象。",
|
||
"affected_signal_sources": [],
|
||
"external_action": "先做映射验证，确认这些外部变化是否真的影响当前项目。",
|
||
}
|
||
|
||
def _build_plan_handoff_fields(
|
||
self,
|
||
*,
|
||
execution_recipe: Optional[dict[str, Any]],
|
||
project_operating_context: Optional[dict[str, Any]],
|
||
) -> dict[str, Any]:
|
||
normalized_recipe = self._normalize_execution_recipe(execution_recipe)
|
||
normalized_context = self._normalize_project_operating_context(project_operating_context)
|
||
handoff_mode = str(normalized_recipe.get("plan_handoff_mode") or "").strip().lower() or None
|
||
if (
|
||
handoff_mode == "offer_after_answer"
|
||
and not _env_bool(self._ENV_ENABLE_DEFAULT_PLAN_HANDOFF_RENDERING, True)
|
||
):
|
||
handoff_mode = None
|
||
can_enter_plan = handoff_mode in {"offer_after_answer", "explicit_plan_now"}
|
||
recommended_next_step = None
|
||
if handoff_mode == "offer_after_answer":
|
||
if normalized_context.get("current_project_id") is not None:
|
||
recommended_next_step = "如果你要，我可以基于当前结论进入 plan，继续把需求范围和下一步收清楚。"
|
||
else:
|
||
recommended_next_step = "如果你要，我可以基于当前结论继续进入 plan。"
|
||
elif handoff_mode == "explicit_plan_now":
|
||
recommended_next_step = "当前已命中明确的计划上下文，可以直接进入 plan 继续推进。"
|
||
return {
|
||
"handoff_mode": handoff_mode,
|
||
"can_enter_plan": can_enter_plan,
|
||
"recommended_next_step": recommended_next_step,
|
||
}
|
||
|
||
@staticmethod
|
||
def _safe_source_metadata(raw: Any) -> dict[str, Any]:
|
||
return raw if isinstance(raw, dict) else {}
|
||
|
||
@staticmethod
|
||
def _source_ref_value(value: Any) -> Any:
|
||
if value is None:
|
||
return None
|
||
if isinstance(value, (str, int, float, bool)):
|
||
text = str(value).strip()
|
||
return text or None
|
||
if isinstance(value, list):
|
||
rows = [str(item).strip() for item in value if str(item).strip()]
|
||
return rows or None
|
||
if isinstance(value, dict):
|
||
try:
|
||
return json.loads(json.dumps(value, ensure_ascii=False))
|
||
except Exception:
|
||
return dict(value)
|
||
text = str(value).strip()
|
||
return text or None
|
||
|
||
@staticmethod
|
||
def _isoformat_or_none(value: Any) -> Optional[str]:
|
||
if value is None:
|
||
return None
|
||
if isinstance(value, datetime):
|
||
try:
|
||
return value.isoformat()
|
||
except Exception:
|
||
return None
|
||
text = str(value).strip()
|
||
return text or None
|
||
|
||
def _normalize_source_type(self, value: Any) -> str:
|
||
raw = str(self._source_ref_value(value) or "").strip().lower()
|
||
return raw or "unknown"
|
||
|
||
def _resolve_source_id(
|
||
self,
|
||
*,
|
||
source_type: str,
|
||
metadata: dict[str, Any],
|
||
explicit_source_id: Any = None,
|
||
) -> Any:
|
||
resolved = self._source_ref_value(explicit_source_id or metadata.get("source_id"))
|
||
if resolved is not None:
|
||
return resolved
|
||
if source_type == "pmflow":
|
||
record_type = self._source_ref_value(metadata.get("record_type"))
|
||
record_id = self._source_ref_value(metadata.get("record_id"))
|
||
if record_type and record_id is not None:
|
||
return f"{record_type}:{record_id}"
|
||
return record_id
|
||
if source_type in {"doc", "url", "mcp_search"}:
|
||
return self._source_ref_value(
|
||
metadata.get("doc_id")
|
||
or metadata.get("knowledge_doc_id")
|
||
or metadata.get("doc_url")
|
||
or metadata.get("file_url")
|
||
or metadata.get("url")
|
||
)
|
||
if source_type == "feishu":
|
||
return self._source_ref_value(
|
||
metadata.get("message_id")
|
||
or metadata.get("attachment_id")
|
||
or metadata.get("file_key")
|
||
or metadata.get("key")
|
||
or metadata.get("chat_id")
|
||
)
|
||
if source_type == "graph":
|
||
relation_id = self._source_ref_value(metadata.get("relation_id"))
|
||
if relation_id is not None:
|
||
return f"relation:{relation_id}"
|
||
entity_id = self._source_ref_value(metadata.get("entity_id"))
|
||
if entity_id is not None:
|
||
return f"entity:{entity_id}"
|
||
return self._source_ref_value(
|
||
metadata.get("path")
|
||
or metadata.get("source_ref")
|
||
or metadata.get("subject_entity_id")
|
||
)
|
||
if source_type == "db":
|
||
table = self._source_ref_value(metadata.get("table"))
|
||
if table is None:
|
||
return None
|
||
project_id = self._source_ref_value(metadata.get("project_id"))
|
||
if project_id is not None:
|
||
return f"{table}:{project_id}"
|
||
return table
|
||
return self._source_ref_value(
|
||
metadata.get("doc_id")
|
||
or metadata.get("knowledge_doc_id")
|
||
or metadata.get("message_id")
|
||
or metadata.get("url")
|
||
or metadata.get("table")
|
||
or metadata.get("matched_project_ids")
|
||
)
|
||
|
||
def _resolve_chunk_id(self, metadata: dict[str, Any], *, explicit_chunk_id: Any = None) -> Any:
|
||
return self._source_ref_value(explicit_chunk_id or metadata.get("chunk_id") or metadata.get("chunk_index"))
|
||
|
||
def _resolve_target_url(
|
||
self,
|
||
*,
|
||
source_type: str,
|
||
metadata: dict[str, Any],
|
||
explicit_target_url: Any = None,
|
||
project_id: Any = None,
|
||
) -> Any:
|
||
target_url = self._source_ref_value(
|
||
explicit_target_url
|
||
or metadata.get("target_url")
|
||
or metadata.get("doc_url")
|
||
or metadata.get("file_url")
|
||
or metadata.get("url")
|
||
or metadata.get("permalink")
|
||
)
|
||
if target_url is not None:
|
||
return target_url
|
||
if source_type != "pmflow" or not hasattr(self, "_build_pmflow_target_url"):
|
||
return None
|
||
try:
|
||
return self._source_ref_value(
|
||
self._build_pmflow_target_url(
|
||
record_type=str(metadata.get("record_type") or ""),
|
||
record_id=metadata.get("record_id"),
|
||
project_id=project_id if project_id is not None else metadata.get("project_id"),
|
||
)
|
||
)
|
||
except Exception:
|
||
return None
|
||
|
||
def _resolve_updated_at(self, metadata: dict[str, Any], *, explicit_updated_at: Any = None) -> Any:
|
||
return self._source_ref_value(
|
||
self._isoformat_or_none(explicit_updated_at)
|
||
or metadata.get("updated_at")
|
||
or metadata.get("doc_updated_at")
|
||
or metadata.get("source_updated_at")
|
||
or metadata.get("captured_at")
|
||
or metadata.get("last_seen_at")
|
||
or metadata.get("last_fetched_at")
|
||
)
|
||
|
||
def _resolve_permission_scope(self, metadata: dict[str, Any], *, project_id: Any = None) -> str:
|
||
explicit_scope = str(self._source_ref_value(metadata.get("permission_scope")) or "").strip().lower()
|
||
if explicit_scope in {"project", "tenant"}:
|
||
return explicit_scope
|
||
resolved_project_id = self._source_ref_value(project_id if project_id is not None else metadata.get("project_id"))
|
||
return "project" if resolved_project_id is not None else "tenant"
|
||
|
||
def _resolve_source_priority(self, metadata: dict[str, Any], *, source_type: str) -> int:
|
||
explicit_priority = metadata.get("source_priority")
|
||
if explicit_priority is not None:
|
||
try:
|
||
return int(explicit_priority)
|
||
except Exception:
|
||
pass
|
||
return int(self._SOURCE_PRIORITY_MAP.get(source_type, 50))
|
||
|
||
def _normalize_source_registry_metadata(
|
||
self,
|
||
*,
|
||
source_type: Any,
|
||
metadata: Any,
|
||
explicit_source_id: Any = None,
|
||
explicit_chunk_id: Any = None,
|
||
explicit_target_url: Any = None,
|
||
explicit_project_id: Any = None,
|
||
explicit_updated_at: Any = None,
|
||
) -> dict[str, Any]:
|
||
normalized = self._safe_source_metadata(metadata).copy()
|
||
resolved_source_type = self._normalize_source_type(source_type or normalized.get("source_type"))
|
||
resolved_project_id = self._source_ref_value(
|
||
explicit_project_id if explicit_project_id is not None else normalized.get("project_id")
|
||
)
|
||
normalized["source_type"] = resolved_source_type
|
||
normalized["source_id"] = self._resolve_source_id(
|
||
source_type=resolved_source_type,
|
||
metadata=normalized,
|
||
explicit_source_id=explicit_source_id,
|
||
)
|
||
normalized["chunk_id"] = self._resolve_chunk_id(normalized, explicit_chunk_id=explicit_chunk_id)
|
||
normalized["target_url"] = self._resolve_target_url(
|
||
source_type=resolved_source_type,
|
||
metadata=normalized,
|
||
explicit_target_url=explicit_target_url,
|
||
project_id=resolved_project_id,
|
||
)
|
||
normalized["project_id"] = resolved_project_id
|
||
normalized["updated_at"] = self._resolve_updated_at(normalized, explicit_updated_at=explicit_updated_at)
|
||
normalized["permission_scope"] = self._resolve_permission_scope(normalized, project_id=resolved_project_id)
|
||
normalized["source_priority"] = self._resolve_source_priority(normalized, source_type=resolved_source_type)
|
||
return normalized
|
||
|
||
def _source_priority_sort_value(self, metadata: Any) -> int:
|
||
normalized = self._safe_source_metadata(metadata)
|
||
source_type = self._normalize_source_type(normalized.get("source_type"))
|
||
return self._resolve_source_priority(normalized, source_type=source_type)
|
||
|
||
@staticmethod
|
||
def _normalize_answer_mode(value: Optional[str]) -> str:
|
||
raw = str(value or "").strip().lower()
|
||
if raw in {
|
||
ANSWER_MODE_FAST_PATH,
|
||
ANSWER_MODE_RETRIEVAL_NORMAL,
|
||
ANSWER_MODE_RETRIEVAL_DEEP,
|
||
ANSWER_MODE_CLARIFY,
|
||
ANSWER_MODE_BLOCKED,
|
||
}:
|
||
return raw
|
||
return ANSWER_MODE_RETRIEVAL_NORMAL
|
||
|
||
def _normalize_grounding_status(
|
||
self,
|
||
value: Optional[str],
|
||
*,
|
||
sources: Optional[list[dict[str, Any]]] = None,
|
||
missing_fields: Optional[list[str]] = None,
|
||
answer_mode: Optional[str] = None,
|
||
reason_code: Optional[str] = None,
|
||
) -> str:
|
||
raw = str(value or "").strip().lower()
|
||
if raw in {
|
||
GROUNDING_STATUS_GROUNDED,
|
||
GROUNDING_STATUS_PARTIALLY_GROUNDED,
|
||
GROUNDING_STATUS_INSUFFICIENT_EVIDENCE,
|
||
GROUNDING_STATUS_BLOCKED,
|
||
}:
|
||
return raw
|
||
|
||
normalized_mode = self._normalize_answer_mode(answer_mode)
|
||
if normalized_mode == ANSWER_MODE_BLOCKED:
|
||
return GROUNDING_STATUS_BLOCKED
|
||
if normalized_mode == ANSWER_MODE_CLARIFY:
|
||
return GROUNDING_STATUS_INSUFFICIENT_EVIDENCE
|
||
|
||
source_rows = sources if isinstance(sources, list) else []
|
||
snapshot_only = False
|
||
if hasattr(self, "_is_snapshot_only_sources"):
|
||
try:
|
||
snapshot_only = bool(self._is_snapshot_only_sources(source_rows))
|
||
except Exception:
|
||
snapshot_only = False
|
||
if not snapshot_only and source_rows:
|
||
snapshot_only = all(str(item.get("source") or "").strip().lower() == "system" for item in source_rows if isinstance(item, dict))
|
||
|
||
missing = [str(item).strip() for item in (missing_fields or []) if str(item).strip()]
|
||
normalized_reason = str(reason_code or "").strip().lower()
|
||
if normalized_reason == "insufficient_evidence":
|
||
return GROUNDING_STATUS_INSUFFICIENT_EVIDENCE
|
||
if snapshot_only or missing:
|
||
return GROUNDING_STATUS_PARTIALLY_GROUNDED
|
||
if source_rows:
|
||
return GROUNDING_STATUS_GROUNDED
|
||
return GROUNDING_STATUS_PARTIALLY_GROUNDED
|
||
|
||
def _build_citations_from_sources(self, sources: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
||
normalized: list[dict[str, Any]] = []
|
||
seen: set[tuple[str, str, str, str]] = set()
|
||
for item in (sources or [])[:8]:
|
||
if not isinstance(item, dict):
|
||
continue
|
||
metadata = self._normalize_source_registry_metadata(
|
||
source_type=item.get("source"),
|
||
metadata=item.get("metadata"),
|
||
)
|
||
source_type = self._source_ref_value(metadata.get("source_type"))
|
||
source_label = self._source_ref_value(item.get("label") or metadata.get("source_label"))
|
||
source_id = self._source_ref_value(metadata.get("source_id"))
|
||
chunk_id = self._source_ref_value(metadata.get("chunk_id"))
|
||
target_url = self._source_ref_value(metadata.get("target_url"))
|
||
project_id = self._source_ref_value(metadata.get("project_id"))
|
||
updated_at = self._source_ref_value(metadata.get("updated_at"))
|
||
citation = {
|
||
"source_type": source_type,
|
||
"source_label": source_label,
|
||
"source_id": source_id,
|
||
"chunk_id": chunk_id,
|
||
"target_url": target_url,
|
||
"project_id": project_id,
|
||
"updated_at": updated_at,
|
||
"permission_scope": self._source_ref_value(metadata.get("permission_scope")),
|
||
"source_priority": metadata.get("source_priority"),
|
||
"confidence": round(self._to_float(item.get("score"), 0.0), 4),
|
||
}
|
||
key = (
|
||
str(source_type or ""),
|
||
str(source_id or ""),
|
||
str(chunk_id or ""),
|
||
str(target_url or ""),
|
||
)
|
||
if key in seen:
|
||
continue
|
||
seen.add(key)
|
||
normalized.append(citation)
|
||
return normalized
|
||
|
||
@staticmethod
|
||
def _build_sources_used_from_citations(citations: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
||
rows: list[dict[str, Any]] = []
|
||
for item in citations:
|
||
if not isinstance(item, dict):
|
||
continue
|
||
rows.append(
|
||
{
|
||
"source_type": item.get("source_type"),
|
||
"source_label": item.get("source_label"),
|
||
"source_id": item.get("source_id"),
|
||
"chunk_id": item.get("chunk_id"),
|
||
"target_url": item.get("target_url"),
|
||
"project_id": item.get("project_id"),
|
||
"updated_at": item.get("updated_at"),
|
||
"permission_scope": item.get("permission_scope"),
|
||
"source_priority": item.get("source_priority"),
|
||
}
|
||
)
|
||
return rows
|
||
|
||
def _build_evidence_pack(
|
||
self,
|
||
*,
|
||
answer: str,
|
||
citations: list[dict[str, Any]],
|
||
tool_trace: list[dict[str, Any]],
|
||
missing_fields: Optional[list[str]] = None,
|
||
grounding_status: Optional[str] = None,
|
||
reason_code: Optional[str] = None,
|
||
) -> dict[str, Any]:
|
||
evidence_labels: list[str] = []
|
||
for item in citations[:5]:
|
||
if not isinstance(item, dict):
|
||
continue
|
||
label = str(item.get("source_label") or item.get("source_id") or item.get("source_type") or "").strip()
|
||
if label:
|
||
evidence_labels.append(label)
|
||
uncertainties = [str(item).strip() for item in (missing_fields or []) if str(item).strip()]
|
||
normalized_grounding = str(grounding_status or "").strip().lower()
|
||
normalized_reason = str(reason_code or "").strip()
|
||
if normalized_grounding in {GROUNDING_STATUS_INSUFFICIENT_EVIDENCE, GROUNDING_STATUS_BLOCKED} and normalized_reason:
|
||
if normalized_reason not in uncertainties:
|
||
uncertainties.append(normalized_reason)
|
||
return {
|
||
"summary": {
|
||
"conclusion": str(answer or "").strip(),
|
||
"evidence": evidence_labels,
|
||
"uncertainties": uncertainties,
|
||
},
|
||
"tool_trace": tool_trace if isinstance(tool_trace, list) else [],
|
||
}
|
||
|
||
def _is_internal_answer_contract_route(
|
||
self,
|
||
*,
|
||
route_decision: Optional[dict[str, Any]] = None,
|
||
sources: Optional[list[dict[str, Any]]] = None,
|
||
) -> bool:
|
||
normalized_route = (
|
||
self._normalize_query_route_decision(route_decision)
|
||
if hasattr(self, "_normalize_query_route_decision")
|
||
else {}
|
||
)
|
||
if str(normalized_route.get("route_mode") or "").strip().lower() == "internal":
|
||
return True
|
||
if str(normalized_route.get("effective_source_policy") or "").strip().lower() == "internal":
|
||
return True
|
||
for item in sources or []:
|
||
if not isinstance(item, dict):
|
||
continue
|
||
if str(item.get("source") or "").strip().lower() in self._INTERNAL_SOURCE_TYPES:
|
||
return True
|
||
return False
|
||
|
||
def _verify_external_answer_contract(
|
||
self,
|
||
*,
|
||
answer: str,
|
||
sources: Optional[list[dict[str, Any]]] = None,
|
||
route_decision: Optional[dict[str, Any]] = None,
|
||
) -> dict[str, Any]:
|
||
normalized_route = (
|
||
self._normalize_query_route_decision(route_decision)
|
||
if hasattr(self, "_normalize_query_route_decision")
|
||
else {}
|
||
)
|
||
if str(normalized_route.get("effective_source_policy") or "").strip().lower() != "external":
|
||
return {"ok": True, "reason_code": None, "missing_fields": []}
|
||
|
||
source_rows = sources if isinstance(sources, list) else []
|
||
if not source_rows:
|
||
return {
|
||
"ok": False,
|
||
"reason_code": "missing_external_evidence",
|
||
"missing_fields": ["external_evidence"],
|
||
}
|
||
|
||
external_source_seen = False
|
||
for item in source_rows:
|
||
if not isinstance(item, dict):
|
||
continue
|
||
source = str(item.get("source") or "").strip().lower()
|
||
metadata = item.get("metadata") if isinstance(item.get("metadata"), dict) else {}
|
||
if source == "system":
|
||
continue
|
||
if source not in {"url", "mcp_search"}:
|
||
return {
|
||
"ok": False,
|
||
"reason_code": "external_source_contract_violation",
|
||
"missing_fields": ["external_source_type"],
|
||
}
|
||
target_url = str(
|
||
metadata.get("target_url")
|
||
or metadata.get("file_url")
|
||
or metadata.get("url")
|
||
or ""
|
||
).strip().lower()
|
||
if not target_url.startswith("http://") and not target_url.startswith("https://"):
|
||
return {
|
||
"ok": False,
|
||
"reason_code": "external_target_url_missing",
|
||
"missing_fields": ["target_url"],
|
||
}
|
||
external_source_seen = True
|
||
|
||
if not external_source_seen:
|
||
return {
|
||
"ok": False,
|
||
"reason_code": "missing_external_grounding",
|
||
"missing_fields": ["external_evidence"],
|
||
}
|
||
_ = answer
|
||
return {"ok": True, "reason_code": None, "missing_fields": []}
|
||
|
||
def _build_external_answer_contract_guard_payload(
|
||
self,
|
||
*,
|
||
reason_code: Optional[str],
|
||
missing_fields: Optional[list[str]] = None,
|
||
) -> dict[str, Any]:
|
||
normalized_reason = str(reason_code or "").strip().lower() or "external_answer_contract_violation"
|
||
normalized_missing = [str(item).strip() for item in (missing_fields or []) if str(item).strip()]
|
||
return {
|
||
"answer": "当前没有拿到可核验的外部实时证据，已阻止直接返回外部结论。请稍后重试，或把要核验的公开对象说得更具体一些。",
|
||
"sources": [
|
||
{
|
||
"source": "system",
|
||
"label": "External Query Contract Guard",
|
||
"score": 0.99,
|
||
"metadata": {
|
||
"mode": "guard",
|
||
"reason": normalized_reason,
|
||
},
|
||
}
|
||
],
|
||
"missing_fields": normalized_missing or ["external_answer_contract"],
|
||
"reason_code": normalized_reason,
|
||
"answer_mode": ANSWER_MODE_CLARIFY,
|
||
"grounding_status": GROUNDING_STATUS_INSUFFICIENT_EVIDENCE,
|
||
}
|
||
|
||
def _verify_internal_answer_contract(
|
||
self,
|
||
*,
|
||
query_type: str,
|
||
answer: str,
|
||
sources: Optional[list[dict[str, Any]]] = None,
|
||
route_decision: Optional[dict[str, Any]] = None,
|
||
internal_context_packet: Any = None,
|
||
) -> dict[str, Any]:
|
||
source_rows = sources if isinstance(sources, list) else []
|
||
if not self._is_internal_answer_contract_route(route_decision=route_decision, sources=source_rows):
|
||
return {"ok": True, "reason_code": None, "missing_fields": []}
|
||
|
||
packet_block = internal_context_block_reason(
|
||
internal_context_packet,
|
||
route_decision=route_decision,
|
||
)
|
||
if packet_block is not None:
|
||
reason_code, missing_fields = packet_block
|
||
return {
|
||
"ok": False,
|
||
"reason_code": reason_code,
|
||
"missing_fields": missing_fields,
|
||
}
|
||
|
||
operation_contract = internal_context_operation_contract(packet=internal_context_packet)
|
||
query_plan = internal_context_query_plan(packet=internal_context_packet)
|
||
normalized_query_type = str(
|
||
operation_contract.get("query_type")
|
||
or query_plan.get("query_type")
|
||
or query_type
|
||
or QUERY_TYPE_UNKNOWN
|
||
).strip().lower()
|
||
normalized_answer = str(answer or "").strip()
|
||
compact_answer = re.sub(r"\s+", "", normalized_answer.lower())
|
||
|
||
if normalized_query_type == QUERY_TYPE_EXISTENCE:
|
||
if "项目总数" in normalized_answer or "总数为" in normalized_answer:
|
||
return {
|
||
"ok": False,
|
||
"reason_code": "no_total_count_substitution",
|
||
"missing_fields": ["matched_evidence", "existence_contract"],
|
||
}
|
||
if (
|
||
"总数" in compact_answer
|
||
and "匹配到" not in normalized_answer
|
||
and "未检索到" not in normalized_answer
|
||
and "任务总数" not in normalized_answer
|
||
and "信号总数" not in normalized_answer
|
||
):
|
||
return {
|
||
"ok": False,
|
||
"reason_code": "no_total_count_substitution",
|
||
"missing_fields": ["matched_evidence", "existence_contract"],
|
||
}
|
||
|
||
if not source_rows:
|
||
return {
|
||
"ok": False,
|
||
"reason_code": "missing_internal_evidence",
|
||
"missing_fields": ["internal_evidence"],
|
||
}
|
||
|
||
return {"ok": True, "reason_code": None, "missing_fields": []}
|
||
|
||
def _build_internal_answer_contract_guard_payload(
|
||
self,
|
||
*,
|
||
query_type: str,
|
||
reason_code: Optional[str],
|
||
missing_fields: Optional[list[str]] = None,
|
||
) -> dict[str, Any]:
|
||
normalized_query_type = str(query_type or QUERY_TYPE_UNKNOWN).strip().lower()
|
||
normalized_reason = str(reason_code or "").strip().lower() or "internal_answer_contract_violation"
|
||
normalized_missing = [str(item).strip() for item in (missing_fields or []) if str(item).strip()]
|
||
if normalized_reason == "no_total_count_substitution" and normalized_query_type == QUERY_TYPE_EXISTENCE:
|
||
answer = "当前内部查询结果与问题类型不一致，已阻止直接返回。你问的是“有没有”，请给我更明确的对象条件后我按存在性重新查询。"
|
||
elif normalized_reason == "missing_internal_evidence":
|
||
answer = "当前内部查询证据不足，已阻止直接返回结论。请补充更明确的对象或范围后我再查。"
|
||
elif normalized_reason == "missing_internal_context_packet":
|
||
answer = "当前内部查询上下文未完成，已停止直接回答。请稍后重试，或补充更明确的对象或范围后我再查。"
|
||
elif normalized_reason == "missing_internal_operation_contract":
|
||
answer = "当前内部查询合同不完整，已停止直接回答。请补充更明确的对象或范围后我再查。"
|
||
elif normalized_reason == "target_resolution_clarify":
|
||
answer = "当前内部查询对象仍有歧义，已停止直接回答。请先明确你要查的项目、配置或对象后我再继续。"
|
||
elif normalized_reason == "missing_internal_query_plan_contract":
|
||
answer = "当前内部查询计划不完整，已停止直接回答。请补充更明确的对象或范围后我再查。"
|
||
else:
|
||
answer = "当前内部查询结果未通过回答合同校验，已阻止直接返回。请补充更明确的对象或范围后我再查。"
|
||
|
||
answer_mode = ANSWER_MODE_BLOCKED
|
||
grounding_status = GROUNDING_STATUS_BLOCKED
|
||
if normalized_reason in {
|
||
"missing_internal_context_packet",
|
||
"missing_internal_operation_contract",
|
||
"target_resolution_clarify",
|
||
"missing_internal_query_plan_contract",
|
||
}:
|
||
answer_mode = ANSWER_MODE_CLARIFY
|
||
grounding_status = GROUNDING_STATUS_INSUFFICIENT_EVIDENCE
|
||
|
||
return {
|
||
"answer": answer,
|
||
"sources": [
|
||
{
|
||
"source": "system",
|
||
"label": "Internal Query Contract Guard",
|
||
"score": 0.99,
|
||
"metadata": {
|
||
"mode": "guard",
|
||
"reason": normalized_reason,
|
||
"query_type": normalized_query_type,
|
||
},
|
||
}
|
||
],
|
||
"missing_fields": normalized_missing or ["internal_answer_contract"],
|
||
"reason_code": normalized_reason,
|
||
"answer_mode": answer_mode,
|
||
"grounding_status": grounding_status,
|
||
}
|
||
|
||
def _build_response_payload(
|
||
self,
|
||
*,
|
||
answer: str,
|
||
sources: list[dict[str, Any]],
|
||
domains_used: list[str],
|
||
response_time_ms: int,
|
||
db_query_ms: int,
|
||
vector_search_ms: int,
|
||
graph_query_ms: int = 0,
|
||
db_timeout: bool = False,
|
||
vector_timeout: bool = False,
|
||
graph_timeout: bool = False,
|
||
qa_id: Optional[int] = None,
|
||
session_id: Optional[int] = None,
|
||
turn_index: int = 1,
|
||
relevance_max: float = 0.0,
|
||
query_type: str = QUERY_TYPE_UNKNOWN,
|
||
confidence: float = 0.0,
|
||
missing_fields: Optional[list[str]] = None,
|
||
tool_trace: Optional[list[dict[str, Any]]] = None,
|
||
thinking_mode: str = THINKING_MODE_NORMAL,
|
||
action_taken: Optional[str] = None,
|
||
signal_id: Optional[int] = None,
|
||
reply_required: bool = False,
|
||
reply_text: Optional[str] = None,
|
||
ack_latency_ms: Optional[int] = None,
|
||
trace_id: Optional[str] = None,
|
||
processing_stage: Optional[str] = None,
|
||
clarification_code: Optional[str] = None,
|
||
clarification_candidates: Optional[list[dict[str, Any]]] = None,
|
||
anchor_mode: Optional[str] = None,
|
||
anchor_kind: Optional[str] = None,
|
||
meta_followup_kind: Optional[str] = None,
|
||
reason_code: Optional[str] = None,
|
||
answer_mode: Optional[str] = None,
|
||
grounding_status: Optional[str] = None,
|
||
policy_version: Optional[str] = None,
|
||
citations: Optional[list[dict[str, Any]]] = None,
|
||
sources_used: Optional[list[dict[str, Any]]] = None,
|
||
evidence_pack: Optional[dict[str, Any]] = None,
|
||
prompt_variant_id: Optional[str] = None,
|
||
route_decision: Optional[dict[str, Any]] = None,
|
||
project_operating_context: Optional[dict[str, Any]] = None,
|
||
execution_recipe: Optional[dict[str, Any]] = None,
|
||
fit_brief: Optional[dict[str, Any]] = None,
|
||
external_recommendation: Optional[dict[str, Any]] = None,
|
||
) -> dict[str, Any]:
|
||
evidence: list[dict[str, Any]] = []
|
||
for item in sources[:8]:
|
||
if not isinstance(item, dict):
|
||
continue
|
||
evidence.append(
|
||
{
|
||
"source": str(item.get("source") or "unknown"),
|
||
"label": str(item.get("label") or "unknown"),
|
||
"score": round(self._to_float(item.get("score"), 0.0), 4),
|
||
"metadata": item.get("metadata") if isinstance(item.get("metadata"), dict) else {},
|
||
}
|
||
)
|
||
normalized_tool_trace = tool_trace if isinstance(tool_trace, list) else []
|
||
normalized_citations = citations if isinstance(citations, list) else self._build_citations_from_sources(sources)
|
||
normalized_sources_used = (
|
||
sources_used
|
||
if isinstance(sources_used, list)
|
||
else self._build_sources_used_from_citations(normalized_citations)
|
||
)
|
||
normalized_answer_mode = self._normalize_answer_mode(answer_mode)
|
||
normalized_grounding_status = self._normalize_grounding_status(
|
||
grounding_status,
|
||
sources=sources,
|
||
missing_fields=missing_fields,
|
||
answer_mode=normalized_answer_mode,
|
||
reason_code=reason_code,
|
||
)
|
||
normalized_policy_version = str(
|
||
policy_version
|
||
or self._build_policy_version(prompt_variant_id=prompt_variant_id)
|
||
).strip() or self._build_policy_version(prompt_variant_id=prompt_variant_id)
|
||
normalized_evidence_pack = (
|
||
evidence_pack
|
||
if isinstance(evidence_pack, dict)
|
||
else self._build_evidence_pack(
|
||
answer=answer,
|
||
citations=normalized_citations,
|
||
tool_trace=normalized_tool_trace,
|
||
missing_fields=missing_fields,
|
||
grounding_status=normalized_grounding_status,
|
||
reason_code=reason_code,
|
||
)
|
||
)
|
||
normalized_route_decision = (
|
||
self._normalize_query_route_decision(route_decision)
|
||
if hasattr(self, "_normalize_query_route_decision")
|
||
else {}
|
||
)
|
||
normalized_project_operating_context = self._normalize_project_operating_context(
|
||
project_operating_context
|
||
)
|
||
normalized_execution_recipe = self._normalize_execution_recipe(execution_recipe)
|
||
normalized_fit_brief = self._normalize_fit_brief(fit_brief)
|
||
normalized_external_recommendation = self._normalize_external_recommendation(external_recommendation)
|
||
handoff_fields = self._build_plan_handoff_fields(
|
||
execution_recipe=normalized_execution_recipe,
|
||
project_operating_context=normalized_project_operating_context,
|
||
)
|
||
return {
|
||
"answer": str(answer or "").strip(),
|
||
"evidence": evidence,
|
||
"confidence": round(max(0.0, min(1.0, self._to_float(confidence, 0.0))), 4),
|
||
"thinking_mode": self._normalize_thinking_mode(thinking_mode),
|
||
"missing_fields": [str(x) for x in (missing_fields or []) if str(x).strip()],
|
||
"query_type": str(query_type or QUERY_TYPE_UNKNOWN),
|
||
"sources": sources,
|
||
"domains_used": domains_used,
|
||
"response_time_ms": int(response_time_ms or 0),
|
||
"retrieval_metrics": {
|
||
"db_query_ms": int(db_query_ms or 0),
|
||
"vector_search_ms": int(vector_search_ms or 0),
|
||
"graph_query_ms": int(graph_query_ms or 0),
|
||
"db_timeout": bool(db_timeout),
|
||
"vector_timeout": bool(vector_timeout),
|
||
"graph_timeout": bool(graph_timeout),
|
||
},
|
||
"tool_trace": normalized_tool_trace,
|
||
"qa_id": int(qa_id) if qa_id is not None else None,
|
||
"session_id": int(session_id) if session_id is not None else None,
|
||
"turn_index": int(turn_index or 1),
|
||
"relevance_max": round(max(0.0, self._to_float(relevance_max, 0.0)), 4),
|
||
"action_taken": str(action_taken).strip() if action_taken else None,
|
||
"signal_id": int(signal_id) if signal_id is not None else None,
|
||
"reply_required": bool(reply_required),
|
||
"reply_text": str(reply_text or "").strip() if reply_text else None,
|
||
"ack_latency_ms": int(ack_latency_ms) if ack_latency_ms is not None else None,
|
||
"trace_id": str(trace_id or "").strip() or None,
|
||
"processing_stage": str(processing_stage or "").strip() or None,
|
||
"clarification_code": str(clarification_code or "").strip() or None,
|
||
"clarification_candidates": (
|
||
clarification_candidates[:3]
|
||
if isinstance(clarification_candidates, list)
|
||
else []
|
||
),
|
||
"anchor_mode": str(anchor_mode or "").strip() or None,
|
||
"anchor_kind": str(anchor_kind or "").strip() or None,
|
||
"meta_followup_kind": str(meta_followup_kind or "").strip() or None,
|
||
"reason_code": str(reason_code or "").strip() or None,
|
||
"answer_mode": normalized_answer_mode,
|
||
"grounding_status": normalized_grounding_status,
|
||
"policy_version": normalized_policy_version,
|
||
"citations": normalized_citations,
|
||
"sources_used": normalized_sources_used,
|
||
"evidence_pack": normalized_evidence_pack,
|
||
"route_decision": normalized_route_decision,
|
||
"project_operating_context": normalized_project_operating_context,
|
||
"execution_recipe": normalized_execution_recipe,
|
||
"fit_brief": normalized_fit_brief,
|
||
"external_recommendation": normalized_external_recommendation,
|
||
"handoff_mode": handoff_fields["handoff_mode"],
|
||
"can_enter_plan": handoff_fields["can_enter_plan"],
|
||
"recommended_next_step": handoff_fields["recommended_next_step"],
|
||
}
|
||
|
||
@staticmethod
|
||
def _extract_ack_metadata_from_sources(
|
||
sources: Any,
|
||
*,
|
||
answer: str = "",
|
||
) -> dict[str, Any]:
|
||
rows = sources if isinstance(sources, list) else []
|
||
action_taken = ""
|
||
signal_id: Optional[int] = None
|
||
reply_required = False
|
||
ack_latency_ms: Optional[int] = None
|
||
trace_id = ""
|
||
processing_stage = ""
|
||
for source in rows:
|
||
if not isinstance(source, dict):
|
||
continue
|
||
meta = source.get("metadata") if isinstance(source.get("metadata"), dict) else {}
|
||
candidate_action = str(meta.get("action_taken") or "").strip()
|
||
if not candidate_action:
|
||
continue
|
||
action_taken = candidate_action
|
||
try:
|
||
signal_id = int(meta.get("signal_id")) if meta.get("signal_id") is not None else None
|
||
except Exception:
|
||
signal_id = None
|
||
trace_id = str(meta.get("trace_id") or "").strip()
|
||
processing_stage = str(meta.get("processing_stage") or meta.get("action_mode") or "").strip()
|
||
try:
|
||
ack_latency_ms = (
|
||
int(meta.get("ack_latency_ms")) if meta.get("ack_latency_ms") is not None else None
|
||
)
|
||
except Exception:
|
||
ack_latency_ms = None
|
||
reply_required = True
|
||
break
|
||
reply_text = str(answer or "").strip() if reply_required else ""
|
||
normalized_stage = processing_stage
|
||
if normalized_stage == "write":
|
||
normalized_stage = "ack_only"
|
||
return {
|
||
"action_taken": action_taken or None,
|
||
"signal_id": signal_id,
|
||
"reply_required": bool(reply_required),
|
||
"reply_text": reply_text or None,
|
||
"ack_latency_ms": ack_latency_ms,
|
||
"trace_id": trace_id or None,
|
||
"processing_stage": normalized_stage or None,
|
||
}
|