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

agentscope_runtime/engine/schemas/response_api.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+from typing import Dict, Literal, TypeAlias
+from pydantic import ConfigDict
+from pydantic.main import BaseModel
+from openai.types.shared import Reasoning
+
+from openai.types.responses import (
+    ResponseFunctionToolCall,
+    ResponseInputItemParam,
+    ResponsePrompt,
+    ResponseReasoningItem,
+)
+from openai.types.responses.response_input_param import Message
+from openai.types.responses.response import ToolChoice
+
+# Backward compatibility for OpenAI client versions
+try:  # For older openai versions (< 1.100.0)
+    from openai.types.responses import ResponseTextConfig
+except ImportError:  # For newer openai versions (>= 1.100.0)
+    from openai.types.responses import (
+        ResponseFormatTextConfig as ResponseTextConfig,
+    )
+
+
+class OpenAIBaseModel(BaseModel):
+    # OpenAI API does allow extra fields
+    model_config = ConfigDict(extra="allow")
+
+
+ResponseInputOutputItem: TypeAlias = (
+    ResponseInputItemParam | ResponseReasoningItem | ResponseFunctionToolCall
+)
+
+
+class ResponseAPI(OpenAIBaseModel):
+    # Ordered by official OpenAI API documentation
+    # https://platform.openai.com/docs/api-reference/responses/create
+    background: bool | None = False
+    include: list[str] | None = None
+    input: str | list[Message]
+    instructions: str | None = None
+    max_output_tokens: int | None = None
+    max_tool_calls: int | None = None
+    metadata: Dict[str, str] | None = None
+    model: str | None = None
+    parallel_tool_calls: bool | None = True
+    previous_response_id: str | None = None
+    prompt: ResponsePrompt | None = None
+    reasoning: Reasoning | None = None
+    service_tier: Literal[
+        "auto",
+        "default",
+        "flex",
+        "scale",
+        "priority",
+    ] = "auto"
+    store: bool | None = True
+    stream: bool | None = False
+    temperature: float | None = None
+    text: ResponseTextConfig | None = None
+    tool_choice: ToolChoice = "auto"
+    top_logprobs: int | None = 0
+    top_p: float | None = None
+    truncation: Literal["auto", "disabled"] | None = "disabled"
+    user: str | None = None

agentscope_runtime/engine/schemas/session.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+from typing import List, Union, Dict, Any
+
+from pydantic import BaseModel
+
+from .agent_schemas import Message
+
+
+class Session(BaseModel):
+    """Represents a single conversation session.
+
+    A session contains the history of a conversation, including all
+    messages, and is uniquely identified by its ID.
+
+    Attributes:
+        id: The unique identifier for the session.
+        user_id: The identifier of the user who owns the session.
+        messages: A list of messages formatted for Agent response
+
+    """
+
+    id: str
+    user_id: str
+    messages: List[Union[Message, Dict[str, Any]]] = []

agentscope_runtime/engine/services/__init__.py

@@ -1,9 +0,0 @@
-# -*- coding: utf-8 -*-
-from .base import (
-    Service,
-    ServiceWithLifecycleManager,
-    ServiceLifecycleManagerMixin,
-)
-from .sandbox_service import SandboxService
-from .memory_service import MemoryService
-from .session_history_service import SessionHistoryService

agentscope_runtime/engine/services/agent_state/__init__.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+from typing import TYPE_CHECKING
+from ....common.utils.lazy_loader import install_lazy_loader
+
+if TYPE_CHECKING:
+    from .state_service import StateService, InMemoryStateService
+    from .redis_state_service import RedisStateService
+
+install_lazy_loader(
+    globals(),
+    {
+        "StateService": ".state_service",
+        "InMemoryStateService": ".state_service",
+        "RedisStateService": ".redis_state_service",
+    },
+)

agentscope_runtime/engine/services/agent_state/redis_state_service.py

