trisynapse-memory 0.1.0__py3-none-any.whl

trisynapse_memory/__init__.py

@@ -0,0 +1,109 @@
+"""Public Trace & Recall API for Trisynapse Memory."""
+
+from trisynapse_memory._version import __version__
+from trisynapse_memory.engine import (
+    Actor,
+    Citation,
+    CompiledClaim,
+    CompletionProvider,
+    ConnectionTestResult,
+    EmbeddingRebuildRequired,
+    EpisodeInfo,
+    EpisodeRecallView,
+    LoadedDocument,
+    MemoryDelta,
+    MemoryEngine,
+    MemoryHistory,
+    MemoryGraphEdge,
+    MemoryGraphNode,
+    MemoryGraphPage,
+    MemoryJob,
+    MemoryNamespace,
+    MemoryPage,
+    MemoryQueryResult,
+    MemorySearchResult,
+    ModelConfiguration,
+    ModelConfigurationChange,
+    ModelDescriptor,
+    PrivacyFilter,
+    ProviderError,
+    ProviderDescriptor,
+    ProviderRole,
+    ProviderSelection,
+    ProviderSettings,
+    QueryCandidateSnapshot,
+    QueryRun,
+    QueryRunPage,
+    QueryRunRemoveRequest,
+    QueryStep,
+    RetrievalConfiguration,
+    IngestionRun,
+    RemoveRequest,
+    RemoveResult,
+    RecallSnapshot,
+    RedactionResult,
+    RetrievalTrace,
+    SearchHit,
+    SnapshotDiff,
+    SourceIngestionResult,
+    SourceInput,
+    SourceRecord,
+    SourcePreview,
+    SourcePreviewItem,
+    TraceVerification,
+    load_document,
+)
+
+__all__ = [
+    "__version__",
+    "Actor",
+    "Citation",
+    "CompiledClaim",
+    "CompletionProvider",
+    "ConnectionTestResult",
+    "EmbeddingRebuildRequired",
+    "EpisodeInfo",
+    "EpisodeRecallView",
+    "LoadedDocument",
+    "MemoryDelta",
+    "MemoryEngine",
+    "MemoryHistory",
+    "MemoryGraphEdge",
+    "MemoryGraphNode",
+    "MemoryGraphPage",
+    "MemoryJob",
+    "MemoryNamespace",
+    "MemoryPage",
+    "MemoryQueryResult",
+    "MemorySearchResult",
+    "ModelConfiguration",
+    "ModelConfigurationChange",
+    "ModelDescriptor",
+    "PrivacyFilter",
+    "ProviderError",
+    "ProviderDescriptor",
+    "ProviderRole",
+    "ProviderSelection",
+    "ProviderSettings",
+    "QueryCandidateSnapshot",
+    "QueryRun",
+    "QueryRunPage",
+    "QueryRunRemoveRequest",
+    "QueryStep",
+    "RetrievalConfiguration",
+    "IngestionRun",
+    "RemoveRequest",
+    "RemoveResult",
+    "RecallSnapshot",
+    "RedactionResult",
+    "RetrievalTrace",
+    "SearchHit",
+    "SnapshotDiff",
+    "SourceIngestionResult",
+    "SourceInput",
+    "SourceRecord",
+    "SourcePreview",
+    "SourcePreviewItem",
+    "TraceVerification",
+    "load_document",
+]

trisynapse_memory/_version.py

