@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/domain/models.py

@@ -0,0 +1,355 @@
+"""Pure domain models.
+
+Rules for this module:
+- no Graphiti imports,
+- no MCP imports,
+- no filesystem/env access,
+- no live model calls.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from enum import Enum
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+
+class SensitivityLabel(str, Enum):
+    PUBLIC = "public"
+    PRIVATE = "private"
+    SENSITIVE = "sensitive"
+    SECONDHAND = "secondhand"
+    UNVERIFIED = "unverified"
+    DO_NOT_SURFACE_UNPROMPTED = "do_not_surface_unprompted"
+
+
+class Evidence(StrictModel):
+    evidence_id: str
+    source_text: str
+    recorded_at: datetime
+    speaker_person_id: str | None = None
+    speaker_label: str | None = None
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
+
+
+class PersonRef(StrictModel):
+    label: str
+    person_id: str | None = None
+    aliases: list[str] = Field(default_factory=list)
+    email: str | None = None
+    phone: str | None = None
+    company_hint: str | None = None
+    source_span: str | None = None
+
+    @field_validator("label")
+    @classmethod
+    def label_must_not_be_empty(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("person reference label cannot be empty")
+        return value
+
+
+class ContactMethod(StrictModel):
+    kind: Literal["email", "phone", "linkedin", "wechat", "address", "other"]
+    value: str
+    label: str | None = None
+    sensitivity: list[SensitivityLabel] = Field(default_factory=list)
+
+
+class WorkHistoryRecord(StrictModel):
+    organization: str
+    role: str | None = None
+    department: str | None = None
+    location: str | None = None
+    start_date: date | None = None
+    end_date: date | None = None
+    is_current: bool = False
+    evidence_id: str | None = None
+
+
+class EducationRecord(StrictModel):
+    school: str
+    degree: str | None = None
+    major: str | None = None
+    start_date: date | None = None
+    end_date: date | None = None
+    evidence_id: str | None = None
+
+
+class ImportantDate(StrictModel):
+    kind: Literal["birthday", "anniversary", "graduation", "first_met", "custom"]
+    value: date
+    label: str | None = None
+    evidence_id: str | None = None
+    sensitivity: list[SensitivityLabel] = Field(default_factory=list)
+
+
+class DirectFact(StrictModel):
+    subject: PersonRef
+    predicate: str
+    value: str
+    effective_at: date | None = None
+    sensitivity: list[SensitivityLabel] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AttributedClaim(StrictModel):
+    speaker: PersonRef | None = None
+    subject: PersonRef | None = None
+    claim_text: str
+    claim_type: str | None = None
+    sensitivity: list[SensitivityLabel] = Field(
+        default_factory=lambda: [SensitivityLabel.SECONDHAND, SensitivityLabel.UNVERIFIED]
+    )
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("claim_text")
+    @classmethod
+    def claim_text_required(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("claim_text cannot be empty")
+        return value
+
+
+class FollowUpTask(StrictModel):
+    description: str
+    due_at: date | None = None
+    related_people: list[PersonRef] = Field(default_factory=list)
+    status: Literal["open", "done", "dismissed"] = "open"
+    sensitivity: list[SensitivityLabel] = Field(default_factory=list)
+
+
+class RelationshipAssertion(StrictModel):
+    source: PersonRef
+    target: PersonRef
+    relationship_type: str
+    directed: bool = False
+    sensitivity: list[SensitivityLabel] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Participant(StrictModel):
+    person: PersonRef
+    role: Literal["participant", "host", "organizer"] = "participant"
+
+
+class MentionedPerson(StrictModel):
+    person: PersonRef
+    mentioned_by: PersonRef | None = None
+    context: str | None = None
+
+
+class SocialInteraction(StrictModel):
+    source_text: str
+    occurred_at: datetime | None = None
+    interaction_type: Literal[
+        "meeting", "coffee", "dinner", "call", "message", "intro", "event", "other"
+    ] = "meeting"
+    place: str | None = None
+    participants: list[Participant] = Field(default_factory=list)
+    mentioned_people: list[MentionedPerson] = Field(default_factory=list)
+    topics: list[str] = Field(default_factory=list)
+    direct_facts: list[DirectFact] = Field(default_factory=list)
+    attributed_claims: list[AttributedClaim] = Field(default_factory=list)
+    follow_ups: list[FollowUpTask] = Field(default_factory=list)
+    relationships: list[RelationshipAssertion] = Field(default_factory=list)
+    sensitivity: list[SensitivityLabel] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("source_text")
+    @classmethod
+    def source_text_required(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("source_text cannot be empty")
+        return value
+
+
+class PersonProfileUpdate(StrictModel):
+    person: PersonRef
+    source_text: str
+    work_history: list[WorkHistoryRecord] = Field(default_factory=list)
+    education: list[EducationRecord] = Field(default_factory=list)
+    interests: list[str] = Field(default_factory=list)
+    important_dates: list[ImportantDate] = Field(default_factory=list)
+    contacts: list[ContactMethod] = Field(default_factory=list)
+    preferences: list[str] = Field(default_factory=list)
+    direct_facts: list[DirectFact] = Field(default_factory=list)
+    sensitivity: list[SensitivityLabel] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class IdentityCandidate(StrictModel):
+    person_id: str
+    display_name: str
+    score: float = Field(ge=0.0, le=1.0)
+    evidence: list[str] = Field(default_factory=list)
+    exact_identifier_match: bool = False
+    exact_name_match: bool = False
+
+
+class IdentityAdvice(StrictModel):
+    recommendation: Literal[
+        "same_person",
+        "different_person",
+        "ambiguous_needs_review",
+        "unknown",
+    ] = "unknown"
+    confidence: float = Field(default=0.0, ge=0.0, le=1.0)
+    candidate_person_id: str | None = None
+    reasons: list[str] = Field(default_factory=list)
+    evidence: list[str] = Field(default_factory=list)
+
+
+class ReviewItem(StrictModel):
+    review_id: str
+    kind: Literal["identity", "relationship", "date", "sensitivity", "merge"]
+    message: str
+    candidates: list[IdentityCandidate] = Field(default_factory=list)
+    subject_person_id: str | None = None
+    source_text: str | None = None
+    created_at: datetime
+    status: Literal["open", "resolved", "dismissed"] = "open"
+    resolved_to_person_id: str | None = None
+    resolved_at: datetime | None = None
+    resolution_note: str | None = None
+
+
+class OpportunityTimeHint(StrictModel):
+    text: str | None = None
+    normalized_date: date | None = None
+    needs_interpretation: bool = False
+    default_assumption: str | None = None
+
+
+class HarnessContextRequest(StrictModel):
+    kind: Literal["search_harness_memory", "inspect_available_tools", "apply_user_preferences"]
+    query: str
+    purpose: str
+
+
+class PostCaptureOpportunity(StrictModel):
+    kind: Literal["open_loop", "context_enrichment", "identity_review", "sensitivity_review"]
+    priority: Literal["low", "medium", "high"] = "medium"
+    summary: str
+    user_value: str
+    recommended_default: Literal["execute_if_supported", "ask_first", "do_not_execute"]
+    possible_next_steps: list[str] = Field(default_factory=list)
+    risk_level: Literal["low", "medium", "high"] = "low"
+    reversibility: Literal["easy", "manual", "hard", "impossible"] = "easy"
+    external_visibility: Literal["private", "local", "visible_to_others"] = "private"
+    requires_confirmation: bool = False
+    undo_hint: str | None = None
+    time_hint: OpportunityTimeHint | None = None
+    related_people: list[PersonRef] = Field(default_factory=list)
+    harness_context_requests: list[HarnessContextRequest] = Field(default_factory=list)
+    evidence: list[Evidence] = Field(default_factory=list)
+
+
+class CapturedPersonSummary(StrictModel):
+    person_id: str
+    label: str
+    action: Literal["created", "updated", "linked"]
+    roles: list[str] = Field(default_factory=list)
+    correction_hint: str | None = None
+
+
+class CaptureSummary(StrictModel):
+    status: Literal["saved"] = "saved"
+    people: list[CapturedPersonSummary] = Field(default_factory=list)
+    details: list[str] = Field(default_factory=list)
+    follow_ups: list[str] = Field(default_factory=list)
+    reviews: list[str] = Field(default_factory=list)
+    correction_hint: str = (
+        "If anything is wrong, tell the assistant immediately, for example "
+        "'different person', 'same person', or 'remove that follow-up'."
+    )
+
+
+class RecordInteractionResult(StrictModel):
+    interaction_id: str
+    saved: bool = True
+    created_people: list[str] = Field(default_factory=list)
+    updated_people: list[str] = Field(default_factory=list)
+    person_ref_map: dict[str, str] = Field(default_factory=dict)
+    needs_review: list[ReviewItem] = Field(default_factory=list)
+    evidence: list[Evidence] = Field(default_factory=list)
+    capture_summary: CaptureSummary | None = None
+    captured_follow_ups: list[FollowUpTask] = Field(default_factory=list)
+    post_capture_opportunities: list[PostCaptureOpportunity] = Field(default_factory=list)
+    harness_context_requests: list[HarnessContextRequest] = Field(default_factory=list)
+
+
+class PersonMemoryRecord(StrictModel):
+    person_id: str
+    display_name: str
+    aliases: list[str] = Field(default_factory=list)
+    work_history: list[WorkHistoryRecord] = Field(default_factory=list)
+    education: list[EducationRecord] = Field(default_factory=list)
+    interests: list[str] = Field(default_factory=list)
+    important_dates: list[ImportantDate] = Field(default_factory=list)
+    contacts: list[ContactMethod] = Field(default_factory=list)
+    preferences: list[str] = Field(default_factory=list)
+    direct_facts: list[DirectFact] = Field(default_factory=list)
+    attributed_claims: list[AttributedClaim] = Field(default_factory=list)
+    relationships: list[RelationshipAssertion] = Field(default_factory=list)
+    interactions: list[SocialInteraction] = Field(default_factory=list)
+    follow_ups: list[FollowUpTask] = Field(default_factory=list)
+    evidence: list[Evidence] = Field(default_factory=list)
+
+
+class PersonCard(StrictModel):
+    person_id: str
+    display_name: str
+    aliases: list[str] = Field(default_factory=list)
+    headline: str | None = None
+    summary: str | None = None
+    work_history: list[WorkHistoryRecord] = Field(default_factory=list)
+    education: list[EducationRecord] = Field(default_factory=list)
+    interests: list[str] = Field(default_factory=list)
+    important_dates: list[ImportantDate] = Field(default_factory=list)
+    contacts: list[ContactMethod] = Field(default_factory=list)
+    preferences: list[str] = Field(default_factory=list)
+    recent_interactions: list[str] = Field(default_factory=list)
+    attributed_claims: list[AttributedClaim] = Field(default_factory=list)
+    relationships: list[RelationshipAssertion] = Field(default_factory=list)
+    open_follow_ups: list[FollowUpTask] = Field(default_factory=list)
+    evidence: list[Evidence] = Field(default_factory=list)
+
+
+class RetrievalItem(StrictModel):
+    item_id: str
+    kind: Literal["person", "interaction", "fact", "claim", "follow_up"]
+    title: str
+    matched_text: str
+    score: float = Field(ge=0.0)
+    why_matched: str
+    person_ids: list[str] = Field(default_factory=list)
+    sensitivity: list[SensitivityLabel] = Field(default_factory=list)
+    evidence: list[Evidence] = Field(default_factory=list)
+    is_secondhand: bool = False
+
+
+class RetrievalResponse(StrictModel):
+    query: str
+    mode: Literal["recall", "brief"] = "recall"
+    sensitivity_policy: Literal["personal", "strict", "task_aware"] = "personal"
+    output_context: Literal["private", "shareable"] = "private"
+    sensitive_results_included: bool = False
+    results: list[RetrievalItem] = Field(default_factory=list)
+    missing_info: list[str] = Field(default_factory=list)
+    needs_review: list[ReviewItem] = Field(default_factory=list)
+    ambiguous: bool = False
+    result_type: str | None = None
+    answer_policy: str | None = None
+    candidates: list[dict[str, Any]] = Field(default_factory=list)
+    final_answer_instruction: str | None = None
+    candidate_results: list[dict[str, Any]] = Field(default_factory=list)

package/src/people_network_memory/fixtures/__init__.py

@@ -0,0 +1,6 @@
+"""Deterministic mock data for testing and demos."""
+
+from people_network_memory.fixtures.generator import MockDataset, generate_mock_dataset
+
+__all__ = ["MockDataset", "generate_mock_dataset"]
+