@@ -0,0 +1,113 @@
+# -*- coding: utf-8 -*-
+import json
+from typing import Optional, Dict, Any
+
+import redis.asyncio as aioredis
+
+from .state_service import StateService
+
+
+class RedisStateService(StateService):
+    """
+    Redis-based implementation of StateService.
+
+    Stores agent states in Redis using a hash per (user_id, session_id),
+    with round_id as the hash field and serialized state as the value.
+    """
+
+    _DEFAULT_SESSION_ID = "default"
+
+    def __init__(
+        self,
+        redis_url: str = "redis://localhost:6379/0",
+        redis_client: Optional[aioredis.Redis] = None,
+    ):
+        self._redis_url = redis_url
+        self._redis = redis_client
+        self._health = False
+
+    async def start(self) -> None:
+        """Initialize the Redis connection."""
+        if self._redis is None:
+            self._redis = aioredis.from_url(
+                self._redis_url,
+                decode_responses=True,
+            )
+        self._health = True
+
+    async def stop(self) -> None:
+        """Close the Redis connection."""
+        if self._redis:
+            await self._redis.close()
+            self._redis = None
+        self._health = False
+
+    async def health(self) -> bool:
+        """Service health check."""
+        if not self._redis:
+            return False
+        try:
+            pong = await self._redis.ping()
+            return pong is True or pong == "PONG"
+        except Exception:
+            return False
+
+    def _session_key(self, user_id: str, session_id: str) -> str:
+        """Generate the Redis key for a user's session."""
+        return f"user_state:{user_id}:{session_id}"
+
+    async def save_state(
+        self,
+        user_id: str,
+        state: Dict[str, Any],
+        session_id: Optional[str] = None,
+        round_id: Optional[int] = None,
+    ) -> int:
+        if not self._redis:
+            raise RuntimeError("Redis connection is not available")
+
+        sid = session_id or self._DEFAULT_SESSION_ID
+        key = self._session_key(user_id, sid)
+
+        existing_fields = await self._redis.hkeys(key)
+        existing_rounds = sorted(
+            int(f) for f in existing_fields if f.isdigit()
+        )
+
+        if round_id is None:
+            if existing_rounds:
+                round_id = max(existing_rounds) + 1
+            else:
+                round_id = 1
+
+        await self._redis.hset(key, round_id, json.dumps(state))
+        return round_id
+
+    async def export_state(
+        self,
+        user_id: str,
+        session_id: Optional[str] = None,
+        round_id: Optional[int] = None,
+    ) -> Optional[Dict[str, Any]]:
+        if not self._redis:
+            raise RuntimeError("Redis connection is not available")
+
+        sid = session_id or self._DEFAULT_SESSION_ID
+        key = self._session_key(user_id, sid)
+
+        existing_fields = await self._redis.hkeys(key)
+        if not existing_fields:
+            return None
+
+        if round_id is None:
+            numeric_fields = [int(f) for f in existing_fields if f.isdigit()]
+            if not numeric_fields:
+                return None
+            latest_round_id = max(numeric_fields)
+            state_json = await self._redis.hget(key, latest_round_id)
+        else:
+            state_json = await self._redis.hget(key, round_id)
+
+        if state_json is None:
+            return None
+        return json.loads(state_json)

agentscope_runtime/engine/services/agent_state/state_service.py