@@ -0,0 +1,34 @@
+"""Resolve the public package version from one canonical source."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+import tomllib
+
+
+def _source_tree_version() -> str | None:
+    """Read pyproject.toml when running directly from a source checkout."""
+
+    pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+    if not pyproject.is_file():
+        return None
+    with pyproject.open("rb") as stream:
+        value = tomllib.load(stream).get("project", {}).get("version")
+    return str(value) if value else None
+
+
+def get_version() -> str:
+    """Return the source version in a checkout or installed distribution metadata."""
+
+    source_version = _source_tree_version()
+    if source_version is not None:
+        return source_version
+    try:
+        return version("trisynapse-memory")
+    except PackageNotFoundError:
+        return "0+unknown"
+
+
+__version__ = get_version()
+

trisynapse_memory/adapters/__init__.py

@@ -0,0 +1,10 @@
+"""Package-wide external integration and dataset-adapter boundary.
+
+Live integrations are exported here; benchmark adapters are available from
+``trisynapse_memory.adapters.benchmarks`` to avoid eagerly loading their registry.
+"""
+
+from trisynapse_memory.adapters.agent_events import AgentEvent, capture_agent_event
+from trisynapse_memory.adapters.trisynapse_live import open_vault_engine
+
+__all__ = ["AgentEvent", "capture_agent_event", "open_vault_engine"]

trisynapse_memory/adapters/agent_events.py

@@ -0,0 +1,82 @@
+"""Generic coding-agent lifecycle events for automatic capture and context injection."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from trisynapse_memory.engine import MemoryEngine
+from trisynapse_memory.engine.models import MemoryNamespace
+
+
+class AgentEvent(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    type: Literal[
+        "session_start", "user_prompt", "pre_tool", "post_tool", "post_tool_failure",
+        "pre_compact", "subagent_start", "subagent_stop", "stop", "session_end",
+    ]
+    session_id: str
+    agent_id: str
+    project_id: str = "default"
+    user_id: str | None = None
+    tool_name: str | None = None
+    content: str | None = None
+    input: dict[str, Any] | None = None
+    output: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+def capture_agent_event(engine: MemoryEngine, event: AgentEvent | dict[str, Any]) -> dict[str, Any]:
+    value = event if isinstance(event, AgentEvent) else AgentEvent.model_validate(event)
+    namespace = MemoryNamespace(
+        user_id=value.user_id,
+        agent_id=value.agent_id,
+        project_id=value.project_id,
+        session_id=value.session_id,
+    )
+    episode_id = f"agent:{value.agent_id}:{value.session_id}"
+    if value.type in {"session_start", "pre_compact"}:
+        query = value.content or "current project decisions, constraints, preferences, failures, and next steps"
+        profile = engine.compile_profile(namespace=namespace, query=query)
+        return {"captured": False, "context": profile, "namespace": namespace.model_dump(mode="json")}
+
+    text = _event_text(value)
+    if not text:
+        return {"captured": False, "reason": "event contains no durable content"}
+    delta = engine.ingest_observation(
+        text,
+        episode_id=episode_id,
+        source_ref={"type": "agent_event", "agent_id": value.agent_id, "session_id": value.session_id},
+        locator={"event_type": value.type, "tool_name": value.tool_name},
+        scope={"event_type": value.type, **value.metadata},
+        namespace=namespace,
+        external_key=value.metadata.get("event_id"),
+    )
+    response: dict[str, Any] = {"captured": True, "delta_id": delta.id}
+    if value.type in {"stop", "session_end"}:
+        engine.build_episode_recall([episode_id], namespace=namespace)
+        response["context"] = engine.compile_profile(namespace=namespace)
+    return response
+
+
+def _event_text(event: AgentEvent) -> str:
+    if event.type == "user_prompt":
+        return f"User prompt: {event.content or ''}".strip()
+    if event.type == "pre_tool":
+        return f"Tool planned: {event.tool_name or 'unknown'} input={_bounded(event.input)}"
+    if event.type in {"post_tool", "post_tool_failure"}:
+        status = "failed" if event.type == "post_tool_failure" else "completed"
+        return f"Tool {event.tool_name or 'unknown'} {status}. Output: {(event.output or '')[:8000]}".strip()
+    if event.type in {"subagent_start", "subagent_stop"}:
+        return f"{event.type.replace('_', ' ')}: {event.content or _bounded(event.metadata)}"
+    if event.type in {"stop", "session_end"}:
+        return f"Session ended: {event.content or 'No explicit summary supplied.'}"
+    return event.content or ""
+
+
+def _bounded(value: Any) -> str:
+    text = str(value or "")
+    return text[:8000]
+

trisynapse_memory/adapters/benchmarks/__init__.py

@@ -0,0 +1,29 @@
+"""Registry of benchmark-specific dataset adapters."""
+
+from __future__ import annotations
+
+from trisynapse_memory.adapters.benchmarks.base import BenchmarkAdapter
+from trisynapse_memory.adapters.benchmarks.halumem import HaluMemAdapter
+from trisynapse_memory.adapters.benchmarks.locomo import LoCoMoAdapter
+from trisynapse_memory.adapters.benchmarks.longmemeval import LongMemEvalAdapter
+from trisynapse_memory.adapters.benchmarks.memorydoc import MemoryDocAdapter
+
+_ADAPTERS: dict[str, BenchmarkAdapter] = {
+    adapter.name: adapter
+    for adapter in (LoCoMoAdapter(), LongMemEvalAdapter(), HaluMemAdapter(), MemoryDocAdapter())
+}
+
+
+def get_adapter(name: str) -> BenchmarkAdapter:
+    try:
+        return _ADAPTERS[name]
+    except KeyError as exc:
+        supported = ", ".join(sorted(_ADAPTERS))
+        raise ValueError(f"unsupported benchmark suite '{name}'; choose one of: {supported}") from exc
+
+
+def adapter_names() -> tuple[str, ...]:
+    return tuple(sorted(_ADAPTERS))
+
+
+__all__ = ["BenchmarkAdapter", "adapter_names", "get_adapter"]

trisynapse_memory/adapters/benchmarks/base.py

@@ -0,0 +1,79 @@
+"""Dataset adapter interface for production memory benchmarks."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, ClassVar
+
+from trisynapse_memory.engine import MemoryEngine
+from trisynapse_memory.engine.models import MemoryNamespace, MemoryQueryResult
+
+
+@dataclass(frozen=True)
+class BenchmarkQuestion:
+    """A normalized question produced by a dataset adapter."""
+
+    id: str
+    question: str
+    gold: str
+    evidence: Any = None
+    evidence_text: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class BenchmarkCase:
+    """One isolated memory world containing one or more questions."""
+
+    id: str
+    payload: dict[str, Any]
+    questions: tuple[BenchmarkQuestion, ...]
+
+
+@dataclass(frozen=True)
+class PreparedCase:
+    """The engine-facing context returned after adapter ingestion."""
+
+    episode_ids: tuple[str, ...]
+    namespace: MemoryNamespace
+    episode_prefix: str | None = None
+
+
+class BenchmarkAdapter(ABC):
+    """Translate one external dataset into the shared benchmark lifecycle.
+
+    Adapters own file/schema interpretation and evidence semantics. They may
+    ingest through public ``MemoryEngine`` methods, but they never control
+    retrieval, extraction, judging, provider selection, or artifact writing.
+    """
+
+    name: ClassVar[str]
+    default_filename: ClassVar[str]
+
+    def resolve_dataset(self, data_root: str | Path) -> Path:
+        path = Path(data_root)
+        if path.is_dir():
+            path = path / self.default_filename
+        if not path.is_file():
+            raise FileNotFoundError(path)
+        return path
+
+    @abstractmethod
+    def load_cases(self, path: Path) -> Iterable[BenchmarkCase]:
+        """Parse source data into isolated, normalized cases."""
+
+    @abstractmethod
+    def ingest_case(self, engine: MemoryEngine, case: BenchmarkCase) -> PreparedCase:
+        """Ingest a case through the shipped engine and return query scope."""
+
+    def result_metadata(
+        self,
+        question: BenchmarkQuestion,
+        result: MemoryQueryResult,
+    ) -> dict[str, Any]:
+        """Return dataset-specific evidence metrics for one answer."""
+
+        return dict(question.metadata)

trisynapse_memory/adapters/benchmarks/halumem.py

@@ -0,0 +1,80 @@
+"""HaluMem dataset adapter."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from pathlib import Path
+
+from trisynapse_memory.adapters.benchmarks.base import (
+    BenchmarkAdapter,
+    BenchmarkCase,
+    BenchmarkQuestion,
+    PreparedCase,
+)
+from trisynapse_memory.engine import MemoryEngine
+from trisynapse_memory.engine.models import MemoryNamespace
+
+
+class HaluMemAdapter(BenchmarkAdapter):
+    name = "halumem"
+    default_filename = "HaluMem-Medium.jsonl"
+
+    def load_cases(self, path: Path) -> Iterable[BenchmarkCase]:
+        with path.open(encoding="utf-8") as handle:
+            for line_index, raw in enumerate(handle):
+                if not raw.strip():
+                    continue
+                user = json.loads(raw)
+                user_id = str(user.get("uuid") or line_index)
+                questions: list[BenchmarkQuestion] = []
+                for session_index, session in enumerate(user.get("sessions") or []):
+                    for question_index, item in enumerate(session.get("questions") or []):
+                        evidence_text = " ".join(
+                            str(value.get("memory_content") if isinstance(value, dict) else value)
+                            for value in item.get("evidence") or []
+                        )
+                        questions.append(BenchmarkQuestion(
+                            id=f"{user_id}:s{session_index}:q{question_index}",
+                            question=str(item.get("question") or ""),
+                            gold=str(item.get("answer") or ""),
+                            evidence=item.get("evidence") or [],
+                            evidence_text=evidence_text,
+                        ))
+                yield BenchmarkCase(id=user_id, payload=user, questions=tuple(questions))
+
+    def ingest_case(self, engine: MemoryEngine, case: BenchmarkCase) -> PreparedCase:
+        namespace = MemoryNamespace(project_id=f"benchmark:halumem:{case.id}")
+        episode_ids: list[str] = []
+        for session_index, session in enumerate(case.payload.get("sessions") or []):
+            episode_id = f"halu:{case.id}:s{session_index:04d}"
+            episode_ids.append(episode_id)
+            messages = [
+                {
+                    "id": f"{session_index}:{turn_index}",
+                    "role": turn.get("role", "speaker"),
+                    "content": turn.get("content", ""),
+                    "timestamp": _normalize_timestamp(turn.get("timestamp")),
+                }
+                for turn_index, turn in enumerate(session.get("dialogue") or [])
+            ]
+            if messages:
+                engine.ingest_messages(messages, episode_id=episode_id, namespace=namespace)
+        return PreparedCase(tuple(episode_ids), namespace, episode_prefix=f"halu:{case.id}:")
+
+
+def _normalize_timestamp(value: object) -> str | None:
+    if value is None or not str(value).strip():
+        return None
+    text = str(value).strip()
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        try:
+            parsed = datetime.strptime(text, "%b %d, %Y, %H:%M:%S").replace(tzinfo=timezone.utc)
+        except ValueError as exc:
+            raise ValueError(f"unsupported HaluMem timestamp: {text}") from exc
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.isoformat()

trisynapse_memory/adapters/benchmarks/locomo.py

@@ -0,0 +1,81 @@
+"""LoCoMo dataset adapter."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from trisynapse_memory.adapters.benchmarks.base import (
+    BenchmarkAdapter,
+    BenchmarkCase,
+    BenchmarkQuestion,
+    PreparedCase,
+)
+from trisynapse_memory.engine import MemoryEngine
+from trisynapse_memory.engine.models import MemoryNamespace, MemoryQueryResult
+
+
+class LoCoMoAdapter(BenchmarkAdapter):
+    name = "locomo"
+    default_filename = "locomo10.json"
+
+    def load_cases(self, path: Path) -> Iterable[BenchmarkCase]:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(payload, list):
+            raise ValueError("LoCoMo dataset root must be a JSON list")
+        for sample_index, sample in enumerate(payload):
+            sample_id = str(sample.get("sample_id") or sample_index)
+            questions = tuple(
+                BenchmarkQuestion(
+                    id=f"{sample_id}:q{index}",
+                    question=str(item.get("question") or ""),
+                    gold=str(item.get("answer") or ""),
+                    evidence=tuple(str(value) for value in item.get("evidence") or []),
+                    metadata={"category": item.get("category")},
+                )
+                for index, item in enumerate(sample.get("qa") or [])
+            )
+            yield BenchmarkCase(id=sample_id, payload=sample, questions=questions)
+
+    def ingest_case(self, engine: MemoryEngine, case: BenchmarkCase) -> PreparedCase:
+        namespace = MemoryNamespace(project_id=f"benchmark:locomo:{case.id}")
+        conversation = case.payload.get("conversation") or {}
+        episode_ids: list[str] = []
+        for key, turns in conversation.items():
+            if not key.startswith("session_") or key.endswith("_date_time") or not isinstance(turns, list):
+                continue
+            episode_id = f"locomo:{case.id}:{key}"
+            episode_ids.append(episode_id)
+            observed = conversation.get(f"{key}_date_time")
+            for index, turn in enumerate(turns):
+                text = f"{turn.get('speaker', 'speaker')}: {turn.get('text', '')}"
+                if observed:
+                    text = f"[{observed}] {text}"
+                engine.ingest_observation(
+                    text,
+                    episode_id=episode_id,
+                    source_ref={"type": "locomo", "sample_id": case.id},
+                    locator={"dia_id": turn.get("dia_id"), "turn_index": index},
+                    external_key=f"locomo:{case.id}:{turn.get('dia_id') or key + ':' + str(index)}",
+                    namespace=namespace,
+                    process=False,
+                    schedule=False,
+                )
+        return PreparedCase(tuple(episode_ids), namespace)
+
+    def result_metadata(
+        self, question: BenchmarkQuestion, result: MemoryQueryResult
+    ) -> dict[str, Any]:
+        cited = {
+            str(citation.locator.get("dia_id"))
+            for citation in result.citations
+            if isinstance(citation.locator, dict) and citation.locator.get("dia_id")
+        }
+        evidence = set(question.evidence or ())
+        return {
+            **question.metadata,
+            "evidence_hit": bool(evidence & cited),
+            "cited_ids": sorted(cited),
+        }

trisynapse_memory/adapters/benchmarks/longmemeval.py

@@ -0,0 +1,75 @@
+"""LongMemEval dataset adapter."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from trisynapse_memory.adapters.benchmarks.base import (
+    BenchmarkAdapter,
+    BenchmarkCase,
+    BenchmarkQuestion,
+    PreparedCase,
+)
+from trisynapse_memory.engine import MemoryEngine
+from trisynapse_memory.engine.models import MemoryNamespace, MemoryQueryResult
+
+
+class LongMemEvalAdapter(BenchmarkAdapter):
+    name = "longmemeval"
+    default_filename = "longmemeval_s_cleaned.json"
+
+    def load_cases(self, path: Path) -> Iterable[BenchmarkCase]:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(payload, list):
+            raise ValueError("LongMemEval dataset root must be a JSON list")
+        for index, item in enumerate(payload):
+            question_id = str(item.get("question_id") or index)
+            question = BenchmarkQuestion(
+                id=question_id,
+                question=str(item.get("question") or ""),
+                gold=str(item.get("answer") or ""),
+                evidence=tuple(str(value) for value in item.get("answer_session_ids") or []),
+                evidence_text=str(item.get("answer") or ""),
+                metadata={"question_type": item.get("question_type")},
+            )
+            yield BenchmarkCase(id=question_id, payload=item, questions=(question,))
+
+    def ingest_case(self, engine: MemoryEngine, case: BenchmarkCase) -> PreparedCase:
+        namespace = MemoryNamespace(project_id=f"benchmark:longmemeval:{case.id}")
+        episode_ids: list[str] = []
+        session_ids = case.payload.get("haystack_session_ids") or []
+        dates = case.payload.get("haystack_dates") or []
+        for session_index, turns in enumerate(case.payload.get("haystack_sessions") or []):
+            session_id = str(session_ids[session_index] if session_index < len(session_ids) else session_index)
+            episode_id = f"lme:{case.id}:{session_id}"
+            episode_ids.append(episode_id)
+            date = dates[session_index] if session_index < len(dates) else None
+            messages = []
+            for turn_index, turn in enumerate(turns):
+                content = str(turn.get("content") or "")
+                if date:
+                    content = f"[{date}] {content}"
+                messages.append({
+                    "id": f"{session_id}:{turn_index}",
+                    "role": turn.get("role"),
+                    "content": content,
+                })
+            engine.ingest_messages(messages, episode_id=episode_id, namespace=namespace)
+        return PreparedCase(tuple(episode_ids), namespace, episode_prefix=f"lme:{case.id}:")
+
+    def result_metadata(
+        self, question: BenchmarkQuestion, result: MemoryQueryResult
+    ) -> dict[str, Any]:
+        prefix = f"lme:{question.id}:"
+        cited_sessions = {
+            str(citation.source_ref.get("id", "")).removeprefix(prefix)
+            for citation in result.citations
+            if isinstance(citation.source_ref, dict)
+        }
+        return {
+            **question.metadata,
+            "evidence_hit": bool(set(question.evidence or ()) & cited_sessions),
+        }

