everalgo-user-memory 0.1.0__py3-none-any.whl

everalgo/user_memory/__init__.py

@@ -0,0 +1,28 @@
+"""User-side memory extractors — 4 Extractors + boundary facade + boundary re-exports.
+
+The user-scenario boundary facade (:class:`BoundaryDetector`) lives here; agent-trajectory
+boundary detection will be added to ``everalgo.agent_memory`` in Stage 4.
+"""
+
+import logging
+
+from everalgo.boundary import DetectionResult
+from everalgo.boundary.workspace import WorkspaceMemCellExtractor
+from everalgo.user_memory.atomic_fact import AtomicFactExtractor
+from everalgo.user_memory.boundary import BoundaryDetector
+from everalgo.user_memory.episode import EpisodeExtractor
+from everalgo.user_memory.foresight import ForesightExtractor
+from everalgo.user_memory.profile import ProfileExtractor
+
+__all__ = [
+    "AtomicFactExtractor",
+    "BoundaryDetector",
+    "DetectionResult",
+    "EpisodeExtractor",
+    "ForesightExtractor",
+    "ProfileExtractor",
+    "WorkspaceMemCellExtractor",
+]
+
+# Library logging setup (ADR-013): NullHandler on each subpackage logger.
+logging.getLogger(__name__).addHandler(logging.NullHandler())

everalgo/user_memory/_render.py

