agently 4.0.7__py3-none-any.whl → 4.0.7.2__py3-none-any.whl

agently/builtins/tools/Cmd.py

@@ -0,0 +1,112 @@
+# Copyright 2023-2025 AgentEra(Agently.Tech)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import shlex
+import subprocess
+from pathlib import Path
+from typing import Iterable, Sequence
+
+from agently.types.plugins import BuiltInTool
+
+
+class Cmd(BuiltInTool):
+    def __init__(
+        self,
+        *,
+        allowed_cmd_prefixes: Sequence[str] | None = None,
+        allowed_workdir_roots: Iterable[str | Path] | None = None,
+        timeout: int = 20,
+        env: dict[str, str] | None = None,
+    ):
+        self.tool_info_list = [
+            {
+                "name": "cmd",
+                "desc": "Run a shell command with allowlist checks.",
+                "kwargs": {
+                    "cmd": ("str | list[str]", "Command to run"),
+                    "workdir": ("str | None", "Working directory"),
+                    "allow_unsafe": ("bool", "Allow command outside allowlist"),
+                },
+                "func": self.run,
+            }
+        ]
+
+        self.allowed_cmd_prefixes = set(
+            allowed_cmd_prefixes
+            if allowed_cmd_prefixes is not None
+            else ["ls", "rg", "cat", "pwd", "whoami", "date", "head", "tail"]
+        )
+        roots = allowed_workdir_roots if allowed_workdir_roots is not None else [Path.cwd()]
+        self.allowed_workdir_roots = [Path(root).resolve() for root in roots]
+        self.timeout = timeout
+        self.env = env
+
+    def _normalize_cmd(self, cmd: str | Sequence[str]) -> list[str]:
+        if isinstance(cmd, str):
+            return shlex.split(cmd)
+        return list(cmd)
+
+    def _is_cmd_allowed(self, args: list[str]) -> bool:
+        if not args:
+            return False
+        cmd = args[0]
+        base = Path(cmd).name
+        return base in self.allowed_cmd_prefixes
+
+    def _is_workdir_allowed(self, workdir: str | Path | None) -> bool:
+        workdir_path = Path(workdir or Path.cwd()).resolve()
+        for root in self.allowed_workdir_roots:
+            try:
+                workdir_path.relative_to(root)
+                return True
+            except ValueError:
+                continue
+        return False
+
+    async def run(
+        self,
+        cmd: str | Sequence[str],
+        workdir: str | Path | None = None,
+        allow_unsafe: bool = False,
+    ) -> dict:
+        args = self._normalize_cmd(cmd)
+        if not self._is_workdir_allowed(workdir):
+            return {
+                "ok": False,
+                "need_approval": True,
+                "reason": "workdir_not_allowed",
+                "workdir": str(workdir or Path.cwd()),
+            }
+        if not self._is_cmd_allowed(args) and not allow_unsafe:
+            return {
+                "ok": False,
+                "need_approval": True,
+                "reason": "cmd_not_allowed",
+                "cmd": args,
+            }
+        result = subprocess.run(
+            args,
+            cwd=str(Path(workdir).resolve()) if workdir else None,
+            capture_output=True,
+            text=True,
+            timeout=self.timeout,
+            env=self.env,
+        )
+        return {
+            "ok": result.returncode == 0,
+            "returncode": result.returncode,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+        }

agently/builtins/tools/Search.py

@@ -19,7 +19,6 @@ from agently.utils import LazyImport, FunctionShifter
 
 
 class Search:
-
     def __init__(
         self,
         *,
@@ -103,7 +102,34 @@ class Search:
         ] = "us-en",
         options: dict[str, Any] | None = None,
     ):
