EvoScientist Ai4Sci

EvoScientist/runtime_integrations.py

@@ -0,0 +1,116 @@
+"""Optional runtime services supplied by an application embedding EvoScientist.
+
+The CLI package must not import a concrete web gateway. Applications such as
+Ai4Sci-Web can register their database, storage, metering, and media services
+at process startup through this module.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, replace
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+AsyncProvider = Callable[[], Awaitable[Any]]
+AsyncFileHandler = Callable[[Path], Awaitable[Any]]
+AsyncUsageRecorder = Callable[[str, str], Awaitable[Any]]
+ModelResolver = Callable[[str | None, str | None], Any | None]
+
+
+class RuntimeIntegrationUnavailable(RuntimeError):
+    """Raised when an optional host-provided service is not configured."""
+
+
+@dataclass(frozen=True)
+class RuntimeIntegrations:
+    app_connection_provider: AsyncProvider | None = None
+    session_connection_provider: AsyncProvider | None = None
+    session_dsn_provider: Callable[[], str | None] | None = None
+    current_date_provider: Callable[[], date] | None = None
+    user_storage_root_provider: Callable[[str], Path] | None = None
+    knowledge_file_handler: AsyncFileHandler | None = None
+    usage_recorder: AsyncUsageRecorder | None = None
+    image_backend_factory: Callable[[], Any] | None = None
+    model_resolver: ModelResolver | None = None
+
+
+_integrations = RuntimeIntegrations()
+
+
+def configure_runtime_integrations(**services: Any) -> RuntimeIntegrations:
+    """Register host-provided services and return the resulting configuration."""
+    global _integrations
+    _integrations = replace(_integrations, **services)
+    return _integrations
+
+
+def reset_runtime_integrations() -> None:
+    """Clear all host-provided services, primarily for tests."""
+    global _integrations
+    _integrations = RuntimeIntegrations()
+
+
+def has_session_connection_provider() -> bool:
+    return _integrations.session_connection_provider is not None
+
+
+def get_session_dsn() -> str | None:
+    provider = _integrations.session_dsn_provider
+    return provider() if provider is not None else None
+
+
+async def get_session_connection() -> Any:
+    provider = _integrations.session_connection_provider
+    if provider is None:
+        raise RuntimeIntegrationUnavailable(
+            "No session connection provider is configured"
+        )
+    return await provider()
+
+
+async def get_app_connection() -> Any:
+    provider = _integrations.app_connection_provider
+    if provider is None:
+        raise RuntimeIntegrationUnavailable(
+            "No application connection provider is configured"
+        )
+    return await provider()
+
+
+def current_date() -> date:
+    provider = _integrations.current_date_provider
+    return provider() if provider is not None else date.today()
+
+
+def resolve_user_storage_root(user_id: str) -> Path | None:
+    provider = _integrations.user_storage_root_provider
+    return provider(user_id) if provider is not None else None
+
+
+def resolve_runtime_model(model: str | None, provider: str | None = None) -> Any | None:
+    """Resolve a host-managed model configuration when one is registered."""
+    resolver = _integrations.model_resolver
+    return resolver(model, provider) if resolver is not None else None
+
+
+async def handle_knowledge_file(path: Path) -> None:
+    handler = _integrations.knowledge_file_handler
+    if handler is not None:
+        await handler(path)
+
+
+async def record_service_usage(service: str, action: str) -> None:
+    recorder = _integrations.usage_recorder
+    if recorder is not None:
+        await recorder(service, action)
+
+
+def get_image_backend() -> Any:
+    factory = _integrations.image_backend_factory
+    if factory is None:
+        raise RuntimeIntegrationUnavailable(
+            "Image generation is unavailable in this runtime. Configure an image backend first."
+        )
+    return factory()