DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""
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)