@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/infrastructure/embeddings.py

@@ -0,0 +1,155 @@
+"""Embedding clients for local and OpenAI-compatible providers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from people_network_memory.config import PeopleMemoryConfig
+from people_network_memory.ports.errors import ConfigError, PeopleMemoryError
+
+
+class EmbeddingError(PeopleMemoryError):
+    """Embedding provider request failed."""
+
+
+@dataclass(frozen=True)
+class EmbeddingCheck:
+    ok: bool
+    provider: str
+    model: str
+    base_url: str
+    dimension: int | None = None
+    error: str | None = None
+
+    def to_json(self) -> dict[str, object]:
+        payload: dict[str, object] = {
+            "ok": self.ok,
+            "provider": self.provider,
+            "model": self.model,
+            "base_url": self.base_url,
+        }
+        if self.dimension is not None:
+            payload["dimension"] = self.dimension
+        if self.error:
+            payload["error"] = self.error
+        return payload
+
+
+@dataclass(frozen=True)
+class EmbeddingSettings:
+    provider: str
+    base_url: str
+    model: str
+    api_key: str
+    dimension: int | None = None
+
+    @classmethod
+    def from_config(cls, config: PeopleMemoryConfig) -> "EmbeddingSettings":
+        provider = (config.embedding_provider or "").strip().lower()
+        if provider in {"ollama", "local_ollama"}:
+            return cls(
+                provider="ollama",
+                base_url=config.embedding_base_url or "http://localhost:11434/v1",
+                model=config.embedding_model or "nomic-embed-text",
+                api_key=config.embedding_api_key or "ollama",
+                dimension=config.embedding_dim or 768,
+            )
+        if provider in {"openai_compatible", "ark", "doubao", "volcengine"}:
+            missing = []
+            if not config.embedding_base_url:
+                missing.append("PEOPLE_MEMORY_EMBEDDING_BASE_URL")
+            if not config.embedding_model:
+                missing.append("PEOPLE_MEMORY_EMBEDDING_MODEL")
+            if not config.embedding_api_key:
+                missing.append("PEOPLE_MEMORY_EMBEDDING_API_KEY")
+            if missing:
+                raise ConfigError(
+                    "OpenAI-compatible embeddings require: " + ", ".join(missing)
+                )
+            return cls(
+                provider="openai_compatible" if provider in {"ark", "doubao", "volcengine"} else provider,
+                base_url=config.embedding_base_url,
+                model=config.embedding_model,
+                api_key=config.embedding_api_key,
+                dimension=config.embedding_dim,
+            )
+        raise ConfigError(
+            "Set PEOPLE_MEMORY_EMBEDDING_PROVIDER to `ollama`, `openai_compatible`, "
+            "or a supported OpenAI-compatible alias such as `volcengine`."
+        )
+
+
+class OpenAICompatibleEmbeddingClient:
+    def __init__(self, settings: EmbeddingSettings, *, timeout_seconds: float = 60.0) -> None:
+        self._settings = settings
+        self._timeout = timeout_seconds
+
+    @property
+    def settings(self) -> EmbeddingSettings:
+        return self._settings
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        if not texts:
+            return []
+        url = self._settings.base_url.rstrip("/") + "/embeddings"
+        headers = {
+            "Authorization": f"Bearer {self._settings.api_key}",
+            "Content-Type": "application/json",
+        }
+        payload = {"model": self._settings.model, "input": texts}
+        try:
+            response = httpx.post(url, headers=headers, json=payload, timeout=self._timeout)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            detail = _safe_error_detail(exc.response)
+            raise EmbeddingError(f"embedding provider returned HTTP {exc.response.status_code}: {detail}") from exc
+        except httpx.HTTPError as exc:
+            raise EmbeddingError(f"embedding provider request failed: {exc}") from exc
+        data = response.json()
+        return _parse_embeddings(data)
+
+
+def check_embedding_provider(config: PeopleMemoryConfig, sample: str) -> EmbeddingCheck:
+    settings = EmbeddingSettings.from_config(config)
+    client = OpenAICompatibleEmbeddingClient(settings)
+    try:
+        vectors = client.embed([sample])
+        dimension = len(vectors[0]) if vectors else 0
+        return EmbeddingCheck(
+            ok=dimension > 0,
+            provider=settings.provider,
+            model=settings.model,
+            base_url=settings.base_url,
+            dimension=dimension,
+        )
+    except PeopleMemoryError as exc:
+        return EmbeddingCheck(
+            ok=False,
+            provider=settings.provider,
+            model=settings.model,
+            base_url=settings.base_url,
+            error=str(exc),
+        )
+
+
+def _parse_embeddings(data: dict[str, Any]) -> list[list[float]]:
+    raw_items = data.get("data")
+    if not isinstance(raw_items, list):
+        raise EmbeddingError("embedding provider response missing `data` list")
+    vectors: list[list[float]] = []
+    for item in raw_items:
+        embedding = item.get("embedding") if isinstance(item, dict) else None
+        if not isinstance(embedding, list):
+            raise EmbeddingError("embedding provider response item missing `embedding` list")
+        vectors.append([float(value) for value in embedding])
+    return vectors
+
+
+def _safe_error_detail(response: httpx.Response) -> str:
+    text = response.text
+    if len(text) > 500:
+        text = text[:500] + "..."
+    return text

package/src/people_network_memory/infrastructure/file_store.py

@@ -0,0 +1,129 @@
+"""Durable local JSON adapter.
+
+This is a pragmatic local-first backend for development and early use while the
+Graphiti spike remains gated. It preserves the same ports as the in-memory
+adapter and keeps the Graphiti boundary untouched.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from people_network_memory.config import PeopleMemoryConfig
+from people_network_memory.domain.models import (
+    PersonMemoryRecord,
+    ReviewItem,
+    SocialInteraction,
+)
+from people_network_memory.infrastructure.in_memory_store import InMemoryPeopleStore
+
+
+class JsonPeopleStore(InMemoryPeopleStore):
+    def __init__(self, path: Path) -> None:
+        super().__init__()
+        self._path = path
+        self._load()
+
+    @classmethod
+    def from_config(cls, config: PeopleMemoryConfig) -> "JsonPeopleStore":
+        return cls(local_json_path(config))
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @classmethod
+    def validate_export_payload(cls, payload: dict[str, Any]) -> dict[str, Any]:
+        people = [
+            PersonMemoryRecord.model_validate(item).model_dump(mode="json")
+            for item in payload.get("people", [])
+        ]
+        review_items = [
+            ReviewItem.model_validate(item).model_dump(mode="json")
+            for item in payload.get("review_items", [])
+        ]
+        interactions = [
+            SocialInteraction.model_validate(item).model_dump(mode="json")
+            for item in payload.get("interactions", [])
+        ]
+        return {
+            "people": people,
+            "review_items": review_items,
+            "interactions": interactions,
+        }
+
+    @classmethod
+    def restore_to_path(cls, path: Path, payload: dict[str, Any]) -> None:
+        validated = cls.validate_export_payload(payload)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(validated, ensure_ascii=False, indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+
+    def save_interaction(self, interaction: SocialInteraction, identity_map: dict[str, str | None]):
+        result = super().save_interaction(interaction, identity_map)
+        self._flush()
+        return result
+
+    def add_review_item(self, item: ReviewItem) -> None:
+        super().add_review_item(item)
+        self._flush()
+
+    def update_review_item(self, item: ReviewItem) -> ReviewItem:
+        updated = super().update_review_item(item)
+        self._flush()
+        return updated
+
+    def merge_people(
+        self, *, source_person_id: str, target_person_id: str, note: str | None = None
+    ) -> PersonMemoryRecord:
+        record = super().merge_people(
+            source_person_id=source_person_id,
+            target_person_id=target_person_id,
+            note=note,
+        )
+        self._flush()
+        return record
+
+    def _load(self) -> None:
+        if not self._path.exists():
+            return
+        data = json.loads(self._path.read_text(encoding="utf-8"))
+        self.people = {
+            item["person_id"]: PersonMemoryRecord.model_validate(item)
+            for item in data.get("people", [])
+        }
+        self.review_items = [
+            ReviewItem.model_validate(item) for item in data.get("review_items", [])
+        ]
+        self.interactions = {
+            f"interaction_{index:04d}": SocialInteraction.model_validate(item)
+            for index, item in enumerate(data.get("interactions", []), start=1)
+        }
+        self.evidence = {
+            evidence.evidence_id: evidence
+            for person in self.people.values()
+            for evidence in person.evidence
+        }
+        self._reserve_loaded_ids()
+
+    def _reserve_loaded_ids(self) -> None:
+        self._ids.reserve_existing_ids("person", self.people)
+        self._ids.reserve_existing_ids("review", [item.review_id for item in self.review_items])
+        self._ids.reserve_existing_ids("evidence", self.evidence)
+        self._ids.reserve_existing_ids("interaction", self.interactions)
+        self._ids.reserve_next_value("interaction", len(self.interactions) + 1)
+
+    def _flush(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(
+            json.dumps(self.export_data(), ensure_ascii=False, indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+
+
+def local_json_path(config: PeopleMemoryConfig) -> Path:
+    return Path(config.data_path).expanduser() / "people-memory.json"

package/src/people_network_memory/infrastructure/graphiti_promotion.py

@@ -0,0 +1,212 @@
+"""Promotion gate for making Graphiti/Kuzu the recommended backend."""
+
+from __future__ import annotations
+
+import tempfile
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+from people_network_memory.config import PeopleMemoryConfig
+from people_network_memory.fixtures.eval import evaluate_services
+from people_network_memory.fixtures.generator import generate_mock_dataset
+from people_network_memory.infrastructure.diagnostics import graphiti_spike_checks
+from people_network_memory.infrastructure.embeddings import check_embedding_provider
+from people_network_memory.ports.errors import PeopleMemoryError
+
+
+def run_graphiti_promotion_gate(
+    config: PeopleMemoryConfig,
+    *,
+    seed: int = 42,
+    max_interactions: int | None = None,
+    max_queries: int | None = None,
+    isolated: bool = True,
+    include_cases: bool = False,
+    failures_only: bool = True,
+    skip_live: bool = False,
+    skip_embedding_check: bool = False,
+) -> dict[str, Any]:
+    """Run the repeatable evidence gate for Graphiti/Kuzu promotion.
+
+    The gate is intentionally stricter than a smoke test: static checks must
+    pass, live embedding must work unless skipped, and the fixture eval must
+    meet V1 recall/evidence/sensitivity thresholds before promotion is green.
+    """
+
+    if config.backend != "graphiti":
+        config = replace(config, backend="graphiti")
+
+    static_checks = [check.to_json() for check in graphiti_spike_checks(config)]
+    static_ok = all(bool(check["ok"]) for check in static_checks)
+    embedding_payload = _embedding_gate(config, skip=skip_embedding_check)
+    eval_payload: dict[str, Any]
+
+    if skip_live:
+        eval_payload = {
+            "ok": False,
+            "skipped": True,
+            "reason": "live Graphiti/Kuzu fixture eval was skipped",
+        }
+    elif not static_ok:
+        eval_payload = {
+            "ok": False,
+            "skipped": True,
+            "reason": "static Graphiti/Kuzu checks did not pass",
+        }
+    elif not embedding_payload["ok"]:
+        eval_payload = {
+            "ok": False,
+            "skipped": True,
+            "reason": "embedding provider check did not pass",
+        }
+    else:
+        eval_payload = _run_live_eval(
+            config,
+            seed=seed,
+            max_interactions=max_interactions,
+            max_queries=max_queries,
+            isolated=isolated,
+            include_cases=include_cases,
+            failures_only=failures_only,
+        )
+
+    checked = int(eval_payload.get("checked", 0) or 0)
+    ingested = int(eval_payload.get("ingested_interactions", 0) or 0)
+    fixture_summary = eval_payload.get("fixture_summary", {})
+    target_queries = (
+        int(fixture_summary.get("eval_queries", 40))
+        if isinstance(fixture_summary, dict)
+        else 40
+    )
+    target_interactions = (
+        int(fixture_summary.get("interactions", 90))
+        if isinstance(fixture_summary, dict)
+        else 90
+    )
+    bounded_run = max_queries is not None or max_interactions is not None
+    full_eval = not bounded_run and checked >= min(40, target_queries)
+    full_ingest = not bounded_run and ingested >= min(60, target_interactions)
+    promotion_ok = (
+        static_ok
+        and bool(embedding_payload["ok"])
+        and bool(eval_payload.get("passes_v1_thresholds"))
+        and full_eval
+        and full_ingest
+    )
+    return {
+        "ok": promotion_ok,
+        "gate": "graphiti_kuzu_promotion",
+        "current_default_backend": "local_json",
+        "candidate_backend": "graphiti",
+        "graph_backend_kind": config.graph_backend_kind,
+        "isolated": isolated,
+        "bounded_run": bounded_run,
+        "seed": seed,
+        "checked": checked,
+        "passes_v1_thresholds": bool(eval_payload.get("passes_v1_thresholds")),
+        "static_checks": static_checks,
+        "embedding_check": embedding_payload,
+        "fixture_eval": eval_payload,
+        "promotion_requirements": {
+            "static_checks": "all pass",
+            "embedding_check": "pass",
+            "recall_at_3": ">= 0.70",
+            "recall_at_5": ">= 0.85",
+            "returned_result_evidence_rate": "1.0",
+            "sensitive_leaks": "0",
+            "full_eval": ">= 40 checked queries; bounded diagnostic runs cannot promote",
+            "full_ingest": ">= 60 ingested interactions; bounded diagnostic runs cannot promote",
+        },
+        "promotion_status": _promotion_status(
+            promotion_ok=promotion_ok,
+            bounded_run=bounded_run,
+            eval_passed=bool(eval_payload.get("passes_v1_thresholds")),
+        ),
+        "next_step": (
+            "Graphiti/Kuzu can be recommended for advanced recall while local_json remains the export fallback."
+            if promotion_ok
+            else "Bounded Graphiti/Kuzu diagnostic passed; run the unbounded gate before promotion."
+            if bounded_run and bool(eval_payload.get("passes_v1_thresholds"))
+            else "Keep local_json as the default and fix failed gate items before promoting Graphiti/Kuzu."
+        ),
+    }
+
+
+def _promotion_status(
+    *, promotion_ok: bool, bounded_run: bool, eval_passed: bool
+) -> str:
+    if promotion_ok:
+        return "ready_to_recommend"
+    if bounded_run and eval_passed:
+        return "bounded_pass_not_promotable"
+    return "keep_gated"
+
+
+def _embedding_gate(config: PeopleMemoryConfig, *, skip: bool) -> dict[str, Any]:
+    if skip:
+        return {
+            "ok": False,
+            "skipped": True,
+            "reason": "embedding provider check was skipped",
+        }
+    try:
+        return check_embedding_provider(config, "Alice likes robotics and coffee.").to_json()
+    except PeopleMemoryError as exc:
+        return {"ok": False, "error": str(exc)}
+
+
+def _run_live_eval(
+    config: PeopleMemoryConfig,
+    *,
+    seed: int,
+    max_interactions: int | None,
+    max_queries: int | None,
+    isolated: bool,
+    include_cases: bool,
+    failures_only: bool,
+) -> dict[str, Any]:
+    from people_network_memory.mcp_server.runtime import build_runtime
+
+    temp_dir: tempfile.TemporaryDirectory[str] | None = None
+    if isolated:
+        temp_dir = tempfile.TemporaryDirectory()
+        config = replace(
+            config,
+            data_path=temp_dir.name,
+            graphiti_kuzu_path=str(Path(temp_dir.name) / "graphiti.kuzu"),
+        )
+
+    runtime = None
+    try:
+        dataset = generate_mock_dataset(seed=seed)
+        runtime = build_runtime(config)
+        result = evaluate_services(
+            dataset,
+            record_service=runtime.record_service,
+            retrieve_service=runtime.retrieve_service,
+            max_interactions=max_interactions,
+            max_queries=max_queries,
+            only_answerable=True,
+        )
+        payload = result.to_json(
+            include_cases=include_cases or failures_only,
+            failures_only=failures_only,
+        )
+        payload.update(
+            {
+                "ok": bool(payload["passes_v1_thresholds"]),
+                "backend": "graphiti",
+                "fixture_summary": dataset.summary(),
+            }
+        )
+        return payload
+    except PeopleMemoryError as exc:
+        return {"ok": False, "error": str(exc)}
+    except Exception as exc:  # pragma: no cover - live provider defensive path
+        return {"ok": False, "error": f"Unexpected Graphiti gate failure: {exc}"}
+    finally:
+        if runtime is not None:
+            runtime.close()
+        if temp_dir is not None:
+            temp_dir.cleanup()

package/src/people_network_memory/infrastructure/id_generator.py

@@ -0,0 +1,40 @@
+"""Deterministic and random ID generation."""
+
+from __future__ import annotations
+
+import re
+import uuid
+from collections.abc import Iterable
+
+
+ID_PATTERN = re.compile(r"^(?P<prefix>.+)_(?P<number>\d+)$")
+
+
+class SequentialIdGenerator:
+    def __init__(self) -> None:
+        self._next_values: dict[str, int] = {}
+
+    def new_id(self, prefix: str) -> str:
+        value = self._next_values.get(prefix, 1)
+        self._next_values[prefix] = value + 1
+        return f"{prefix}_{value:04d}"
+
+    def reserve_existing_ids(self, prefix: str, ids: Iterable[str]) -> None:
+        max_value = 0
+        for item_id in ids:
+            match = ID_PATTERN.match(item_id)
+            if not match or match.group("prefix") != prefix:
+                continue
+            max_value = max(max_value, int(match.group("number")))
+        if max_value:
+            self.reserve_next_value(prefix, max_value + 1)
+
+    def reserve_next_value(self, prefix: str, next_value: int) -> None:
+        if next_value < 1:
+            return
+        self._next_values[prefix] = max(self._next_values.get(prefix, 1), next_value)
+
+
+class UuidGenerator:
+    def new_id(self, prefix: str) -> str:
+        return f"{prefix}_{uuid.uuid4().hex[:12]}"