-        LazyImport.import_package("ddgs")
+        self.tool_info_list = [
+            {
+                "name": "search",
+                "desc": "Search the web with {query}",
+                "kwargs": {"query": [("str", "search query")]},
+                "func": self.search,
+            },
+            {
+                "name": "search_news",
+                "desc": "Search news with {query}",
+                "kwargs": {"query": [("str", "search query")]},
+                "func": self.search_news,
+            },
+            {
+                "name": "search_wikipedia",
+                "desc": "Search wikipedia with {query}",
+                "kwargs": {"query": [("str", "search query")]},
+                "func": self.search_wikipedia,
+            },
+            {
+                "name": "search_arxiv",
+                "desc": "Search arXiv with {query}",
+                "kwargs": {"query": [("str", "search query")]},
+                "func": self.search_arxiv,
+            },
+        ]
+
+        LazyImport.import_package("ddgs", version_constraint=">=9.10.0")
         from ddgs import DDGS
 
         self.proxy = proxy

agently/builtins/tools/__init__.py

@@ -15,3 +15,4 @@
 
 from .Search import Search
 from .Browse import Browse
+from .Cmd import Cmd

agently/core/Agent.py

@@ -16,7 +16,7 @@ import uuid
 import yaml
 import json
 
-from typing import Any, TYPE_CHECKING
+from typing import Any, Sequence, TYPE_CHECKING
 
 from agently.core import Prompt, ExtensionHandlers, ModelRequest
 from agently.utils import Settings
@@ -116,15 +116,15 @@ class BaseAgent:
             self.agent_prompt.set("chat_history", [])
         return self
 
-    def set_chat_history(self, chat_history: "list[dict[str, Any] | ChatMessage]"):
+    def set_chat_history(self, chat_history: "Sequence[dict[str, Any] | ChatMessage]"):
         self.reset_chat_history()
-        if not isinstance(chat_history, list):
+        if not isinstance(chat_history, Sequence):
             chat_history = [chat_history]
         self.agent_prompt.set("chat_history", chat_history)
         return self
 
-    def add_chat_history(self, chat_history: "list[dict[str, Any] | ChatMessage] | dict[str, Any] | ChatMessage"):
-        if not isinstance(chat_history, list):
+    def add_chat_history(self, chat_history: "Sequence[dict[str, Any] | ChatMessage] | dict[str, Any] | ChatMessage"):
+        if not isinstance(chat_history, Sequence):
             chat_history = [chat_history]
         self.agent_prompt.set("chat_history", chat_history)
         return self
@@ -151,9 +151,9 @@ class BaseAgent:
         always: bool = False,
     ):
         if always:
-            self.agent_prompt.set("input", prompt, mappings)
+            self.agent_prompt.set("system", prompt, mappings)
         else:
