agentscope-runtime 1.0.0b2__py3-none-any.whl → 1.0.2__py3-none-any.whl

agentscope_runtime/engine/services/memory/memory_service_factory.py

@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+
+from typing import Callable, Dict
+
+from ..service_factory import ServiceFactory
+from .memory_service import MemoryService, InMemoryMemoryService
+from .redis_memory_service import RedisMemoryService
+from .mem0_memory_service import Mem0MemoryService
+from .reme_personal_memory_service import ReMePersonalMemoryService
+from .reme_task_memory_service import ReMeTaskMemoryService
+
+try:
+    from .tablestore_memory_service import (
+        TablestoreMemoryService,
+        SearchStrategy,
+    )
+
+    TABLESTORE_AVAILABLE = True
+except ImportError:
+    TABLESTORE_AVAILABLE = False
+    SearchStrategy = None  # type: ignore
+
+
+class MemoryServiceFactory(ServiceFactory[MemoryService]):
+    """
+    Factory for MemoryService, supporting both environment variables and
+    kwargs.
+
+    Usage examples:
+        1. Startup using only environment variables:
+            export MEMORY_BACKEND=redis
+            export MEMORY_REDIS_REDIS_URL="redis://localhost:6379/5"
+            service = await MemoryServiceFactory.create()
+
+        2. Override environment variables using arguments:
+            export MEMORY_BACKEND=redis
+            export MEMORY_REDIS_REDIS_URL="redis://localhost:6379/5"
+            service = await MemoryServiceFactory.create(
+                redis_url="redis://otherhost:6379/1"
+            )
+
+        3. Register a custom backend:
+            from my_backend import PostgresMemoryService
+            MemoryServiceFactory.register_backend(
+                "postgres",
+                PostgresMemoryService,
+            )
+            export MEMORY_BACKEND=postgres
+            export MEMORY_POSTGRES_DSN="postgresql://user:pass@localhost/db"
+            service = await MemoryServiceFactory.create()
+    """
+
+    _registry: Dict[str, Callable[..., MemoryService]] = {}
+    _env_prefix = "MEMORY_"
+    _default_backend = "in_memory"
+
+
+# === Default built-in backend registration ===
+
+MemoryServiceFactory.register_backend(
+    "in_memory",
+    lambda **kwargs: InMemoryMemoryService(),
+)
+
+MemoryServiceFactory.register_backend(
+    "redis",
+    RedisMemoryService,
+)
+
+MemoryServiceFactory.register_backend(
+    "mem0",
+    Mem0MemoryService,
+)
+
+MemoryServiceFactory.register_backend(
+    "reme_personal",
+    ReMePersonalMemoryService,
+)
+
+MemoryServiceFactory.register_backend(
+    "reme_task",
+    ReMeTaskMemoryService,
+)
+
+if TABLESTORE_AVAILABLE:
+
+    def _create_tablestore_memory_service(**kwargs):
+        """Helper function to create a TablestoreMemoryService instance."""
+        search_strategy = kwargs.get("search_strategy")
+        if isinstance(search_strategy, str):
+            search_strategy = SearchStrategy(search_strategy.lower())
+        elif search_strategy is None:
+            search_strategy = SearchStrategy.FULL_TEXT
+
+        return TablestoreMemoryService(
+            tablestore_client=kwargs["tablestore_client"],
+            search_strategy=search_strategy,
+            embedding_model=kwargs.get("embedding_model"),
+            vector_dimension=int(kwargs.get("vector_dimension", 1536)),
+            table_name=kwargs.get("table_name", "agentscope_runtime_memory"),
+            search_index_schema=kwargs.get("search_index_schema"),
+            text_field=kwargs.get("text_field", "text"),
+            embedding_field=kwargs.get("embedding_field", "embedding"),
+            vector_metric_type=kwargs.get("vector_metric_type"),
+            **{
+                k: v
+                for k, v in kwargs.items()
+                if k
+                not in [
+                    "tablestore_client",
+                    "search_strategy",
+                    "embedding_model",
+                    "vector_dimension",
+                    "table_name",
+                    "search_index_schema",
+                    "text_field",
+                    "embedding_field",
+                    "vector_metric_type",
+                ]
+            },
+        )
+
+    MemoryServiceFactory.register_backend(
+        "tablestore",
+        _create_tablestore_memory_service,
+    )

agentscope_runtime/engine/services/sandbox/__init__.py

