DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""Factory registry for built-in and external chat-loop extensions."""
from __future__ import annotations
from collections.abc import Callable, Iterator, Sequence
from dataclasses import dataclass
from functools import cache
import importlib
import inspect
import logging
from typing import Any, cast
import warnings
from deeptutor.capabilities.protocol import LoopExtension
from deeptutor.core.context import UnifiedContext
from deeptutor.modules.catalog import contribution_enabled, manifests
from deeptutor.plugins.entry_points import load_entry_point_group
from deeptutor.runtime.capability_catalog import EmptyConfig, get_capability_catalog
logger = logging.getLogger(__name__)
EXTENSIONS_GROUP = "deeptutor.extensions"
LOOP_CAPABILITIES_GROUP = "deeptutor.loop_capabilities"
LoopFactory = Callable[[], LoopExtension]
@dataclass(frozen=True, slots=True)
class LoopCapabilitySpec:
"""Import-free descriptor for a built-in chat-loop extension."""
name: str
class_path: str
def create(self) -> LoopExtension:
module_path, class_name = self.class_path.rsplit(":", 1)
factory = getattr(importlib.import_module(module_path), class_name)
extension = factory()
if getattr(extension, "name", None) != self.name:
raise RuntimeError(
f"Loop capability descriptor drift for {self.class_path}: "
f"expected {self.name!r}, got {getattr(extension, 'name', None)!r}"
)
return cast(LoopExtension, extension)
def __call__(self) -> LoopExtension:
return self.create()
BUILTIN_LOOP_CAPABILITY_SPECS: tuple[LoopCapabilitySpec, ...] = tuple(
LoopCapabilitySpec(name, spec["class_path"])
for module in manifests().values()
for name, spec in module["loops"].items()
)
# Compatibility surface: the descriptors remain zero-argument callables.
LOOP_EXTENSION_FACTORIES: tuple[LoopFactory, ...] = cast(
tuple[LoopFactory, ...], BUILTIN_LOOP_CAPABILITY_SPECS
)
def _builtin_loop_extensions() -> tuple[LoopExtension, ...]:
return tuple(
spec() for spec in BUILTIN_LOOP_CAPABILITY_SPECS if contribution_enabled("loops", spec.name)
)
class _LegacyLoopCapabilitiesView(Sequence[LoopExtension]):
"""Deprecated sequence view that never retains extension instances."""
def __len__(self) -> int:
return sum(
contribution_enabled("loops", spec.name) for spec in BUILTIN_LOOP_CAPABILITY_SPECS
)
def __iter__(self) -> Iterator[LoopExtension]:
return iter(_builtin_loop_extensions())
def __getitem__(self, index): # noqa: ANN001, ANN204
return _builtin_loop_extensions()[index]
LOOP_CAPABILITIES: Sequence[LoopExtension] = _LegacyLoopCapabilitiesView()
def _coerce_loop_factory(loaded: object) -> tuple[LoopExtension, LoopFactory] | None:
obj: Any = loaded
if inspect.isclass(obj):
factory = obj
instance = obj()
elif callable(obj) and getattr(obj, "owned_tools", None) is None:
produced = obj()
if inspect.isclass(produced):
factory = produced
instance = produced()
else:
instance = produced
factory = obj
else:
instance = obj
factory = type(obj)
name = getattr(instance, "name", None)
tools = getattr(instance, "owned_tools", None)
if not isinstance(name, str) or not name.strip() or tools is None:
return None
try:
tuple(tools)
except TypeError:
return None
if not callable(getattr(instance, "is_active", None)):
return None
return cast(LoopExtension, instance), cast(LoopFactory, factory)
@cache
def _discover_external_loop_capabilities() -> tuple[tuple[str, LoopFactory], ...]:
"""Discover factory specs from canonical and one-version legacy groups."""
seen = {spec.name for spec in BUILTIN_LOOP_CAPABILITY_SPECS}
def _accept(ep_name: str, loaded: object) -> tuple[str, LoopFactory] | None:
resolved = _coerce_loop_factory(loaded)
if resolved is None:
logger.warning("Ignoring loop extension plugin '%s': invalid class or factory", ep_name)
return None
extension, factory = resolved
if extension.name in seen:
logger.warning(
"Loop extension plugin '%s' shadowed by built-in or earlier plugin (ignored)",
extension.name,
)
return None
seen.add(extension.name)
return extension.name, factory
canonical = load_entry_point_group(EXTENSIONS_GROUP, _accept, log=logger)
legacy = load_entry_point_group(LOOP_CAPABILITIES_GROUP, _accept, log=logger)
if legacy:
warnings.warn(
f"{LOOP_CAPABILITIES_GROUP} is deprecated; register under {EXTENSIONS_GROUP}",
DeprecationWarning,
stacklevel=2,
)
return tuple([*canonical, *legacy])
def discover_external_loop_capabilities():
return tuple(
item
for item in _discover_external_loop_capabilities()
if getattr(item[1], "_plugin_allowed", lambda: True)()
)
# Preserve the public reset hook while checking plugin revocation on every discovery.
discover_external_loop_capabilities.cache_clear = _discover_external_loop_capabilities.cache_clear # type: ignore[attr-defined]
def all_loop_capabilities(context: UnifiedContext | None = None) -> tuple[LoopExtension, ...]:
"""Create once per turn, rechecking activation and revocation on each use."""
specs: list[tuple[str, LoopFactory]] = [
(spec.name, spec)
for spec in BUILTIN_LOOP_CAPABILITY_SPECS
if contribution_enabled("loops", spec.name)
]
specs.extend(discover_external_loop_capabilities())
instances = context.runtime.loop_extensions if context is not None else {}
allowed = {name for name, _ in specs}
for name in tuple(instances):
if name not in allowed:
del instances[name]
result = []
for name, factory in specs:
instance = instances.get(name)
if instance is None:
instance = factory()
instances[name] = instance
get_capability_catalog().register(
name=name,
kind="loop_extension",
manifest={"name": name, "owned_tools": tuple(instance.owned_tools)},
factory=factory,
config_model=EmptyConfig,
replace=True,
)
result.append(cast(LoopExtension, instance))
return tuple(result)
def active_loop_capabilities(context: UnifiedContext) -> tuple[LoopExtension, ...]:
return tuple(
extension for extension in all_loop_capabilities(context) if extension.is_active(context)
)
def any_exclusive_capability_active(context: UnifiedContext) -> bool:
return any(
getattr(extension, "exclusive_tools", False)
for extension in active_loop_capabilities(context)
)
def capability_tool_owners() -> dict[str, str]:
return {
name: extension.name
for extension in all_loop_capabilities()
for name in extension.owned_tools
}
__all__ = [
"EXTENSIONS_GROUP",
"BUILTIN_LOOP_CAPABILITY_SPECS",
"LOOP_CAPABILITIES",
"LOOP_CAPABILITIES_GROUP",
"LOOP_EXTENSION_FACTORIES",
"active_loop_capabilities",
"all_loop_capabilities",
"any_exclusive_capability_active",
"capability_tool_owners",
"discover_external_loop_capabilities",
]