-            self.request.prompt.set("input", prompt, mappings)
+            self.request.prompt.set("system", prompt, mappings)
         return self
 
     def rule(

agently/core/ModelRequest.py

@@ -61,10 +61,6 @@ class ModelResponseResult:
         self.async_get_meta = self._response_parser.async_get_meta
         self.get_text = self._response_parser.get_text
         self.async_get_text = self._response_parser.async_get_text
-        # self.get_data = self._response_parser.get_data
-        # self.async_get_data = self._response_parser.async_get_data
-        # self.get_data_object = self._response_parser.get_data_object
-        # self.async_get_data_object = self._response_parser.async_get_data_object
         self.get_data = FunctionShifter.syncify(self.async_get_data)
         self.get_data_object = FunctionShifter.syncify(self.async_get_data_object)
         self.get_generator = self._response_parser.get_generator
@@ -153,6 +149,11 @@ class ModelResponseResult:
                         return await self._response_parser.async_get_data(type=type)
         return await self._response_parser.async_get_data(type=type)
 
+    @overload
+    async def async_get_data_object(
+        self,
+    ) -> "BaseModel | None": ...
+
     @overload
     async def async_get_data_object(
         self,
@@ -467,7 +468,7 @@ class ModelRequest:
         prompt: Any,
         mappings: dict[str, Any] | None = None,
     ):
-        self.prompt.set("system", ["YOU MUST REACT AND RESPOND AS {system.role}!"])
+        self.prompt.set("system", ["YOU MUST REACT AND RESPOND AS {system.your_role}!"])
         self.prompt.set("system.your_role", prompt, mappings)
         return self
 

agently/core/Prompt.py

@@ -161,5 +161,5 @@ class Prompt(RuntimeData):
         else:
             super().append(key, value)
 
-    def get(self, key: "PromptStandardSlot | None" = None, default: T = None, inherit: bool = True) -> Any | T:
+    def get(self, key: "PromptStandardSlot | str | None" = None, default: T = None, inherit: bool = True) -> Any | T:
         return super().get(key, default=default, inherit=inherit)

agently/core/Session.py

@@ -0,0 +1,85 @@
+# Copyright 2023-2025 AgentEra(Agently.Tech)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal, cast
+
+from agently.utils import Settings
+
+if TYPE_CHECKING:
+    from agently.core import PluginManager, BaseAgent
+    from agently.types.plugins import (
+        SessionProtocol,
+        MemoResizePolicyHandler,
+        MemoResizeHandler,
+        AttachmentSummaryHandler,
+        MemoUpdateHandler,
+    )
+
+
+class Session:
+    def __init__(
+        self,
+        *,
+        policy_handler: "MemoResizePolicyHandler | None" = None,
+        resize_handlers: "dict[Literal['lite', 'deep'] | str, MemoResizeHandler] | None" = None,
+        attachment_summary_handler: "AttachmentSummaryHandler | None" = None,
+        memo_update_handler: "MemoUpdateHandler | None" = None,
+        parent_settings: Settings | None = None,
+        agent: "BaseAgent | None" = None,
+        plugin_manager: "PluginManager | None" = None,
+    ):
+        if plugin_manager is None:
+            from agently.base import plugin_manager as global_plugin_manager, settings as global_settings
+
+            plugin_manager = global_plugin_manager
+            if parent_settings is None:
+                parent_settings = global_settings
+
+        if parent_settings is None:
+            parent_settings = Settings(name="Session-Settings")
+
+        session_settings = Settings(
+            name="Session-Settings",
+            parent=parent_settings,
+        )
+        plugin_name = str(session_settings.get("plugins.Session.activate", "AgentlyMemoSession"))
+        SessionPlugin = cast(
+            type["SessionProtocol"],
+            plugin_manager.get_plugin("Session", plugin_name),
+        )
+        impl = SessionPlugin(
+            policy_handler=policy_handler,
+            resize_handlers=resize_handlers,
+            attachment_summary_handler=attachment_summary_handler,
+            memo_update_handler=memo_update_handler,
+            parent_settings=session_settings,
+            agent=agent,
+        )
+        object.__setattr__(self, "_impl", impl)
+        object.__setattr__(self, "settings", impl.settings)
+        object.__setattr__(self, "plugin_manager", plugin_manager)
+
+    def __getattr__(self, name: str):
+        return getattr(self._impl, name)
+
+    def __setattr__(self, name: str, value):
+        if name in {"_impl", "settings", "plugin_manager"}:
+            object.__setattr__(self, name, value)
+            return
+        if "_impl" in self.__dict__ and hasattr(self._impl, name):
+            setattr(self._impl, name, value)
+            return
+        object.__setattr__(self, name, value)

agently/core/TriggerFlow/TriggerFlow.py

@@ -227,7 +227,7 @@ class TriggerFlow:
         self,
         initial_value: Any = None,
         *,
-        timeout: int | None = 10,
+        timeout: float | None = 10.0,
         concurrency: int | None = None,
     ):
         execution = self.create_execution(concurrency=concurrency)

agently/core/TriggerFlow/process/BaseProcess.py

@@ -294,16 +294,20 @@ class TriggerFlowBaseProcess:
                 chunk = self._flow_chunk(chunk_name)(chunk_func)
             else:
                 chunk = self._flow_chunk(chunk.__name__)(chunk) if callable(chunk) else chunk
