@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/harness_adapters/openclaw/smoke.py

@@ -0,0 +1,292 @@
+"""OpenClaw adapter smoke checks.
+
+These checks do not try to automate OpenClaw itself. They verify the adapter
+surface that OpenClaw depends on: install materialization, prompt-routing
+expectations, and the three public MCP tool workflows.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from people_network_memory.config import PeopleMemoryConfig
+from people_network_memory.harness_adapters.openclaw.installer import (
+    SKILL_MARKDOWN,
+    install_openclaw_adapter,
+    openclaw_checks,
+)
+from people_network_memory.mcp_server.runtime import build_runtime
+
+
+ToolName = Literal["record_interaction", "retrieve_network_context", "get_person"]
+
+
+@dataclass(frozen=True)
+class PromptRouteCase:
+    prompt: str
+    expected_tool: ToolName
+    expected_mode: Literal["recall", "brief"] | None = None
+
+    def to_json(self) -> dict[str, object]:
+        payload: dict[str, object] = {
+            "prompt": self.prompt,
+            "expected_tool": self.expected_tool,
+        }
+        if self.expected_mode:
+            payload["expected_mode"] = self.expected_mode
+        return payload
+
+
+PROMPT_ROUTE_CASES = [
+    PromptRouteCase(
+        prompt="Remember Alice Zhang. Alice works at Tencent Robotics as product lead.",
+        expected_tool="record_interaction",
+    ),
+    PromptRouteCase(
+        prompt="Met Alice Zhang at Blue Bottle and discussed robotics hiring.",
+        expected_tool="record_interaction",
+    ),
+    PromptRouteCase(
+        prompt="今天在潘家园见了胡八一（胖子），聊了北京的项目。",
+        expected_tool="record_interaction",
+    ),
+    PromptRouteCase(
+        prompt="Who was the robotics person I met at the coffee shop?",
+        expected_tool="retrieve_network_context",
+        expected_mode="recall",
+    ),
+    PromptRouteCase(
+        prompt="Brief me before I meet Alice Zhang.",
+        expected_tool="retrieve_network_context",
+        expected_mode="brief",
+    ),
+    PromptRouteCase(
+        prompt="Who should I invite to dinner in Shanghai for robotics and founder intros?",
+        expected_tool="retrieve_network_context",
+        expected_mode="recall",
+    ),
+    PromptRouteCase(
+        prompt="Draft a warm intro message to Alice Zhang about the robotics founder dinner.",
+        expected_tool="retrieve_network_context",
+        expected_mode="recall",
+    ),
+    PromptRouteCase(
+        prompt="Open the person card for person_0001.",
+        expected_tool="get_person",
+    ),
+    PromptRouteCase(
+        prompt="Show me Alice Zhang's person card.",
+        expected_tool="get_person",
+    ),
+    PromptRouteCase(
+        prompt="Remember that I met Test Clara Wu today at % Arabica. She works on AI hardware hiring.",
+        expected_tool="record_interaction",
+    ),
+    PromptRouteCase(
+        prompt="/ppl Remember that I met Test Clara Wu today at % Arabica.",
+        expected_tool="record_interaction",
+    ),
+    PromptRouteCase(
+        prompt="/people_network_memory Remember that I met Test Clara Wu today at % Arabica.",
+        expected_tool="record_interaction",
+    ),
+    PromptRouteCase(
+        prompt="/people-network-memory Show me Test Clara Wu's person card.",
+        expected_tool="get_person",
+    ),
+]
+
+
+def route_prompt_for_openclaw_skill(prompt: str) -> dict[str, object]:
+    """Deterministic guardrail for the skill examples and prompt tests."""
+
+    lowered = prompt.lower()
+    if "person card" in lowered or "get_person" in lowered:
+        return {"tool": "get_person"}
+    if "brief" in lowered or "before i meet" in lowered:
+        return {"tool": "retrieve_network_context", "mode": "brief"}
+    recall_markers = [
+        "who was",
+        "who should",
+        "find",
+        "recall",
+        "search",
+        "who did",
+        "which person",
+        "recommend",
+        "draft",
+        "intro message",
+        "invite",
+    ]
+    if any(marker in lowered for marker in recall_markers):
+        return {"tool": "retrieve_network_context", "mode": "recall"}
+    capture_markers = [
+        "remember",
+        "met ",
+        "spoke with",
+        "had coffee",
+        "had dinner",
+        "called",
+        "add ",
+        "save ",
+        "见了",
+        "记住",
+        "记录",
+        "保存",
+        "认识了",
+        "遇到",
+        "提到",
+    ]
+    if any(marker in lowered for marker in capture_markers):
+        return {"tool": "record_interaction"}
+    return {"tool": "retrieve_network_context", "mode": "recall"}
+
+
+def run_openclaw_adapter_smoke(
+    *,
+    home: str | Path | None = None,
+    install: bool = True,
+    backend: str = "local_json",
+) -> dict[str, Any]:
+    temp_home: tempfile.TemporaryDirectory[str] | None = None
+    if home is None:
+        temp_home = tempfile.TemporaryDirectory()
+        home = temp_home.name
+    try:
+        install_result = (
+            install_openclaw_adapter(home=home, backend=backend) if install else None
+        )
+        checks = [check.to_json() for check in openclaw_checks(home)]
+        route_checks = _route_checks()
+        workflow = _workflow_smoke()
+        ok = all(check["ok"] for check in checks) and all(
+            case["ok"] for case in route_checks
+        ) and workflow["ok"]
+        payload: dict[str, Any] = {
+            "ok": ok,
+            "home": str(Path(home).expanduser()),
+            "installed": install_result.to_json() if install_result else None,
+            "checks": checks,
+            "route_checks": route_checks,
+            "workflow": workflow,
+        }
+        return payload
+    finally:
+        if temp_home is not None:
+            temp_home.cleanup()
+
+
+def _route_checks() -> list[dict[str, object]]:
+    checks = []
+    for case in PROMPT_ROUTE_CASES:
+        actual = route_prompt_for_openclaw_skill(case.prompt)
+        expected = {"tool": case.expected_tool}
+        if case.expected_mode:
+            expected["mode"] = case.expected_mode
+        checks.append(
+            {
+                **case.to_json(),
+                "actual": actual,
+                "ok": all(actual.get(key) == value for key, value in expected.items()),
+            }
+        )
+    return checks
+
+
+def _workflow_smoke() -> dict[str, Any]:
+    runtime = build_runtime(PeopleMemoryConfig(test_mode=True))
+    try:
+        record = runtime.tools.record_interaction(
+            {
+                "source_text": (
+                    "Met Alice Zhang at Blue Bottle Coffee. We discussed robotics hiring. "
+                    "Alice Zhang mentioned Bob Li may be useful for founder intros. "
+                    "I promised to send Alice Zhang two founder contacts next week."
+                )
+            }
+        )
+        recall = runtime.tools.retrieve_network_context(
+            {"query": "robotics person from Blue Bottle", "limit": 5}
+        )
+        brief = runtime.tools.retrieve_network_context(
+            {"query": "Brief me before I meet Alice Zhang", "mode": "brief", "limit": 5}
+        )
+        person_id = record["person_ref_map"].get("Alice Zhang") or "person_0001"
+        card = runtime.tools.get_person({"person_id": person_id})
+        ok = (
+            bool(record["saved"])
+            and bool(record["post_capture_opportunities"])
+            and bool(record["harness_context_requests"])
+            and bool(recall["results"])
+            and bool(brief["results"])
+            and bool(card["found"])
+            and card["display_name"] == "Alice Zhang"
+        )
+        return {
+            "ok": ok,
+            "record_created_people": record["created_people"],
+            "post_capture_opportunity_count": len(record["post_capture_opportunities"]),
+            "harness_context_request_count": len(record["harness_context_requests"]),
+            "recall_result_count": len(recall["results"]),
+            "brief_result_count": len(brief["results"]),
+            "person_found": card["found"],
+            "person_display_name": card.get("display_name"),
+        }
+    finally:
+        runtime.close()
+
+
+def skill_contains_required_routing_text(skill_text: str = SKILL_MARKDOWN) -> dict[str, object]:
+    required = [
+        "/ppl",
+        "/people_network_memory",
+        "/people-network-memory",
+        "Remove only that trigger prefix before saving `source_text`",
+        "record_interaction",
+        "retrieve_network_context",
+        "get_person",
+        "people-network-memory__record_interaction",
+        "people-network-memory__retrieve_network_context",
+        "people-network-memory__get_person",
+        "Do not call a tool named `ppl` or `people-network-memory`",
+        "Do not satisfy a people-memory request by only reading or writing OpenClaw `MEMORY.md`",
+        "Never use OpenClaw `read`, `write`, or `edit` as a substitute",
+        "call `get_person` again even if the same card was shown earlier",
+        "If `get_person` returns `found=false` with `ambiguous=true`",
+        "If `retrieve_network_context` returns `ambiguous=true`",
+        "final_answer_instruction",
+        "do not choose one candidate",
+        "render the `get_person` JSON result directly inline in chat",
+        "Unauthorized",
+        "present the card inline",
+        "Do not use canvas, browser, hosted embeds, local URLs, or OpenClaw memory files",
+        "Preserve the user's original wording",
+        "Separate participants from mentioned people",
+        "attributed claim",
+        "Preserve Chinese names and aliases exactly",
+        "胡八一（胖子）",
+        "tool-side LLM extractor",
+        "provisional second-degree card",
+        "post_capture_opportunities",
+        "harness_context_requests",
+        "capture_summary",
+        "brief capture summary",
+        "correction checkpoint",
+        "proactively execute low-risk",
+        "Action:",
+        "Why:",
+        "Undo:",
+        "source of truth for the user's people/network memory",
+        "source of truth for the user's stable preferences",
+        "Combine both memory sources deliberately",
+        "If the harness memory and MCP evidence conflict",
+        "For exact-name questions where multiple person cards share the same display name",
+        "do not say \"you probably mean\"",
+        "For ambiguous yes/no questions",
+        "mode=\"brief\"",
+    ]
+    missing = [item for item in required if item not in skill_text]
+    return {"ok": not missing, "missing": missing}

package/src/people_network_memory/infrastructure/__init__.py

@@ -0,0 +1,2 @@
+"""Local infrastructure adapters."""
+

package/src/people_network_memory/infrastructure/archive_backup.py

@@ -0,0 +1,171 @@
+"""Archive backup and restore helpers for local data backends."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from people_network_memory.config import PeopleMemoryConfig
+from people_network_memory.infrastructure.file_store import JsonPeopleStore, local_json_path
+from people_network_memory.ports.errors import PersistenceError
+
+
+MANIFEST_NAME = "manifest.json"
+PROJECTION_NAME = "projection.json"
+KUZU_PREFIX = "graphiti_kuzu"
+
+
+def create_archive_backup(config: PeopleMemoryConfig, output: str | Path) -> dict[str, Any]:
+    output_path = Path(output).expanduser()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    projection = _read_projection_payload(config)
+    manifest: dict[str, Any] = {
+        "schema_version": 1,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "backend": config.backend,
+        "data_path": str(Path(config.data_path).expanduser()),
+        "graph_backend_kind": config.graph_backend_kind,
+        "graphiti_kuzu_path": str(Path(config.graphiti_kuzu_path).expanduser()),
+        "includes": [PROJECTION_NAME],
+    }
+
+    kuzu_path = Path(config.graphiti_kuzu_path).expanduser()
+    if config.backend == "graphiti" and config.graph_backend_kind == "kuzu" and kuzu_path.exists():
+        manifest["includes"].append(KUZU_PREFIX)
+        manifest["kuzu_kind"] = "directory" if kuzu_path.is_dir() else "file"
+
+    with zipfile.ZipFile(output_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        archive.writestr(MANIFEST_NAME, json.dumps(manifest, ensure_ascii=False, indent=2))
+        archive.writestr(PROJECTION_NAME, json.dumps(projection, ensure_ascii=False, indent=2))
+        if config.backend == "graphiti" and kuzu_path.exists():
+            _write_path_to_archive(archive, kuzu_path, KUZU_PREFIX)
+
+    return {
+        "ok": True,
+        "output": str(output_path),
+        "backend": config.backend,
+        "people": len(projection.get("people", [])),
+        "includes": manifest["includes"],
+    }
+
+
+def restore_archive_backup(
+    config: PeopleMemoryConfig, archive_path: str | Path, *, confirm: str
+) -> dict[str, Any]:
+    if confirm != "OVERWRITE":
+        raise PersistenceError("restore-archive requires --confirm OVERWRITE")
+    source = Path(archive_path).expanduser()
+    if not source.exists():
+        raise PersistenceError(f"Archive does not exist: {source}")
+
+    with zipfile.ZipFile(source, "r") as archive:
+        _validate_archive_members(archive)
+        manifest = json.loads(archive.read(MANIFEST_NAME).decode("utf-8"))
+        projection = json.loads(archive.read(PROJECTION_NAME).decode("utf-8"))
+        JsonPeopleStore.validate_export_payload(projection)
+
+        if config.backend == "graphiti":
+            restored_to = _restore_graphiti_archive(config, archive, projection, manifest)
+        else:
+            target = local_json_path(config)
+            JsonPeopleStore.restore_to_path(target, projection)
+            restored_to = [str(target)]
+
+    return {
+        "ok": True,
+        "input": str(source),
+        "backend": config.backend,
+        "archive_backend": manifest.get("backend"),
+        "restored_to": restored_to,
+        "people": len(projection.get("people", [])),
+    }
+
+
+def _read_projection_payload(config: PeopleMemoryConfig) -> dict[str, Any]:
+    if config.backend == "graphiti":
+        path = Path(config.data_path).expanduser() / "people-memory.graphiti-cache.json"
+    else:
+        path = local_json_path(config)
+    if not path.exists():
+        return {"people": [], "review_items": [], "interactions": []}
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return JsonPeopleStore.validate_export_payload(payload)
+
+
+def _write_path_to_archive(archive: zipfile.ZipFile, path: Path, prefix: str) -> None:
+    if path.is_file():
+        archive.write(path, f"{prefix}/{path.name}")
+        return
+    for child in path.rglob("*"):
+        if child.is_file():
+            archive.write(child, f"{prefix}/{child.relative_to(path).as_posix()}")
+
+
+def _restore_graphiti_archive(
+    config: PeopleMemoryConfig,
+    archive: zipfile.ZipFile,
+    projection: dict[str, Any],
+    manifest: dict[str, Any],
+) -> list[str]:
+    restored: list[str] = []
+    cache_path = Path(config.data_path).expanduser() / "people-memory.graphiti-cache.json"
+    JsonPeopleStore.restore_to_path(cache_path, projection)
+    restored.append(str(cache_path))
+
+    kuzu_members = [
+        name
+        for name in archive.namelist()
+        if name.startswith(f"{KUZU_PREFIX}/") and not name.endswith("/")
+    ]
+    if kuzu_members:
+        target = Path(config.graphiti_kuzu_path).expanduser()
+        _assert_safe_graphiti_target(target)
+        with tempfile.TemporaryDirectory() as tmp:
+            temp_root = Path(tmp) / KUZU_PREFIX
+            for name in kuzu_members:
+                relative = PurePosixPath(name).relative_to(KUZU_PREFIX)
+                destination = temp_root.joinpath(*relative.parts)
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                destination.write_bytes(archive.read(name))
+            if manifest.get("kuzu_kind") == "file":
+                source_file = next(path for path in temp_root.rglob("*") if path.is_file())
+                target.parent.mkdir(parents=True, exist_ok=True)
+                if target.exists():
+                    target.unlink()
+                shutil.copy2(source_file, target)
+            else:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                if target.exists():
+                    shutil.rmtree(target)
+                shutil.copytree(temp_root, target)
+        restored.append(str(target))
+    return restored
+
+
+def _validate_archive_members(archive: zipfile.ZipFile) -> None:
+    names = archive.namelist()
+    if MANIFEST_NAME not in names or PROJECTION_NAME not in names:
+        raise PersistenceError("Archive must contain manifest.json and projection.json")
+    for name in names:
+        path = PurePosixPath(name)
+        if path.is_absolute() or ".." in path.parts:
+            raise PersistenceError(f"Unsafe archive member path: {name}")
+
+
+def _assert_safe_graphiti_target(path: Path) -> None:
+    resolved = path.resolve()
+    if resolved.parent == resolved:
+        raise PersistenceError(f"Refusing to overwrite filesystem root: {resolved}")
+    if resolved == Path.home().resolve():
+        raise PersistenceError(f"Refusing to overwrite home directory: {resolved}")
+    lowered = resolved.name.lower()
+    if "graphiti" not in lowered and not lowered.endswith(".kuzu"):
+        raise PersistenceError(
+            "Refusing to overwrite graph backend path without graphiti/.kuzu in the name: "
+            f"{resolved}"
+        )

package/src/people_network_memory/infrastructure/diagnostics.py

@@ -0,0 +1,171 @@
+"""Environment diagnostics for local setup and spike gates."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from dataclasses import dataclass
+
+from people_network_memory.config import PeopleMemoryConfig
+from people_network_memory.infrastructure.embeddings import EmbeddingSettings
+from people_network_memory.ports.errors import PeopleMemoryError
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    ok: bool
+    detail: str | None = None
+    remediation: str | None = None
+
+    def to_json(self) -> dict[str, object]:
+        payload: dict[str, object] = {"name": self.name, "ok": self.ok}
+        if self.detail:
+            payload["detail"] = self.detail
+        if self.remediation:
+            payload["remediation"] = self.remediation
+        return payload
+
+
+def graphiti_spike_checks(config: PeopleMemoryConfig) -> list[CheckResult]:
+    graphiti_package = "graphiti" + "_core"
+    graphiti_installed = importlib.util.find_spec(graphiti_package) is not None
+    kuzu_installed = importlib.util.find_spec("kuzu") is not None
+    checks = [
+        CheckResult(
+            name="graphiti_core_package",
+            ok=graphiti_installed,
+            detail=f"{graphiti_package} importable"
+            if graphiti_installed
+            else f"{graphiti_package} is not installed",
+            remediation="Install graphiti-core in an environment with compatible numpy wheels.",
+        ),
+        _graph_backend_check(config, kuzu_installed),
+        _embedding_settings_check(config),
+        _llm_settings_check(config),
+        _graphiti_projection_path_check(config),
+        CheckResult(
+            name="telemetry_disabled",
+            ok=not config.telemetry_enabled,
+            detail=(
+                "GRAPHITI_TELEMETRY_ENABLED is false"
+                if not config.telemetry_enabled
+                else "GRAPHITI_TELEMETRY_ENABLED is true"
+            ),
+            remediation="Set GRAPHITI_TELEMETRY_ENABLED=false for local personal data.",
+        ),
+    ]
+    return checks
+
+
+def _graph_backend_check(config: PeopleMemoryConfig, kuzu_installed: bool) -> CheckResult:
+    if config.graph_backend_kind == "kuzu":
+        path = Path(config.graphiti_kuzu_path).expanduser()
+        nearest = path.parent
+        while not nearest.exists() and nearest.parent != nearest:
+            nearest = nearest.parent
+        ok = kuzu_installed and nearest.exists() and _path_is_writable(nearest)
+        detail = (
+            f"kuzu importable; database path={path}; nearest existing parent={nearest}"
+            if kuzu_installed
+            else "kuzu package is not installed"
+        )
+        return CheckResult(
+            name="graph_backend_kuzu",
+            ok=ok,
+            detail=detail,
+            remediation="Install graphiti-core[kuzu] in the Python 3.11 venv."
+            if not kuzu_installed
+            else "Create or choose a writable parent directory for PEOPLE_MEMORY_GRAPHITI_KUZU_PATH.",
+        )
+    ok = bool(config.graph_backend_url)
+    return CheckResult(
+        name=f"graph_backend_{config.graph_backend_kind}",
+        ok=ok,
+        detail=config.graph_backend_url or "PEOPLE_MEMORY_GRAPH_BACKEND_URL is not set",
+        remediation="Set PEOPLE_MEMORY_GRAPH_BACKEND_URL for the chosen graph backend.",
+    )
+
+
+def _embedding_settings_check(config: PeopleMemoryConfig) -> CheckResult:
+    try:
+        settings = EmbeddingSettings.from_config(config)
+    except PeopleMemoryError as exc:
+        return CheckResult(
+            name="embedding_settings",
+            ok=False,
+            detail=str(exc),
+            remediation=(
+                "Configure PEOPLE_MEMORY_EMBEDDING_PROVIDER plus model/base URL/key. "
+                "Use provider=ollama for local embeddings or provider=volcengine/openai_compatible "
+                "for an OpenAI-compatible cloud endpoint."
+            ),
+        )
+    return CheckResult(
+        name="embedding_settings",
+        ok=True,
+        detail=(
+            f"provider={settings.provider}; model={settings.model}; "
+            f"base_url={settings.base_url}; dimension={settings.dimension or 'provider_default'}"
+        ),
+    )
+
+
+def _llm_settings_check(config: PeopleMemoryConfig) -> CheckResult:
+    missing: list[str] = []
+    if not config.llm_provider:
+        missing.append("PEOPLE_MEMORY_LLM_PROVIDER")
+    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 config.llm_provider and config.llm_provider.lower() in {"openai_compatible", "openai"}:
+        if not config.llm_base_url:
+            missing.append("PEOPLE_MEMORY_LLM_BASE_URL")
+    if missing:
+        return CheckResult(
+            name="llm_settings",
+            ok=False,
+            detail="Missing " + ", ".join(sorted(set(missing))),
+            remediation=(
+                "Graphiti needs an LLM for episode extraction. Configure provider, model, "
+                "credential, and base URL when using an OpenAI-compatible gateway."
+            ),
+        )
+    return CheckResult(
+        name="llm_settings",
+        ok=True,
+        detail=(
+            f"provider={config.llm_provider}; model={config.llm_model}; "
+            f"base_url={config.llm_base_url or 'provider_default'}; "
+            f"response_format={config.llm_response_format}"
+        ),
+    )
+
+
+def _graphiti_projection_path_check(config: PeopleMemoryConfig) -> CheckResult:
+    cache_path = Path(config.data_path).expanduser() / "people-memory.graphiti-cache.json"
+    nearest = cache_path.parent
+    while not nearest.exists() and nearest.parent != nearest:
+        nearest = nearest.parent
+    ok = nearest.exists() and _path_is_writable(nearest)
+    return CheckResult(
+        name="graphiti_projection_cache",
+        ok=ok,
+        detail=f"cache={cache_path}; nearest existing parent={nearest}",
+        remediation="Create a writable PEOPLE_MEMORY_DATA_PATH for the Graphiti projection cache."
+        if not ok
+        else None,
+    )
+
+
+def _path_is_writable(path: Path) -> bool:
+    if not path.exists():
+        return False
+    probe = path / ".people-memory-write-check"
+    try:
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink()
+        return True
+    except OSError:
+        return False