@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/infrastructure/semantic_index.py

@@ -0,0 +1,262 @@
+"""Local semantic sidecar for projection-cache recall.
+
+The graph backend owns graph extraction and graph search. This sidecar keeps
+small, evidence-backed interaction chunks searchable by embedding so vague
+event-level queries do not depend only on Graphiti edge granularity.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable
+
+from people_network_memory.domain.models import (
+    Evidence,
+    RetrievalItem,
+    SensitivityLabel,
+    SocialInteraction,
+)
+
+
+EmbedTexts = Callable[[list[str]], list[list[float]]]
+
+
+@dataclass(frozen=True)
+class SemanticIndexEntry:
+    entry_id: str
+    text: str
+    embedding: list[float]
+    source_text: str
+    recorded_at: datetime
+    person_ids: list[str]
+    sensitivity: list[SensitivityLabel]
+
+
+class SemanticProjectionIndex:
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._entries: dict[str, SemanticIndexEntry] = {}
+        self._load()
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @property
+    def entries(self) -> list[SemanticIndexEntry]:
+        return list(self._entries.values())
+
+    def build_from_interactions(
+        self,
+        interactions: list[SocialInteraction],
+        *,
+        embed_texts: EmbedTexts,
+        batch_size: int = 16,
+        reset: bool = False,
+    ) -> dict[str, object]:
+        if reset:
+            self._entries = {}
+        chunks = [
+            _interaction_chunk(interaction)
+            for interaction in interactions
+            if _interaction_chunk(interaction)["entry_id"] not in self._entries
+        ]
+        embedded = 0
+        for start in range(0, len(chunks), batch_size):
+            batch = chunks[start : start + batch_size]
+            vectors = embed_texts([str(chunk["text"]) for chunk in batch])
+            if len(vectors) != len(batch):
+                raise ValueError("embedding provider returned the wrong number of vectors")
+            for chunk, vector in zip(batch, vectors):
+                labels = [
+                    SensitivityLabel(label)
+                    for label in chunk["sensitivity"]
+                    if label in {item.value for item in SensitivityLabel}
+                ]
+                self._entries[str(chunk["entry_id"])] = SemanticIndexEntry(
+                    entry_id=str(chunk["entry_id"]),
+                    text=str(chunk["text"]),
+                    embedding=[float(value) for value in vector],
+                    source_text=str(chunk["source_text"]),
+                    recorded_at=chunk["recorded_at"],  # type: ignore[arg-type]
+                    person_ids=list(chunk["person_ids"]),  # type: ignore[arg-type]
+                    sensitivity=labels,
+                )
+                embedded += 1
+            self._flush()
+        self._flush()
+        return {
+            "ok": True,
+            "target_index": str(self._path),
+            "attempted": len(interactions),
+            "embedded": embedded,
+            "skipped_existing": len(interactions) - len(chunks),
+            "entries": len(self._entries),
+        }
+
+    def search(
+        self,
+        query: str,
+        *,
+        embed_texts: EmbedTexts,
+        limit: int,
+        include_sensitive: bool = False,
+    ) -> list[RetrievalItem]:
+        if not self._entries:
+            return []
+        query_vectors = embed_texts([query])
+        if not query_vectors:
+            return []
+        query_vector = query_vectors[0]
+        scored: list[tuple[float, SemanticIndexEntry]] = []
+        for entry in self._entries.values():
+            if _blocked(entry.sensitivity, include_sensitive):
+                continue
+            score = _cosine(query_vector, entry.embedding)
+            if score <= 0:
+                continue
+            scored.append((score, entry))
+        scored.sort(key=lambda item: item[0], reverse=True)
+        return [
+                RetrievalItem(
+                    item_id=f"semantic:{entry.entry_id}",
+                    kind="interaction",
+                    title="Semantic interaction match",
+                    matched_text=entry.text,
+                    score=max(score, 0.0) * 2.0,
+                    why_matched="Matched by local semantic projection index.",
+                person_ids=entry.person_ids,
+                sensitivity=entry.sensitivity,
+                evidence=[
+                    Evidence(
+                        evidence_id=entry.entry_id,
+                        source_text=entry.source_text,
+                        recorded_at=entry.recorded_at,
+                    )
+                ],
+                is_secondhand=SensitivityLabel.SECONDHAND in entry.sensitivity,
+            )
+            for score, entry in scored[:limit]
+        ]
+
+    def _load(self) -> None:
+        if not self._path.exists():
+            return
+        payload = json.loads(self._path.read_text(encoding="utf-8"))
+        for item in payload.get("entries", []):
+            labels = [
+                SensitivityLabel(label)
+                for label in item.get("sensitivity", [])
+                if label in {entry.value for entry in SensitivityLabel}
+            ]
+            self._entries[item["entry_id"]] = SemanticIndexEntry(
+                entry_id=item["entry_id"],
+                text=item["text"],
+                embedding=[float(value) for value in item["embedding"]],
+                source_text=item["source_text"],
+                recorded_at=datetime.fromisoformat(item["recorded_at"]),
+                person_ids=list(item.get("person_ids", [])),
+                sensitivity=labels,
+            )
+
+    def _flush(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "schema_version": 1,
+            "entries": [
+                {
+                    "entry_id": entry.entry_id,
+                    "text": entry.text,
+                    "embedding": entry.embedding,
+                    "source_text": entry.source_text,
+                    "recorded_at": entry.recorded_at.isoformat(),
+                    "person_ids": entry.person_ids,
+                    "sensitivity": [label.value for label in entry.sensitivity],
+                }
+                for entry in self._entries.values()
+            ],
+        }
+        self._path.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+
+
+def _interaction_chunk(interaction: SocialInteraction) -> dict[str, object]:
+    participants = [participant.person.label for participant in interaction.participants]
+    mentioned = [
+        f"{mentioned.mentioned_by.label} mentioned {mentioned.person.label}"
+        if mentioned.mentioned_by
+        else mentioned.person.label
+        for mentioned in interaction.mentioned_people
+    ]
+    direct_facts = [
+        f"{fact.subject.label} {fact.predicate} {fact.value}"
+        for fact in interaction.direct_facts
+    ]
+    follow_ups = [follow_up.description for follow_up in interaction.follow_ups]
+    person_ids = sorted(
+        {
+            ref.person_id
+            for ref in [
+                *[participant.person for participant in interaction.participants],
+                *[mentioned.person for mentioned in interaction.mentioned_people],
+            ]
+            if ref.person_id
+        }
+    )
+    sensitivity = set(interaction.sensitivity)
+    for claim in interaction.attributed_claims:
+        sensitivity.update(claim.sensitivity)
+    for fact in interaction.direct_facts:
+        sensitivity.update(fact.sensitivity)
+    parts = [
+        interaction.source_text,
+        f"Place: {interaction.place}" if interaction.place else "",
+        "Participants: " + ", ".join(participants) if participants else "",
+        "Mentioned: " + ", ".join(mentioned) if mentioned else "",
+        "Topics: " + ", ".join(interaction.topics) if interaction.topics else "",
+        "Direct facts: " + "; ".join(direct_facts) if direct_facts else "",
+        "Follow-ups: " + "; ".join(follow_ups) if follow_ups else "",
+    ]
+    text = "\n".join(part for part in parts if part)
+    recorded_at = interaction.occurred_at or datetime.now(timezone.utc)
+    return {
+        "entry_id": hashlib.sha256(
+            interaction.model_dump_json().encode("utf-8")
+        ).hexdigest(),
+        "text": text,
+        "source_text": interaction.source_text,
+        "recorded_at": recorded_at,
+        "person_ids": person_ids,
+        "sensitivity": [label.value for label in sorted(sensitivity, key=lambda item: item.value)],
+    }
+
+
+def _cosine(left: list[float], right: list[float]) -> float:
+    if not left or not right or len(left) != len(right):
+        return 0.0
+    dot = sum(a * b for a, b in zip(left, right))
+    left_norm = math.sqrt(sum(value * value for value in left))
+    right_norm = math.sqrt(sum(value * value for value in right))
+    if left_norm == 0 or right_norm == 0:
+        return 0.0
+    return dot / (left_norm * right_norm)
+
+
+def _blocked(labels: list[SensitivityLabel], include_sensitive: bool) -> bool:
+    if include_sensitive:
+        return False
+    return any(
+        label
+        in {
+            SensitivityLabel.SENSITIVE,
+            SensitivityLabel.DO_NOT_SURFACE_UNPROMPTED,
+        }
+        for label in labels
+    )

package/src/people_network_memory/mcp_server/__init__.py

@@ -0,0 +1,2 @@
+"""MCP transport layer."""
+

package/src/people_network_memory/mcp_server/contracts.py

@@ -0,0 +1,85 @@
+"""Public V1 MCP tool contracts."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import Field, model_validator
+
+from people_network_memory.domain.models import (
+    PersonCard,
+    RecordInteractionResult,
+    RetrievalResponse,
+    SocialInteraction,
+    StrictModel,
+)
+
+
+CONTRACT_VERSION = "v1"
+
+
+class RetrieveNetworkContextInput(StrictModel):
+    query: str = Field(min_length=1)
+    limit: int = Field(default=10, ge=1, le=50)
+    include_sensitive: bool | None = None
+    sensitivity_policy: Literal["personal", "strict", "task_aware"] | None = None
+    output_context: Literal["private", "shareable"] = "private"
+    mode: Literal["recall", "brief"] = "recall"
+
+
+class GetPersonInput(StrictModel):
+    person_id: str | None = Field(default=None, min_length=1)
+    name: str | None = Field(default=None, min_length=1)
+
+    @model_validator(mode="after")
+    def require_identifier(self) -> "GetPersonInput":
+        if not (self.person_id or self.name):
+            raise ValueError("get_person requires either person_id or name")
+        return self
+
+
+class PersonCardFoundResponse(PersonCard):
+    found: bool = True
+
+
+class PersonCardMissingResponse(StrictModel):
+    person_id: str | None = None
+    name: str | None = None
+    found: bool = False
+    missing_info: list[str] = Field(default_factory=list)
+    candidates: list[dict[str, Any]] = Field(default_factory=list)
+
+
+def public_tool_names() -> list[str]:
+    return ["record_interaction", "retrieve_network_context", "get_person"]
+
+
+def public_tool_contracts() -> list[dict[str, Any]]:
+    return [
+        {
+            "name": "record_interaction",
+            "version": CONTRACT_VERSION,
+            "description": "Capture a social interaction or memory note.",
+            "input_schema": SocialInteraction.model_json_schema(),
+            "output_schema": RecordInteractionResult.model_json_schema(),
+        },
+        {
+            "name": "retrieve_network_context",
+            "version": CONTRACT_VERSION,
+            "description": "Retrieve relevant social-memory context from a vague query.",
+            "input_schema": RetrieveNetworkContextInput.model_json_schema(),
+            "output_schema": RetrievalResponse.model_json_schema(),
+        },
+        {
+            "name": "get_person",
+            "version": CONTRACT_VERSION,
+            "description": "Return one projected person card by stable person_id, or by name as a best-effort harness fallback.",
+            "input_schema": GetPersonInput.model_json_schema(),
+            "output_schema": {
+                "oneOf": [
+                    PersonCardFoundResponse.model_json_schema(),
+                    PersonCardMissingResponse.model_json_schema(),
+                ]
+            },
+        },
+    ]

