agently 4.0.7.1__py3-none-any.whl → 4.0.7.3__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,6 +102,33 @@ class Search:
         ] = "us-en",
         options: dict[str, Any] | None = None,
     ):
+        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
 

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

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,218 @@
+# 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,
+        SessionMode,
+        SessionLimit,
+        MemoResizeDecision,
+        MemoResizeType,
+        MemoResizePolicyHandler,
+        MemoResizeHandler,
+        AttachmentSummaryHandler,
+        MemoUpdateHandler,
+    )
+    from agently.types.data import ChatMessage, ChatMessageDict, SerializableValue, SerializableData
+
+
+class Session:
+    _impl: "SessionProtocol"
+    settings: Settings
+    plugin_manager: "PluginManager"
+    id: str
+    memo: "SerializableData"
+    full_chat_history: "list[ChatMessage]"
+    current_chat_history: "list[ChatMessage]"
+
+    def __init__(
+        self,
+        *,
+        policy_handler: "MemoResizePolicyHandler | None" = None,
+        resize_handlers: "dict[MemoResizeType, 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 configure(
+        self,
+        *,
+        mode: "SessionMode | None" = None,
+        limit: "SessionLimit | None" = None,
+        every_n_turns: int | None = None,
+    ) -> "Session":
+        self._impl.configure(
+            mode=mode,
+            limit=limit,
+            every_n_turns=every_n_turns,
+        )
+        return self
+
+    def set_limit(
+        self,
+        *,
+        chars: int | None = None,
+        messages: int | None = None,
+    ) -> "Session":
+        self._impl.set_limit(chars=chars, messages=messages)
+        return self
+
+    def use_lite(
+        self,
+        *,
+        chars: int | None = None,
+        messages: int | None = None,
+        every_n_turns: int | None = None,
+    ) -> "Session":
+        self._impl.use_lite(chars=chars, messages=messages, every_n_turns=every_n_turns)
+        return self
+
+    def use_memo(
+        self,
+        *,
+        chars: int | None = None,
+        messages: int | None = None,
+        every_n_turns: int | None = None,
+    ) -> "Session":
+        self._impl.use_memo(chars=chars, messages=messages, every_n_turns=every_n_turns)
+        return self
+
+    def append_message(self, message: "ChatMessage | ChatMessageDict") -> "Session":
+        self._impl.append_message(message)
+        return self
+
+    def set_settings(
+        self,
+        key: str,
+        value: "SerializableValue",
+        *,
+        auto_load_env: bool = False,
+    ) -> Settings:
+        return self._impl.set_settings(key, value, auto_load_env=auto_load_env)
+
+    def set_policy_handler(self, policy_handler: "MemoResizePolicyHandler") -> "Session":
+        self._impl.set_policy_handler(policy_handler)
+        return self
+
+    def set_resize_handlers(
+        self,
+        resize_type: "MemoResizeType",
+        resize_handler: "MemoResizeHandler",
+    ) -> "Session":
+        self._impl.set_resize_handlers(resize_type, resize_handler)
+        return self
+
+    def set_attachment_summary_handler(
+        self,
+        attachment_summary_handler: "AttachmentSummaryHandler",
+    ) -> "Session":
+        self._impl.set_attachment_summary_handler(attachment_summary_handler)
+        return self
+
+    def set_memo_update_handler(
+        self,
+        memo_update_handler: "MemoUpdateHandler",
+    ) -> "Session":
+        self._impl.set_memo_update_handler(memo_update_handler)
+        return self
+
+    def judge_resize(
+        self,
+        force: "Literal['lite', 'deep', False, None] | str" = False,
+    ) -> "MemoResizeDecision | None":
+        return self._impl.judge_resize(force=force)
+
+    def resize(
+        self,
+        force: "Literal['lite', 'deep', False, None] | str" = False,
+    ) -> "list[ChatMessage]":
+        return self._impl.resize(force=force)
+
+    async def async_judge_resize(
+        self,
+        force: "Literal['lite', 'deep', False, None] | str" = False,
+    ) -> "MemoResizeDecision | None":
+        return await self._impl.async_judge_resize(force=force)
+
+    async def async_resize(
+        self,
+        force: "Literal['lite', 'deep', False, None] | str" = False,
+    ) -> "list[ChatMessage]":
+        return await self._impl.async_resize(force=force)
+
+    def to_json(self) -> str:
+        return self._impl.to_json()
+
+    def to_yaml(self) -> str:
+        return self._impl.to_yaml()
+
+    def load_json(self, value: str) -> "Session":
+        self._impl.load_json(value)
+        return self
+
+    def load_yaml(self, value: str) -> "Session":
+        self._impl.load_yaml(value)
+        return self
+
+    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/__init__.py

@@ -25,6 +25,7 @@ from .TriggerFlow import (
     TriggerFlowExecution,
     TriggerFlowChunk,
 )
+from .Session import Session
 
 # from .TriggerFlow_old import (
 #     TriggerFlow,

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]