trisynapse_memory/adapters/benchmarks/memorydoc.py

@@ -0,0 +1,83 @@
+"""MemoryDoc micro-world dataset adapter."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+
+from trisynapse_memory.adapters.benchmarks.base import (
+    BenchmarkAdapter,
+    BenchmarkCase,
+    BenchmarkQuestion,
+    PreparedCase,
+)
+from trisynapse_memory.engine import MemoryEngine
+from trisynapse_memory.engine.formation import chunk_document
+from trisynapse_memory.engine.models import MemoryNamespace
+
+
+class MemoryDocAdapter(BenchmarkAdapter):
+    name = "memorydoc"
+    default_filename = "fixtures/smoke_micro_world.json"
+
+    def load_cases(self, path: Path) -> Iterable[BenchmarkCase]:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        worlds = payload if isinstance(payload, list) else payload.get("micro_worlds") or payload.get("worlds") or [payload]
+        for world_index, world in enumerate(worlds):
+            world_id = str(world.get("micro_world_id") or world.get("world_id") or world.get("id") or world_index)
+            questions = []
+            for index, item in enumerate(world.get("qa_pairs") or world.get("questions") or []):
+                evidence = item.get("evidence_references") or item.get("evidence") or []
+                evidence_text = " ".join(
+                    str(ref.get("passage_span") or ref.get("excerpt") or "")
+                    if isinstance(ref, dict) else str(ref)
+                    for ref in evidence
+                )
+                questions.append(BenchmarkQuestion(
+                    id=f"{world_id}:q{index}",
+                    question=str(item.get("question") or ""),
+                    gold=str(item.get("gold_answer") or item.get("answer") or ""),
+                    evidence=evidence,
+                    evidence_text=evidence_text,
+                ))
+            yield BenchmarkCase(id=world_id, payload=world, questions=tuple(questions))
+
+    def ingest_case(self, engine: MemoryEngine, case: BenchmarkCase) -> PreparedCase:
+        namespace = MemoryNamespace(project_id=f"benchmark:memorydoc:{case.id}")
+        prefix = f"mwd:{case.id}:"
+        episode_ids: list[str] = []
+        for document in case.payload.get("documents") or []:
+            document_id = str(document.get("document_id") or document.get("id"))
+            episode_id = f"{prefix}doc:{document_id}"
+            episode_ids.append(episode_id)
+            text = str(document.get("text") or document.get("content") or "")
+            for chunk_index, chunk in enumerate(chunk_document(text, chunk_chars=3500)):
+                engine.ingest_observation(
+                    chunk,
+                    episode_id=episode_id,
+                    source_ref={"type": "document", "id": document_id},
+                    locator={"kind": "chunk", "index": chunk_index},
+                    external_key=f"mwd:{case.id}:doc:{document_id}:{chunk_index}",
+                    namespace=namespace,
+                    process=False,
+                    schedule=False,
+                )
+        for session in case.payload.get("conversations") or case.payload.get("sessions") or []:
+            session_id = str(session.get("session_id") or session.get("event_id") or session.get("id"))
+            episode_id = f"{prefix}chat:{session_id}"
+            episode_ids.append(episode_id)
+            utterances = session.get("utterances") or session.get("messages") or []
+            engine.ingest_messages(
+                [
+                    {
+                        "id": utterance.get("utterance_id") or utterance.get("id") or index,
+                        "role": utterance.get("speaker") or utterance.get("persona") or utterance.get("role") or "speaker",
+                        "content": utterance.get("text") or utterance.get("content") or "",
+                    }
+                    for index, utterance in enumerate(utterances)
+                ],
+                episode_id=episode_id,
+                namespace=namespace,
+            )
+        return PreparedCase(tuple(episode_ids), namespace, episode_prefix=prefix)