package/src/people_network_memory/mcp_server/runtime.py

@@ -0,0 +1,133 @@
+"""Runtime wiring for CLI and MCP server."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from people_network_memory.application.services import (
+    BuildPersonCardService,
+    RecordInteractionService,
+    RetrieveContextService,
+    ReviewWorkflowService,
+)
+from people_network_memory.config import PeopleMemoryConfig
+from people_network_memory.graphiti_adapter.graphiti_store import GraphitiGraphStore
+from people_network_memory.infrastructure.file_store import JsonPeopleStore
+from people_network_memory.infrastructure.id_generator import SequentialIdGenerator
+from people_network_memory.infrastructure.in_memory_store import InMemoryPeopleStore
+from people_network_memory.mcp_server.tools import PeopleMemoryTools
+from people_network_memory.projection.builders import DefaultPersonProjector
+
+
+@dataclass
+class PeopleMemoryRuntime:
+    tools: PeopleMemoryTools
+    store: Any
+    record_service: RecordInteractionService
+    retrieve_service: RetrieveContextService
+    review_workflow: ReviewWorkflowService
+
+    def close(self) -> None:
+        close_store = getattr(self.store, "close", None)
+        if callable(close_store):
+            close_store()
+
+    def run_stdio(self) -> None:
+        from mcp.server.fastmcp import FastMCP
+
+        mcp = FastMCP("people-network-memory")
+
+        @mcp.tool()
+        def record_interaction(payload: dict[str, Any]) -> dict[str, Any]:
+            """Capture a messy social interaction note."""
+
+            return self.tools.record_interaction(payload)
+
+        @mcp.tool()
+        def retrieve_network_context(payload: dict[str, Any]) -> dict[str, Any]:
+            """Retrieve relevant personal network context from a vague query."""
+
+            return self.tools.retrieve_network_context(payload)
+
+        @mcp.tool()
+        def get_person(payload: dict[str, Any]) -> dict[str, Any]:
+            """Return a projected person card."""
+
+            return self.tools.get_person(payload)
+
+        mcp.run()
+
+
+def build_runtime(config: PeopleMemoryConfig) -> PeopleMemoryRuntime:
+    config.validate_runtime()
+    store = _build_store(config)
+    ids = getattr(store, "id_generator", SequentialIdGenerator())
+    projector = DefaultPersonProjector()
+    record_service = RecordInteractionService(
+        memory_store=store,
+        identity_index=store,
+        review_queue=store,
+        id_generator=ids,
+        interaction_extractor=_build_interaction_extractor(config),
+        identity_advisor=_build_identity_advisor(config),
+    )
+    retrieve_service = RetrieveContextService(
+        graph_search=store,
+        review_queue=store,
+        default_sensitivity_policy=config.sensitivity_policy,
+        retrieval_judge=_build_retrieval_judge(config),
+    )
+    card_service = BuildPersonCardService(memory_store=store, projector=projector)
+    review_workflow = ReviewWorkflowService(memory_store=store, review_queue=store)
+    return PeopleMemoryRuntime(
+        tools=PeopleMemoryTools(
+            record_interaction_service=record_service,
+            retrieve_context_service=retrieve_service,
+            build_person_card_service=card_service,
+        ),
+        store=store,
+        record_service=record_service,
+        retrieve_service=retrieve_service,
+        review_workflow=review_workflow,
+    )
+
+
+def _build_store(config: PeopleMemoryConfig) -> InMemoryPeopleStore | JsonPeopleStore | GraphitiGraphStore:
+    if config.backend == "graphiti":
+        return GraphitiGraphStore.from_config(config)
+    if config.backend == "local_json":
+        return JsonPeopleStore.from_config(config)
+    return InMemoryPeopleStore()
+
+
+def _build_retrieval_judge(config: PeopleMemoryConfig) -> Any | None:
+    if config.retrieval_judge != "llm":
+        return None
+    from people_network_memory.infrastructure.llm_judge import OpenAICompatibleRetrievalJudge
+
+    return OpenAICompatibleRetrievalJudge.from_config(config)
+
+
+def _build_interaction_extractor(config: PeopleMemoryConfig) -> Any | None:
+    if config.ingestion_extractor != "llm":
+        return None
+    if not config.has_llm_settings():
+        return None
+    from people_network_memory.infrastructure.llm_extractor import (
+        OpenAICompatibleInteractionExtractor,
+    )
+
+    return OpenAICompatibleInteractionExtractor.from_config(config)
+
+
+def _build_identity_advisor(config: PeopleMemoryConfig) -> Any | None:
+    if config.identity_advisor != "llm":
+        return None
+    if not config.has_llm_settings():
+        return None
+    from people_network_memory.infrastructure.llm_identity_advisor import (
+        OpenAICompatibleIdentityAdvisor,
+    )
+
+    return OpenAICompatibleIdentityAdvisor.from_config(config)