@@ -4,10 +4,12 @@ from ....common.utils.lazy_loader import install_lazy_loader
 
 if TYPE_CHECKING:
     from .sandbox_service import SandboxService
+    from .sandbox_service_factory import SandboxServiceFactory
 
 install_lazy_loader(
     globals(),
     {
         "SandboxService": ".sandbox_service",
+        "SandboxServiceFactory": ".sandbox_service_factory",
     },
 )

agentscope_runtime/engine/services/sandbox/sandbox_service_factory.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+
+from typing import Callable, Dict
+
+from ..service_factory import ServiceFactory
+from .sandbox_service import SandboxService
+
+
+class SandboxServiceFactory(ServiceFactory[SandboxService]):
+    """
+    Factory for SandboxService, supporting both environment variables and
+    kwargs.
+
+    Usage examples:
+        1. Start with only environment variables:
+            export SANDBOX_BACKEND=default
+            export SANDBOX_DEFAULT_BASE_URL="http://localhost:8080"
+            export SANDBOX_DEFAULT_BEARER_TOKEN="token123"
+            service = await SandboxServiceFactory.create()
+
+        2. Override environment variables with arguments:
+            export SANDBOX_DEFAULT_BASE_URL="http://localhost:8080"
+            service = await SandboxServiceFactory.create(
+                base_url="http://otherhost:8080",
+                bearer_token="custom_token"
+            )
+
+        3. Register a custom backend:
+            from my_backend import CustomSandboxService
+            SandboxServiceFactory.register_backend(
+                "custom",
+                CustomSandboxService,
+            )
+            export SANDBOX_BACKEND=custom
+            export SANDBOX_CUSTOM_ENDPOINT="https://api.example.com"
+            export SANDBOX_CUSTOM_API_KEY="key123"
+            service = await SandboxServiceFactory.create()
+    """
+
+    _registry: Dict[str, Callable[..., SandboxService]] = {}
+    _env_prefix = "SANDBOX_"
+    _default_backend = "default"
+
+
+# === Default backend registration ===
+SandboxServiceFactory.register_backend(
+    "default",
+    SandboxService,
+)

agentscope_runtime/engine/services/service_factory.py

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+
+import os
+import inspect
+
+from typing import Callable, Dict, Any, Optional, TypeVar, Generic
+
+from .base import ServiceWithLifecycleManager
+
+T = TypeVar("T", bound=ServiceWithLifecycleManager)
+
+
+class ServiceFactory(Generic[T]):
+    """
+    Generic Service Factory base class that supports environment variables
+    and kwargs.
+
+    This base class provides a generic factory pattern that supports:
+    - Loading configuration from environment variables
+    - Overriding environment variables with kwargs
+    - Registering custom backends
+    """
+
+    _registry: Dict[str, Callable[..., T]] = {}
+    _env_prefix: str = ""
+    _default_backend: str = "in_memory"
+
+    @classmethod
+    def register_backend(
+        cls,
+        backend_type: str,
+        constructor: Callable[..., T],
+    ) -> None:
+        """Register a constructor function for a backend type.
+
+        Args:
+            backend_type: Backend type name (case-insensitive)
+            constructor: Constructor function used to create the service
+                instance
+        """
+        cls._registry[backend_type.lower()] = constructor
+
+    @classmethod
+    def _load_env_kwargs(cls, backend_type: str) -> Dict[str, Any]:
+        """Load backend-specific kwargs from environment variables.
+
+        Args:
+            backend_type: Backend type name
+
+        Returns:
+            A dictionary of parameters loaded from environment variables
+        """
+        result = {}
+        prefix = f"{cls._env_prefix}{backend_type.upper()}_"
+
+        for key, value in os.environ.items():
+            if key.startswith(prefix):
+                # env var: SERVICE_TYPE_BACKEND_PARAM -> param
+                param_name = key[len(prefix) :].lower()
+                result[param_name] = value
+
+        return result
+
+    @classmethod
+    async def create(
+        cls,
+        backend_type: Optional[str] = None,
+        **kwargs: Any,
+    ) -> T:
+        """
+        Create and start a service instance, supporting environment
+        variables and kwargs.
+
+        Args:
+            backend_type: Backend type, if None will read from environment
+                variables
+            **kwargs: Additional parameters, having higher priority than
+                environment variables
+
+        Returns:
+            A started service instance
+
+        Raises:
+            ValueError: If the backend_type is unsupported
+        """
+        if backend_type is None:
+            backend_type = os.getenv(
+                f"{cls._env_prefix}BACKEND",
+                cls._default_backend,
+            )
+        backend_type = backend_type.lower()
+
+        constructor = cls._registry.get(backend_type)
+        if constructor is None:
+            raise ValueError(f"Unsupported backend type: {backend_type}")
+
+        # 1. Load kwargs for this backend from environment variables
+        env_kwargs = cls._load_env_kwargs(backend_type)
+
+        # 2. Merge priority: kwargs > environment variables
+        final_kwargs = {**env_kwargs, **kwargs}
+
+        # 3. Filter out kwargs that are not accepted by the constructor
+        sig = inspect.signature(constructor)
+
+        has_var_kwargs = any(
+            p.kind == inspect.Parameter.VAR_KEYWORD
+            for p in sig.parameters.values()
+        )
+
+        if not has_var_kwargs:
+            accepted_keys = sig.parameters.keys()
+            final_kwargs = {
+                k: v for k, v in final_kwargs.items() if k in accepted_keys
+            }
+
+        # 4. Create instance
+        service = constructor(**final_kwargs)
+        return service

