Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

31.6 KB
Raw Blame
"""Mastery path loop-capability hooks.

A posed question ends its turn (see
:meth:`MasteryLoopCapability.final_text_override`), which is what removed this
module's most tangled machinery. A mastery question used to travel on the
generic ``ask_user`` pause channel, so every clarifying card the tutor raised
had to be inspected and rewritten in case it was really a quiz, and the
learner's reply to any card had to be considered as a possible answer to the
open question. Both were guesses about which card was which, made in the wrong
place. Now the engine poses its own card and answers arrive as ordinary
messages committed at turn start, so ``ask_user`` is left alone: in this mode
it is only ever a clarifying question.
"""

from __future__ import annotations

from collections.abc import Callable
import json
import logging
from typing import Any

from deeptutor.capabilities.mastery.tools import MASTERY_TOOL_NAMES
from deeptutor.capabilities.protocol import PromptBlock
from deeptutor.core.context import UnifiedContext
from deeptutor.core.tool_protocol import TOOL_EVENT_PROJECTION, ToolEventProjection
from deeptutor.services.prompt.lookup import prompt_text as _prompt_text
from deeptutor.tools.mastery_nav import MASTERY_NAV_TOOL_NAMES

logger = logging.getLogger(__name__)

# Tools that may move the turn onto a different path, and so need a handle on
# the live binding rather than just the path id it started with.
_PATH_BINDING_TOOLS = frozenset({"mastery_switch", "mastery_leave"})

#: Set on the turn by :class:`~deeptutor.capabilities.mastery.pipeline.MasteryLoopPipeline`
#: so this extension knows the playbook is already the foundation of the
#: prompt and must not contribute a second copy of it. Declared here, next to
#: its only reader, so the tutor loop can import one string without this
#: module having to import the loop engine back.
NATIVE_LOOP_FLAG = "mastery_native_loop"