@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+import copy
+
+from abc import abstractmethod
+from typing import Dict, Any, Optional
+
+from ..base import ServiceWithLifecycleManager
+
+
+class StateService(ServiceWithLifecycleManager):
+    """
+    Abstract base class for agent state management services.
+
+    Stores and manages agent states organized by user_id, session_id,
+    and round_id. Supports saving, retrieving, listing, and deleting states.
+    """
+
+    async def start(self) -> None:
+        pass
+
+    async def stop(self) -> None:
+        pass
+
+    @abstractmethod
+    async def save_state(
+        self,
+        user_id: str,
+        state: Dict[str, Any],
+        session_id: Optional[str] = None,
+        round_id: Optional[int] = None,
+    ) -> int:
+        """
+        Save serialized state data for a specific user/session.
+
+        If round_id is provided, store the state in that round.
+        If round_id is None, append as a new round with automatically
+        assigned round_id.
+
+        Args:
+            user_id: The unique ID of the user.
+            state: A dictionary representing serialized agent state.
+            session_id: Optional session/conversation ID. Defaults to
+                "default".
+            round_id: Optional conversation round number.
+
+        Returns:
+            The round_id in which the state was saved.
+        """
+
+    @abstractmethod
+    async def export_state(
+        self,
+        user_id: str,
+        session_id: Optional[str] = None,
+        round_id: Optional[int] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Retrieve serialized state data for a user/session.
+
+        If round_id is provided, return that round's state.
+        If round_id is None, return the latest round's state.
+
+        Args:
+            user_id: The unique ID of the user.
+            session_id: Optional session/conversation ID.
+            round_id: Optional round number.
+
+        Returns:
+            A dictionary representing the agent state, or None if not found.
+        """
+
+
+class InMemoryStateService(StateService):
+    """
+    In-memory implementation of StateService using dictionaries
+    for sparse round storage.
+
+    - Multiple users, sessions, and non-contiguous round IDs are supported.
+    - If round_id is None when saving, a new round is appended automatically.
+    - If round_id is None when exporting, the latest round is returned.
+    """
+
+    _DEFAULT_SESSION_ID = "default"
+
+    def __init__(self) -> None:
+        # Structure:
+        # { user_id: { session_id: { round_id: state_dict } } }
+        self._store: Optional[
+            Dict[str, Dict[str, Dict[int, Dict[str, Any]]]]
+        ] = None
+        self._health = False
+
+    async def start(self) -> None:
+        """Initialize the in-memory store."""
+        if self._store is None:
+            self._store = {}
+        self._health = True
+
+    async def stop(self) -> None:
+        """Clear all in-memory state data."""
+        if self._store is not None:
+            self._store.clear()
+        self._store = None
+        self._health = False
+
+    async def health(self) -> bool:
+        """Service health check."""
+        return self._health
+
+    async def save_state(
+        self,
+        user_id: str,
+        state: Dict[str, Any],
+        session_id: Optional[str] = None,
+        round_id: Optional[int] = None,
+    ) -> int:
+        """
+        Save serialized state in sparse dict storage.
+
+        If round_id is None, a new round_id will be assigned
+        as (max existing round_id + 1) or 1 if none exist.
+        Otherwise, the given round_id will be overwritten.
+
+        Returns:
+            The round_id where the state was saved.
+        """
+        if self._store is None:
+            raise RuntimeError("Service not started")
+
+        sid = session_id or self._DEFAULT_SESSION_ID
+
+        self._store.setdefault(user_id, {})
+        self._store[user_id].setdefault(sid, {})
+
+        rounds_dict = self._store[user_id][sid]
+
+        # Auto-generate round_id if not provided
+        if round_id is None:
+            if rounds_dict:
+                round_id = max(rounds_dict.keys()) + 1
+            else:
+                round_id = 1
+
+        # Store a deep copy so caller modifications don't affect saved state
+        rounds_dict[round_id] = copy.deepcopy(state)
+
+        return round_id
+
+    async def export_state(
+        self,
+        user_id: str,
+        session_id: Optional[str] = None,
+        round_id: Optional[int] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Retrieve state data for given user/session/round.
+
+        If round_id is None: return the latest round.
+        If round_id is provided: return that round's state.
+
+        Returns:
+            Dictionary representing the agent state, or None if not found.
+        """
+        if self._store is None:
+            raise RuntimeError("Service not started")
+
+        sid = session_id or self._DEFAULT_SESSION_ID
+        sessions = self._store.get(user_id, {})
+        rounds_dict = sessions.get(sid, {})
+
+        if not rounds_dict:
+            return None
+
+        if round_id is None:
+            # Get the latest round_id
+            latest_round_id = max(rounds_dict.keys())
+            return rounds_dict[latest_round_id]
+
+        return rounds_dict.get(round_id)

agentscope_runtime/engine/services/memory/__init__.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+from typing import TYPE_CHECKING
+from ....common.utils.lazy_loader import install_lazy_loader
+
+if TYPE_CHECKING:
+    from .memory_service import MemoryService, InMemoryMemoryService
+    from .redis_memory_service import RedisMemoryService
+    from .reme_task_memory_service import ReMeTaskMemoryService
+    from .reme_personal_memory_service import ReMePersonalMemoryService
+    from .mem0_memory_service import Mem0MemoryService
+    from .tablestore_memory_service import TablestoreMemoryService
+
+install_lazy_loader(
+    globals(),
+    {
+        "MemoryService": ".memory_service",
+        "InMemoryMemoryService": ".memory_service",
+        "RedisMemoryService": ".redis_memory_service",
+        "ReMeTaskMemoryService": ".reme_task_memory_service",
+        "ReMePersonalMemoryService": ".reme_personal_memory_service",
+        "Mem0MemoryService": ".mem0_memory_service",
+        "TablestoreMemoryService": ".tablestore_memory_service",
+    },
+)

agentscope_runtime/engine/services/{mem0_memory_service.py → memory/mem0_memory_service.py}

@@ -1,8 +1,11 @@
 # -*- coding: utf-8 -*-
 import os
 from typing import Optional, Dict, Any, List
+
+from mem0 import AsyncMemoryClient
+
 from .memory_service import MemoryService
-from ..schemas.agent_schemas import Message, MessageType, ContentType
+from ...schemas.agent_schemas import Message, MessageType, ContentType
 
 
 class Mem0MemoryService(MemoryService):
@@ -14,15 +17,8 @@ class Mem0MemoryService(MemoryService):
 
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
-        from mem0 import AsyncMemoryClient
-
-        mem0_api_key = os.getenv("MEM0_API_KEY")
-        if mem0_api_key is None:
-            raise ValueError("MEM0_API_KEY is not set")
-        mem0_api_key = os.getenv("MEM0_API_KEY")
-
-        # get the mem0 client instance
-        self.service = AsyncMemoryClient(api_key=mem0_api_key)
+        self.service = None
+        self._health = False
 
     @staticmethod
     async def get_query_text(message: Message) -> str:
@@ -63,13 +59,21 @@ class Mem0MemoryService(MemoryService):
         return [self.transform_message(message) for message in messages]
 
     async def start(self):
-        pass
+        mem0_api_key = os.getenv("MEM0_API_KEY")
+        if mem0_api_key is None:
+            raise ValueError("MEM0_API_KEY is not set")
+        mem0_api_key = os.getenv("MEM0_API_KEY")
+
+        # get the mem0 client instance
+        self.service = AsyncMemoryClient(api_key=mem0_api_key)
+        self._health = True
 
     async def stop(self):
-        pass
+        self.service = None
+        self._health = False
 
     async def health(self):
-        pass
+        return self._health
 
     async def add_memory(
         self,

agentscope_runtime/engine/services/{memory_service.py → memory/memory_service.py}

@@ -5,8 +5,8 @@ from typing import Optional, Dict, Any
 
 from pydantic import Field
 
-from .base import ServiceWithLifecycleManager
-from ..schemas.agent_schemas import MessageType, Message
+from ..base import ServiceWithLifecycleManager
+from ...schemas.agent_schemas import MessageType, Message
 
 
 class MemoryService(ServiceWithLifecycleManager):
@@ -99,20 +99,29 @@ class InMemoryMemoryService(MemoryService):
     An in-memory implementation of the memory service.
     """
 
-    _store: Dict[str, Dict[str, list]] = {}
     _DEFAULT_SESSION_ID = "default"
 
+    def __init__(self) -> None:
+        """Initializes the InMemorySessionHistoryService."""
+        self._store: Optional[Dict[str, Dict[str, list]]] = None
+        self._health = False
+
     async def start(self) -> None:
-        """Starts the service."""
-        self._store = {}
+        """Initialize the in-memory store."""
+        if self._store is None:
+            self._store = {}
+        self._health = True
 
     async def stop(self) -> None:
         """Stops the service."""
-        self._store = {}
+        if self._store is not None:
+            self._store.clear()
+        self._store = None
+        self._health = False
 
     async def health(self) -> bool:
         """Checks the health of the service."""
-        return True
+        return self._health
 
     async def add_memory(
         self,
@@ -129,6 +138,9 @@ class InMemoryMemoryService(MemoryService):
             session_id: An optional session identifier. If not provided,
             a default session is used.
         """
+        if self._store is None:
+            raise RuntimeError("Service not started")
+
         if user_id not in self._store:
             self._store[user_id] = {}
 
@@ -160,6 +172,9 @@ class InMemoryMemoryService(MemoryService):
         Returns:
             A list of matching messages from the store.
         """
+        if self._store is None:
+            raise RuntimeError("Service not started")
+
         if user_id not in self._store:
             return []
 
@@ -231,6 +246,9 @@ class InMemoryMemoryService(MemoryService):
         Returns:
             A paginated list of messages.
         """
+        if self._store is None:
+            raise RuntimeError("Service not started")
+
         if user_id not in self._store:
             return []
 
@@ -260,6 +278,9 @@ class InMemoryMemoryService(MemoryService):
             session_id: If provided, only deletes the messages for that
                 session. Otherwise, deletes all messages for the user.
         """
+        if self._store is None:
+            raise RuntimeError("Service not started")
+
         if user_id not in self._store:
             return
 

agentscope_runtime/engine/services/{redis_memory_service.py → memory/redis_memory_service.py}

@@ -5,7 +5,7 @@ import redis.asyncio as aioredis
 
 
 from .memory_service import MemoryService
-from ..schemas.agent_schemas import Message, MessageType
+from ...schemas.agent_schemas import Message, MessageType
 
 
 class RedisMemoryService(MemoryService):

agentscope_runtime/engine/services/{reme_personal_memory_service.py → memory/reme_personal_memory_service.py}

@@ -2,8 +2,12 @@
 import os
 from typing import Optional, Dict, Any, List
 
+from reme_ai.service.personal_memory_service import (
+    PersonalMemoryService,
+)
+
 from .memory_service import MemoryService
-from ..schemas.agent_schemas import Message
+from ...schemas.agent_schemas import Message
 
 
 class ReMePersonalMemoryService(MemoryService):
@@ -26,10 +30,6 @@ class ReMePersonalMemoryService(MemoryService):
             if os.getenv(key) is None:
                 raise ValueError(f"{key} is not set")
 
-        from reme_ai.service.personal_memory_service import (
-            PersonalMemoryService,
-        )
-
         self.service = PersonalMemoryService()
 
     @staticmethod
@@ -65,7 +65,10 @@ class ReMePersonalMemoryService(MemoryService):
         return await self.service.stop()
 
     async def health(self) -> bool:
-        return await self.service.health()
+        try:
+            return await self.service.health()
+        except Exception:
+            return False
 
     async def add_memory(
         self,

agentscope_runtime/engine/services/{reme_task_memory_service.py → memory/reme_task_memory_service.py}

@@ -1,4 +1,6 @@
 # -*- coding: utf-8 -*-
+from reme_ai.service.task_memory_service import TaskMemoryService
+
 from .reme_personal_memory_service import ReMePersonalMemoryService
 
 
@@ -6,6 +8,4 @@ class ReMeTaskMemoryService(ReMePersonalMemoryService):
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
 
-        from reme_ai.service.task_memory_service import TaskMemoryService
-
         self.service = TaskMemoryService()

agentscope_runtime/engine/services/{tablestore_memory_service.py → memory/tablestore_memory_service.py}

@@ -5,25 +5,19 @@ import copy
 from enum import Enum
 from typing import Any, Dict, List, Optional
 
-try:
-    import tablestore
-    from langchain_community.embeddings import DashScopeEmbeddings
-    from langchain_core.embeddings import Embeddings
-    from tablestore import AsyncOTSClient as AsyncTablestoreClient
-    from tablestore import VectorMetricType
-    from tablestore_for_agent_memory.base.filter import Filters
-    from tablestore_for_agent_memory.knowledge.async_knowledge_store import (
-        AsyncKnowledgeStore,
-    )
-except ImportError as e:
-    raise ImportError(
-        "aliyun_tablestore is not available. "
-        "Please run pip install agentscope-runtime[aliyun_tablestore_ext]",
-    ) from e
-
-from ..schemas.agent_schemas import Message, MessageType
+import tablestore
+from langchain_community.embeddings import DashScopeEmbeddings
+from langchain_core.embeddings import Embeddings
+from tablestore import AsyncOTSClient as AsyncTablestoreClient
+from tablestore import VectorMetricType
+from tablestore_for_agent_memory.base.filter import Filters
+from tablestore_for_agent_memory.knowledge.async_knowledge_store import (
+    AsyncKnowledgeStore,
+)
+
+from ...schemas.agent_schemas import Message, MessageType
 from .memory_service import MemoryService
-from .utils.tablestore_service_utils import (
+from ..utils.tablestore_service_utils import (
     convert_messages_to_tablestore_documents,
     convert_tablestore_document_to_message,
     get_message_metadata_names,

agentscope_runtime/engine/services/sandbox/__init__.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+from typing import TYPE_CHECKING
+from ....common.utils.lazy_loader import install_lazy_loader
+
+if TYPE_CHECKING:
+    from .sandbox_service import SandboxService
+
+install_lazy_loader(
+    globals(),
+    {
+        "SandboxService": ".sandbox_service",
+    },
+)