chronem 0.1.0__py3-none-any.whl

chronem/__init__.py

@@ -0,0 +1,111 @@
+"""Chronem temporal memory engine."""
+
+from chronem.answers import (
+    NO_EVIDENCE_MESSAGE,
+    RecallAnswerInvariantError,
+    RecallAnswerOutcome,
+    RecallAnswerResult,
+    RecallAnswerService,
+    SynthesizedAnswer,
+)
+from chronem.entities import DeterministicEntityResolver, normalize_entity_name
+from chronem.ingestion import (
+    CandidateIngestionOutcome,
+    CandidateIngestionResult,
+    EntityMentionRole,
+    IngestionInvariantError,
+    IngestionResult,
+    IngestionService,
+)
+from chronem.interfaces import (
+    AnswerSynthesizer,
+    CaptureRepository,
+    Clock,
+    EntityRepository,
+    EntityResolution,
+    EntityResolutionOutcome,
+    EntityResolver,
+    Extractor,
+    MemoryQuery,
+    MemoryQueryOrder,
+    MemoryQueryRepository,
+    MemoryRepository,
+    RecallPlanner,
+    RepositoryInvariantError,
+)
+from chronem.lifecycle.engine import LifecycleAction, LifecycleDecision, LifecycleEngine
+from chronem.models.candidate import CandidateMemory
+from chronem.models.capture import Capture, SourceType
+from chronem.models.entity import Entity, EntityType
+from chronem.models.memory import Memory
+from chronem.models.types import MemoryKind, MemoryStatus
+from chronem.recall import (
+    RecallExecutionOutcome,
+    RecallExecutionResult,
+    RecallInvariantError,
+    RecallMode,
+    RecallOrchestrationInvariantError,
+    RecallOrchestrationService,
+    RecallOutcome,
+    RecallPlan,
+    RecallPlanOutcome,
+    RecallRequestExecution,
+    StructuredRecallRequest,
+    StructuredRecallResult,
+    StructuredRecallService,
+)
+
+__all__ = [
+    "AnswerSynthesizer",
+    "CandidateMemory",
+    "CandidateIngestionOutcome",
+    "CandidateIngestionResult",
+    "Capture",
+    "CaptureRepository",
+    "Clock",
+    "DeterministicEntityResolver",
+    "Entity",
+    "EntityResolution",
+    "EntityResolutionOutcome",
+    "EntityRepository",
+    "EntityResolver",
+    "EntityType",
+    "EntityMentionRole",
+    "Extractor",
+    "IngestionInvariantError",
+    "IngestionResult",
+    "IngestionService",
+    "LifecycleAction",
+    "LifecycleDecision",
+    "LifecycleEngine",
+    "Memory",
+    "MemoryKind",
+    "MemoryRepository",
+    "MemoryQuery",
+    "MemoryQueryOrder",
+    "MemoryQueryRepository",
+    "MemoryStatus",
+    "NO_EVIDENCE_MESSAGE",
+    "RepositoryInvariantError",
+    "RecallInvariantError",
+    "RecallAnswerInvariantError",
+    "RecallAnswerOutcome",
+    "RecallAnswerResult",
+    "RecallAnswerService",
+    "RecallExecutionOutcome",
+    "RecallExecutionResult",
+    "RecallMode",
+    "RecallOutcome",
+    "RecallOrchestrationInvariantError",
+    "RecallOrchestrationService",
+    "RecallPlan",
+    "RecallPlanner",
+    "RecallPlanOutcome",
+    "RecallRequestExecution",
+    "SourceType",
+    "StructuredRecallRequest",
+    "StructuredRecallResult",
+    "StructuredRecallService",
+    "SynthesizedAnswer",
+    "normalize_entity_name",
+]

chronem/answers/__init__.py

@@ -0,0 +1,18 @@
+"""Grounded answer synthesis public API."""
+
+from chronem.answers.models import (
+    NO_EVIDENCE_MESSAGE,
+    RecallAnswerOutcome,
+    RecallAnswerResult,
+    SynthesizedAnswer,
+)
+from chronem.answers.service import RecallAnswerInvariantError, RecallAnswerService
+
+__all__ = [
+    "NO_EVIDENCE_MESSAGE",
+    "RecallAnswerInvariantError",
+    "RecallAnswerOutcome",
+    "RecallAnswerResult",
+    "RecallAnswerService",
+    "SynthesizedAnswer",
+]

chronem/answers/models.py

