@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/config.py

@@ -0,0 +1,268 @@
+"""Runtime configuration and validation.
+
+This module intentionally lives outside the domain/application layers because it
+reads environment variables and filesystem-like paths.
+"""
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from people_network_memory.ports.errors import ConfigError
+
+
+BackendKind = Literal["inmemory", "local_json", "graphiti"]
+SensitivityPolicy = Literal["personal", "strict", "task_aware"]
+RetrievalJudgeKind = Literal["off", "llm"]
+IngestionExtractorKind = Literal["off", "llm"]
+IdentityAdvisorKind = Literal["off", "llm"]
+
+
+@dataclass(frozen=True)
+class PeopleMemoryConfig:
+    backend: BackendKind = "inmemory"
+    graph_backend_kind: Literal["kuzu", "neo4j", "falkordb"] = "kuzu"
+    graph_backend_url: str | None = None
+    graphiti_kuzu_path: str = "~/.people-network-memory/graphiti.kuzu"
+    embedding_provider: str | None = None
+    embedding_base_url: str | None = None
+    embedding_model: str | None = None
+    embedding_api_key: str | None = None
+    embedding_dim: int | None = None
+    llm_provider: str | None = None
+    llm_base_url: str | None = None
+    llm_model: str | None = None
+    llm_api_key: str | None = None
+    llm_response_format: Literal["none", "json_object", "json_schema"] = "none"
+    ingestion_extractor: IngestionExtractorKind = "llm"
+    ingestion_extractor_timeout_seconds: float = 30.0
+    identity_advisor: IdentityAdvisorKind = "off"
+    identity_advisor_timeout_seconds: float = 30.0
+    retrieval_judge: RetrievalJudgeKind = "off"
+    retrieval_judge_timeout_seconds: float = 30.0
+    sensitivity_policy: SensitivityPolicy = "personal"
+    data_path: str = "~/.people-network-memory"
+    telemetry_enabled: bool = False
+    graphiti_add_timeout_seconds: float = 240.0
+    graphiti_search_timeout_seconds: float = 120.0
+    graphiti_retry_attempts: int = 3
+    test_mode: bool = False
+
+    @classmethod
+    def from_env(cls, *, test_mode: bool = False) -> "PeopleMemoryConfig":
+        local_env = _load_local_env()
+        backend = _env(
+            "PEOPLE_MEMORY_BACKEND",
+            local_env,
+            "inmemory" if test_mode else "local_json",
+        ).strip().lower()
+        if backend not in {"inmemory", "local_json", "graphiti"}:
+            raise ConfigError(f"Unsupported PEOPLE_MEMORY_BACKEND: {backend}")
+        llm_response_format = _env(
+            "PEOPLE_MEMORY_LLM_RESPONSE_FORMAT",
+            local_env,
+            "none",
+        ).strip().lower()
+        if llm_response_format not in {"none", "json_object", "json_schema"}:
+            raise ConfigError(
+                "Unsupported PEOPLE_MEMORY_LLM_RESPONSE_FORMAT: "
+                f"{llm_response_format}"
+            )
+        sensitivity_policy = _env(
+            "PEOPLE_MEMORY_SENSITIVITY_POLICY",
+            local_env,
+            "personal",
+        ).strip().lower()
+        if sensitivity_policy not in {"personal", "strict", "task_aware"}:
+            raise ConfigError(
+                "Unsupported PEOPLE_MEMORY_SENSITIVITY_POLICY: "
+                f"{sensitivity_policy}"
+            )
+        retrieval_judge = _env(
+            "PEOPLE_MEMORY_RETRIEVAL_JUDGE",
+            local_env,
+            "off",
+        ).strip().lower()
+        if retrieval_judge not in {"off", "llm"}:
+            raise ConfigError(
+                "Unsupported PEOPLE_MEMORY_RETRIEVAL_JUDGE: "
+                f"{retrieval_judge}"
+            )
+        ingestion_extractor = _env(
+            "PEOPLE_MEMORY_INGESTION_EXTRACTOR",
+            local_env,
+            "llm",
+        ).strip().lower()
+        if ingestion_extractor not in {"off", "llm"}:
+            raise ConfigError(
+                "Unsupported PEOPLE_MEMORY_INGESTION_EXTRACTOR: "
+                f"{ingestion_extractor}"
+            )
+        identity_advisor = _env(
+            "PEOPLE_MEMORY_IDENTITY_ADVISOR",
+            local_env,
+            "off",
+        ).strip().lower()
+        if identity_advisor not in {"off", "llm"}:
+            raise ConfigError(
+                "Unsupported PEOPLE_MEMORY_IDENTITY_ADVISOR: "
+                f"{identity_advisor}"
+            )
+        return cls(
+            backend=backend,  # type: ignore[arg-type]
+            graph_backend_kind=_env("PEOPLE_MEMORY_GRAPH_BACKEND", local_env, "kuzu").strip().lower(),  # type: ignore[arg-type]
+            graph_backend_url=_env("PEOPLE_MEMORY_GRAPH_BACKEND_URL", local_env),
+            graphiti_kuzu_path=_env(
+                "PEOPLE_MEMORY_GRAPHITI_KUZU_PATH",
+                local_env,
+                "~/.people-network-memory/graphiti.kuzu",
+            ),
+            embedding_provider=_env("PEOPLE_MEMORY_EMBEDDING_PROVIDER", local_env),
+            embedding_base_url=_env("PEOPLE_MEMORY_EMBEDDING_BASE_URL", local_env),
+            embedding_model=_env("PEOPLE_MEMORY_EMBEDDING_MODEL", local_env),
+            embedding_api_key=_env("PEOPLE_MEMORY_EMBEDDING_API_KEY", local_env),
+            embedding_dim=_optional_int(_env("PEOPLE_MEMORY_EMBEDDING_DIM", local_env)),
+            llm_provider=_env("PEOPLE_MEMORY_LLM_PROVIDER", local_env),
+            llm_base_url=_env("PEOPLE_MEMORY_LLM_BASE_URL", local_env),
+            llm_model=_env("PEOPLE_MEMORY_LLM_MODEL", local_env),
+            llm_api_key=_env("PEOPLE_MEMORY_LLM_API_KEY", local_env),
+            llm_response_format=llm_response_format,  # type: ignore[arg-type]
+            ingestion_extractor=ingestion_extractor,  # type: ignore[arg-type]
+            ingestion_extractor_timeout_seconds=_optional_float(
+                _env("PEOPLE_MEMORY_INGESTION_EXTRACTOR_TIMEOUT_SECONDS", local_env)
+            )
+            or 30.0,
+            identity_advisor=identity_advisor,  # type: ignore[arg-type]
+            identity_advisor_timeout_seconds=_optional_float(
+                _env("PEOPLE_MEMORY_IDENTITY_ADVISOR_TIMEOUT_SECONDS", local_env)
+            )
+            or 30.0,
+            retrieval_judge=retrieval_judge,  # type: ignore[arg-type]
+            retrieval_judge_timeout_seconds=_optional_float(
+                _env("PEOPLE_MEMORY_RETRIEVAL_JUDGE_TIMEOUT_SECONDS", local_env)
+            )
+            or 30.0,
+            sensitivity_policy=sensitivity_policy,  # type: ignore[arg-type]
+            data_path=_env("PEOPLE_MEMORY_DATA_PATH", local_env, "~/.people-network-memory"),
+            telemetry_enabled=_env("GRAPHITI_TELEMETRY_ENABLED", local_env, "false").lower()
+            in {"1", "true", "yes"},
+            graphiti_add_timeout_seconds=_optional_float(
+                _env("PEOPLE_MEMORY_GRAPHITI_ADD_TIMEOUT_SECONDS", local_env)
+            )
+            or 240.0,
+            graphiti_search_timeout_seconds=_optional_float(
+                _env("PEOPLE_MEMORY_GRAPHITI_SEARCH_TIMEOUT_SECONDS", local_env)
+            )
+            or 120.0,
+            graphiti_retry_attempts=_optional_int(
+                _env("PEOPLE_MEMORY_GRAPHITI_RETRY_ATTEMPTS", local_env)
+            )
+            or 3,
+            test_mode=test_mode,
+        )
+
+    def validate_runtime(self) -> None:
+        if self.backend in {"inmemory", "local_json"}:
+            self._validate_retrieval_judge()
+            self.validate_ingestion_extractor()
+            self.validate_identity_advisor()
+            return
+        missing: list[str] = []
+        if self.graph_backend_kind not in {"kuzu", "neo4j", "falkordb"}:
+            missing.append("PEOPLE_MEMORY_GRAPH_BACKEND")
+        if self.graph_backend_kind != "kuzu" and not self.graph_backend_url:
+            missing.append("PEOPLE_MEMORY_GRAPH_BACKEND_URL")
+        if not self.embedding_provider:
+            missing.append("PEOPLE_MEMORY_EMBEDDING_PROVIDER")
+        if missing:
+            raise ConfigError(
+                "Graphiti backend requires: " + ", ".join(sorted(missing))
+            )
+        self._validate_retrieval_judge()
+        self.validate_ingestion_extractor()
+        self.validate_identity_advisor()
+
+    def _validate_retrieval_judge(self) -> None:
+        if self.retrieval_judge != "llm":
+            return
+        self._validate_llm_settings("LLM retrieval judge")
+
+    def validate_ingestion_extractor(self) -> None:
+        if self.ingestion_extractor != "llm":
+            return
+        # Capture extraction is intentionally best-effort: V1 defaults it to
+        # on, but a fresh install without LLM credentials must still boot and
+        # fall back to deterministic normalization.
+        return
+
+    def validate_identity_advisor(self) -> None:
+        if self.identity_advisor != "llm":
+            return
+        # Identity advice is a best-effort brake. Without LLM credentials the
+        # runtime falls back to deterministic identity policy.
+        return
+
+    def has_llm_settings(self) -> bool:
+        return bool(self.llm_base_url and self.llm_model and self.llm_api_key)
+
+    def _validate_llm_settings(self, feature_name: str) -> None:
+        missing: list[str] = []
+        if not self.llm_base_url:
+            missing.append("PEOPLE_MEMORY_LLM_BASE_URL")
+        if not self.llm_model:
+            missing.append("PEOPLE_MEMORY_LLM_MODEL")
+        if not self.llm_api_key:
+            missing.append("PEOPLE_MEMORY_LLM_API_KEY")
+        if missing:
+            raise ConfigError(
+                f"{feature_name} requires: " + ", ".join(sorted(missing))
+            )
+
+
+def _optional_int(value: str | None) -> int | None:
+    if not value:
+        return None
+    return int(value)
+
+
+def _optional_float(value: str | None) -> float | None:
+    if not value:
+        return None
+    return float(value)
+
+
+def _env(name: str, local_env: dict[str, str], default: str | None = None) -> str | None:
+    return os.getenv(name) or local_env.get(name) or default
+
+
+def _load_local_env() -> dict[str, str]:
+    if os.getenv("PEOPLE_MEMORY_DISABLE_LOCAL_ENV", "").lower() in {"1", "true", "yes"}:
+        return {}
+    path = os.getenv("PEOPLE_MEMORY_LOCAL_ENV_FILE")
+    candidates = [Path(path).expanduser()] if path else []
+    candidates.append(Path.cwd() / ".people-network-memory" / "local.env.json")
+    for candidate in candidates:
+        if not candidate.exists():
+            continue
+        try:
+            payload = json.loads(candidate.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise ConfigError(f"Invalid local env JSON at {candidate}: {exc}") from exc
+        if not isinstance(payload, dict):
+            raise ConfigError(f"Local env JSON must be an object: {candidate}")
+        return {
+            str(key): str(value)
+            for key, value in payload.items()
+            if _allowed_local_env_name(str(key)) and isinstance(value, str) and value
+        }
+    return {}
+
+
+def _allowed_local_env_name(name: str) -> bool:
+    return (
+        name.startswith("PEOPLE_MEMORY_")
+        or name == "GRAPHITI_TELEMETRY_ENABLED"
+        or name == "VOLCENGINE_" + "API" + "_KEY"
+    )

package/src/people_network_memory/domain/__init__.py

@@ -0,0 +1,55 @@
+"""Pure domain models and policies."""
+
+from people_network_memory.domain.models import (
+    AttributedClaim,
+    CaptureSummary,
+    CapturedPersonSummary,
+    ContactMethod,
+    DirectFact,
+    EducationRecord,
+    Evidence,
+    FollowUpTask,
+    HarnessContextRequest,
+    ImportantDate,
+    MentionedPerson,
+    Participant,
+    PersonCard,
+    PersonMemoryRecord,
+    PersonProfileUpdate,
+    PersonRef,
+    PostCaptureOpportunity,
+    RelationshipAssertion,
+    RetrievalItem,
+    ReviewItem,
+    SensitivityLabel,
+    SocialInteraction,
+    OpportunityTimeHint,
+    WorkHistoryRecord,
+)
+
+__all__ = [
+    "AttributedClaim",
+    "CaptureSummary",
+    "CapturedPersonSummary",
+    "ContactMethod",
+    "DirectFact",
+    "EducationRecord",
+    "Evidence",
+    "FollowUpTask",
+    "HarnessContextRequest",
+    "ImportantDate",
+    "MentionedPerson",
+    "Participant",
+    "PersonCard",
+    "PersonMemoryRecord",
+    "PersonProfileUpdate",
+    "PersonRef",
+    "PostCaptureOpportunity",
+    "RelationshipAssertion",
+    "RetrievalItem",
+    "ReviewItem",
+    "SensitivityLabel",
+    "SocialInteraction",
+    "OpportunityTimeHint",
+    "WorkHistoryRecord",
+]

package/src/people_network_memory/domain/identity.py

@@ -0,0 +1,77 @@
+"""Conservative identity policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from people_network_memory.domain.models import IdentityCandidate, PersonRef
+
+
+IdentityDecisionKind = Literal["link", "review", "provisional"]
+
+
+@dataclass(frozen=True)
+class IdentityDecision:
+    kind: IdentityDecisionKind
+    person_id: str | None = None
+    reason: str = ""
+    candidates: tuple[IdentityCandidate, ...] = ()
+
+
+def choose_identity(ref: PersonRef, candidates: list[IdentityCandidate]) -> IdentityDecision:
+    """Apply the V1 conservative identity policy.
+
+    Exact user-provided IDs link directly. Exact email/phone matches can link.
+    Ambiguous name/company matches go to review. Unknown people become provisional.
+    """
+
+    if ref.person_id:
+        return IdentityDecision(kind="link", person_id=ref.person_id, reason="explicit person_id")
+    exact = [candidate for candidate in candidates if candidate.exact_identifier_match]
+    if len(exact) == 1:
+        return IdentityDecision(
+            kind="link",
+            person_id=exact[0].person_id,
+            reason="single exact email/phone match",
+            candidates=tuple(exact),
+        )
+    exact_name = [
+        candidate
+        for candidate in candidates
+        if candidate.exact_name_match
+        or _normal_label(candidate.display_name) == _normal_label(ref.label)
+    ]
+    if len(exact_name) == 1:
+        return IdentityDecision(
+            kind="link",
+            person_id=exact_name[0].person_id,
+            reason="single exact name or alias match",
+            candidates=tuple(exact_name),
+        )
+    if len(exact_name) > 1:
+        return IdentityDecision(
+            kind="review",
+            reason="multiple exact name or alias matches",
+            candidates=tuple(exact_name),
+        )
+    strong = [candidate for candidate in candidates if candidate.score >= 0.82]
+    if len(strong) == 1 and (ref.email or ref.phone):
+        return IdentityDecision(
+            kind="link",
+            person_id=strong[0].person_id,
+            reason="strong match with identifier hint",
+            candidates=tuple(strong),
+        )
+    reviewable = [candidate for candidate in candidates if candidate.score >= 0.75]
+    if reviewable:
+        return IdentityDecision(
+            kind="review",
+            reason="ambiguous high-confidence person reference",
+            candidates=tuple(reviewable),
+        )
+    return IdentityDecision(kind="provisional", reason="no existing candidate")
+
+
+def _normal_label(value: str) -> str:
+    return " ".join(value.casefold().split())