@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/application/services.py

@@ -0,0 +1,921 @@
+"""Application services orchestrating domain policies and ports."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from typing import Literal
+
+from people_network_memory.domain.identity import IdentityDecision, choose_identity
+from people_network_memory.domain.models import (
+    CapturedPersonSummary,
+    CaptureSummary,
+    Evidence,
+    FollowUpTask,
+    HarnessContextRequest,
+    IdentityAdvice,
+    OpportunityTimeHint,
+    PersonCard,
+    PersonRef,
+    PostCaptureOpportunity,
+    RecordInteractionResult,
+    RelationshipAssertion,
+    RetrievalResponse,
+    ReviewItem,
+    SensitivityLabel,
+    SocialInteraction,
+)
+from people_network_memory.application.normalization import normalize_interaction
+from people_network_memory.ports.errors import PersistenceError
+from people_network_memory.ports.interfaces import (
+    GraphMemoryStore,
+    GraphSearch,
+    IdentityAdvisor,
+    IdentityIndex,
+    IdGenerator,
+    InteractionExtractor,
+    PersonProjector,
+    RetrievalJudge,
+    ReviewQueue,
+)
+
+
+SensitivityPolicy = Literal["personal", "strict", "task_aware"]
+OutputContext = Literal["private", "shareable"]
+
+
+class ResolveIdentityService:
+    def __init__(self, identity_index: IdentityIndex) -> None:
+        self._identity_index = identity_index
+
+    def candidates(self, ref: PersonRef) -> list:
+        return self._identity_index.find_identity_candidates(ref)
+
+    def resolve(self, ref: PersonRef) -> IdentityDecision:
+        candidates = self.candidates(ref)
+        return choose_identity(ref, candidates)
+
+
+class RecordInteractionService:
+    def __init__(
+        self,
+        *,
+        memory_store: GraphMemoryStore,
+        identity_index: IdentityIndex,
+        review_queue: ReviewQueue,
+        id_generator: IdGenerator,
+        interaction_extractor: InteractionExtractor | None = None,
+        identity_advisor: IdentityAdvisor | None = None,
+    ) -> None:
+        self._memory_store = memory_store
+        self._identity = ResolveIdentityService(identity_index)
+        self._review_queue = review_queue
+        self._ids = id_generator
+        self._interaction_extractor = interaction_extractor
+        self._identity_advisor = identity_advisor
+
+    def record(self, interaction: SocialInteraction) -> RecordInteractionResult:
+        interaction = self._extract_interaction(interaction)
+        interaction = normalize_interaction(interaction)
+        identity_map: dict[str, str | None] = {}
+        identity_decisions: dict[str, IdentityDecision] = {}
+        pending_reviews: list[tuple[str, ReviewItem]] = []
+        for ref in self._iter_person_refs(interaction):
+            key = self._ref_key(ref)
+            if key in identity_decisions:
+                continue
+            if _explicit_separate_person_reference(interaction.source_text, ref):
+                candidates = self._identity.candidates(ref)
+                decision = IdentityDecision(
+                    kind="provisional",
+                    reason="explicit different-person reference",
+                    candidates=tuple(candidates),
+                )
+            else:
+                decision = self._identity.resolve(ref)
+            decision = self._apply_identity_advice(interaction, ref, decision)
+            identity_decisions[key] = decision
+            identity_map[key] = decision.person_id
+            if decision.kind == "review":
+                pending_reviews.append(
+                    (
+                        key,
+                        ReviewItem(
+                            review_id=self._ids.new_id("review"),
+                            kind="identity",
+                            message=f"Ambiguous person reference: {ref.label}",
+                            candidates=list(decision.candidates),
+                            source_text=interaction.source_text,
+                            created_at=datetime.now(timezone.utc),
+                        ),
+                    )
+                )
+            elif decision.kind == "provisional" and decision.candidates:
+                pending_reviews.append(
+                    (
+                        key,
+                        ReviewItem(
+                            review_id=self._ids.new_id("review"),
+                            kind="identity",
+                            message=(
+                                f"Recorded separate person for {decision.reason}: "
+                                f"{ref.label}"
+                            ),
+                            candidates=list(decision.candidates),
+                            source_text=interaction.source_text,
+                            created_at=datetime.now(timezone.utc),
+                        ),
+                    )
+                )
+        try:
+            result = self._memory_store.save_interaction(interaction, identity_map)
+        except Exception as exc:  # pragma: no cover - defensive boundary
+            raise PersistenceError(str(exc)) from exc
+        review_items = [
+            item.model_copy(update={"subject_person_id": result.person_ref_map.get(key)})
+            for key, item in pending_reviews
+        ]
+        for item in review_items:
+            self._review_queue.add_review_item(item)
+        enrichment_items = self._second_degree_enrichment_reviews(
+            interaction, result, identity_decisions
+        )
+        for item in enrichment_items:
+            self._review_queue.add_review_item(item)
+        merged_reviews = [*result.needs_review, *review_items, *enrichment_items]
+        opportunities = _post_capture_opportunities(
+            interaction=interaction,
+            result=result,
+            reviews=merged_reviews,
+        )
+        context_requests = _unique_context_requests(
+            request
+            for opportunity in opportunities
+            for request in opportunity.harness_context_requests
+        )
+        return result.model_copy(
+            update={
+                "needs_review": merged_reviews,
+                "capture_summary": _capture_summary(interaction, result, merged_reviews),
+                "captured_follow_ups": interaction.follow_ups,
+                "post_capture_opportunities": opportunities,
+                "harness_context_requests": context_requests,
+            }
+        )
+
+    def _extract_interaction(self, interaction: SocialInteraction) -> SocialInteraction:
+        if not self._interaction_extractor:
+            return interaction
+        try:
+            return self._interaction_extractor.extract(interaction)
+        except Exception:
+            return interaction
+
+    def _iter_person_refs(self, interaction: SocialInteraction) -> list[PersonRef]:
+        refs: list[PersonRef] = []
+        refs.extend(participant.person for participant in interaction.participants)
+        refs.extend(mentioned.person for mentioned in interaction.mentioned_people)
+        for claim in interaction.attributed_claims:
+            if claim.speaker:
+                refs.append(claim.speaker)
+            if claim.subject:
+                refs.append(claim.subject)
+        for fact in interaction.direct_facts:
+            refs.append(fact.subject)
+        for follow_up in interaction.follow_ups:
+            refs.extend(follow_up.related_people)
+        for relationship in interaction.relationships:
+            refs.extend([relationship.source, relationship.target])
+        return refs
+
+    def _ref_key(self, ref: PersonRef) -> str:
+        return ref.person_id or ref.email or ref.phone or ref.label
+
+    def _apply_identity_advice(
+        self,
+        interaction: SocialInteraction,
+        ref: PersonRef,
+        decision: IdentityDecision,
+    ) -> IdentityDecision:
+        if (
+            self._identity_advisor is None
+            or ref.person_id
+            or ref.email
+            or ref.phone
+            or not decision.candidates
+        ):
+            return decision
+        if _is_single_generated_cjk_alias_link(ref, decision):
+            return decision
+        try:
+            advice = self._identity_advisor.advise(
+                interaction=interaction,
+                ref=ref,
+                candidates=list(decision.candidates),
+            )
+        except Exception:
+            return decision
+        if decision.kind != "link":
+            return decision
+        if advice.recommendation == "different_person":
+            return IdentityDecision(
+                kind="provisional",
+                reason=_identity_advice_reason(advice),
+                candidates=decision.candidates,
+            )
+        if advice.recommendation == "ambiguous_needs_review":
+            return IdentityDecision(
+                kind="review",
+                reason=_identity_advice_reason(advice),
+                candidates=decision.candidates,
+            )
+        return decision
+
+    def _second_degree_enrichment_reviews(
+        self,
+        interaction: SocialInteraction,
+        result: RecordInteractionResult,
+        identity_decisions: dict[str, IdentityDecision],
+    ) -> list[ReviewItem]:
+        participant_keys = {
+            self._ref_key(participant.person) for participant in interaction.participants
+        }
+        relationship_targets = _relationship_targets(interaction.relationships)
+        created = set(result.created_people)
+        seen_person_ids: set[str] = set()
+        items: list[ReviewItem] = []
+        for ref, relationship_type, source_label in relationship_targets:
+            key = self._ref_key(ref)
+            if key in participant_keys:
+                continue
+            person_id = result.person_ref_map.get(key)
+            if not person_id or person_id not in created or person_id in seen_person_ids:
+                continue
+            decision = identity_decisions.get(key)
+            if decision and decision.kind != "provisional":
+                continue
+            seen_person_ids.add(person_id)
+            items.append(
+                ReviewItem(
+                    review_id=self._ids.new_id("review"),
+                    kind="relationship",
+                    message=(
+                        f"Created a provisional card for {ref.label} because "
+                        f"{_relationship_phrase(source_label, relationship_type)}. "
+                        "Add details later if useful, or mark this as second-degree only."
+                    ),
+                    subject_person_id=person_id,
+                    source_text=interaction.source_text,
+                    created_at=datetime.now(timezone.utc),
+                )
+            )
+        return items
+
+
+def _relationship_targets(
+    relationships: list[RelationshipAssertion],
+) -> list[tuple[PersonRef, str, str]]:
+    return [
+        (relationship.target, relationship.relationship_type, relationship.source.label)
+        for relationship in relationships
+    ]
+
+
+def _relationship_phrase(source_label: str, relationship_type: str) -> str:
+    if relationship_type == "friends_with":
+        return f"{source_label} is friends with them"
+    if relationship_type == "introduced_by":
+        return f"{source_label} introduced you to them"
+    if relationship_type == "knows":
+        return f"{source_label} knows them"
+    if relationship_type == "works_with":
+        return f"{source_label} works with them"
+    return f"{source_label} {relationship_type.replace('_', ' ')} them"
+
+
+def _identity_advice_reason(advice: IdentityAdvice) -> str:
+    reasons = "; ".join(advice.reasons[:2]).strip()
+    suffix = f": {reasons}" if reasons else ""
+    return f"identity advisor suggested {advice.recommendation}{suffix}"
+
+
+def _is_single_generated_cjk_alias_link(
+    ref: PersonRef, decision: IdentityDecision
+) -> bool:
+    if (
+        decision.kind != "link"
+        or decision.reason != "single exact name or alias match"
+        or len(decision.candidates) != 1
+    ):
+        return False
+    candidate = decision.candidates[0]
+    if candidate.person_id != decision.person_id or not candidate.exact_name_match:
+        return False
+    label = re.sub(r"\s+", "", ref.label.strip())
+    return label in _generated_cjk_name_aliases(candidate.display_name)
+
+
+def _generated_cjk_name_aliases(label: str) -> set[str]:
+    original = label.strip()
+    compact = re.sub(r"\s+", "", original)
+    if compact.startswith("测试"):
+        compact = compact.removeprefix("测试")
+    if not re.fullmatch(r"[\u4e00-\u9fff]{3,4}", compact):
+        return set()
+    aliases = [compact, compact[-2:]]
+    return {alias for alias in aliases if alias and alias != original}
+
+
+def _ref_key(ref: PersonRef) -> str:
+    return ref.person_id or ref.email or ref.phone or ref.label
+
+
+def _explicit_separate_person_reference(source_text: str, ref: PersonRef) -> bool:
+    if ref.person_id or ref.email or ref.phone:
+        return False
+    label = ref.label.strip()
+    if not label:
+        return False
+    escaped = re.escape(label)
+    patterns = [
+        rf"\b(?:another|a\s+different|different|new)\s+{escaped}\b",
+        rf"\b{escaped}\b[^.;。]*\b(?:is|was|are|were)?\s*(?:a\s+)?different person\b",
+        rf"\bdifferent person\s+from\s+{escaped}\b",
+        rf"(?:另一个|另外一个|另一位|另位|不同的|新的)\s*{escaped}",
+        rf"{escaped}[^。；;,.，]*(?:不同的人|不是同一个人|不是一个人)",
+        rf"和[^。；;,.，]*{escaped}[^。；;,.，]*(?:不同的人|不是同一个人|不是一个人)",
+        rf"{escaped}[^。；;,.，]*(?:不是|并不是)[^。；;,.，]*(?:同一个人|一个人)",
+    ]
+    return any(re.search(pattern, source_text, flags=re.IGNORECASE) for pattern in patterns)
+
+
+def _capture_summary(
+    interaction: SocialInteraction,
+    result: RecordInteractionResult,
+    reviews: list[ReviewItem],
+) -> CaptureSummary:
+    people: dict[str, dict[str, object]] = {}
+
+    def add_person(ref: PersonRef, role: str) -> None:
+        person_id = result.person_ref_map.get(_ref_key(ref)) or ref.person_id
+        if not person_id:
+            return
+        entry = people.setdefault(
+            person_id,
+            {
+                "labels": [],
+                "aliases": [],
+                "roles": [],
+            },
+        )
+        labels = entry["labels"]
+        aliases = entry["aliases"]
+        roles = entry["roles"]
+        if isinstance(labels, list) and ref.label not in labels:
+            labels.append(ref.label)
+        if isinstance(aliases, list):
+            for alias in ref.aliases:
+                if alias != ref.label and alias not in aliases:
+                    aliases.append(alias)
+        if isinstance(roles, list) and role not in roles:
+            roles.append(role)
+
+    for participant in interaction.participants:
+        add_person(participant.person, "participant")
+    for mentioned in interaction.mentioned_people:
+        add_person(mentioned.person, "mentioned")
+        if mentioned.mentioned_by:
+            add_person(mentioned.mentioned_by, "speaker")
+    for claim in interaction.attributed_claims:
+        if claim.speaker:
+            add_person(claim.speaker, "speaker")
+        if claim.subject:
+            add_person(claim.subject, "claim_subject")
+    for fact in interaction.direct_facts:
+        add_person(fact.subject, "direct_fact_subject")
+    for follow_up in interaction.follow_ups:
+        for ref in follow_up.related_people:
+            add_person(ref, "follow_up")
+    for relationship in interaction.relationships:
+        add_person(relationship.source, "relationship_source")
+        add_person(relationship.target, "relationship_target")
+
+    created = set(result.created_people)
+    updated = set(result.updated_people)
+    person_summaries: list[CapturedPersonSummary] = []
+    for person_id, entry in people.items():
+        labels = [str(label) for label in entry.get("labels", [])]
+        roles = [str(role) for role in entry.get("roles", [])]
+        action: Literal["created", "updated", "linked"] = "linked"
+        if person_id in created:
+            action = "created"
+        elif person_id in updated:
+            action = "updated"
+        label = _display_label(labels)
+        person_summaries.append(
+            CapturedPersonSummary(
+                person_id=person_id,
+                label=label,
+                action=action,
+                roles=roles,
+                correction_hint=(
+                    f"If {label} was matched to the wrong card, say "
+                    f"'different person: {label}'."
+                ),
+            )
+        )
+
+    details: list[str] = []
+    if interaction.place:
+        details.append(f"Place: {interaction.place}")
+    if interaction.topics:
+        details.append("Topics: " + ", ".join(interaction.topics))
+    for _person_id, entry in people.items():
+        labels = [str(label) for label in entry.get("labels", [])]
+        aliases = [str(alias) for alias in entry.get("aliases", [])]
+        if labels and aliases:
+            details.append(f"Aliases: {_display_label(labels)} also known as {', '.join(aliases)}")
+    for mentioned in interaction.mentioned_people:
+        if mentioned.mentioned_by:
+            details.append(f"{mentioned.mentioned_by.label} mentioned {mentioned.person.label}")
+        else:
+            details.append(f"Mentioned {mentioned.person.label}")
+    for claim in interaction.attributed_claims:
+        details.append(f"Attributed claim: {claim.claim_text}")
+    for relationship in interaction.relationships:
+        details.append(
+            f"Relationship: {relationship.source.label} "
+            f"{relationship.relationship_type.replace('_', ' ')} {relationship.target.label}"
+        )
+    for fact in interaction.direct_facts:
+        details.append(f"Fact: {fact.subject.label} {fact.predicate} {fact.value}")
+
+    correction_hint = (
+        "Show this brief summary to the user. If any person, fact, or follow-up "
+        "is wrong, the user can correct it immediately with phrases like "
+        "'different person', 'same person', or 'remove that follow-up'."
+    )
+    if reviews:
+        correction_hint = (
+            "Show this brief summary and the review items. Do not merge identities "
+            "until the user confirms which person is meant."
+        )
+    return CaptureSummary(
+        people=sorted(person_summaries, key=lambda item: item.label.lower()),
+        details=details,
+        follow_ups=[follow_up.description for follow_up in interaction.follow_ups],
+        reviews=[review.message for review in reviews],
+        correction_hint=correction_hint,
+    )
+
+
+def _display_label(labels: list[str]) -> str:
+    if not labels:
+        return "Unknown person"
+    return sorted(labels, key=lambda label: (len(label.split()), len(label)), reverse=True)[0]
+
+
+def _post_capture_opportunities(
+    *,
+    interaction: SocialInteraction,
+    result: RecordInteractionResult,
+    reviews: list[ReviewItem],
+) -> list[PostCaptureOpportunity]:
+    opportunities: list[PostCaptureOpportunity] = []
+    evidence = result.evidence
+    for follow_up in interaction.follow_ups:
+        related_people = _unique_person_refs(follow_up.related_people)
+        people_text = ", ".join(ref.label for ref in related_people)
+        summary = follow_up.description
+        if people_text and people_text.lower() not in summary.lower():
+            summary = f"{summary} ({people_text})"
+        time_hint = _time_hint_for_follow_up(follow_up)
+        opportunities.append(
+            PostCaptureOpportunity(
+                kind="open_loop",
+                priority="high",
+                summary=summary,
+                user_value="Prevent a social promise or next action from being forgotten.",
+                recommended_default="execute_if_supported",
+                possible_next_steps=[
+                    "create_private_one_time_reminder_without_asking",
+                    "create_private_reminder",
+                    "search_harness_memory_for_relevant_context",
+                    "draft_follow_up_message_without_sending",
+                    "add_to_private_task_manager",
+                ],
+                risk_level="low",
+                reversibility="easy",
+                external_visibility="private",
+                requires_confirmation=False,
+                undo_hint="Delete or dismiss the reminder/task if the user says it is unnecessary.",
+                time_hint=time_hint,
+                related_people=related_people,
+                harness_context_requests=[
+                    HarnessContextRequest(
+                        kind="search_harness_memory",
+                        query=_context_query(
+                            [follow_up.description, interaction.source_text, people_text]
+                        ),
+                        purpose=(
+                            "Find user-specific context, preferences, related people, or "
+                            "prior events that can make this follow-up more useful."
+                        ),
+                    ),
+                    HarnessContextRequest(
+                        kind="inspect_available_tools",
+                        query="private reminder task calendar cron draft message",
+                        purpose=(
+                            "Choose the best available low-risk reversible harness action "
+                            "for the captured follow-up."
+                        ),
+                    ),
+                ],
+                evidence=evidence,
+            )
+        )
+    opportunities.extend(_mentioned_person_opportunities(interaction, result))
+    opportunities.extend(_review_opportunities(reviews, evidence))
+    return _unique_opportunities(opportunities)
+
+
+def _mentioned_person_opportunities(
+    interaction: SocialInteraction, result: RecordInteractionResult
+) -> list[PostCaptureOpportunity]:
+    participant_keys = {
+        _ref_key(participant.person).lower() for participant in interaction.participants
+    }
+    opportunities: list[PostCaptureOpportunity] = []
+    for item in interaction.mentioned_people:
+        key = _ref_key(item.person).lower()
+        if key in participant_keys:
+            continue
+        person_id = result.person_ref_map.get(_ref_key(item.person))
+        if person_id not in result.created_people:
+            continue
+        people = [item.person]
+        if item.mentioned_by:
+            people.append(item.mentioned_by)
+        summary = f"{item.person.label} was mentioned but was not present in this interaction."
+        if item.mentioned_by:
+            summary = f"{item.mentioned_by.label} mentioned {item.person.label}."
+        opportunities.append(
+            PostCaptureOpportunity(
+                kind="context_enrichment",
+                priority="medium",
+                summary=summary,
+                user_value=(
+                    "Connect second-degree people to existing harness memory or gather "
+                    "enough context to make the network graph more useful later."
+                ),
+                recommended_default="execute_if_supported",
+                possible_next_steps=[
+                    "search_harness_memory_for_this_person",
+                    "link_to_related_events_or_projects",
+                    "mark_as_second_degree_until_user_adds_details",
+                    "ask_user_later_if_full_card_is_needed",
+                ],
+                risk_level="low",
+                reversibility="easy",
+                external_visibility="private",
+                requires_confirmation=False,
+                undo_hint="Dismiss or merge the provisional person card if it is not useful.",
+                related_people=_unique_person_refs(people),
+                harness_context_requests=[
+                    HarnessContextRequest(
+                        kind="search_harness_memory",
+                        query=_context_query([item.person.label, interaction.source_text]),
+                        purpose=(
+                            "Check whether the harness already knows useful context about "
+                            "this mentioned person, without treating it as confirmed graph evidence."
+                        ),
+                    )
+                ],
+                evidence=result.evidence,
+            )
+        )
+    return opportunities
+
+
+def _review_opportunities(
+    reviews: list[ReviewItem], evidence: list[Evidence]
+) -> list[PostCaptureOpportunity]:
+    opportunities: list[PostCaptureOpportunity] = []
+    for review in reviews:
+        if review.kind == "identity":
+            opportunities.append(
+                PostCaptureOpportunity(
+                    kind="identity_review",
+                    priority="medium",
+                    summary=review.message,
+                    user_value="Avoid accidentally merging two different people.",
+                    recommended_default="ask_first",
+                    possible_next_steps=[
+                        "show_identity_review_to_user",
+                        "defer_until_more_evidence",
+                    ],
+                    risk_level="medium",
+                    reversibility="manual",
+                    external_visibility="private",
+                    requires_confirmation=True,
+                    undo_hint="Identity merges should stay reviewable and should not be automatic.",
+                    related_people=[],
+                    evidence=list(evidence),
+                )
+            )
+    return opportunities
+
+
+def _time_hint_for_follow_up(follow_up: FollowUpTask) -> OpportunityTimeHint | None:
+    text = _extract_time_hint(follow_up.description)
+    if follow_up.due_at is None and not text:
+        return None
+    default_assumption = None
+    if follow_up.due_at is not None:
+        default_assumption = (
+            "Create a private one-time reminder/task for this date without asking; "
+            "the user can undo it by deleting or dismissing the reminder."
+        )
+    elif text:
+        default_assumption = (
+            "Use the harness or user's normal private reminder convention unless "
+            "the action is costly."
+        )
+    return OpportunityTimeHint(
+        text=text,
+        normalized_date=follow_up.due_at,
+        needs_interpretation=follow_up.due_at is None and bool(text),
+        default_assumption=default_assumption,
+    )
+
+
+def _extract_time_hint(text: str) -> str | None:
+    lowered = text.lower()
+    zh_match = re.search(
+        r"(下(?:周|星期|礼拜)[一二三四五六日天](?:上午|下午|晚上|早上)?\s*\d{1,2}点?)",
+        text,
+    )
+    if zh_match:
+        return zh_match.group(1).replace(" ", "")
+    for phrase in [
+        "today",
+        "tomorrow",
+        "next week",
+        "this week",
+        "next month",
+        "later this week",
+        "by end of next week",
+    ]:
+        if phrase in lowered:
+            return phrase
+    return None
+
+
+def _unique_person_refs(refs: list[PersonRef]) -> list[PersonRef]:
+    seen: set[str] = set()
+    result: list[PersonRef] = []
+    for ref in refs:
+        key = _ref_key(ref).lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(ref)
+    return result
+
+
+def _unique_context_requests(requests: Iterable[HarnessContextRequest]) -> list[HarnessContextRequest]:
+    seen: set[tuple[str, str]] = set()
+    result: list[HarnessContextRequest] = []
+    for request in requests:
+        key = (request.kind, request.query.lower())
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(request)
+    return result
+
+
+def _unique_opportunities(opportunities: list[PostCaptureOpportunity]) -> list[PostCaptureOpportunity]:
+    seen: set[tuple[str, str]] = set()
+    result: list[PostCaptureOpportunity] = []
+    for opportunity in opportunities:
+        key = (opportunity.kind, opportunity.summary.lower())
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(opportunity)
+    return result
+
+
+def _context_query(parts: list[str]) -> str:
+    return " ".join(part.strip() for part in parts if part and part.strip())
+
+
+class RetrieveContextService:
+    def __init__(
+        self,
+        *,
+        graph_search: GraphSearch,
+        review_queue: ReviewQueue,
+        default_sensitivity_policy: SensitivityPolicy = "personal",
+        retrieval_judge: RetrievalJudge | None = None,
+    ) -> None:
+        self._graph_search = graph_search
+        self._review_queue = review_queue
+        self._default_sensitivity_policy = default_sensitivity_policy
+        self._retrieval_judge = retrieval_judge
+
+    def retrieve(
+        self,
+        query: str,
+        *,
+        limit: int = 10,
+        include_sensitive: bool | None = None,
+        mode: str = "recall",
+        sensitivity_policy: SensitivityPolicy | None = None,
+        output_context: OutputContext = "private",
+    ) -> RetrievalResponse:
+        policy = sensitivity_policy or self._default_sensitivity_policy
+        include_sensitive_result = _should_include_sensitive(
+            include_sensitive=include_sensitive,
+            policy=policy,
+            output_context=output_context,
+        )
+        candidate_limit = max(limit * 4, limit)
+        results = self._graph_search.search(
+            query,
+            limit=candidate_limit,
+            include_sensitive=include_sensitive_result,
+            mode=mode,
+        )
+        results = _dedupe_retrieval_items(results)
+        if self._retrieval_judge:
+            results = _diversify_retrieval_items(
+                self._retrieval_judge.judge(query, results, limit=candidate_limit),
+                limit=limit,
+            )
+        else:
+            results = _diversify_retrieval_items(results, limit=limit)
+        missing_info: list[str] = []
+        if not results:
+            missing_info.append("No matching people, interactions, or facts were found.")
+        return RetrievalResponse(
+            query=query,
+            mode="brief" if mode == "brief" else "recall",
+            sensitivity_policy=policy,
+            output_context=output_context,
+            sensitive_results_included=any(
+                _has_sensitive_label(item.sensitivity) for item in results
+            ),
+            results=results,
+            missing_info=missing_info,
+            needs_review=self._review_queue.list_review_items(status="open"),
+        )
+
+
+def _dedupe_retrieval_items(items: list[RetrievalItem]) -> list[RetrievalItem]:
+    seen: set[str] = set()
+    result: list[RetrievalItem] = []
+    for item in items:
+        if item.item_id in seen:
+            continue
+        seen.add(item.item_id)
+        result.append(item)
+    return result
+
+
+def _diversify_retrieval_items(
+    items: list[RetrievalItem], *, limit: int
+) -> list[RetrievalItem]:
+    if limit <= 0:
+        return []
+    selected: list[RetrievalItem] = []
+    selected_ids: set[str] = set()
+    seen_people: set[str] = set()
+    for item in items:
+        key = _retrieval_person_key(item)
+        if key in seen_people:
+            continue
+        seen_people.add(key)
+        selected.append(item)
+        selected_ids.add(item.item_id)
+        if len(selected) >= limit:
+            return selected
+    for item in items:
+        if item.item_id in selected_ids:
+            continue
+        selected.append(item)
+        if len(selected) >= limit:
+            break
+    return selected
+
+
+def _retrieval_person_key(item: RetrievalItem) -> str:
+    if item.person_ids:
+        return "|".join(sorted(item.person_ids))
+    return item.item_id
+
+
+class BuildPersonCardService:
+    def __init__(self, *, memory_store: GraphMemoryStore, projector: PersonProjector) -> None:
+        self._memory_store = memory_store
+        self._projector = projector
+
+    def get_person(self, person_id: str) -> PersonCard | None:
+        record = self._memory_store.get_person_memory(person_id)
+        if record is None:
+            return None
+        return self._projector.build_card(record)
+
+    def get_people_by_name(self, name: str) -> list[PersonCard]:
+        return [
+            self._projector.build_card(record)
+            for record in self._memory_store.find_person_memory_by_name(name)
+        ]
+
+
+class ReviewWorkflowService:
+    def __init__(
+        self,
+        *,
+        memory_store: GraphMemoryStore,
+        review_queue: ReviewQueue,
+    ) -> None:
+        self._memory_store = memory_store
+        self._review_queue = review_queue
+
+    def list_reviews(self, *, status: str | None = "open") -> list[ReviewItem]:
+        if status == "all":
+            status = None
+        return self._review_queue.list_review_items(status=status)
+
+    def resolve_identity_review(
+        self,
+        *,
+        review_id: str,
+        source_person_id: str,
+        target_person_id: str,
+        note: str | None = None,
+    ) -> ReviewItem:
+        reviews = self._review_queue.list_review_items(status=None)
+        review = next((item for item in reviews if item.review_id == review_id), None)
+        if review is None:
+            raise PersistenceError(f"Review item not found: {review_id}")
+        if review.status != "open":
+            raise PersistenceError(f"Review item is not open: {review_id}")
+        if review.kind != "identity":
+            raise PersistenceError(f"Review item is not an identity review: {review_id}")
+        self._memory_store.merge_people(
+            source_person_id=source_person_id,
+            target_person_id=target_person_id,
+            note=note,
+        )
+        resolved = review.model_copy(
+            update={
+                "status": "resolved",
+                "resolved_to_person_id": target_person_id,
+                "resolved_at": datetime.now(timezone.utc),
+                "resolution_note": note,
+            }
+        )
+        return self._review_queue.update_review_item(resolved)
+
+    def dismiss_review(self, *, review_id: str, note: str | None = None) -> ReviewItem:
+        reviews = self._review_queue.list_review_items(status=None)
+        review = next((item for item in reviews if item.review_id == review_id), None)
+        if review is None:
+            raise PersistenceError(f"Review item not found: {review_id}")
+        if review.status != "open":
+            raise PersistenceError(f"Review item is not open: {review_id}")
+        dismissed = review.model_copy(
+            update={
+                "status": "dismissed",
+                "resolved_at": datetime.now(timezone.utc),
+                "resolution_note": note,
+            }
+        )
+        return self._review_queue.update_review_item(dismissed)
+
+
+def _should_include_sensitive(
+    *,
+    include_sensitive: bool | None,
+    policy: SensitivityPolicy,
+    output_context: OutputContext,
+) -> bool:
+    if include_sensitive is not None:
+        return include_sensitive
+    if policy == "strict":
+        return False
+    if policy == "task_aware":
+        return output_context == "private"
+    return True
+
+
+def _has_sensitive_label(labels: list[SensitivityLabel]) -> bool:
+    sensitive = {
+        SensitivityLabel.SENSITIVE,
+        SensitivityLabel.DO_NOT_SURFACE_UNPROMPTED,
+    }
+    return any(label in sensitive for label in labels)