DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""Process-level dependency container and scoped runtime registry."""
from __future__ import annotations
import asyncio
import contextlib
import os
import socket
from typing import Any
import uuid
from deeptutor.runtime.capability_catalog import get_capability_catalog
from deeptutor.runtime.coordination import (
CoordinationSettings,
MemoryCoordinator,
RedisCoordinator,
RuntimeConfigurationError,
RuntimeCoordinator,
TurnRecoveryService,
)
from deeptutor.runtime.registry.capability_registry import CapabilityRegistry
from deeptutor.runtime.turn_engine import TurnEngine
from deeptutor.services.config import load_integrations_settings, load_system_settings
from deeptutor.services.session import get_session_store
from deeptutor.services.session.protocol import SessionStoreProtocol
from deeptutor.services.session.scope import store_scope
from deeptutor.services.session.turn_runtime import TurnRuntimeManager
from .service import TurnApplicationService
class StoreProvider:
def get(self) -> SessionStoreProtocol:
return get_session_store()
class RuntimeRegistry:
def __init__(
self,
coordinator: RuntimeCoordinator,
worker_id: str,
turn_engine: TurnEngine | None = None,
) -> None:
self.coordinator = coordinator
self.worker_id = worker_id
self.turn_engine = turn_engine
self._runtimes: dict[str, TurnRuntimeManager] = {}
def get(self, store: SessionStoreProtocol) -> TurnRuntimeManager:
key = store_scope(store).cache_key
runtime = self._runtimes.get(key)
if runtime is None:
runtime = TurnRuntimeManager(
store,
coordinator=self.coordinator,
owner_id=self.worker_id,
turn_engine=self.turn_engine,
)
self._runtimes[key] = runtime
return runtime
async def close(self, *, drain_timeout_seconds: float = 60.0) -> None:
runtimes = list(self._runtimes.values())
self._runtimes.clear()
if runtimes:
await asyncio.gather(
*(
runtime.close(drain_timeout_seconds=drain_timeout_seconds)
for runtime in runtimes
),
return_exceptions=True,
)
def owner_turn_count(self) -> int:
return sum(len(runtime._executions) for runtime in self._runtimes.values())
class ApplicationContainer:
def __init__(
self,
*,
settings: CoordinationSettings,
coordinator: RuntimeCoordinator,
worker_id: str,
) -> None:
self.settings = settings
self.coordinator = coordinator
self.worker_id = worker_id
self.capability_catalog = get_capability_catalog()
self.capability_registry = CapabilityRegistry(self.capability_catalog)
self.capability_registry.load_builtins()
self.capability_registry.load_plugins()
self.turn_engine = TurnEngine(self.capability_registry)
self.store_provider = StoreProvider()
self.runtime_registry = RuntimeRegistry(coordinator, worker_id, self.turn_engine)
self.turns = TurnApplicationService(
self.store_provider,
self.runtime_registry,
coordinator,
)
self._recovery_services: dict[str, TurnRecoveryService] = {}
self._started = False
self._module_lease: contextlib.AbstractContextManager | None = None
@classmethod
def build(cls) -> "ApplicationContainer":
settings = CoordinationSettings.from_runtime_settings(
load_system_settings(), load_integrations_settings()
)
coordinator: RuntimeCoordinator
if settings.backend == "redis":
coordinator = RedisCoordinator(
settings.redis_url,
key_prefix=settings.key_prefix,
lease_ttl_seconds=settings.lease_ttl_seconds,
stream_retention_seconds=settings.stream_retention_seconds,
)
else:
coordinator = MemoryCoordinator(lease_ttl_seconds=settings.lease_ttl_seconds)
worker_id = f"{socket.gethostname()}:{os.getpid()}:{uuid.uuid4().hex[:8]}"
return cls(settings=settings, coordinator=coordinator, worker_id=worker_id)
async def start(self) -> None:
if self._started:
return
from deeptutor.modules.lifecycle import environment_lease
lease = environment_lease()
lease.__enter__()
self._module_lease = lease
try:
if not await self.coordinator.health():
raise RuntimeConfigurationError(
"Turn coordination backend is unavailable; refusing to start"
)
self._started = True
except BaseException:
lease.__exit__(None, None, None)
self._module_lease = None
raise
async def close(self) -> None:
if not self._started:
return
try:
# Await cancellation cleanup before releasing the environment lease.
await self.runtime_registry.close(drain_timeout_seconds=0.0)
from deeptutor.runtime.memory_reclaim import cancel_idle_reclaim
from deeptutor.runtime.ts_engine import close_engine_clients
cancel_idle_reclaim()
await close_engine_clients()
with contextlib.suppress(Exception):
await self.coordinator.close()
finally:
self._started = False
lease = getattr(self, "_module_lease", None)
if lease is not None:
lease.__exit__(None, None, None)
self._module_lease = None
async def recover_once(self) -> None:
"""Recover expired turns across every registered user repository.
Missing turns are deliberately not acknowledged by a repository's
recovery service; the next user scope therefore still gets a chance
to claim and recover them.
"""
from deeptutor.multi_user.paths import user_context
from deeptutor.services.workspace.activity import acquire_activity
from deeptutor.services.workspace.models import WorkspaceError
seen: set[str] = set()
for user in self._local_users():
with user_context(user):
try:
activity = acquire_activity()
except WorkspaceError:
continue
try:
await self._recover_user_workspaces(seen)
finally:
activity.close()
async def _recover_user_workspaces(self, seen: set[str]) -> None:
from deeptutor.services.workspace import get_content_workspace_service
from deeptutor.services.workspace.context import workspace_context
from deeptutor.services.workspace.models import WorkspaceError
workspace_ids = [""] + [
row["workspace_id"]
for row in get_content_workspace_service()._catalog()
if row.get("kind") == "workspace" and os.path.isdir(row["path"])
]
for workspace_id in workspace_ids:
try:
with workspace_context(workspace_id):
store = self.store_provider.get()
scope_key = store_scope(store).cache_key
if scope_key in seen:
continue
seen.add(scope_key)
recovery = self._recovery_services.get(scope_key)
if recovery is None:
recovery = TurnRecoveryService(self.coordinator, store)
self._recovery_services[scope_key] = recovery
await recovery.recover_once()
except WorkspaceError:
continue
@staticmethod
def _local_users() -> list[Any]:
"""Return the admin plus every registered local user scope."""
from deeptutor.multi_user.identity import list_user_info
from deeptutor.multi_user.models import CurrentUser
from deeptutor.multi_user.paths import local_admin_user, scope_for_user
users = [local_admin_user()]
for record in list_user_info():
user_id = str(record.get("id") or "").strip()
role = str(record.get("role") or "user")
if not user_id or role == "admin":
continue
users.append(
CurrentUser(
id=user_id,
username=str(record.get("username") or user_id),
role="user",
scope=scope_for_user(user_id, is_admin=False),
)
)
return users
async def migrate_legacy_chat(self, *, dry_run: bool = False) -> dict[str, Any]:
"""Migrate the current scope's removed v1 JSON chat store."""
from deeptutor.services.path_service import get_path_service
from deeptutor.services.session.legacy_migration import (
LegacyChatSessionMigrator,
)
paths = get_path_service()
migrator = LegacyChatSessionMigrator(
self.store_provider.get(),
paths.get_session_file("chat"),
paths.get_user_root() / "archive" / "legacy-chat",
)
return (await migrator.migrate(dry_run=dry_run)).to_dict()
async def migrate_all_legacy_chats(self, *, dry_run: bool = False) -> list[dict[str, Any]]:
"""Migrate admin and every registered local user scope."""
from deeptutor.services.session.legacy_migration import (
migrate_all_legacy_chat_scopes,
)
return await migrate_all_legacy_chat_scopes(dry_run=dry_run)
async def migrate_all_workspace_preferences(self) -> list[dict[str, Any]]:
"""Upgrade legacy Reading/Mastery metadata in every account scope."""
from deeptutor.multi_user.identity import list_user_info
from deeptutor.multi_user.models import CurrentUser
from deeptutor.multi_user.paths import local_admin_user, scope_for_user, user_context
users = [local_admin_user()]
users.extend(
CurrentUser(
id=str(record.get("id") or ""),
username=str(record.get("username") or record.get("id") or ""),
role="admin" if str(record.get("role") or "user") == "admin" else "user",
scope=scope_for_user(
str(record.get("id") or ""),
is_admin=str(record.get("role") or "user") == "admin",
),
)
for record in list_user_info()
if str(record.get("id") or "").strip()
)
reports: list[dict[str, Any]] = []
seen_users: set[str] = set()
for user in users:
if user.id in seen_users:
continue
seen_users.add(user.id)
with user_context(user):
from deeptutor.services.workspace.activity import acquire_activity
from deeptutor.services.workspace.models import WorkspaceError
try:
activity = acquire_activity()
except WorkspaceError as exc:
reports.append({"user_id": user.id, "skipped": str(exc)})
continue
try:
migrated = await self.store_provider.get().migrate_workspace_preferences()
finally:
activity.close()
reports.append(
{
"user_id": user.id,
"scope": user.scope.cache_key,
"migrated": migrated,
}
)
return reports
async def adopt_all_book_chat_sessions(self) -> list[dict[str, Any]]:
"""Link page chats to their books in every account and workspace."""
from deeptutor.modules.catalog import module_enabled
if not module_enabled("books"):
return []
from deeptutor.book.chat_sessions import adopt_book_chat_sessions
from deeptutor.multi_user.paths import user_context
from deeptutor.services.workspace import get_content_workspace_service
from deeptutor.services.workspace.context import workspace_context
from deeptutor.services.workspace.models import WorkspaceError
reports: list[dict[str, Any]] = []
for user in self._local_users():
with user_context(user):
try:
scopes = [""] + [
row["workspace_id"]
for row in get_content_workspace_service().list_workspaces()
if row["kind"] == "workspace" and row["status"] == "ready"
]
except WorkspaceError as exc:
reports.append({"user_id": user.id, "skipped": str(exc)})
continue
tagged = 0
for scope in scopes:
try:
with workspace_context(scope):
tagged += await adopt_book_chat_sessions()
except WorkspaceError:
continue
reports.append({"user_id": user.id, "tagged": tagged})
return reports
async def run_startup_data_migrations(self) -> dict[str, list[dict[str, Any]]]:
"""Run every idempotent migration shared by all server launch modes."""
result = {
"legacy_chat": await self.migrate_all_legacy_chats(),
"workspace_preferences": await self.migrate_all_workspace_preferences(),
"book_chats": await self.adopt_all_book_chat_sessions(),
}
from deeptutor.multi_user.paths import user_context
from deeptutor.services.workspace.session_move import migrate_legacy_bindings
reports = []
for user in self._local_users():
with user_context(user):
from deeptutor.services.workspace.models import WorkspaceError
try:
reports.append(
{
"user_id": user.id,
"migrated": await asyncio.to_thread(migrate_legacy_bindings),
}
)
except WorkspaceError as exc:
reports.append({"user_id": user.id, "skipped": str(exc)})
result["workspace_data"] = reports
return result
async def runtime_report(self) -> dict[str, Any]:
report = self.settings.runtime_report()
coordinator_healthy = await self.coordinator.health()
report.update(
{
"worker_id": self.worker_id,
"redis_status": (
"ok"
if self.settings.backend == "redis" and coordinator_healthy
else ("unavailable" if self.settings.backend == "redis" else "not_configured")
),
"leader_id": await self.coordinator.leader_id(),
"owner_turn_count": self.runtime_registry.owner_turn_count(),
"recovery_backlog": sum(
recovery.backlog for recovery in self._recovery_services.values()
),
}
)
return report
_default_container: ApplicationContainer | None = None
def get_application_container() -> ApplicationContainer:
global _default_container
if _default_container is None:
_default_container = ApplicationContainer.build()
return _default_container
def set_application_container(container: ApplicationContainer | None) -> None:
global _default_container
_default_container = container
async def close_application_container() -> None:
"""Close an existing default runtime without constructing one for cleanup."""
global _default_container
container = _default_container
if container is None:
return
try:
await container.close()
finally:
if _default_container is container:
_default_container = None
__all__ = [
"ApplicationContainer",
"RuntimeRegistry",
"StoreProvider",
"get_application_container",
"set_application_container",
"close_application_container",
]