@@ -0,0 +1,28 @@
+"""Shared rendering helpers for user-memory extractors.
+
+This module is internal (``_render``-prefixed) — not part of the public API of ``everalgo.user_memory``.
+``render_content`` is re-exported from ``everalgo.types._render`` (moved to core in Stage 4 so that
+``everalgo-agent-memory`` can import it without creating a cross-package dependency on user-memory).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from everalgo.types._render import render_content
+from everalgo.types.chat import ChatMessage
+
+if TYPE_CHECKING:
+    from everalgo.types.conversation import MemCell
+
+__all__ = ["chat_messages", "render_content"]
+
+
+def chat_messages(memcell: MemCell) -> list[ChatMessage]:
+    """Filter ``memcell.items`` to ``ChatMessage`` entries only.
+
+    User-memory extractors silently skip ``ToolCallRequest`` / ``ToolCallResult`` — this is an
+    explicit contract supporting the agent → user-memory pipeline (see EverAlgo AGENTS.md). The
+    caller need not pre-filter; an AgentMemCell-shaped ``MemCell`` is acceptable input.
+    """
+    return [item for item in memcell.items if isinstance(item, ChatMessage)]

everalgo/user_memory/atomic_fact.py

@@ -0,0 +1,158 @@
+"""Extract atomic facts (single verifiable assertions) from a conversation slice."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import TYPE_CHECKING, Any, cast
+
+from asgiref.sync import async_to_sync
+
+from everalgo.llm.format import format_natural_language_time
+from everalgo.llm.parse import parse_llm_json_object
+from everalgo.llm.types import ChatMessage as LLMChatMessage
+from everalgo.prompts import render_prompt
+from everalgo.types import AtomicFact, MemCell
+from everalgo.user_memory._render import chat_messages, render_content
+from everalgo.user_memory.prompts.en.atomic_fact import ATOMIC_FACT_PROMPT
+
+if TYPE_CHECKING:
+    from everalgo.llm.protocols import LLMClient
+
+logger = logging.getLogger(__name__)
+
+
+class AtomicFactExtractor:
+    """Extract zero or more atomic facts from one MemCell.
+
+    Non-ChatMessage items in memcell.items are silently skipped (agent → user-memory contract).
+    Each string in the LLM ``atomic_facts.atomic_fact`` list becomes one :class:`AtomicFact` entity.
+    """
+
+    def __init__(self, *, llm: LLMClient) -> None:
+        self._llm = llm
+
+    async def aextract(
+        self,
+        memcell: MemCell,
+        *,
+        sender_id: str | None,
+        prompt: str | None = None,
+    ) -> list[AtomicFact]:
+        """Extract atomic facts for ``sender_id`` from ``memcell``.
+
+        Args:
+            memcell: Source slice from boundary detection.
+            sender_id: Owner tag stamped on each resulting AtomicFact; pass ``None`` for generic
+                (whole-memcell) facts that do not bind to any user. The prompt itself does not
+                consume sender_id.
+            prompt: Prompt override; ``None`` uses the bundled default.
+
+        Raises:
+            LLMError: From the LLM call.
+            json.JSONDecodeError: If all parse strategies fail.
+            ValueError: On schema validation failure (missing required fields or empty list).
+        """
+        rendered = render_prompt(
+            ATOMIC_FACT_PROMPT,
+            prompt,
+            INPUT_TEXT=_render_input_text(memcell),
+            TIME=_format_time_label(memcell.timestamp),
+        )
+
+        response = await self._llm.chat(
+            messages=[LLMChatMessage(role="user", content=rendered)],
+            response_format={"type": "json_object"},
+        )
+        data = _parse_llm_response(response.content)
+        atomic_facts_block = _validate_atomic_facts(data)
+        return _build_atomic_facts(atomic_facts_block, sender_id=sender_id, memcell=memcell)
+
+    extract = async_to_sync(aextract)
+
+
+# Module-level helpers.
+
+
+def _render_input_text(memcell: MemCell) -> str:
+    """Render ChatMessage items as the raw conversation transcript for the ``{INPUT_TEXT}`` placeholder."""
+    lines: list[str] = []
+    for m in chat_messages(memcell):
+        text = render_content(m.content)
+        if not text:
+            continue
+        speaker = m.sender_name or m.sender_id
+        lines.append(f"{speaker}: {text}")
+    return "\n".join(lines)
+
+
+def _format_time_label(timestamp_ms: int) -> str:
+    """Render timestamp as ``March 10, 2024 (Sunday) at 2:00 PM UTC``."""
+    return format_natural_language_time(timestamp_ms)
+
+
+def _parse_llm_response(raw: str) -> object:
+    """Parse LLM JSON response.
+
+    Schema-specific regex is tried first as a main-path optimisation (targets the nested
+    ``{"atomic_facts": {"time": ..., "atomic_fact": [...]}}`` shape); falls back to the shared
+    three-tier parser (fence → direct loads → outermost braces).
+
+    Raises:
+        ValueError: If all strategies fail to find a valid JSON object.
+    """
+    match = re.search(
+        r'\{[^{}]*"atomic_facts"[^{}]*\{[^{}]*"time"[^{}]*"atomic_fact"[^{}]*\}[^{}]*\}',
+        raw,
+        re.DOTALL,
+    )
+    if match:
+        try:
+            return json.loads(match.group())
+        except json.JSONDecodeError:
+            pass
+    return parse_llm_json_object(raw)
+
+
+def _validate_atomic_facts(data: object) -> dict[str, Any]:
+    """Validate ``atomic_facts`` schema; raise :class:`ValueError` on any violation."""
+    if not isinstance(data, dict):
+        raise ValueError("LLM response is not a JSON object")  # noqa: TRY004
+    data_dict = cast("dict[str, Any]", data)
+    block_raw = data_dict.get("atomic_facts")
+    if not isinstance(block_raw, dict):
+        raise ValueError("Missing 'atomic_facts' field in LLM response")  # noqa: TRY004
+    block = cast("dict[str, Any]", block_raw)
+    if "time" not in block or not block["time"]:
+        raise ValueError("Missing time field in atomic_facts")
+    if "atomic_fact" not in block:
+        raise ValueError("Missing atomic_fact field in atomic_facts")
+    atomic_fact_raw = block["atomic_fact"]
+    if not isinstance(atomic_fact_raw, list):
+        raise ValueError(f"atomic_fact is not a list: {type(atomic_fact_raw)}")  # noqa: TRY004
+    atomic_fact_list = cast("list[object]", atomic_fact_raw)
+    if not atomic_fact_list:
+        raise ValueError("atomic_fact list is empty")
+    return block
+
+
+def _build_atomic_facts(block: dict[str, Any], *, sender_id: str | None, memcell: MemCell) -> list[AtomicFact]:
+    """Split ``atomic_facts.atomic_fact`` list into individual AtomicFact entities."""
+    time_label = block["time"] if isinstance(block.get("time"), str) else _format_time_label(memcell.timestamp)
+    facts_list = cast("list[object]", block["atomic_fact"])
+    out: list[AtomicFact] = []
+    for item in facts_list:
+        if not isinstance(item, str) or not item.strip():
+            continue
+        out.append(
+            AtomicFact.model_validate(
+                {
+                    "owner_id": sender_id,
+                    "fact": item.strip(),
+                    "timestamp": memcell.timestamp,
+                    "time_label": time_label,
+                }
+            )
+        )
+    return out

