Skip to content

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

10.9 KB
Raw Blame
"""
Chat Orchestrator
=================

Unified entry point that routes user messages to the appropriate capability.
All consumers (CLI, WebSocket, SDK) call the orchestrator.
"""

from __future__ import annotations

import asyncio
import contextlib
import logging
from typing import Any, AsyncIterator
import uuid

from deeptutor.capabilities.protocol import AGENT_OUTPUT, EVENT_METADATA
from deeptutor.core.capability_protocol import TurnCapability
from deeptutor.core.context import UnifiedContext
from deeptutor.core.stream import StreamEvent, StreamEventType
from deeptutor.events.event_bus import Event, EventType, get_event_bus
from deeptutor.runtime.registry.capability_registry import get_capability_registry
from deeptutor.runtime.registry.tool_registry import get_tool_registry
from deeptutor.runtime.stream_bus import StreamBus, register_bus, unregister_bus
from deeptutor.services.prompt.lookup import prompt_text
from deeptutor.services.prompt.manager import get_prompt_manager

logger = logging.getLogger(__name__)


def completion_event_fields(context: UnifiedContext, cap_name: str) -> tuple[str, dict[str, Any]]:
    """Build CAPABILITY_COMPLETE ``agent_output`` + metadata.

    Capabilities publish through ``context.capability_output``. The two legacy
    metadata keys remain readable for one major version.
    ``capability``, ``session_id`` and ``turn_id`` always win so consumers can
    rely on those keys.

    Only that explicit sub-dict is forwarded, never ``context.metadata`` whole.
    Only the explicit output dict is forwarded, never compatibility metadata.
    """
    meta = context.metadata or {}
    agent_output = str(context.capability_output.agent_output or meta.get(AGENT_OUTPUT) or "")
    published = context.capability_output.event_metadata or meta.get(EVENT_METADATA)
    extras = dict(published) if isinstance(published, dict) else {}
    return agent_output, {
        **extras,
        "capability": cap_name,
        "session_id": context.session_id,
        "turn_id": str(meta.get("turn_id") or ""),
    }