agentscope_runtime/engine/services/session_history/__init__.py

@@ -11,6 +11,7 @@ if TYPE_CHECKING:
     from .tablestore_session_history_service import (
         TablestoreSessionHistoryService,
     )
+    from .session_history_service_factory import SessionHistoryServiceFactory
 
 install_lazy_loader(
     globals(),
@@ -19,5 +20,6 @@ install_lazy_loader(
         "InMemorySessionHistoryService": ".session_history_service",
         "RedisSessionHistoryService": ".redis_session_history_service",
         "TablestoreSessionHistoryService": ".tablestore_session_history_service",  # noqa
+        "SessionHistoryServiceFactory": ".session_history_service_factory",
     },
 )

agentscope_runtime/engine/services/session_history/session_history_service_factory.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+
+from typing import Callable, Dict
+
+from ..service_factory import ServiceFactory
+from .session_history_service import (
+    SessionHistoryService,
+    InMemorySessionHistoryService,
+)
+from .redis_session_history_service import RedisSessionHistoryService
+
+try:
+    from .tablestore_session_history_service import (
+        TablestoreSessionHistoryService,
+    )
+
+    TABLESTORE_AVAILABLE = True
+except ImportError:
+    TABLESTORE_AVAILABLE = False
+
+
+class SessionHistoryServiceFactory(ServiceFactory[SessionHistoryService]):
+    """
+    Factory for SessionHistoryService, supporting both environment variables
+    and keyword arguments.
+
+    Usage examples:
+        1. Start with only environment variables:
+            export SESSION_HISTORY_BACKEND=redis
+            export SESSION_HISTORY_REDIS_REDIS_URL="redis://localhost:6379/5"
+            service = await SessionHistoryServiceFactory.create()
+
+        2. Override environment variables with arguments:
+            export SESSION_HISTORY_BACKEND=redis
+            export SESSION_HISTORY_REDIS_REDIS_URL="redis://localhost:6379/5"
+            service = await SessionHistoryServiceFactory.create(
+                redis_url="redis://otherhost:6379/1"
+            )
+
+        3. Register a custom backend:
+            from my_backend import PostgresSessionHistoryService
+            SessionHistoryServiceFactory.register_backend(
+                "postgres",
+                PostgresSessionHistoryService,
+            )
+            export SESSION_HISTORY_BACKEND=postgres
+            export SESSION_HISTORY_POSTGRES_DSN="postgresql://user:pass@localhost/db"  # noqa
+            export SESSION_HISTORY_POSTGRES_POOL_SIZE="20"
+            service = await SessionHistoryServiceFactory.create()
+    """
+
+    _registry: Dict[str, Callable[..., SessionHistoryService]] = {}
+    _env_prefix = "SESSION_HISTORY_"
+    _default_backend = "in_memory"
+
+
+# === Default built-in backend registration ===
+
+SessionHistoryServiceFactory.register_backend(
+    "in_memory",
+    InMemorySessionHistoryService,
+)
+
+SessionHistoryServiceFactory.register_backend(
+    "redis",
+    RedisSessionHistoryService,
+)
+
+if TABLESTORE_AVAILABLE:
+    SessionHistoryServiceFactory.register_backend(
+        "tablestore",
+        TablestoreSessionHistoryService,
+    )