everalgo/user_memory/boundary.py

@@ -0,0 +1,57 @@
+"""User-scenario boundary detection facade.
+
+Thin wrapper around the low-level ``everalgo.boundary.detect_boundaries`` primitive. Accepts
+``list[ChatMessage]`` (user-scenario path; agent trajectories with tool calls go through
+``everalgo.agent_memory.AgentBoundaryDetector`` instead).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from asgiref.sync import async_to_sync
+
+from everalgo.boundary import detect_boundaries
+
+if TYPE_CHECKING:
+    from everalgo.boundary import DetectionResult
+    from everalgo.llm.protocols import LLMClient
+    from everalgo.types import ChatMessage
+
+
+class BoundaryDetector:
+    """Boundary detection on a list of ``ChatMessage``. Native-async with sync bridge.
+
+    Calls ``everalgo.boundary.detect_boundaries`` directly — no extra state, no extra logic.
+    Exists so user-scenario callers have a class-style facade consistent with the rest of the
+    EverAlgo facade surface.
+
+    The LLM client is bound to the instance at construction time.
+    """
+
+    def __init__(self, *, llm: LLMClient) -> None:
+        self._llm = llm
+
+    async def adetect(
+        self,
+        messages: list[ChatMessage],
+        *,
+        is_final: bool = False,
+        prompt: str | None = None,
+    ) -> DetectionResult:
+        """Detect conversation boundaries in a list of ``ChatMessage``.
+
+        Args:
+            messages: Ordered list of chat messages to split into :class:`~everalgo.types.MemCell` slices.
+            is_final: When ``True``, treat the message stream as complete — the tail is flushed into the
+                last cell rather than held back as a pending partial window.
+            prompt: Optional prompt template override passed through to ``detect_boundaries``.
+
+        Returns:
+            Named tuple ``(cells, tail)`` — ``cells`` contains completed :class:`~everalgo.types.MemCell`
+            slices; ``tail`` carries any unconfirmed trailing messages.
+        """
+        return await detect_boundaries(messages, llm=self._llm, is_final=is_final, prompt=prompt)
+
+    detect = async_to_sync(adetect)
+    """Sync bridge — only callable from non-event-loop contexts."""

everalgo/user_memory/episode.py

@@ -0,0 +1,159 @@
+"""Extract a single Episode for one sender from a MemCell."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import TYPE_CHECKING, Any, cast
+
+from asgiref.sync import async_to_sync
+
+from everalgo.llm.format import format_message_timestamp, format_natural_language_time
+from everalgo.llm.parse import parse_llm_json_object
+from everalgo.llm.types import ChatMessage as LLMChatMessage
+from everalgo.prompts import render_prompt
+from everalgo.types import Episode, MemCell
+from everalgo.user_memory._render import chat_messages, render_content
+from everalgo.user_memory.prompts.en.episode import (
+    DEFAULT_CUSTOM_INSTRUCTIONS,
+    EPISODE_GENERATION_PROMPT,
+    USER_EPISODE_GENERATION_PROMPT,
+)
+
+if TYPE_CHECKING:
+    from everalgo.llm.protocols import LLMClient
+
+
+class EpisodeExtractor:
+    """Extract one Episode for a given sender from a MemCell.
+
+    Non-ChatMessage items in memcell.items are silently skipped (agent → user-memory contract).
+    """
+
+    def __init__(self, *, llm: LLMClient) -> None:
+        self._llm = llm
+
+    async def aextract(
+        self,
+        memcell: MemCell,
+        *,
+        sender_id: str | None,
+        prompt: str | None = None,
+        custom_instructions: str | None = None,
+    ) -> Episode:
+        """Extract one Episode from ``memcell``.
+
+        Args:
+            memcell: Source slice from boundary detection.
+            sender_id: Specific chat sender to centre the episode on (uses USER_EPISODE_GENERATION_PROMPT);
+                pass ``None`` to extract one whole-memcell generic episode (uses EPISODE_GENERATION_PROMPT)
+                — cheaper than per-user fan-out.
+            prompt: Prompt override; ``None`` uses the bundled default.
+            custom_instructions: Extra instruction block appended to the system prompt; ``None`` uses the default.
+
+        Raises:
+            LLMError: From the LLM call.
+            json.JSONDecodeError: If all parse strategies fail.
+            ValueError: If the LLM response is missing a non-empty ``title`` or ``content``.
+        """
+        custom_instr = custom_instructions or DEFAULT_CUSTOM_INSTRUCTIONS
+        conv_start = _format_conversation_start_time(memcell.timestamp)
+        conversation = _render_conversation(memcell)
+
+        if sender_id is None:
+            rendered = render_prompt(
+                EPISODE_GENERATION_PROMPT,
+                prompt,
+                conversation_start_time=conv_start,
+                conversation=conversation,
+                custom_instructions=custom_instr,
+            )
+        else:
+            user_name = _resolve_user_name(memcell, sender_id)
+            rendered = render_prompt(
+                USER_EPISODE_GENERATION_PROMPT,
+                prompt,
+                conversation_start_time=conv_start,
+                conversation=conversation,
+                custom_instructions=custom_instr,
+                user_name=user_name,
+            )
+
+        response = await self._llm.chat(
+            messages=[LLMChatMessage(role="user", content=rendered)],
+            response_format={"type": "json_object"},
+        )
+        data = _parse_llm_response(response.content)
+        if "title" not in data or not data["title"]:
+            raise ValueError("LLM response missing title field")
+        if "content" not in data or not data["content"]:
+            raise ValueError("LLM response missing content field")
+
+        return _build_episode(data, sender_id=sender_id, memcell=memcell)
+
+    extract = async_to_sync(aextract)
+
+
+# Module-level helpers.
+
+
+def _resolve_user_name(memcell: MemCell, sender_id: str) -> str:
+    """Look up ``sender_id``'s ``sender_name`` from ChatMessage items; fall back to ``sender_id`` literal."""
+    for m in chat_messages(memcell):
+        if m.sender_id == sender_id and m.sender_name:
+            return m.sender_name
+    return sender_id
+
+
+def _build_episode(data: dict[str, Any], *, sender_id: str | None, memcell: MemCell) -> Episode:
+    """Assemble an :class:`Episode` from the parsed LLM payload and memcell metadata."""
+    title = cast("str", data["title"])
+    content = cast("str", data["content"])
+    summary_raw = data.get("summary")
+    summary = summary_raw if isinstance(summary_raw, str) and summary_raw.strip() else content[:200]
+    return Episode.model_validate(
+        {
+            "owner_id": sender_id,
+            "episode": content,
+            "subject": title,
+            "timestamp": memcell.timestamp,
+            "summary": summary,  # preserved via extra='allow' without a schema bump
+        }
+    )
+
+
+def _format_conversation_start_time(timestamp_ms: int) -> str:
+    """Render the MemCell timestamp as ``March 14, 2024 (Thursday) at 3:00 PM UTC``."""
+    return format_natural_language_time(timestamp_ms)
+
+
+def _render_conversation(memcell: MemCell) -> str:
+    """Render ChatMessage items as ``[YYYY-MM-DDTHH:MM:SSZ] speaker: content`` lines."""
+    lines: list[str] = []
+    for m in chat_messages(memcell):
+        text = render_content(m.content)
+        if not text:
+            continue
+        speaker = m.sender_name or m.sender_id
+        time_str = format_message_timestamp(m.timestamp)
+        lines.append(f"[{time_str}] {speaker}: {text}")
+    return "\n".join(lines)
+
+
+def _parse_llm_response(raw: str) -> dict[str, Any]:
+    """Parse LLM JSON response.
+
+    Schema-specific regex is tried first as a main-path optimisation (targets in-prose
+    ``{"title": ..., "content": ...}`` fragments); falls back to the shared three-tier parser
+    (fence → direct loads → outermost braces).
+
+    Raises:
+        ValueError: If all strategies fail.
+    """
+    match = re.search(r'\{[^{}]*"title"[^{}]*"content"[^{}]*\}', raw, re.DOTALL)
+    if match:
+        try:
+            return cast("dict[str, Any]", json.loads(match.group()))
+        except json.JSONDecodeError:
+            pass
+    return parse_llm_json_object(raw)

