@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/mcp_server/tools.py

@@ -0,0 +1,588 @@
+"""Stable tool contract for the V1 MCP surface."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from people_network_memory.application.services import (
+    BuildPersonCardService,
+    RecordInteractionService,
+    RetrieveContextService,
+)
+from people_network_memory.domain.models import SocialInteraction
+from people_network_memory.mcp_server.contracts import (
+    GetPersonInput,
+    RetrieveNetworkContextInput,
+    public_tool_names,
+)
+
+
+class PeopleMemoryTools:
+    def __init__(
+        self,
+        *,
+        record_interaction_service: RecordInteractionService,
+        retrieve_context_service: RetrieveContextService,
+        build_person_card_service: BuildPersonCardService,
+    ) -> None:
+        self._record = record_interaction_service
+        self._retrieve = retrieve_context_service
+        self._card = build_person_card_service
+
+    def tool_names(self) -> list[str]:
+        return public_tool_names()
+
+    def record_interaction(self, payload: dict[str, Any]) -> dict[str, Any]:
+        payload = _coerce_record_interaction_payload(payload)
+        interaction = SocialInteraction.model_validate(payload)
+        result = self._record.record(interaction)
+        return result.model_dump(mode="json")
+
+    def retrieve_network_context(self, payload: dict[str, Any]) -> dict[str, Any]:
+        request = RetrieveNetworkContextInput.model_validate(payload)
+        response = self._retrieve.retrieve(
+            request.query.strip(),
+            limit=request.limit,
+            include_sensitive=request.include_sensitive,
+            sensitivity_policy=request.sensitivity_policy,
+            output_context=request.output_context,
+            mode=request.mode,
+        )
+        data = response.model_dump(mode="json")
+        resolved_card = self._duplicate_query_name_resolution(request.query.strip())
+        if resolved_card is None:
+            resolved_card = self._single_query_name_resolution(request.query.strip())
+        if resolved_card is not None:
+            data["results"] = _filter_results_to_person(
+                data["results"], resolved_card.person_id
+            )
+            data["results"] = _augment_resolved_person_results(
+                query=request.query.strip(),
+                results=data["results"],
+                card=resolved_card,
+            )
+        ambiguity = None
+        if resolved_card is None:
+            ambiguity = self._duplicate_profile_name_ambiguity(
+                data["results"]
+            ) or self._duplicate_query_name_ambiguity(request.query.strip())
+        if ambiguity:
+            data.update(ambiguity)
+            candidate_ids = {
+                str(candidate["person_id"])
+                for candidate in data["candidates"]
+                if candidate.get("person_id")
+            }
+            candidate_results = [
+                item
+                for item in data["results"]
+                if any(person_id in candidate_ids for person_id in item["person_ids"])
+            ]
+            data["candidate_results"] = _candidate_results(
+                candidates=data["candidates"],
+                results=candidate_results,
+            )
+            data["results"] = [
+                _ambiguity_result(
+                    query=request.query.strip(),
+                    candidates=data["candidates"],
+                    score=999.0,
+                ),
+                *candidate_results,
+            ]
+            data["final_answer_instruction"] = (
+                "Start the final answer by saying multiple people match the queried name. "
+                "List every candidate with person_id and distinguishing details. "
+                "Do not start with a yes/no answer and do not answer as if one candidate was chosen. "
+                "If evidence applies to only one candidate, say that candidate-specific evidence after listing all candidates."
+            )
+            data["missing_info"].insert(
+                0,
+                "Multiple person cards matched this full-name query. You must list all candidates; do not infer that the user probably means only one candidate.",
+            )
+            if not candidate_results and len(data["missing_info"]) == 1:
+                data["missing_info"].append(
+                    "No matching retrieval items were found for the ambiguous candidates."
+                )
+        return data
+
+    def get_person(self, payload: dict[str, Any]) -> dict[str, Any]:
+        request = GetPersonInput.model_validate(payload)
+        person_id = request.person_id.strip() if request.person_id else ""
+        if not person_id and request.name:
+            name = request.name.strip()
+            exact_cards = self._card.get_people_by_name(name)
+            if len(exact_cards) == 1:
+                data = exact_cards[0].model_dump(mode="json")
+                data["found"] = True
+                return data
+            if len(exact_cards) > 1:
+                return {
+                    "person_id": None,
+                    "name": name,
+                    "found": False,
+                    "ambiguous": True,
+                    "result_type": "ambiguous_person_name",
+                    "answer_policy": (
+                        "Do not choose one candidate. Present every candidate "
+                        "and ask the user to clarify by person_id or distinguishing details."
+                    ),
+                    "missing_info": [
+                        "Multiple person cards matched this name. You must list all candidates; do not answer as if one person matched."
+                    ],
+                    "candidates": [
+                        _candidate_payload_from_card(card) for card in exact_cards
+                    ],
+                }
+            person_id = self._find_person_id_by_name(name)
+            if not person_id:
+                return {
+                    "person_id": None,
+                    "name": name,
+                    "found": False,
+                    "missing_info": ["No person card found for this name."],
+                    "candidates": [],
+                }
+        card = self._card.get_person(person_id)
+        if card is None:
+            return {
+                "person_id": person_id,
+                "name": request.name.strip() if request.name else None,
+                "found": False,
+                "missing_info": ["No person card found for this person_id."],
+                "candidates": [],
+            }
+        data = card.model_dump(mode="json")
+        data["found"] = True
+        return data
+
+    def _find_person_id_by_name(self, name: str) -> str | None:
+        response = self._retrieve.retrieve(name, limit=5, mode="recall")
+        person_ids: list[str] = []
+        for item in response.results:
+            for person_id in item.person_ids:
+                if person_id not in person_ids:
+                    person_ids.append(person_id)
+        if len(person_ids) != 1:
+            return None
+        return person_ids[0]
+
+    def _duplicate_profile_name_ambiguity(
+        self, results: list[dict[str, Any]]
+    ) -> dict[str, Any] | None:
+        profile_person_ids_by_name: dict[str, set[str]] = {}
+        for item in results:
+            title = str(item.get("title") or "")
+            if not title.startswith("Profile summary for "):
+                continue
+            name = title.removeprefix("Profile summary for ").strip()
+            if not name:
+                continue
+            person_ids = {
+                str(person_id)
+                for person_id in item.get("person_ids", [])
+                if person_id
+            }
+            profile_person_ids_by_name.setdefault(name, set()).update(person_ids)
+
+        for name, profile_person_ids in profile_person_ids_by_name.items():
+            cards = self._card.get_people_by_name(name)
+            if len(cards) <= 1:
+                continue
+            card_ids = {card.person_id for card in cards}
+            if len(profile_person_ids & card_ids) <= 1:
+                continue
+            return {
+                "ambiguous": True,
+                "result_type": "ambiguous_person_name",
+                "answer_policy": (
+                    "Do not choose one candidate or say the user probably means one candidate. "
+                    "Present every candidate first with person_id and distinguishing details, "
+                    "then ask the user to clarify if needed."
+                ),
+                "candidates": [_candidate_payload_from_card(card) for card in cards],
+            }
+        return None
+
+    def _duplicate_query_name_ambiguity(self, query: str) -> dict[str, Any] | None:
+        for candidate_name in _query_name_candidates(query):
+            cards = self._card.get_people_by_name(candidate_name)
+            if len(cards) <= 1:
+                continue
+            narrowed_cards = _narrow_cards_by_query_qualifiers(query, cards)
+            if len(narrowed_cards) == 1:
+                continue
+            return {
+                "ambiguous": True,
+                "result_type": "ambiguous_person_name",
+                "answer_policy": (
+                    "Do not choose one candidate or say the user probably means one candidate. "
+                    "Present every candidate first with person_id and distinguishing details, "
+                    "then ask the user to clarify if needed."
+                ),
+                "candidates": [_candidate_payload_from_card(card) for card in cards],
+            }
+        return None
+
+    def _duplicate_query_name_resolution(self, query: str) -> Any | None:
+        for candidate_name in _query_name_candidates(query):
+            cards = self._card.get_people_by_name(candidate_name)
+            if len(cards) <= 1:
+                continue
+            narrowed_cards = _narrow_cards_by_query_qualifiers(query, cards)
+            if len(narrowed_cards) == 1:
+                return narrowed_cards[0]
+        return None
+
+    def _single_query_name_resolution(self, query: str) -> Any | None:
+        for candidate_name in _query_name_candidates(query):
+            cards = self._card.get_people_by_name(candidate_name)
+            if len(cards) > 1:
+                return None
+            if len(cards) == 1:
+                return cards[0]
+        return None
+
+
+def _coerce_record_interaction_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    coerced = dict(payload)
+    if "location" in coerced and "place" not in coerced:
+        coerced["place"] = coerced.pop("location")
+    if "date" in coerced and "occurred_at" not in coerced:
+        date_value = str(coerced.pop("date")).strip()
+        if re.fullmatch(r"\d{4}-\d{2}-\d{2}", date_value):
+            coerced["occurred_at"] = f"{date_value}T00:00:00+00:00"
+    for field_name in ["participants"]:
+        if isinstance(coerced.get(field_name), list):
+            coerced[field_name] = [
+                _coerce_participant(item) for item in coerced[field_name]
+            ]
+    if isinstance(coerced.get("mentioned_people"), list):
+        coerced["mentioned_people"] = [
+            _coerce_mentioned_person(item) for item in coerced["mentioned_people"]
+        ]
+    if isinstance(coerced.get("follow_ups"), list):
+        coerced["follow_ups"] = [
+            _coerce_follow_up(item) for item in coerced["follow_ups"]
+        ]
+    return coerced
+
+
+def _coerce_participant(item: Any) -> Any:
+    if isinstance(item, str):
+        return {"person": {"label": item}}
+    if not isinstance(item, dict):
+        return item
+    if "person" in item:
+        return {**item, "person": _coerce_person_ref(item["person"])}
+    if "name" in item:
+        role = item.get("role", "participant")
+        return {"person": {"label": item["name"]}, "role": role}
+    return item
+
+
+def _coerce_mentioned_person(item: Any) -> Any:
+    if isinstance(item, str):
+        return {"person": {"label": item}}
+    if not isinstance(item, dict):
+        return item
+    coerced = dict(item)
+    if "person" in coerced:
+        coerced["person"] = _coerce_person_ref(coerced["person"])
+    elif "name" in coerced:
+        coerced["person"] = {"label": coerced.pop("name")}
+    if "mentioned_by" in coerced:
+        coerced["mentioned_by"] = _coerce_person_ref(coerced["mentioned_by"])
+    return coerced
+
+
+def _coerce_follow_up(item: Any) -> Any:
+    if isinstance(item, str):
+        return {"description": item}
+    if not isinstance(item, dict):
+        return item
+    coerced = dict(item)
+    if "what" in coerced and "description" not in coerced:
+        coerced["description"] = coerced.pop("what")
+    if "due" in coerced and "due_at" not in coerced:
+        coerced["due_at"] = coerced.pop("due")
+    if isinstance(coerced.get("related_people"), list):
+        coerced["related_people"] = [
+            _coerce_person_ref(ref) for ref in coerced["related_people"]
+        ]
+    return coerced
+
+
+def _coerce_person_ref(item: Any) -> Any:
+    if isinstance(item, str):
+        return {"label": item}
+    if isinstance(item, dict) and "name" in item and "label" not in item:
+        coerced = dict(item)
+        coerced["label"] = coerced.pop("name")
+        return coerced
+    return item
+
+
+def _query_name_candidates(query: str) -> list[str]:
+    candidates: list[str] = []
+    for run in re.findall(r"[\u4e00-\u9fff]{2,20}", query):
+        max_width = min(8, len(run))
+        for width in range(max_width, 1, -1):
+            for start in range(0, len(run) - width + 1):
+                candidates.append(run[start : start + width])
+
+    ascii_tokens = re.findall(r"[A-Za-z][A-Za-z0-9_-]*", query)
+    max_width = min(5, len(ascii_tokens))
+    for width in range(max_width, 1, -1):
+        for start in range(0, len(ascii_tokens) - width + 1):
+            candidates.append(" ".join(ascii_tokens[start : start + width]))
+
+    seen: set[str] = set()
+    unique: list[str] = []
+    for candidate in sorted(candidates, key=len, reverse=True):
+        normalized = candidate.casefold()
+        if normalized in seen:
+            continue
+        seen.add(normalized)
+        unique.append(candidate)
+    return unique
+
+
+def _filter_results_to_person(
+    results: list[dict[str, Any]], person_id: str
+) -> list[dict[str, Any]]:
+    return [
+        item
+        for item in results
+        if person_id in {str(value) for value in item.get("person_ids", [])}
+    ]
+
+
+def _augment_resolved_person_results(
+    *, query: str, results: list[dict[str, Any]], card: Any
+) -> list[dict[str, Any]]:
+    augmented = list(results)
+    seen_texts = {str(item.get("matched_text") or "") for item in augmented}
+    if _query_mentions_follow_up_status(query):
+        follow_up_result = _resolved_person_follow_up_result(card)
+        if follow_up_result["matched_text"] not in seen_texts:
+            augmented.append(follow_up_result)
+            seen_texts.add(follow_up_result["matched_text"])
+    for index, source_text in enumerate(getattr(card, "recent_interactions", []), 1):
+        if not source_text or source_text in seen_texts:
+            continue
+        if not _should_add_resolved_recent_interaction(query, source_text):
+            continue
+        augmented.append(
+            {
+                "item_id": f"card-recent:{card.person_id}:{index}",
+                "kind": "interaction",
+                "title": f"Interaction with {card.display_name}",
+                "matched_text": source_text,
+                "score": _resolved_person_interaction_score(query, source_text),
+                "why_matched": (
+                    "Recent interaction for the person identified by explicit query qualifiers."
+                ),
+                "person_ids": [card.person_id],
+                "sensitivity": [],
+                "evidence": [],
+                "is_secondhand": False,
+            }
+        )
+        seen_texts.add(source_text)
+    return sorted(
+        augmented,
+        key=lambda item: float(item.get("score") or 0.0),
+        reverse=True,
+    )
+
+
+def _resolved_person_interaction_score(query: str, text: str) -> float:
+    compact_query = _compact_match_text(query)
+    compact_text = _compact_match_text(text)
+    score = 1.0
+    if "资料" in compact_query and "资料" in compact_text:
+        score += 2.0
+    if "发" in compact_query and "发" in compact_text:
+        score += 2.0
+    if "已经" in compact_text and "发" in compact_text:
+        score += 3.0
+    return score
+
+
+def _should_add_resolved_recent_interaction(query: str, text: str) -> bool:
+    compact_query = _compact_match_text(query)
+    compact_text = _compact_match_text(text)
+    if "资料" in compact_query and "资料" in compact_text:
+        return True
+    if _query_mentions_follow_up_status(query) and any(
+        term in compact_text for term in ["已经", "约好", "答应", "承诺", "待跟进"]
+    ):
+        return True
+    return False
+
+
+def _query_mentions_follow_up_status(query: str) -> bool:
+    compact_query = _compact_match_text(query)
+    return any(
+        term in compact_query
+        for term in ["待跟进", "还需要", "需要发", "需要给", "followup", "follow-up"]
+    )
+
+
+def _resolved_person_follow_up_result(card: Any) -> dict[str, Any]:
+    open_follow_ups = list(getattr(card, "open_follow_ups", []) or [])
+    label = _card_label_with_aliases(card)
+    if open_follow_ups:
+        descriptions = [
+            str(getattr(item, "description", "") or item)
+            for item in open_follow_ups
+        ]
+        matched_text = (
+            f"{label}（{card.person_id}）当前有"
+            f"{len(open_follow_ups)}个待跟进事项：" + "；".join(descriptions)
+        )
+    else:
+        matched_text = f"{label}（{card.person_id}）当前没有待跟进事项。"
+    return {
+        "item_id": f"follow-up-status:{card.person_id}",
+        "kind": "follow_up",
+        "title": f"Open follow-ups for {card.display_name}",
+        "matched_text": matched_text,
+        "score": 9.0,
+        "why_matched": "Follow-up status for the person identified by the query.",
+        "person_ids": [card.person_id],
+        "sensitivity": [],
+        "evidence": [],
+        "is_secondhand": False,
+    }
+
+
+def _card_label_with_aliases(card: Any) -> str:
+    aliases = [str(alias) for alias in getattr(card, "aliases", []) if alias]
+    if not aliases:
+        return str(card.display_name)
+    return f"{card.display_name}，别名：" + "、".join(aliases)
+
+
+def _narrow_cards_by_query_qualifiers(query: str, cards: list[Any]) -> list[Any]:
+    scored_cards = [
+        (_card_query_qualifier_score(query, card), card)
+        for card in cards
+    ]
+    positive_scores = [score for score, _card in scored_cards if score > 0]
+    if not positive_scores:
+        return []
+    winning_score = max(positive_scores)
+    return [card for score, card in scored_cards if score == winning_score]
+
+
+def _card_query_qualifier_score(query: str, card: Any) -> int:
+    compact_query = _compact_match_text(query)
+    score = 0
+    for term, weight in _card_query_qualifier_terms(card):
+        compact_term = _compact_match_text(term)
+        if len(compact_term) < 2:
+            continue
+        if compact_term in compact_query:
+            score += weight
+    return score
+
+
+def _card_query_qualifier_terms(card: Any) -> list[tuple[str, int]]:
+    terms: list[tuple[str, int]] = []
+    for work in getattr(card, "work_history", []):
+        for field_name in ["organization", "role", "department", "location"]:
+            value = getattr(work, field_name, None)
+            if value:
+                terms.append((str(value), 10))
+    for value in [
+        getattr(card, "headline", None),
+        getattr(card, "summary", None),
+    ]:
+        if value:
+            terms.append((str(value), 3))
+    for value in getattr(card, "interests", []):
+        if value:
+            terms.append((str(value), 2))
+    return terms
+
+
+def _compact_match_text(text: str) -> str:
+    return re.sub(r"\s+", "", text.casefold())
+
+
+def _ambiguity_result(
+    *, query: str, candidates: list[dict[str, Any]], score: float
+) -> dict[str, Any]:
+    candidate_lines = []
+    person_ids = []
+    for candidate in candidates:
+        person_id = str(candidate.get("person_id") or "")
+        if person_id:
+            person_ids.append(person_id)
+        candidate_lines.append(
+            " - ".join(
+                part
+                for part in [
+                    person_id,
+                    str(candidate.get("display_name") or ""),
+                    str(candidate.get("headline") or ""),
+                ]
+                if part
+            )
+        )
+    matched_text = (
+        f"Ambiguous people-memory query: {query}. "
+        "Do not answer this as a single-person yes/no or single-person fact. "
+        "List every candidate first and ask which one if needed. Candidates: "
+        + " | ".join(candidate_lines)
+    )
+    return {
+        "item_id": f"ambiguity:{abs(hash(matched_text))}",
+        "kind": "fact",
+        "title": "Ambiguous person name",
+        "matched_text": matched_text,
+        "score": score,
+        "why_matched": "Multiple person cards share the queried display name.",
+        "person_ids": person_ids,
+        "sensitivity": [],
+        "evidence": [],
+        "is_secondhand": False,
+    }
+
+
+def _candidate_results(
+    *, candidates: list[dict[str, Any]], results: list[dict[str, Any]]
+) -> list[dict[str, Any]]:
+    grouped: list[dict[str, Any]] = []
+    for candidate in candidates:
+        person_id = str(candidate.get("person_id") or "")
+        grouped.append(
+            {
+                "person_id": person_id,
+                "display_name": candidate.get("display_name"),
+                "headline": candidate.get("headline"),
+                "matched_results": [
+                    item
+                    for item in results
+                    if person_id and person_id in item.get("person_ids", [])
+                ],
+            }
+        )
+    return grouped
+
+
+def _candidate_payload_from_card(card: Any) -> dict[str, Any]:
+    return {
+        "person_id": card.person_id,
+        "display_name": card.display_name,
+        "aliases": getattr(card, "aliases", []),
+        "headline": card.headline,
+        "summary": card.summary,
+        "work_history": [item.model_dump(mode="json") for item in card.work_history],
+        "interests": card.interests,
+        "preferences": card.preferences,
+        "recent_interactions": card.recent_interactions,
+    }

package/src/people_network_memory/ports/__init__.py

@@ -0,0 +1,2 @@
+"""Application ports."""
+

package/src/people_network_memory/ports/errors.py

@@ -0,0 +1,25 @@
+"""Typed errors shared across non-domain layers."""
+
+
+class PeopleMemoryError(Exception):
+    """Base class for expected product errors."""
+
+
+class ConfigError(PeopleMemoryError):
+    """Runtime configuration is invalid or incomplete."""
+
+
+class BackendUnavailableError(PeopleMemoryError):
+    """The configured memory backend cannot be reached."""
+
+
+class SearchError(PeopleMemoryError):
+    """Search failed in the configured backend."""
+
+
+class PersistenceError(PeopleMemoryError):
+    """A write operation failed."""
+
+
+class HarnessInstallError(PeopleMemoryError):
+    """A harness adapter could not be installed or inspected."""