+            typed_chunk = cast(TriggerFlowChunk, chunk)
             triggers_to_wait[chunk.trigger] = False
             trigger_to_chunk_name[chunk.trigger] = chunk.name
             results[chunk.name] = None
 
             if semaphore is None:
-                handler = chunk.async_call
+                handler = typed_chunk.async_call
             else:
-                async def handler(data: "TriggerFlowEventData", _chunk=chunk):
-                    async with semaphore:
-                        return await _chunk.async_call(data)
+                def make_handler(bound_chunk: TriggerFlowChunk):
+                    async def handler(data: "TriggerFlowEventData"):
+                        async with semaphore:
+                            return await bound_chunk.async_call(data)
+                    return handler
+                handler = make_handler(typed_chunk)
 
             self._blue_print.add_handler(
                 self.trigger_type,

agently/integrations/chromadb.py

@@ -38,7 +38,7 @@ if TYPE_CHECKING:
     )
     from chromadb.api.collection_configuration import CreateCollectionConfiguration
     from chromadb.api import ClientAPI
-    from agently.core import BaseAgent
+    from agently.base import Agent
 
 
 class ChromaDataDictOptional(TypedDict, total=False):
@@ -57,7 +57,7 @@ class ChromaData:
         original_data: ChromaDataDict | list[ChromaDataDict],
         *,
         embedding_function: "Callable[[str | list[str]], Embeddings] | None" = None,
-        agent: "BaseAgent | None" = None,
+        agent: "Agent | None" = None,
     ):
         self._original_data = original_data if isinstance(original_data, list) else [original_data]
         if embedding_function:
@@ -157,7 +157,7 @@ class ChromaEmbeddingFunction(EmbeddingFunction):
     def __init__(
         self,
         *,
-        embedding_agent: "BaseAgent",
+        embedding_agent: "Agent",
     ):
         def embedding_function_by_agent(texts: list[str]) -> "Embeddings":
             return embedding_agent.input(texts).start()
@@ -180,7 +180,7 @@ class ChromaCollection:
         schema: "Schema | None" = None,
         configuration: "CreateCollectionConfiguration | None" = None,
         metadata: dict[str, Any] | None = None,
-        embedding_agent: "BaseAgent | None" = None,
+        embedding_agent: "Agent | None" = None,
         data_loader: "DataLoader[Loadable] | None" = None,
         get_or_create: bool = False,
         hnsw_space: Literal["l2", "cosine", "ip"] = "cosine",

agently/types/data/__init__.py