everalgo/user_memory/foresight.py

@@ -0,0 +1,227 @@
+"""Extract anticipated commitments (Foresight) from a conversation slice."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any, cast
+
+from asgiref.sync import async_to_sync
+
+from everalgo.llm.format import format_message_timestamp
+from everalgo.llm.types import ChatMessage as LLMChatMessage
+from everalgo.prompts import render_prompt
+from everalgo.types import Foresight, MemCell
+from everalgo.user_memory._render import chat_messages, render_content
+from everalgo.user_memory.prompts.en.foresight import FORESIGHT_GENERATION_PROMPT
+
+if TYPE_CHECKING:
+    from everalgo.llm.protocols import LLMClient
+
+logger = logging.getLogger(__name__)
+
+_FORESIGHT_TEMPERATURE = 0.3
+_FORESIGHT_MAX_COUNT = 10
+_FORESIGHT_MIN_COUNT = 4  # warn-only floor; LLM may legitimately produce fewer
+
+
+class ForesightExtractor:
+    """Extract zero or more foresights from one MemCell.
+
+    Non-ChatMessage items in memcell.items are silently skipped (agent → user-memory contract).
+    """
+
+    def __init__(self, *, llm: LLMClient) -> None:
+        self._llm = llm
+
+    async def aextract(
+        self,
+        memcell: MemCell,
+        *,
+        sender_id: str,
+        prompt: str | None = None,
+    ) -> list[Foresight]:
+        """Extract foresights for ``sender_id`` from ``memcell``.
+
+        Args:
+            memcell: Source slice from boundary detection.
+            sender_id: Must be one of memcell's chat senders; not inferred.
+            prompt: Prompt override; ``None`` uses the bundled default.
+
+        Raises:
+            LLMError: From the LLM call.
+            json.JSONDecodeError: On unparseable response.
+        """
+        user_name = _resolve_user_name(memcell, sender_id)
+        rendered = render_prompt(
+            FORESIGHT_GENERATION_PROMPT,
+            prompt,
+            USER_ID=sender_id,
+            USER_NAME=user_name,
+            CONVERSATION_TEXT=_render_conversation(memcell),
+        )
+
+        start_time_fallback = _format_start_time_from_timestamp(memcell.timestamp)
+
+        response = await self._llm.chat(
+            messages=[LLMChatMessage(role="user", content=rendered)],
+            response_format={"type": "json_object"},
+            temperature=_FORESIGHT_TEMPERATURE,
+        )
+        foresights = _parse_and_build_foresights(
+            response.content,
+            memcell=memcell,
+            sender_id=sender_id,
+            start_time_fallback=start_time_fallback,
+        )
+        if len(foresights) > _FORESIGHT_MAX_COUNT:
+            foresights = foresights[:_FORESIGHT_MAX_COUNT]
+        elif 0 < len(foresights) < _FORESIGHT_MIN_COUNT:
+            logger.warning("foresight count below soft floor: %d", len(foresights))
+        return foresights
+
+    extract = async_to_sync(aextract)
+
+
+# Module-level helpers.
+
+
+def _resolve_user_name(memcell: MemCell, sender_id: str) -> str:
+    """Look up ``sender_id``'s ``sender_name`` from ChatMessage items; fall back to ``sender_id`` literal."""
+    for m in chat_messages(memcell):
+        if m.sender_id == sender_id and m.sender_name:
+            return m.sender_name
+    return sender_id
+
+
+def _render_conversation(memcell: MemCell) -> str:
+    """Render ChatMessage items as ``[YYYY-MM-DDTHH:MM:SSZ] speaker: content`` lines."""
+    lines: list[str] = []
+    for m in chat_messages(memcell):
+        text = render_content(m.content)
+        if not text:
+            continue
+        speaker = m.sender_name or m.sender_id
+        time_str = format_message_timestamp(m.timestamp)
+        lines.append(f"[{time_str}] {speaker}: {text}")
+    return "\n".join(lines)
+
+
+def _format_start_time_from_timestamp(timestamp_ms: int) -> str:
+    """Render MemCell timestamp as ``YYYY-MM-DD`` for foresight start_time fallback."""
+    return datetime.fromtimestamp(timestamp_ms / 1000, tz=UTC).strftime("%Y-%m-%d")
+
+
+def _clean_date_string(date_str: object) -> str | None:
+    """Normalize to ``YYYY-MM-DD`` — keep digits + hyphens, validate regex + constructibility. Returns ``None`` if invalid."""
+    if not isinstance(date_str, str) or not date_str:
+        return None
+    cleaned = re.sub(r"[^\d\-]", "", date_str)
+    if not re.match(r"^\d{4}-\d{2}-\d{2}$", cleaned):
+        return None
+    try:
+        year, month, day = map(int, cleaned.split("-"))
+        datetime(year, month, day, tzinfo=UTC)
+    except ValueError:
+        return None
+    return cleaned
+
+
+def _calculate_end_time_from_duration(start_time: str, duration_days: int) -> str | None:
+    """Compute ``end_time = start_time + duration_days`` in ``YYYY-MM-DD``."""
+    try:
+        start_date = datetime.strptime(start_time, "%Y-%m-%d").replace(tzinfo=UTC)
+        end_date = start_date + timedelta(days=duration_days)
+    except ValueError:
+        return None
+    return end_date.strftime("%Y-%m-%d")
+
+
+def _calculate_duration_days(start_time: str, end_time: str) -> int | None:
+    """Compute ``end_time - start_time`` in days."""
+    try:
+        start_date = datetime.strptime(start_time, "%Y-%m-%d").replace(tzinfo=UTC)
+        end_date = datetime.strptime(end_time, "%Y-%m-%d").replace(tzinfo=UTC)
+    except ValueError:
+        return None
+    return (end_date - start_date).days
+
+
+def _parse_and_build_foresights(
+    raw: str,
+    *,
+    memcell: MemCell,
+    sender_id: str,
+    start_time_fallback: str,
+) -> list[Foresight]:
+    """Parse LLM foresight payload + apply date cleaning + mutual time computation.
+
+    Accepts top-level JSON array OR ``{"foresights": [...]}`` wrapped form.
+    """
+    data = _parse_llm_response(raw)
+
+    items: list[Any]
+    if isinstance(data, list):
+        items = cast("list[Any]", data)  # type: ignore[redundant-cast]
+    elif isinstance(data, dict):
+        wrapped = cast("dict[str, Any]", data).get("foresights")
+        if isinstance(wrapped, list):
+            items = cast("list[Any]", wrapped)  # type: ignore[redundant-cast]
+        else:
+            return []
+    else:
+        return []
+
+    out: list[Foresight] = []
+    for raw_item in items:
+        if not isinstance(raw_item, dict):
+            continue
+        item = cast("dict[str, Any]", raw_item)
+        content = item.get("content")
+        if not isinstance(content, str) or not content.strip():
+            continue
+        evidence_raw = item.get("evidence", "")
+        evidence = evidence_raw if isinstance(evidence_raw, str) else ""
+
+        item_start_time = _clean_date_string(item.get("start_time")) or start_time_fallback
+        item_end_time = _clean_date_string(item.get("end_time"))
+        item_duration_days = item.get("duration_days") if isinstance(item.get("duration_days"), int) else None
+
+        # Mutual time computation
+        if item_start_time:
+            if item_duration_days is not None and not item_end_time:
+                item_end_time = _calculate_end_time_from_duration(item_start_time, item_duration_days)
+            elif item_end_time and item_duration_days is None:
+                item_duration_days = _calculate_duration_days(item_start_time, item_end_time)
+
+        out.append(
+            Foresight(
+                owner_id=sender_id,
+                foresight=content,
+                evidence=evidence,
+                timestamp=memcell.timestamp,
+                start_time=item_start_time,
+                end_time=item_end_time,
+                duration_days=item_duration_days,
+            )
+        )
+    return out
+
+
+def _parse_llm_response(raw: str) -> object:
+    r"""Parse LLM JSON response: `` ```json `` fence first, then direct ``json.loads``.
+
+    Raises:
+        json.JSONDecodeError: If both strategies fail.
+    """
+    if "```json" in raw:
+        start = raw.find("```json") + 7
+        end = raw.find("```", start)
+        if end > start:
+            try:
+                return json.loads(raw[start:end].strip())
+            except json.JSONDecodeError:
+                pass
+    return json.loads(raw)