class MasteryLoopCapability:
    """Turn-scoped integration for mastery-path tutoring.

    Reuses the full chat tool surface (rag / ask_user / … under the same user
    toggles as chat) and adds the mastery engine tools on top, plus its own
    ``read_source`` mount.

    ``read_source`` is owned here rather than left to chat's
    ``explore_context`` pre-pass on purpose: a topic's materials (see
    :mod:`deeptutor.learning.topic_materials`) are announced every turn as a
    plain-text manifest (``context.source_manifest``) — "here is what's
    attached" — but never force a read. The forced, bounded investigation
    explore_context runs before the model's first token is right for chat
    (where a referenced transcript must be read once, objectively, before
    answering) and wrong for tutoring, where the model should decide *itself*,
    knowledge point by knowledge point, whether the source text is worth
    reading this turn. Mounting ``read_source`` directly on the answer loop —
    fed from ``mastery_topic_source_index`` rather than the ``source_index``
    key explore_context watches — gives the tutor that choice without forcing
    it.
    """

    name = "mastery"
    owned_tools = (*MASTERY_TOOL_NAMES, "read_source")
    # Declared to the dispatcher so a call that repoints the turn runs first
    # and the rest of the round lands on the new target. Every call in a round
    # is bound before any of them runs, so without this a ``mastery_switch`` +
    # ``mastery_build`` round rebuilt the map of the path the conversation was
    # leaving.
    #
    # ``mastery_mode`` belongs here for the same reason and was missing it. It
    # repoints the turn's mode (``_bind_active_mode``, below), and every
    # mode-gated tool reads ``_mastery_session_mode`` from the bind — so in the
    # round the prompt explicitly asks for, "switch to study and get on with
    # it", ``mastery_quiz`` still saw ``outline`` and was refused. The tutor
    # had already written the lead-in, the card never appeared, and the turn
    # carried on: one of the ways a question ends up answered in prose.
    rebinding_tools = tuple(_PATH_BINDING_TOOLS | {"mastery_mode"})

    def is_active(self, context: UnifiedContext) -> bool:
        return bool(context.metadata.get("mastery_mode"))

    def system_block(
        self,
        context: UnifiedContext,
        *,
        language: str,
        prompts: dict[str, Any],
    ) -> PromptBlock | None:
        """The tutor playbook, for a mastery turn that is not on the tutor loop.

        :class:`~deeptutor.capabilities.mastery.pipeline.MasteryLoopPipeline`
        makes the playbook the *foundation* of its prompt, so contributing it
        again there would put two copies in the window. It is still needed on
        the chat pipeline: a mastery workspace can run another action (a quiz,
        a visualization) and that turn should still know it is inside a course
        rather than being silently untutored.
        """
        if not self.is_active(context):
            return None
        if context.metadata.get(NATIVE_LOOP_FLAG):
            return None
        override = _prompt_text(prompts, ("mastery", "system"))
        return PromptBlock("mastery_tutor", override or _load_playbook(language))

    def augment_kwargs(
        self,
        tool_name: str,
        kwargs: dict[str, Any],
        context: UnifiedContext,
    ) -> dict[str, Any]:
        if not self.is_active(context):
            return kwargs
        path_id = str(context.metadata.get("mastery_path_id") or "").strip()
        state = context.extension("mastery")
        if tool_name == "rag":
            import asyncio

            from deeptutor.learning.service import LearningService

            session_id = str(context.session_id or "").strip()
            turn_id = str(context.metadata.get("turn_id") or "").strip()

            async def present_sources(sources, purpose):
                if (
                    context.metadata.get("mastery_path_id") != path_id
                    or context.session_id != session_id
                    or str(context.metadata.get("turn_id") or "").strip() != turn_id
                ):
                    raise ValueError("The mastery source presentation context changed.")
                return await asyncio.to_thread(
                    LearningService().present_sources,
                    path_id,
                    sources,
                    purpose,
                    session_id=session_id,
                    turn_id=turn_id,
                )

            return {
                **kwargs,
                "_mastery_source_context": True,
                TOOL_EVENT_PROJECTION: ToolEventProjection(
                    arguments={"presentation": kwargs.get("presentation") or "inspect"}
                ),
                "_present_mastery_sources": present_sources,
            }
        # ``ask_user`` is deliberately untouched here. It carries clarifying
        # questions only; the graded ones are posed by ``mastery_quiz``.
        if tool_name == "read_source":
            # Deliberately a different key from chat's ``source_index``: that
            # one wakes the explore_context pre-pass (see the class docstring).
            # The tutor calls this tool on its own schedule instead.
            updated = dict(kwargs)
            updated["source_index"] = context.metadata.get("mastery_topic_source_index") or {}
            updated["_mastery_source_context"] = True
            updated[TOOL_EVENT_PROJECTION] = ToolEventProjection()
            return updated
        if tool_name in MASTERY_TOOL_NAMES:
            updated = dict(kwargs)
            if tool_name == "mastery_quiz":
                state["quiz_requested"] = True
                state["quiz_awaiting_grade"] = True
                # Only preparation after the latest failed attempt can earn a
                # final delivery round; an old packet must not reopen the loop.
                state.pop("quiz_recovery_receipt", None)
                updated["_end_turn_on_card"] = _card_end_marker(context)
            elif tool_name == "mastery_grade":
                state["quiz_awaiting_grade"] = False
                state["quiz_graded"] = True
            updated["_mastery_path_id"] = path_id
            updated["_attached_kb_names"] = list(context.knowledge_bases)
            updated["_inspected_image_hashes"] = list(
                context.extension("source_visual_evidence").get("image_hashes", [])
            )
            # Raw, not normalised: "this conversation never recorded a mode"
            # has to survive down to the tools, or every pre-modes conversation
            # (and every CLI / SDK turn, which pass none) would be enforced as
            # a study session and lose tools it has always been able to call.
            updated["_mastery_session_mode"] = context.metadata.get("mastery_session_mode")
            updated["_session_id"] = str(context.session_id or "").strip()
            updated["_turn_id"] = str(context.metadata.get("turn_id") or "").strip()
            if tool_name == "mastery_profile":
                updated["_learner_message"] = context.user_message or ""
                selection = int(state.get("profile_selection", 0)) + 1
                state["profile_selection"] = selection
                state["profile_write_pending"] = True

                def profile_recorded(receipt):
                    if (
                        state.get("profile_selection") == selection
                        and context.metadata.get("mastery_path_id") == path_id
                    ):
                        state["profile_write_pending"] = False
                        state["profile_receipt"] = receipt

                updated["_profile_recorded"] = profile_recorded

            if tool_name == "mastery_note_explained":
                session_id = str(context.session_id or "").strip()
                turn_id = str(context.metadata.get("turn_id") or "").strip()

                def teaching_delivery():
                    # A rebind must not let an earlier tool record teaching on
                    # the new path or under another session/turn's provenance.
                    if (
                        str(context.metadata.get("mastery_path_id") or "").strip() != path_id
                        or str(context.session_id or "").strip() != session_id
                        or str(context.metadata.get("turn_id") or "").strip() != turn_id
                    ):
                        return None
                    snapshot = context.extension("published_assistant_content").get("snapshot")
                    return {
                        "path_id": path_id,
                        "session_id": session_id,
                        "turn_id": turn_id,
                        "segments": snapshot() if callable(snapshot) else (),
                    }

                # Always override model-supplied private kwargs.
                updated["_teaching_delivery"] = teaching_delivery

            if tool_name == "mastery_revise":
                updated["_revision_request_id"] = str(
                    context.extension("agent_loop").get("model_call_id") or ""
                )

            if tool_name in {
                "mastery_quiz",
                "mastery_grade",
                "mastery_assess",
                "mastery_prepare_lesson",
            }:
                # A replacement needs a quote from the actual current learner
                # request, not a model-supplied claim about their intention.
                updated["_learner_message"] = context.user_message or ""
            if tool_name == "mastery_prepare_lesson":
                updated["_language"] = context.language
                from deeptutor.learning.policy import next_objective
                from deeptutor.learning.storage import LearningStore

                def bind_lesson(kp_id):
                    progress = LearningStore().load(path_id)
                    context.metadata["mastery_lesson_objective"] = {
                        "path_id": path_id,
                        "kp_id": kp_id,
                        "policy_id": next_objective(progress).knowledge_point_id
                        if progress
                        else "",
                    }
                    if (
                        progress is not None
                        and context.metadata.get("mastery_path_id") == path_id
                        and state.get("quiz_requested")
                        and not state.get("card_posted")
                    ):
                        state["quiz_recovery_receipt"] = {
                            **context.metadata["mastery_lesson_objective"],
                            "revision": progress.version,
                        }

                updated["_bind_lesson_objective"] = bind_lesson
            if tool_name == "mastery_mode":
                # The narrowest handle on the turn for a tool that changes what
                # the rest of it may do — the same shape as ``_bind_active_path``
                # below, and for the same reason: the tool must not have to know
                # a turn context exists.
                updated["_bind_active_mode"] = _mode_binder(context)
            if tool_name in _PATH_BINDING_TOOLS:
                # The narrowest possible handle on the turn: "point it at this
                # path". A tool that can switch paths has to change what the
                # rest of the turn operates on, and this keeps the tool from
                # needing to know a turn context exists.
                updated["_bind_active_path"] = _path_binder(context)
            return updated
        if tool_name in MASTERY_NAV_TOOL_NAMES:
            # The navigation tools stay mounted inside a mastery session —
            # sending the learner to a *different* topic is a real thing to
            # want mid-course. What they could not see is which topic this
            # turn is already tutoring, so a hand-off card could point back at
            # this very conversation's topic (#1412).
            updated = dict(kwargs)
            updated["_tutoring_path_id"] = path_id
            return updated
        return kwargs

    def settlement_recovery(self, context: UnifiedContext) -> tuple[str, tuple[str, ...]] | None:
        """Spend one final card-only round when a failed quiz's source was repaired."""
        if not self.is_active(context):
            return None
        state = context.extension("mastery")
        receipt = state.pop("quiz_recovery_receipt", None)
        if (
            not receipt
            or not state.get("quiz_requested")
            or state.get("card_posted")
            or state.get("quiz_recovery_used")
        ):
            return None
        from deeptutor.learning.policy import next_objective
        from deeptutor.learning.storage import LearningStore

        path_id = context.metadata.get("mastery_path_id")
        binding = context.metadata.get("mastery_lesson_objective") or {}
        if receipt["path_id"] != path_id or any(
            receipt[key] != binding.get(key) for key in ("path_id", "kp_id", "policy_id")
        ):
            return None
        progress = LearningStore().load(path_id)
        if (
            progress is None
            or progress.version != receipt["revision"]
            or next_objective(progress).knowledge_point_id != receipt["policy_id"]
        ):
            return None
        state["quiz_recovery_used"] = True
        return (
            "Source preparation for the quiz selected in this turn has now succeeded. "
            "Use this single final delivery round to call mastery_quiz with a supported question "
            "contract from the prepared evidence. Preserve the current pending question and "
            "replacement rules. Do not search, prepare again, grade, or claim a card was delivered "
            "in prose. If verification still fails, this turn cannot complete the delivery.",
            ("mastery_quiz",),
        )

    def finish_instruction(self, context: UnifiedContext, final_text: str) -> str | None:
        """Retry failed tool operations without classifying the learner-facing prose.

        Discussing options, questioning a grade or quoting a question is ordinary
        tutoring. Only an actual failed operation can require follow-up work;
        answer wording is never evidence that the model must pose another quiz.
        """
        if not self.is_active(context):
            return None
        state = context.extension("mastery")
        if state.get("profile_write_pending") and not state.get("profile_repair_requested"):
            state["profile_repair_requested"] = True
            return (
                "The selected mastery_profile update has no successful storage receipt. "
                "If repairable, retry once with the current revision and only the requested "
                "changed fields. Blank optional fields keep existing values. Otherwise continue "
                "the useful teaching, apply the request for this turn, and explain that it was "
                "not saved for future sessions. Do not claim durable persistence without a "
                "successful receipt. Do not delay teaching with repeated optional profile retries."
            )
        if state.get("quiz_requested") and not state.get("card_posted"):
            return (
                "This turn selected mastery_quiz, but no question card was successfully "
                "posted. Inspect the tool error and retry mastery_quiz with corrected "
                "arguments. A prose reply or a grading call cannot complete the selected "
                "question delivery. If delivery remains unsuccessful, this turn must "
                "fail rather than report successful completion."
            )
        return None

    def final_text_override(self, context: UnifiedContext, final_text: str) -> str | None:
        """End the turn on the card once a question has been posed.

        A posed question used to park the turn inside ``pause_for_user``: the
        runtime moved it to ``waiting_input`` and waited on a reply queue, so
        one conversation held a live turn — and the path's lease — for as long
        as the learner took, which could be forever. Everything they might do
        instead of answering (ask something, come back tomorrow, reload) had to
        be handled as an interruption of that parked turn, and the composer had
        no honest state to show while it was parked.

        Ending here inverts it. The card is this turn's artefact; answering it
        is the next message, exactly like typing one. So the learner may answer,
        ask something else, or walk away, and each is just the next turn —
        which is what makes the conversation feel continuous instead of gated.

        Returning ``""`` and not a sentence is deliberate: the tutor's own prose
        from this round is already published (mastery tool rounds keep their
        learner-facing text), and the question is on the card. There is nothing
        left for the turn to say.
        """
        if not self.is_active(context):
            return None
        state = context.extension("mastery")
        notice = ""
        if state.get("profile_write_pending"):
            if not final_text.strip() and not state.get("card_posted"):
                # This hook also runs after every tool batch. An optional
                # storage notice cannot end work still in progress; append it
                # only to a real final answer or an accepted question card.
                return None
            # Optional memory failure must not deadlock otherwise valid tutoring.
            # The native status corrects any unsupported persistence promise;
            # it does not classify or discard the learner-facing explanation.
            state["profile_write_pending"] = False
            state["profile_receipt"] = {"status": "not_saved"}
            from deeptutor.services.prompt import get_prompt_manager
            from deeptutor.services.prompt.lookup import prompt_text

            pack = get_prompt_manager().load_prompts("mastery", "mastery_loop", context.language)
            notice = prompt_text(pack, ("notices", "profile_not_saved"))

        def with_notice(override):
            if not notice:
                return override
            content = final_text if override is None else override
            return notice + ("\n\n" + content if content.strip() else "")

        if not state.get("card_posted"):
            return with_notice(None)
        if final_text.strip():
            # A tool-less finish round already wrote the answer; the card was
            # posed earlier in the turn and has nothing to override.
            return with_notice(None)
        state["card_posted"] = False
        return with_notice("")

    async def pre_loop(
        self, context: UnifiedContext, stream: Any, *, usage: Any = None
    ) -> PromptBlock | None:
        """Read current state once before the first model call, without an LLM.

        This is a fresh read for this turn, never a session cache. Reuse the
        status tool so objective gates and pending answers have one authority.
        The loop's pre-pass wrapper falls back to the tool on read failure.
        """
        context.extension("mastery").pop("status_snapshot", None)
        if not self.is_active(context) or not context.metadata.get("mastery_path_id"):
            return None
        from deeptutor.capabilities.mastery.mode import normalize_mode
        from deeptutor.capabilities.mastery.tools import MasteryStatusTool

        binding = (
            context.metadata.get("mastery_path_id"),
            context.metadata.get("mastery_session_mode"),
        )
        result = await MasteryStatusTool().execute(
            **self.augment_kwargs("mastery_status", {}, context),
            _working_brief=normalize_mode(context.metadata.get("mastery_session_mode"))
            != "outline",
        )
        if not result.success:
            return None
        # A rebind during the read must not seed the new path with old state.
        current = (
            context.metadata.get("mastery_path_id"),
            context.metadata.get("mastery_session_mode"),
        )
        if (
            binding != current
            or json.loads(result.content).get("path_id") != str(binding[0]).strip()
        ):
            return None
        block = PromptBlock(
            "mastery_status_snapshot",
            "[Current-turn mastery_status snapshot]\n"
            "The runtime has already read mastery_status for this turn and active path. "
            "Use this result directly; do not call mastery_status again just to begin. "
            "Refresh with mastery_status after changing the path, mode, outline, or progress "
            "when updated state is needed. Earlier turns' snapshots are historical only.\n"
            + result.content,
        )
        context.extension("mastery")["status_snapshot"] = block.content
        return block

    def pre_loop_seed(self, context: UnifiedContext) -> str:
        """Hand over whatever this turn already settled on the open card.

        A card answer is graded when the turn starts, so by the time the tutor
        reads anything the gate has ruled and the learner can already see the
        verdict on their card. Without this the tutor would open the turn
        looking at a bare "C" with no open question to match it to — and the
        engine would have nothing left to grade, since it is already done.

        So the ruling is stated here as fact, and what is left for the tutor is
        the part only it can do: say what this attempt shows and carry on. A
        declined question is the same story with no verdict in it.
        """
        if not self.is_active(context):
            return ""
        skipped = self._skip_seed(context)
        graded = self._grade_seed(context)
        return "\n\n".join(part for part in (skipped, graded) if part)

    def skip_kb_seed(self, context: UnifiedContext) -> bool:
        """Don't pre-search the knowledge base with a card answer.

        The message of a card turn is the learner's pick ("A", "True") or a
        declined question, not a question to look up. The engine grades it
        against the stored key, and the tutor can still call ``rag`` with the
        actual question if it needs the material.
        """
        if not self.is_active(context):
            return False
        meta = context.metadata
        grade = meta.get("mastery_card_grade")
        skip = meta.get("mastery_card_skip")
        return bool(
            meta.get("mastery_card_answered")
            or (isinstance(grade, dict) and grade)
            or (isinstance(skip, dict) and skip.get("skipped"))
        )

    def _skip_seed(self, context: UnifiedContext) -> str:
        """State that the learner's declined question is already gone.

        Without this the tutor reads "let's skip this question" and reaches for
        ``mastery_skip_question`` — which now finds nothing open and reports so,
        costing a round to learn what the runtime already did. Worse, a tutor
        that does not know the question is gone tends to re-pose it.
        """
        skip = context.metadata.get("mastery_card_skip")
        if not isinstance(skip, dict) or not skip.get("skipped"):
            return ""
        return (
            "[Mastery] The learner declined the open question and the engine has "
            "already dropped it — do not call mastery_skip_question, and do not "
            "pose that same question again. Nothing was graded and no mastery "
            "credit was given, so the objective's gate is exactly where it was. "
            "Answer whatever they asked, then continue the objective from "
            "mastery_status.next — with a different question when you are ready "
            "to ask one."
        )

    def _grade_seed(self, context: UnifiedContext) -> str:
        grade = context.metadata.get("mastery_card_grade")
        if not isinstance(grade, dict) or not grade:
            return ""
        result = grade.get("result") if isinstance(grade.get("result"), dict) else {}

        def verdict(item):
            typed = item.get("result")
            return (
                typed
                if isinstance(typed, str)
                and typed in {"correct", "partial", "incorrect", "ungraded"}
                else (
                    "ungraded"
                    if item.get("is_correct") is None
                    else "correct"
                    if item.get("is_correct")
                    else "incorrect"
                )
            )

        results = result.get("results")
        if isinstance(results, list) and results:
            parts = [
                f"{item.get('question_id', '')}: "
                f"{verdict(item)}; final={item.get('final', True)}; "
                f"objective {item.get('knowledge_point_id', '')}; "
                f"mastered={bool(item.get('mastered'))}; feedback={item.get('feedback', '')}"
                for item in results
                if isinstance(item, dict)
            ]
            complete = result.get("complete", grade.get("complete", True)) is not False
            status = (
                "The question group was already graded by the engine. "
                if complete
                else "Only the submitted group replies were graded by the engine. "
                "These children still need an answer or clarification: "
                + ", ".join(result.get("remaining_question_ids", []))
                + ". "
                "Preserve final siblings. Clarify nonfinal replies and then assess the learner's explicit revision. "
                "Explain reported gaps, but never infer confusion from an unanswered "
                "item or invent its reply. "
            )
            return (
                "[Mastery] "
                + status
                + "Do not regrade final replies or repeat their answer keys. Each result belongs "
                "only to its own objective; the parent group gives no extra credit. "
                "Address the specific gap, then use the fresh status for the next step.\n"
                + "\n".join(parts)
            )
        outcome = verdict(
            {**result, "is_correct": result.get("is_correct", grade.get("is_correct"))}
        )
        learner_answer = str(result.get("learner_answer") or "").strip()
        learner_body = str(result.get("learner_body") or "").strip()
        picked = f"{learner_answer}: {learner_body}" if learner_body else learner_answer
        lines = [
            "[Mastery] The learner answered the open question on its card and the "
            f"engine reports: {outcome}" + (f' (they answered "{picked}")' if picked else "") + ".",
            str(result.get("feedback") or ""),
        ]
        if result.get("final") is False or outcome == "ungraded":
            lines.append(
                "This is not a final grade and created no mastery penalty. Ask for the needed clarification, preserve the same question, and assess an explicit revised learner answer. Do not infer a wrong answer or replace this question automatically."
            )
            return "\n".join(line for line in lines if line)
        lines.append(
            "The engine already graded this reply; do not call mastery_grade. The card shows the saved final result. Do not repeat the answer key or grade this reply again."
        )
        if grade.get("mastered"):
            lines.append(
                "This cleared the objective's gate. Say what the attempt showed, "
                "then continue with mastery_status.next."
            )
        else:
            lines.append(
                "The gate is not cleared yet. Say what the attempt showed, teach "
                "the gap if there is one, and pose the next question with "
                "mastery_quiz when you are ready — that call ends the turn, so "
                "put it last."
            )
        return "\n".join(lines)