agentscope_runtime/engine/services/utils/tablestore_service_utils.py

@@ -56,6 +56,32 @@ def exclude_None_fields_in_place(obj: Dict):
             del obj[key]
 
 
+def stringify_values(d: dict) -> dict:
+    for k, v in d.items():
+        if v is None:
+            continue
+        if isinstance(v, (dict, list)):
+            d[k] = json.dumps(v, ensure_ascii=False)
+        elif not isinstance(v, str):
+            d[k] = str(v)
+    return d
+
+
+def _json_loads_if_str(v):
+    if isinstance(v, str):
+        try:
+            return json.loads(v)
+        except Exception:
+            return v
+    return v
+
+
+def restore_json_strings(d: dict) -> dict:
+    for k, v in d.items():
+        d[k] = _json_loads_if_str(v)
+    return d
+
+
 def tablestore_log(msg: str):
     print(msg)
 
@@ -111,6 +137,7 @@ def convert_message_to_tablestore_message(
     """Convert Message to TablestoreMessage"""
     content, content_list = _generate_tablestore_content_from_message(message)
     tablestore_message_metadata = message.model_dump(exclude={"content", "id"})
+    tablestore_message_metadata = stringify_values(tablestore_message_metadata)
     tablestore_message_metadata[content_list_name] = json.dumps(
         content_list,
         ensure_ascii=False,
@@ -241,6 +268,9 @@ def _generate_init_json_from_tablestore_message(
 ) -> Dict[str, Any]:
     """Generate initialization JSON from TablestoreMessage"""
     tablestore_message = copy.deepcopy(tablestore_message)
+    tablestore_message.metadata = restore_json_strings(
+        tablestore_message.metadata,
+    )
     tablestore_message_content_list = tablestore_message.metadata.pop(
         content_list_name,
         None,
@@ -249,11 +279,7 @@ def _generate_init_json_from_tablestore_message(
         "id": tablestore_message.message_id,
         "content": _generate_content_from_tablestore_content(
             text=tablestore_message.content,
-            content_list=(
-                json.loads(tablestore_message_content_list)
-                if tablestore_message_content_list
-                else None
-            ),
+            content_list=tablestore_message_content_list,
         ),
     }
     init_json.update(tablestore_message.metadata)
@@ -265,6 +291,9 @@ def _generate_init_json_from_tablestore_document(
 ) -> Dict[str, Any]:
     """Generate initialization JSON from TablestoreDocument"""
     tablestore_document = copy.deepcopy(tablestore_document)
+    tablestore_document.metadata = restore_json_strings(
+        tablestore_document.metadata,
+    )
     tablestore_document_content_list = tablestore_document.metadata.pop(
         content_list_name,
         None,
@@ -273,11 +302,7 @@ def _generate_init_json_from_tablestore_document(
         "id": tablestore_document.document_id,
         "content": _generate_content_from_tablestore_content(
             text=tablestore_document.text,
-            content_list=(
-                json.loads(tablestore_document_content_list)
-                if tablestore_document_content_list
-                else None
-            ),
+            content_list=tablestore_document_content_list,
         ),
     }
     init_json.update(tablestore_document.metadata)

agentscope_runtime/engine/tracing/wrapper.py

@@ -7,6 +7,7 @@ import json
 import os
 import re
 import time
+import threading
 import uuid
 from collections.abc import Callable
 from copy import deepcopy
@@ -25,7 +26,7 @@ from typing import (
 from pydantic import BaseModel
 from opentelemetry.propagate import extract
 from opentelemetry.context import attach
-from opentelemetry.trace import StatusCode
+from opentelemetry.trace import StatusCode, NoOpTracerProvider
 from opentelemetry import trace as ot_trace
 from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
     OTLPSpanExporter as OTLPSpanGrpcExporter,
@@ -177,7 +178,7 @@ def trace(  # pylint: disable=too-many-statements
                 **common_attrs,
             }
 
-            with _ot_tracer.start_as_current_span(
+            with _get_ot_tracer().start_as_current_span(
                 final_trace_name,
                 context=parent_ctx,
                 attributes=span_attributes,
@@ -280,7 +281,7 @@ def trace(  # pylint: disable=too-many-statements
                 **common_attrs,
             }
 
-            with _ot_tracer.start_as_current_span(
+            with _get_ot_tracer().start_as_current_span(
                 final_trace_name,
                 context=parent_ctx,
                 attributes=span_attributes,
@@ -385,7 +386,7 @@ def trace(  # pylint: disable=too-many-statements
                 **common_attrs,
             }
 
-            with _ot_tracer.start_as_current_span(
+            with _get_ot_tracer().start_as_current_span(
                 final_trace_name,
                 context=parent_ctx,
                 attributes=span_attributes,
@@ -518,7 +519,7 @@ def trace(  # pylint: disable=too-many-statements
                 **common_attrs,
             }
 
-            with _ot_tracer.start_as_current_span(
+            with _get_ot_tracer().start_as_current_span(
                 final_trace_name,
                 context=parent_ctx,
                 attributes=span_attributes,
@@ -897,13 +898,17 @@ def _get_service_name() -> str:
 
 def _get_tracer() -> Tracer:
     handlers: list[TracerHandler] = []
-    if _str_to_bool(os.getenv("TRACE_ENABLE_LOG", "true")):
+    if _str_to_bool(os.getenv("TRACE_ENABLE_LOG", "false")):
         handlers.append(LocalLogHandler(enable_console=True))
 
     tracer = Tracer(handlers=handlers)
     return tracer
 
 
+_otel_tracer_lock = threading.Lock()
+_otel_tracer = None
+
+
 # TODO: support more tracing protocols and platforms
 def _get_ot_tracer() -> ot_trace.Tracer:
     """Get the OpenTelemetry tracer.
@@ -912,35 +917,48 @@ def _get_ot_tracer() -> ot_trace.Tracer:
         ot_trace.Tracer: The OpenTelemetry tracer instance.
     """
 
-    resource = Resource(
-        attributes={
-            SERVICE_NAME: _get_service_name(),
-            SERVICE_VERSION: os.getenv("SERVICE_VERSION", "1.0.0"),
-            "source": "agentscope_runtime-source",
-        },
-    )
-    provider = TracerProvider(resource=resource)
-    if _str_to_bool(os.getenv("TRACE_ENABLE_REPORT", "false")):
-        span_exporter = BatchSpanProcessor(
-            OTLPSpanGrpcExporter(
-                endpoint=os.getenv("TRACE_ENDPOINT", ""),
-                headers=f"Authentication="
-                f"{os.getenv('TRACE_AUTHENTICATION', '')}",
-            ),
+    def _get_ot_tracer_inner() -> ot_trace.Tracer:
+        existing_provider = ot_trace.get_tracer_provider()
+
+        if not isinstance(existing_provider, NoOpTracerProvider):
+            return ot_trace.get_tracer("agentscope_runtime")
+
+        resource = Resource(
+            attributes={
+                SERVICE_NAME: _get_service_name(),
+                SERVICE_VERSION: os.getenv("SERVICE_VERSION", "1.0.0"),
+                "source": "agentscope_runtime-source",
+            },
         )
-        provider.add_span_processor(span_exporter)
+        provider = TracerProvider(resource=resource)
+        if _str_to_bool(os.getenv("TRACE_ENABLE_REPORT", "false")):
+            span_exporter = BatchSpanProcessor(
+                OTLPSpanGrpcExporter(
+                    endpoint=os.getenv("TRACE_ENDPOINT", ""),
+                    headers=f"Authentication="
+                    f"{os.getenv('TRACE_AUTHENTICATION', '')}",
+                ),
+            )
+            provider.add_span_processor(span_exporter)
 
-    if _str_to_bool(os.getenv("TRACE_ENABLE_DEBUG", "false")):
-        span_logger = BatchSpanProcessor(ConsoleSpanExporter())
-        provider.add_span_processor(span_logger)
+        if _str_to_bool(os.getenv("TRACE_ENABLE_DEBUG", "false")):
+            span_logger = BatchSpanProcessor(ConsoleSpanExporter())
+            provider.add_span_processor(span_logger)
 
-    tracer = ot_trace.get_tracer(
-        "agentscope_runtime",
-        tracer_provider=provider,
-    )
-    return tracer
+        tracer = ot_trace.get_tracer(
+            "agentscope_runtime",
+            tracer_provider=provider,
+        )
+        return tracer
+
+    global _otel_tracer
+
+    if _otel_tracer is None:
+        with _otel_tracer_lock:
+            if _otel_tracer is None:
+                _otel_tracer = _get_ot_tracer_inner()
 
+    return _otel_tracer
 
-_ot_tracer = _get_ot_tracer()
 
 _tracer = _get_tracer()