@@ -36,6 +36,7 @@ EMPTY = AVOID_COPY()
 from .serializable import SerializableData, SerializableValue
 from .prompt import (
     ChatMessage,
+    ChatMessageDict,
     ChatMessageContent,
     TextMessageContent,
     PromptModel,
@@ -71,4 +72,5 @@ from .tool import (
     ReturnType,
     MCPConfig,
     MCPConfigs,
+    ToolInfo,
 )

agently/types/data/prompt.py

@@ -52,8 +52,13 @@ ChatMessageContent = TextMessageContent | AttachmentMessageContent
 ChatMessageContentAdapter = TypeAdapter(Annotated[ChatMessageContent, Field(union_mode="left_to_right")])
 
 
+class ChatMessageDict(TypedDict):
+    role: Literal["system", "developer", "tool", "user", "assistant"] | str
+    content: str | list[dict[str, Any] | ChatMessageContent]
+
+
 class ChatMessage(BaseModel):
-    role: str = "user"
+    role: Literal["system", "developer", "tool", "user", "assistant"] | str = "user"
     content: str | list[dict[str, Any] | ChatMessageContent]
 
     model_config = ConfigDict(extra="allow")

agently/types/data/tool.py

@@ -40,3 +40,12 @@ class MCPConfig(TypedDict):
 
 class MCPConfigs(TypedDict):
     mcpServers: dict[str, MCPConfig]
+
+
+class ToolInfo(TypedDict, total=False):
+    name: str
+    desc: str
+    kwargs: dict[str, Any]
+    func: Callable[..., Any]
+    returns: ReturnType
+    tags: str | list[str]

agently/types/plugins/BuiltInTool.py

@@ -0,0 +1,22 @@
+# Copyright 2023-2025 AgentEra(Agently.Tech)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from typing import Protocol
+
+from agently.types.data import ToolInfo
+
+
+class BuiltInTool(Protocol):
+    tool_info_list: list[ToolInfo]

agently/types/plugins/Session.py

@@ -0,0 +1,159 @@
+# Copyright 2023-2025 AgentEra(Agently.Tech)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from __future__ import annotations
+
+from typing import Any, Literal, Awaitable, Callable, TypeAlias, TYPE_CHECKING, Protocol
+from typing_extensions import TypedDict, NotRequired, Self
+
+if TYPE_CHECKING:
+    from agently.utils import Settings
+    from agently.types.data import SerializableData, ChatMessage
+
+MemoResizeType: TypeAlias = Literal["lite", "deep"] | str
+SessionMode: TypeAlias = Literal["lite", "memo"] | str
+
+
+class SessionLimit(TypedDict, total=False):
+    chars: int
+    messages: int
+
+
+class SessionConfig(TypedDict, total=False):
+    mode: SessionMode
+    limit: SessionLimit
+    every_n_turns: int
+
+
+class MemoResizeDecision(TypedDict):
+    type: MemoResizeType
+    reason: NotRequired[str]
+    severity: NotRequired[int]
+    meta: NotRequired[dict[str, Any]]
+
+
+MemoResizePolicyResult: TypeAlias = "MemoResizeType | MemoResizeDecision | None"
+
+MemoResizePolicyHandler: TypeAlias = (
+    "Callable[[list[ChatMessage], list[ChatMessage], Settings], MemoResizePolicyResult | Awaitable[MemoResizePolicyResult]]"
+)
+
+MemoResizePolicyAsyncHandler: TypeAlias = (
+    "Callable[[list[ChatMessage], list[ChatMessage], Settings], Awaitable[MemoResizePolicyResult]]"
+)
+
+MemoResizeHandlerResult: TypeAlias = "tuple[list[ChatMessage], list[ChatMessage], SerializableData]"
+
+MemoResizeHandler: TypeAlias = (
+    "Callable[[list[ChatMessage], list[ChatMessage], SerializableData, Settings], MemoResizeHandlerResult | Awaitable[MemoResizeHandlerResult]]"
+)
+
+MemoResizeAsyncHandler: TypeAlias = (
+    "Callable[[list[ChatMessage], list[ChatMessage], SerializableData, Settings], Awaitable[MemoResizeHandlerResult]]"
+)
+
+MemoUpdateResult: TypeAlias = "dict[str, Any]"
+MemoUpdateHandler: TypeAlias = (
+    "Callable[[dict[str, Any], list[ChatMessage], list[AttachmentSummary], Settings], MemoUpdateResult | Awaitable[MemoUpdateResult]]"
+)
+MemoUpdateAsyncHandler: TypeAlias = (
+    "Callable[[dict[str, Any], list[ChatMessage], list[AttachmentSummary], Settings], Awaitable[MemoUpdateResult]]"
+)
+
+AttachmentSummary: TypeAlias = "dict[str, Any]"
+AttachmentSummaryHandler: TypeAlias = (
+    "Callable[[ChatMessage], list[AttachmentSummary] | Awaitable[list[AttachmentSummary]]]"
+)
+
+AttachmentSummaryAsyncHandler: TypeAlias = "Callable[[ChatMessage], Awaitable[list[AttachmentSummary]]]"
+
+
+class SessionProtocol(Protocol):
+    id: str
+    settings: "Settings"
+    memo: "SerializableData"
+    full_chat_history: "list[ChatMessage]"
+    current_chat_history: "list[ChatMessage]"
+    set_settings: Callable[..., Any]
+    judge_resize: Callable[..., Any]
+    resize: Callable[..., Any]
+
+    def __init__(
+        self,
+        *,
+        policy_handler: MemoResizePolicyHandler | None = None,
+        resize_handlers: dict[Literal["lite", "deep"] | str, MemoResizeHandler] | None = None,
+        attachment_summary_handler: AttachmentSummaryHandler | None = None,
+        memo_update_handler: MemoUpdateHandler | None = None,
+        parent_settings: "Settings | None" = None,
+        agent: Any | None = None,
+    ): ...
+
+    def configure(
+        self,
+        *,
+        mode: SessionMode | None = None,
+        limit: SessionLimit | None = None,
+        every_n_turns: int | None = None,
+    ) -> Self: ...
+
+    def set_limit(
+        self,
+        *,
+        chars: int | None = None,
+        messages: int | None = None,
+    ) -> Self: ...
+
+    def use_lite(
+        self,
+        *,
+        chars: int | None = None,
+        messages: int | None = None,
+        every_n_turns: int | None = None,
+    ) -> Self: ...
+
+    def use_memo(
+        self,
+        *,
+        chars: int | None = None,
+        messages: int | None = None,
+        every_n_turns: int | None = None,
+    ) -> Self: ...
+
+    def append_message(self, message: "ChatMessage | dict[str, Any]") -> Self: ...
+
+    def set_policy_handler(self, policy_handler: MemoResizePolicyHandler) -> Self: ...
+
+    def set_resize_handlers(
+        self,
+        resize_type: Literal["lite", "deep"] | str,
+        resize_handler: MemoResizeHandler,
+    ) -> Self: ...
+
+    def set_attachment_summary_handler(self, attachment_summary_handler: AttachmentSummaryHandler) -> Self: ...
+
+    def set_memo_update_handler(self, memo_update_handler: MemoUpdateHandler) -> Self: ...
+
+    async def async_judge_resize(self, force: Literal["lite", "deep", False, None] | str = False): ...
+
+    async def async_resize(self, force: Literal["lite", "deep", False, None] | str = False): ...
+
+    def to_json(self) -> str: ...
+
+    def to_yaml(self) -> str: ...
+
+    def load_json(self, value: str) -> Self: ...
+
+    def load_yaml(self, value: str) -> Self: ...

agently/types/plugins/__init__.py

@@ -18,3 +18,24 @@ from .PromptGenerator import PromptGenerator
 from .ModelRequester import ModelRequester
 from .ResponseParser import ResponseParser
 from .ToolManager import ToolManager
+from .BuiltInTool import BuiltInTool
+from .Session import (
+    SessionProtocol,
+    SessionMode,
+    SessionLimit,
+    SessionConfig,
+    MemoResizePolicyHandler,
+    MemoResizePolicyAsyncHandler,
+    MemoResizePolicyResult,
+    MemoResizeHandler,
+    MemoResizeAsyncHandler,
+    MemoResizeHandlerResult,
+    MemoResizeType,
+    MemoResizeDecision,
+    MemoUpdateHandler,
+    MemoUpdateAsyncHandler,
+    MemoUpdateResult,
+    AttachmentSummaryHandler,
+    AttachmentSummaryAsyncHandler,
+    AttachmentSummary,
+)

agently/types/plugins/base.py

@@ -14,7 +14,7 @@
 
 from typing import Any, Literal, Protocol, runtime_checkable
 
-AgentlyPluginType = Literal["PromptGenerator", "ModelRequester", "ResponseParser", "ToolManager"]
+AgentlyPluginType = Literal["PromptGenerator", "ModelRequester", "ResponseParser", "ToolManager", "Session"]
 
 
 @runtime_checkable