class ChatOrchestrator:
    """
    Routes a ``UnifiedContext`` to the correct capability, manages
    the ``StreamBus`` lifecycle, and publishes completion events.
    """

    def __init__(self, capability_registry=None) -> None:  # noqa: ANN001
        self._cap_registry = capability_registry or get_capability_registry()
        self._tool_registry = get_tool_registry()

    async def handle(self, context: UnifiedContext) -> AsyncIterator[StreamEvent]:
        """
        Execute a single user turn and yield streaming events.

        If ``context.active_capability`` is set, the corresponding capability
        handles the turn. Otherwise, the default ``chat`` capability is used.
        """
        if not context.session_id:
            context.session_id = str(uuid.uuid4())

        try:
            if context.knowledge_bases:
                from deeptutor.modules.catalog import require_module

                require_module("knowledge")
                from deeptutor.services.rag.pipelines.pageindex import (
                    validate_pageindex_oss_selection,
                )

                validate_pageindex_oss_selection(context.knowledge_bases)
        except ValueError as exc:
            bus = StreamBus()
            await bus.error(
                str(exc),
                source="orchestrator",
                metadata={"turn_terminal": True, "status": "failed"},
            )
            await bus.emit(
                StreamEvent(
                    type=StreamEventType.DONE,
                    source="orchestrator",
                    metadata={"status": "failed"},
                )
            )
            await bus.close()
            async for event in bus.subscribe():
                yield event
            return

        capability: TurnCapability | None
        if context.runtime.answer_by:
            # The turn belongs to someone else: a partner or a connected agent
            # answers in place of the selected mode. Not a registry entry —
            # it is never a mode a learner picks, only who replies.
            from deeptutor.capabilities.handoff import HandoffCapability

            cap_name = "handoff"
            capability = HandoffCapability()
        else:
            cap_name = context.active_capability or "chat"
            capability = self._cap_registry.get(cap_name)

        if capability is None:
            bus = StreamBus()
            await bus.error(
                f"Unknown capability: {cap_name}. "
                f"Available: {self._cap_registry.list_capabilities()}",
                source="orchestrator",
                metadata={"turn_terminal": True, "status": "failed"},
            )
            await bus.emit(
                StreamEvent(
                    type=StreamEventType.DONE,
                    source="orchestrator",
                    metadata={"status": "failed"},
                )
            )
            await bus.close()
            async for event in bus.subscribe():
                yield event
            return

        yield StreamEvent(
            type=StreamEventType.SESSION,
            source="orchestrator",
            metadata={
                "session_id": context.session_id,
                "turn_id": str(context.metadata.get("turn_id", "")),
            },
        )

        bus = StreamBus()
        _turn_id = str(context.metadata.get("turn_id") or "")
        if _turn_id:
            register_bus(_turn_id, bus)

        async def _run() -> None:
            from deeptutor.services.llm.metrics import TurnUsage, current_usage

            turn_usage = current_usage.get()
            usage_token = None
            if (
                turn_usage is None
                or not _turn_id
                or turn_usage.turn_id != _turn_id
                or turn_usage.session_id != context.session_id
            ):
                turn_usage = TurnUsage(
                    session_id=context.session_id, turn_id=_turn_id, source=cap_name
                )
                usage_token = current_usage.set(turn_usage)
            status = "completed"
            terminal_error_metadata: dict[str, Any] = {}
            try:
                await capability.run(context, bus)
                if bus.result_completion is False:
                    status = "failed"
                    terminal_error_metadata = {
                        "error_code": "capability_incomplete",
                        "retryable": True,
                    }
                    prompts = get_prompt_manager().load_prompts(
                        "capabilities", "turn_status", language=context.language
                    )
                    await bus.error(
                        prompt_text(prompts, ("notices", "capability_incomplete")),
                        source=cap_name,
                        metadata={
                            "turn_terminal": True,
                            "status": status,
                            **terminal_error_metadata,
                        },
                    )
            except Exception as exc:
                status = "failed"
                logger.error("Capability %s failed: %s", cap_name, exc, exc_info=True)
                error_metadata: dict[str, Any] = {
                    "turn_terminal": True,
                    "status": status,
                }
                error_code = getattr(exc, "error_code", None)
                if isinstance(error_code, str) and error_code:
                    error_metadata["error_code"] = error_code
                retryable = getattr(exc, "retryable", None)
                if isinstance(retryable, bool):
                    error_metadata["retryable"] = retryable
                partial_response = getattr(exc, "partial_response", None)
                if isinstance(partial_response, bool):
                    error_metadata["partial_response"] = partial_response
                terminal_error_metadata = {
                    key: error_metadata[key]
                    for key in ("error_code", "retryable", "partial_response")
                    if key in error_metadata
                }
                await bus.error(
                    str(exc),
                    source=cap_name,
                    metadata=error_metadata,
                )
            finally:
                await bus.emit(
                    StreamEvent(
                        type=StreamEventType.DONE,
                        source=cap_name,
                        metadata={
                            "status": status,
                            **terminal_error_metadata,
                            **({"usage_summary": turn_usage.summary()} if turn_usage.calls else {}),
                        },
                    )
                )
                if usage_token is not None:
                    current_usage.reset(usage_token)
                await bus.close()
                if _turn_id:
                    unregister_bus(_turn_id)

        stream = bus.subscribe()
        task = asyncio.create_task(_run())
        try:
            async for event in stream:
                yield event
            await task
        finally:
            # The capability runs in its own task, so a consumer that stops
            # reading — a cancelled turn, or a stream closed early — does not
            # stop it. Left running, it keeps calling the model and tools for a
            # turn already reported as stopped; left parked on ``ask_user``, it
            # is collected mid-await and ``_run`` never unregisters the bus.
            if not task.done():
                task.cancel()
                with contextlib.suppress(asyncio.CancelledError):
                    await task

        await self._publish_completion(context, cap_name)

    async def _publish_completion(self, context: UnifiedContext, cap_name: str) -> None:
        """Publish CAPABILITY_COMPLETE to the global EventBus."""
        try:
            bus = get_event_bus()
            agent_output, metadata = completion_event_fields(context, cap_name)
            await bus.publish(
                Event(
                    type=EventType.CAPABILITY_COMPLETE,
                    task_id=str(context.metadata.get("turn_id") or context.session_id),
                    user_input=context.user_message,
                    agent_output=agent_output,
                    metadata=metadata,
                )
            )
        except Exception:
            logger.debug("EventBus publish failed (may not be running)", exc_info=True)

    def list_tools(self) -> list[str]:
        return self._tool_registry.list_tools()

    def list_capabilities(self) -> list[str]:
        return self._cap_registry.list_capabilities()

    def get_capability_manifests(self) -> list[dict[str, Any]]:
        return self._cap_registry.get_manifests()

    def get_tool_schemas(self, names: list[str] | None = None) -> list[dict[str, Any]]:
        return self._tool_registry.build_openai_schemas(names)