@@ -0,0 +1,92 @@
+"""Provider-independent models for grounded recall answers."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from uuid import UUID
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from chronem.models._shared import require_non_blank
+from chronem.models.memory import Memory
+from chronem.recall.models import RecallExecutionOutcome, RecallExecutionResult
+
+NO_EVIDENCE_MESSAGE = "I don't have that saved."
+
+
+class SynthesizedAnswer(BaseModel):
+    """User-facing wording and the grounded memory ids supporting it."""
+
+    text: str = Field(min_length=1)
+    cited_memory_ids: tuple[UUID, ...] = Field(min_length=1)
+
+    @field_validator("text")
+    @classmethod
+    def _validate_text(cls, value: str) -> str:
+        return require_non_blank(value, field_name="answer text")
+
+    @model_validator(mode="after")
+    def _reject_duplicate_citations(self) -> SynthesizedAnswer:
+        if len(self.cited_memory_ids) != len(set(self.cited_memory_ids)):
+            raise ValueError("cited_memory_ids must not contain duplicates")
+        return self
+
+
+class RecallAnswerOutcome(StrEnum):
+    """Outcome of deterministic recall plus optional grounded phrasing."""
+
+    ANSWERED = "ANSWERED"
+    PARTIAL = "PARTIAL"
+    NOT_FOUND = "NOT_FOUND"
+    UNSUPPORTED = "UNSUPPORTED"
+    AMBIGUOUS_PLAN = "AMBIGUOUS_PLAN"
+    AMBIGUOUS_SUBJECT = "AMBIGUOUS_SUBJECT"
+    SUBJECT_TYPE_CONFLICT = "SUBJECT_TYPE_CONFLICT"
+
+
+class RecallAnswerResult(BaseModel):
+    """Complete recall evidence and its validated user-facing answer, if any."""
+
+    outcome: RecallAnswerOutcome
+    text: str | None = None
+    cited_memory_ids: tuple[UUID, ...] = ()
+    recall_result: RecallExecutionResult
+
+    @property
+    def evidence(self) -> tuple[Memory, ...]:
+        """Return evidence unchanged in deterministic recall order."""
+        return self.recall_result.memories
+
+    @model_validator(mode="after")
+    def _validate_shape(self) -> RecallAnswerResult:
+        if self.outcome in (RecallAnswerOutcome.ANSWERED, RecallAnswerOutcome.PARTIAL):
+            if self.text is None or not self.text.strip():
+                raise ValueError("answered results require nonblank text")
+            if not self.cited_memory_ids:
+                raise ValueError("answered results require at least one citation")
+        elif self.cited_memory_ids:
+            raise ValueError("non-answered results cannot contain citations")
+
+        if self.outcome == RecallAnswerOutcome.NOT_FOUND:
+            if self.text != NO_EVIDENCE_MESSAGE:
+                raise ValueError("NOT_FOUND requires the deterministic no-evidence message")
+        elif self.outcome not in (
+            RecallAnswerOutcome.ANSWERED,
+            RecallAnswerOutcome.PARTIAL,
+        ) and self.text is not None:
+            raise ValueError("abstained results cannot contain answer text")
+
+        expected_recall_outcome = {
+            RecallAnswerOutcome.ANSWERED: RecallExecutionOutcome.FOUND,
+            RecallAnswerOutcome.PARTIAL: RecallExecutionOutcome.PARTIAL,
+            RecallAnswerOutcome.NOT_FOUND: RecallExecutionOutcome.NOT_FOUND,
+            RecallAnswerOutcome.UNSUPPORTED: RecallExecutionOutcome.UNSUPPORTED,
+            RecallAnswerOutcome.AMBIGUOUS_PLAN: RecallExecutionOutcome.AMBIGUOUS_PLAN,
+            RecallAnswerOutcome.AMBIGUOUS_SUBJECT: RecallExecutionOutcome.AMBIGUOUS_SUBJECT,
+            RecallAnswerOutcome.SUBJECT_TYPE_CONFLICT: (
+                RecallExecutionOutcome.SUBJECT_TYPE_CONFLICT
+            ),
+        }[self.outcome]
+        if self.recall_result.outcome != expected_recall_outcome:
+            raise ValueError("answer outcome must match the deterministic recall outcome")
+        return self

chronem/answers/service.py

@@ -0,0 +1,160 @@
+"""Provider-independent orchestration from grounded recall to an answer."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from chronem.answers.models import (
+    NO_EVIDENCE_MESSAGE,
+    RecallAnswerOutcome,
+    RecallAnswerResult,
+    SynthesizedAnswer,
+)
+from chronem.models._shared import require_non_blank, require_timezone_aware
+from chronem.models.memory import Memory
+from chronem.models.types import MemoryKind
+from chronem.recall.models import RecallExecutionOutcome, RecallExecutionResult
+from chronem.recall.orchestration import RecallOrchestrationService
+
+if TYPE_CHECKING:
+    from chronem.interfaces.answers import AnswerSynthesizer
+
+
+class RecallAnswerInvariantError(ValueError):
+    """Raised when grounded synthesis violates the answer boundary."""
+
+
+class RecallAnswerService:
+    """Phrase deterministic recall evidence without adding retrieval authority."""
+
+    def __init__(
+        self,
+        *,
+        recall_orchestration_service: RecallOrchestrationService,
+        answer_synthesizer: AnswerSynthesizer,
+    ) -> None:
+        self._recall_orchestration_service = recall_orchestration_service
+        self._answer_synthesizer = answer_synthesizer
+
+    def answer(
+        self,
+        *,
+        user_id: str,
+        question: str,
+        asked_at: datetime,
+    ) -> RecallAnswerResult:
+        scoped_user_id = require_non_blank(user_id, field_name="user_id")
+        question_text = require_non_blank(question, field_name="question")
+        reference_time = require_timezone_aware(asked_at, field_name="asked_at")
+        recall_result = self._recall_orchestration_service.recall(
+            user_id=scoped_user_id,
+            question=question_text,
+            asked_at=reference_time,
+        )
+
+        deterministic_outcome = _non_synthesis_outcome(recall_result.outcome)
+        if deterministic_outcome is not None:
+            return RecallAnswerResult(
+                outcome=deterministic_outcome,
+                text=(
+                    NO_EVIDENCE_MESSAGE
+                    if deterministic_outcome == RecallAnswerOutcome.NOT_FOUND
+                    else None
+                ),
+                recall_result=recall_result,
+            )
+
+        evidence = recall_result.memories
+        self._validate_evidence(user_id=scoped_user_id, evidence=evidence)
+        synthesized = self._answer_synthesizer.synthesize(
+            question=question_text,
+            evidence=evidence,
+            asked_at=reference_time,
+        )
+        self._validate_synthesis(
+            synthesized=synthesized,
+            evidence=evidence,
+            recall_result=recall_result,
+        )
+
+        return RecallAnswerResult(
+            outcome=(
+                RecallAnswerOutcome.ANSWERED
+                if recall_result.outcome == RecallExecutionOutcome.FOUND
+                else RecallAnswerOutcome.PARTIAL
+            ),
+            text=synthesized.text,
+            cited_memory_ids=synthesized.cited_memory_ids,
+            recall_result=recall_result,
+        )
+
+    @staticmethod
+    def _validate_evidence(*, user_id: str, evidence: tuple[Memory, ...]) -> None:
+        if not evidence:
+            raise RecallAnswerInvariantError(
+                "FOUND and PARTIAL recall outcomes require grounded evidence"
+            )
+        if any(memory.user_id != user_id for memory in evidence):
+            raise RecallAnswerInvariantError(
+                "recall evidence contains a memory from another user scope"
+            )
+
+    @staticmethod
+    def _validate_synthesis(
+        *,
+        synthesized: SynthesizedAnswer,
+        evidence: tuple[Memory, ...],
+        recall_result: RecallExecutionResult,
+    ) -> None:
+        cited_ids = synthesized.cited_memory_ids
+        if not cited_ids:
+            raise RecallAnswerInvariantError("a grounded answer requires at least one citation")
+        if len(cited_ids) != len(set(cited_ids)):
+            raise RecallAnswerInvariantError(
+                "grounded answer citations must not contain duplicates"
+            )
+
+        evidence_ids = {memory.id for memory in evidence}
+        unknown_ids = set(cited_ids) - evidence_ids
+        if unknown_ids:
+            raise RecallAnswerInvariantError(
+                "grounded answer cites memory ids outside the supplied evidence"
+            )
+
+        required_fact_ids = _multi_fact_request_ids(recall_result)
+        if not required_fact_ids.issubset(cited_ids):
+            raise RecallAnswerInvariantError(
+                "grounded answer must cite every FACT memory returned by a "
+                "multi-memory FACT request"
+            )
+
+
+def _non_synthesis_outcome(
+    outcome: RecallExecutionOutcome,
+) -> RecallAnswerOutcome | None:
+    return {
+        RecallExecutionOutcome.NOT_FOUND: RecallAnswerOutcome.NOT_FOUND,
+        RecallExecutionOutcome.UNSUPPORTED: RecallAnswerOutcome.UNSUPPORTED,
+        RecallExecutionOutcome.AMBIGUOUS_PLAN: RecallAnswerOutcome.AMBIGUOUS_PLAN,
+        RecallExecutionOutcome.AMBIGUOUS_SUBJECT: RecallAnswerOutcome.AMBIGUOUS_SUBJECT,
+        RecallExecutionOutcome.SUBJECT_TYPE_CONFLICT: (
+            RecallAnswerOutcome.SUBJECT_TYPE_CONFLICT
+        ),
+    }.get(outcome)
+
+
+def _multi_fact_request_ids(recall_result: RecallExecutionResult) -> set[UUID]:
+    required_ids: set[UUID] = set()
+    for execution in recall_result.executions:
+        if execution.request.kind != MemoryKind.FACT:
+            continue
+        fact_memories = tuple(
+            memory
+            for memory in execution.result.memories
+            if memory.kind == MemoryKind.FACT
+        )
+        if len(fact_memories) > 1:
+            required_ids.update(memory.id for memory in fact_memories)
+    return required_ids

