@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/infrastructure/llm_judge.py

@@ -0,0 +1,162 @@
+"""Optional OpenAI-compatible final retrieval judge."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from people_network_memory.config import PeopleMemoryConfig
+from people_network_memory.domain.models import RetrievalItem
+from people_network_memory.ports.errors import ConfigError
+
+
+@dataclass(frozen=True)
+class LlmJudgeSettings:
+    base_url: str
+    model: str
+    api_key: str
+    timeout_seconds: float = 30.0
+    response_format: str = "none"
+
+    @classmethod
+    def from_config(cls, config: PeopleMemoryConfig) -> "LlmJudgeSettings":
+        missing: list[str] = []
+        if not config.llm_base_url:
+            missing.append("PEOPLE_MEMORY_LLM_BASE_URL")
+        if not config.llm_model:
+            missing.append("PEOPLE_MEMORY_LLM_MODEL")
+        if not config.llm_api_key:
+            missing.append("PEOPLE_MEMORY_LLM_API_KEY")
+        if missing:
+            raise ConfigError("LLM retrieval judge requires: " + ", ".join(missing))
+        return cls(
+            base_url=config.llm_base_url or "",
+            model=config.llm_model or "",
+            api_key=config.llm_api_key or "",
+            timeout_seconds=config.retrieval_judge_timeout_seconds,
+            response_format=config.llm_response_format,
+        )
+
+
+class OpenAICompatibleRetrievalJudge:
+    """Rerank already-retrieved candidates using a small JSON LLM decision."""
+
+    def __init__(self, settings: LlmJudgeSettings) -> None:
+        self._settings = settings
+
+    @classmethod
+    def from_config(cls, config: PeopleMemoryConfig) -> "OpenAICompatibleRetrievalJudge":
+        return cls(LlmJudgeSettings.from_config(config))
+
+    def judge(
+        self,
+        query: str,
+        candidates: list[RetrievalItem],
+        *,
+        limit: int,
+    ) -> list[RetrievalItem]:
+        if not candidates:
+            return []
+        try:
+            ranked_ids = self._request_ranked_ids(query, candidates, limit=limit)
+        except (httpx.HTTPError, ValueError, KeyError, TypeError, json.JSONDecodeError):
+            return candidates[:limit]
+        by_id = {item.item_id: item for item in candidates}
+        ranked = [by_id[item_id] for item_id in ranked_ids if item_id in by_id]
+        seen = {item.item_id for item in ranked}
+        ranked.extend(item for item in candidates if item.item_id not in seen)
+        return ranked[:limit]
+
+    def _request_ranked_ids(
+        self,
+        query: str,
+        candidates: list[RetrievalItem],
+        *,
+        limit: int,
+    ) -> list[str]:
+        url = self._settings.base_url.rstrip("/") + "/chat/completions"
+        payload: dict[str, Any] = {
+            "model": self._settings.model,
+            "messages": [
+                {
+                    "role": "system",
+                    "content": (
+                        "You are a retrieval judge for a personal network memory tool. "
+                        "Rank only candidates that directly answer the query. Prefer one "
+                        "candidate that satisfies all query constraints for the same person. "
+                        "Return JSON with ranked_item_ids and rejected_item_ids."
+                    ),
+                },
+                {
+                    "role": "user",
+                    "content": json.dumps(
+                        {
+                            "query": query,
+                            "limit": limit,
+                            "candidates": [_candidate_payload(item) for item in candidates],
+                        },
+                        ensure_ascii=False,
+                    ),
+                },
+            ],
+            "temperature": 0,
+        }
+        if self._settings.response_format == "json_object":
+            payload["response_format"] = {"type": "json_object"}
+        response = httpx.post(
+            url,
+            headers={
+                "Authorization": f"Bearer {self._settings.api_key}",
+                "Content-Type": "application/json",
+            },
+            json=payload,
+            timeout=self._settings.timeout_seconds,
+        )
+        response.raise_for_status()
+        content = response.json()["choices"][0]["message"]["content"]
+        parsed = _parse_json_object(content)
+        ranked = parsed.get("ranked_item_ids", [])
+        if not isinstance(ranked, list):
+            raise ValueError("LLM judge response ranked_item_ids must be a list")
+        return [str(item_id) for item_id in ranked]
+
+
+def _candidate_payload(item: RetrievalItem) -> dict[str, object]:
+    return {
+        "item_id": item.item_id,
+        "kind": item.kind,
+        "title": item.title,
+        "matched_text": item.matched_text,
+        "why_matched": item.why_matched,
+        "person_ids": item.person_ids,
+        "evidence": [
+            {
+                "evidence_id": evidence.evidence_id,
+                "source_text": evidence.source_text,
+                "recorded_at": evidence.recorded_at.isoformat(),
+            }
+            for evidence in item.evidence[:3]
+        ],
+    }
+
+
+def _parse_json_object(text: str) -> dict[str, Any]:
+    stripped = text.strip()
+    if stripped.startswith("```"):
+        lines = stripped.splitlines()
+        if len(lines) >= 3 and lines[-1].strip() == "```":
+            stripped = "\n".join(lines[1:-1]).strip()
+    try:
+        parsed = json.loads(stripped)
+    except json.JSONDecodeError:
+        start = stripped.find("{")
+        end = stripped.rfind("}")
+        if start < 0 or end <= start:
+            raise
+        parsed = json.loads(stripped[start : end + 1])
+    if not isinstance(parsed, dict):
+        raise ValueError("LLM judge response must be a JSON object")
+    return parsed

package/src/people_network_memory/infrastructure/redaction.py

@@ -0,0 +1,21 @@
+"""Redaction helpers for logs and diagnostics."""
+
+from __future__ import annotations
+
+import re
+
+
+EMAIL_RE = re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")
+PHONE_RE = re.compile(r"(?<!\d)(?:\+?\d[\d\s().-]{6,}\d)(?!\d)")
+SENSITIVE_MARKERS = re.compile(
+    r"\b(?:leaving|salary|compensation|health|private|confidential|sensitive)\b",
+    flags=re.IGNORECASE,
+)
+
+
+def redact_sensitive_text(text: str) -> str:
+    redacted = EMAIL_RE.sub("[REDACTED_EMAIL]", text)
+    redacted = PHONE_RE.sub("[REDACTED_PHONE]", redacted)
+    redacted = SENSITIVE_MARKERS.sub("[REDACTED_SENSITIVE]", redacted)
+    return redacted
+

package/src/people_network_memory/infrastructure/release_check.py

@@ -0,0 +1,186 @@
+"""Local V1 release readiness checks."""
+
+from __future__ import annotations
+
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from people_network_memory.config import PeopleMemoryConfig
+from people_network_memory.fixtures.eval import evaluate_dataset
+from people_network_memory.fixtures.generator import generate_mock_dataset
+from people_network_memory.harness_adapters.openclaw.integration_eval import (
+    run_harness_memory_integration_eval,
+)
+from people_network_memory.harness_adapters.openclaw.smoke import run_openclaw_adapter_smoke
+from people_network_memory.infrastructure.archive_backup import (
+    create_archive_backup,
+    restore_archive_backup,
+)
+from people_network_memory.infrastructure.redaction import redact_sensitive_text
+from people_network_memory.mcp_server.contracts import public_tool_contracts, public_tool_names
+from people_network_memory.mcp_server.runtime import build_runtime
+
+
+@dataclass(frozen=True)
+class ReleaseCheck:
+    name: str
+    ok: bool
+    detail: dict[str, Any]
+
+    def to_json(self) -> dict[str, Any]:
+        return {"name": self.name, "ok": self.ok, "detail": self.detail}
+
+
+def run_local_release_check() -> dict[str, Any]:
+    checks = [
+        _check_test_mode_mcp_start(),
+        _check_tool_contracts(),
+        _check_fixture_eval(),
+        _check_openclaw_smoke(),
+        _check_harness_memory_integration(),
+        _check_backup_restore(),
+        _check_redaction(),
+    ]
+    return {
+        "ok": all(check.ok for check in checks),
+        "scope": "local_v1",
+        "checks": [check.to_json() for check in checks],
+    }
+
+
+def _check_test_mode_mcp_start() -> ReleaseCheck:
+    runtime = build_runtime(PeopleMemoryConfig(test_mode=True))
+    try:
+        tools = sorted(runtime.tools.tool_names())
+        expected = sorted(public_tool_names())
+        return ReleaseCheck(
+            name="mcp_test_mode_start",
+            ok=tools == expected,
+            detail={"tools": tools, "expected_tools": expected},
+        )
+    finally:
+        runtime.close()
+
+
+def _check_tool_contracts() -> ReleaseCheck:
+    contracts = public_tool_contracts()
+    names = [contract["name"] for contract in contracts]
+    return ReleaseCheck(
+        name="tool_contracts",
+        ok=names == public_tool_names() and all(contract["version"] == "v1" for contract in contracts),
+        detail={"contract_version": "v1", "tool_names": names},
+    )
+
+
+def _check_fixture_eval() -> ReleaseCheck:
+    result = evaluate_dataset(generate_mock_dataset(seed=42))
+    payload = result.to_json(include_cases=False)
+    return ReleaseCheck(
+        name="fixture_retrieval_eval",
+        ok=bool(payload["passes_v1_thresholds"]),
+        detail={
+            "checked": payload["checked"],
+            "recall_at_3": payload["recall_at_3"],
+            "recall_at_5": payload["recall_at_5"],
+            "returned_result_evidence_rate": payload["returned_result_evidence_rate"],
+            "sensitive_leaks": payload["sensitive_leaks"],
+            "no_result_count": payload["no_result_count"],
+        },
+    )
+
+
+def _check_openclaw_smoke() -> ReleaseCheck:
+    payload = run_openclaw_adapter_smoke()
+    return ReleaseCheck(
+        name="openclaw_adapter_smoke",
+        ok=bool(payload["ok"]),
+        detail={
+            "workflow_ok": payload["workflow"]["ok"],
+            "route_checks": [
+                {"prompt": item["prompt"], "ok": item["ok"], "actual": item["actual"]}
+                for item in payload["route_checks"]
+            ],
+        },
+    )
+
+
+def _check_harness_memory_integration() -> ReleaseCheck:
+    payload = run_harness_memory_integration_eval()
+    return ReleaseCheck(
+        name="harness_memory_integration_eval",
+        ok=bool(payload["ok"]),
+        detail={
+            "checked": payload["checked"],
+            "passed": payload["passed"],
+            "failed": payload["failed"],
+            "failed_cases": [
+                case["case"]["case_id"] for case in payload["cases"] if not case["ok"]
+            ],
+        },
+    )
+
+
+def _check_backup_restore() -> ReleaseCheck:
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        data_path = root / "data"
+        restore_path = root / "restore"
+        archive_path = root / "backup.zip"
+        runtime = build_runtime(
+            PeopleMemoryConfig(backend="local_json", data_path=str(data_path))
+        )
+        try:
+            runtime.tools.record_interaction(
+                {
+                    "source_text": (
+                        "Remember Alice Zhang. Alice Zhang works at Tencent Robotics "
+                        "as product lead. Alice Zhang studied at Tsinghua."
+                    )
+                }
+            )
+        finally:
+            runtime.close()
+        backup = create_archive_backup(
+            PeopleMemoryConfig(backend="local_json", data_path=str(data_path)),
+            archive_path,
+        )
+        restore = restore_archive_backup(
+            PeopleMemoryConfig(backend="local_json", data_path=str(restore_path)),
+            archive_path,
+            confirm="OVERWRITE",
+        )
+        restored_runtime = build_runtime(
+            PeopleMemoryConfig(backend="local_json", data_path=str(restore_path))
+        )
+        try:
+            card = restored_runtime.tools.get_person({"person_id": "person_0001"})
+        finally:
+            restored_runtime.close()
+        ok = bool(backup["ok"]) and bool(restore["ok"]) and bool(card["found"])
+        return ReleaseCheck(
+            name="backup_restore_roundtrip",
+            ok=ok,
+            detail={
+                "backup_people": backup["people"],
+                "restore_people": restore["people"],
+                "person_found": card["found"],
+                "display_name": card.get("display_name"),
+            },
+        )
+
+
+def _check_redaction() -> ReleaseCheck:
+    sample = "Email alice@example.com or +1 415 555 1234 about private salary."
+    redacted = redact_sensitive_text(sample)
+    leaked = [
+        token
+        for token in ["alice@example.com", "+1 415 555 1234", "private", "salary"]
+        if token in redacted
+    ]
+    return ReleaseCheck(
+        name="redaction",
+        ok=not leaked,
+        detail={"leaked_tokens": leaked, "redacted": redacted},
+    )

package/src/people_network_memory/infrastructure/retrieval_intent.py

@@ -0,0 +1,98 @@
+"""Small query-intent helpers for retrieval and eval.
+
+These are intentionally deterministic. They do not replace semantic search;
+they keep common social-memory intents from being scored by accidental token
+overlap alone.
+"""
+
+from __future__ import annotations
+
+import re
+
+
+MENTIONED_QUERY_RE = re.compile(
+    r"\bwho\s+(?:mentioned|said|told\s+me\s+about)\s+(?P<target>.+?)\s*$",
+    flags=re.IGNORECASE,
+)
+CHINESE_TARGET_WHO_MENTIONED_RE = re.compile(
+    r"(?P<target>[\u4e00-\u9fffA-Za-z0-9 _-]{1,40})是谁(?:提到|提起|说到)的"
+)
+CHINESE_MENTIONED_QUERY_RE = re.compile(r"(?:谁|誰).*(?:提到|提起|说到)(?P<target>.+?)$")
+
+
+def mentioned_query_target(query: str) -> str | None:
+    stripped = query.strip(" ?.!。！？")
+    match = MENTIONED_QUERY_RE.search(stripped)
+    if match:
+        return _clean_target(match.group("target"))
+    match = CHINESE_TARGET_WHO_MENTIONED_RE.search(stripped)
+    if match:
+        return _clean_target(match.group("target"))
+    match = CHINESE_MENTIONED_QUERY_RE.search(stripped)
+    if match:
+        return _clean_target(match.group("target"))
+    return None
+
+
+def is_follow_up_query(query: str) -> bool:
+    lowered = query.lower()
+    return any(
+        term in lowered
+        for term in [
+            "follow up",
+            "follow-up",
+            "promise",
+            "promised",
+            "commitment",
+            "what did i promise",
+            "owe",
+            "owed",
+            "what do i owe",
+            "todo",
+            "next step",
+        ]
+    ) or any(term in query for term in ["跟进", "承诺", "答应", "待办"])
+
+
+def text_answers_mentioned_query(text: str, target: str) -> bool:
+    lowered = _squash(text)
+    target_lower = _squash(target)
+    if not target_lower or target_lower not in lowered:
+        return False
+    if re.search(rf"\b(?:mentioned|said|told)\b.*\b{re.escape(target_lower)}\b", lowered):
+        return True
+    if re.search(rf"\b{re.escape(target_lower)}\b.*\b(?:was|is)\s+mentioned\b", lowered):
+        return True
+    compact = lowered.replace(" ", "")
+    compact_target = target_lower.replace(" ", "")
+    return (
+        f"提到{compact_target}" in compact
+        or f"提起{compact_target}" in compact
+        or f"说到{compact_target}" in compact
+    )
+
+
+def person_is_only_mentioned_target(
+    *,
+    person_label: str,
+    target_label: str,
+    mentioned_pairs: list[tuple[str, str | None]],
+) -> bool:
+    if _squash(person_label) != _squash(target_label):
+        return False
+    person = _squash(person_label)
+    target = _squash(target_label)
+    was_target = any(_squash(mentioned) == target for mentioned, _ in mentioned_pairs)
+    was_speaker_for_target = any(
+        _squash(mentioned) == target and _squash(speaker or "") == person
+        for mentioned, speaker in mentioned_pairs
+    )
+    return was_target and not was_speaker_for_target
+
+
+def _clean_target(value: str) -> str:
+    return value.strip(" ?.!。！？'\"")
+
+
+def _squash(value: str) -> str:
+    return re.sub(r"\s+", " ", value.strip().lower())