def _card_end_marker(context: UnifiedContext) -> Callable[[], None]:
    """Return the callback ``mastery_quiz`` calls once the card is posed."""

    def mark() -> None:
        context.extension("mastery")["card_posted"] = True

    return mark


def _path_binder(context: UnifiedContext) -> Callable[[str], None]:
    """Return the callback that repoints ``context`` at another path."""

    def bind(path_id: str) -> None:
        context.metadata["mastery_path_id"] = path_id

    return bind


def _mode_binder(context: UnifiedContext) -> Callable[[str], None]:
    """Return the callback that puts ``context`` into another mode.

    Only the rest of *this* turn is repointed. Persisting the change onto the
    conversation is the runtime's job — a tool cannot reach the session store,
    and a mode that survived only in memory would be forgotten on reload.
    """

    def bind(mode: str) -> None:
        context.metadata["mastery_session_mode"] = mode
        # Read back by the turn runtime after the turn, so the conversation
        # resumes in the mode it ended in rather than the one it began in.
        context.metadata["mastery_session_mode_changed"] = True

    return bind


def _load_playbook(language: str) -> str:
    """Render the tutor playbook from the mastery prompt pack, as one block.

    One source of truth with the tutor loop, which renders these very sections
    as separate foundation blocks: a rule fixed in one place is fixed for both.
    """
    from deeptutor.services.prompt import get_prompt_manager

    pack = (
        get_prompt_manager().load_prompts(
            module_name="mastery",
            agent_name="mastery_loop",
            language=language,
        )
        or {}
    )
    loop_section = pack.get("loop") if isinstance(pack.get("loop"), dict) else {}
    sections = (
        pack.get("general"),
        pack.get("runtime_policy"),
        loop_section.get("system"),
        pack.get("playbook"),
    )
    return "\n\n".join(text for section in sections if (text := str(section or "").strip()))


__all__ = ["MasteryLoopCapability"]