chronem/entities/__init__.py

@@ -0,0 +1,6 @@
+"""Deterministic, conservative entity-resolution behavior."""
+
+from chronem.entities.normalization import normalize_entity_name
+from chronem.entities.resolver import DeterministicEntityResolver
+
+__all__ = ["DeterministicEntityResolver", "normalize_entity_name"]

chronem/entities/normalization.py

@@ -0,0 +1,15 @@
+"""Pure normalization for deterministic entity-name comparison."""
+
+import unicodedata
+
+
+def normalize_entity_name(value: str) -> str:
+    """Normalize a name without erasing identity-significant distinctions.
+
+    NFKC normalization is followed by outer trimming, whitespace collapsing,
+    and Unicode case folding. Punctuation and diacritics remain intact.
+    """
+    normalized = " ".join(unicodedata.normalize("NFKC", value).split()).casefold()
+    if not normalized:
+        raise ValueError("entity name must not be blank")
+    return normalized

chronem/entities/resolver.py

@@ -0,0 +1,57 @@
+"""Conservative deterministic entity resolution."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from chronem.entities.normalization import normalize_entity_name
+from chronem.interfaces.entities import EntityResolution, EntityResolutionOutcome, EntityResolver
+from chronem.interfaces.repositories import EntityRepository, RepositoryInvariantError
+from chronem.models._shared import require_non_blank
+from chronem.models.entity import Entity
+
+
+class DeterministicEntityResolver(EntityResolver):
+    """Match only normalized canonical names and explicit aliases.
+
+    Resolution is read-only. Unmatched entity creation and all merge decisions
+    belong outside this resolver; ingestion orchestration may create an entity.
+    """
+
+    def __init__(self, repository: EntityRepository) -> None:
+        self._repository = repository
+
+    def resolve(self, *, user_id: str, mention: str) -> EntityResolution:
+        scoped_user_id = require_non_blank(user_id, field_name="user_id")
+        normalized_mention = normalize_entity_name(mention)
+        matches: dict[UUID, Entity] = {}
+
+        for entity in self._repository.list_for_user(user_id=scoped_user_id):
+            if entity.user_id != scoped_user_id:
+                raise RepositoryInvariantError(
+                    "entity repository returned a record from a different user scope"
+                )
+            names = (entity.canonical_name, *entity.aliases)
+            if any(normalize_entity_name(name) == normalized_mention for name in names):
+                matches[entity.id] = entity
+
+        candidates = tuple(matches[entity_id] for entity_id in sorted(matches))
+        if not candidates:
+            return EntityResolution(
+                user_id=scoped_user_id,
+                mention=mention,
+                outcome=EntityResolutionOutcome.UNMATCHED,
+            )
+        if len(candidates) == 1:
+            return EntityResolution(
+                user_id=scoped_user_id,
+                mention=mention,
+                outcome=EntityResolutionOutcome.MATCHED,
+                matched_entity=candidates[0],
+            )
+        return EntityResolution(
+            user_id=scoped_user_id,
+            mention=mention,
+            outcome=EntityResolutionOutcome.AMBIGUOUS,
+            candidates=candidates,
+        )

chronem/evaluation/__init__.py

@@ -0,0 +1,40 @@
+"""Provider-independent deterministic evaluation public API."""
+
+from chronem.evaluation.metrics import classification_metrics, summarize_results
+from chronem.evaluation.models import (
+    AnswerGroundingEvaluationCase,
+    ClassificationMetrics,
+    EntityResolutionEvaluationCase,
+    EvaluationCase,
+    EvaluationDomain,
+    EvaluationReport,
+    EvaluationResult,
+    EvaluationSummary,
+    ExtractionEvaluationCase,
+    LifecycleEvaluationCase,
+    RecallPlanningEvaluationCase,
+    StructuredRecallEvaluationCase,
+)
+from chronem.evaluation.runner import build_report, evaluation_exit_code, run_core_evaluations
+from chronem.evaluation.structured_recall import evaluate_structured_recall
+
+__all__ = [
+    "AnswerGroundingEvaluationCase",
+    "ClassificationMetrics",
+    "EntityResolutionEvaluationCase",
+    "EvaluationCase",
+    "EvaluationDomain",
+    "EvaluationReport",
+    "EvaluationResult",
+    "EvaluationSummary",
+    "ExtractionEvaluationCase",
+    "LifecycleEvaluationCase",
+    "RecallPlanningEvaluationCase",
+    "StructuredRecallEvaluationCase",
+    "classification_metrics",
+    "build_report",
+    "evaluate_structured_recall",
+    "evaluation_exit_code",
+    "run_core_evaluations",
+    "summarize_results",
+]

chronem/evaluation/data/__init__.py

@@ -0,0 +1 @@
+"""Versioned evaluation datasets packaged with Chronem."""

chronem/evaluation/data/recall_planning.json

@@ -0,0 +1,14 @@
+[
+  {"name":"parking_current","question":"Where did I park?","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"PLANNED","expected_requests":[{"subject":"my car","expected_subject_type":"vehicle","kind":"CURRENT_STATE","predicate":"parked_at","mode":"CURRENT"}]},
+  {"name":"passport_current","question":"Where is my passport?","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"PLANNED","expected_requests":[{"subject":"my passport","expected_subject_type":"object","kind":"CURRENT_STATE","predicate":"located_at","mode":"CURRENT"}]},
+  {"name":"birthday_fact","question":"When is Kevin's birthday?","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"PLANNED","expected_requests":[{"subject":"Kevin","expected_subject_type":"person","kind":"FACT","predicate":"birthday","mode":"CURRENT"}]},
+  {"name":"friend_preferences","question":"What does Kevin like?","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"PLANNED","expected_requests":[{"subject":"Kevin","expected_subject_type":"person","kind":"PREFERENCE","predicate":"likes","mode":"ACTIVE"}]},
+  {"name":"bench_history","question":"Show my recent bench press history.","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"PLANNED","expected_requests":[{"subject":"me","expected_subject_type":"person","kind":"EVENT","predicate":"bench_press","mode":"HISTORY"}]},
+  {"name":"latest_oil_change","question":"When did I last change the oil?","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"PLANNED","expected_requests":[{"subject":"my vehicle","expected_subject_type":"vehicle","kind":"EVENT","predicate":"oil_changed","mode":"LATEST"}]},
+  {"name":"active_shopping","question":"What am I still planning to buy?","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"PLANNED","expected_requests":[{"subject":"me","expected_subject_type":"person","kind":"INTENT","predicate":"buy","mode":"ACTIVE"}]},
+  {"name":"workouts_this_week","question":"What workouts did I log this week?","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"UNSUPPORTED","expected_requests":[]},
+  {"name":"bench_yesterday","question":"What did I bench yesterday?","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"PLANNED","expected_requests":[{"subject":"me","expected_subject_type":"person","kind":"EVENT","predicate":"bench_press","mode":"HISTORY","since":"2026-10-08T00:00:00+00:00","until":"2026-10-08T23:59:59.999999+00:00"}]},
+  {"name":"maintenance_last_month","question":"What maintenance did I record last month?","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"UNSUPPORTED","expected_requests":[]},
+  {"name":"unsupported_semantic","question":"Find memories similar to my happiest notes.","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"UNSUPPORTED","expected_requests":[]},
+  {"name":"ambiguous_target","question":"Where is it?","asked_at":"2026-10-09T15:30:00+00:00","expected_outcome":"AMBIGUOUS","expected_requests":[]}
+]