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

agently/core/Agent.py

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 import uuid
+import yaml
+import json
 
 from typing import Any, TYPE_CHECKING
 
@@ -64,6 +66,8 @@ class BaseAgent:
         self.request_prompt = self.request.prompt
         self.prompt = self.request_prompt
 
+        self.set_settings = self.settings.set_settings
+
         self.get_response = self.request.get_response
         self.get_result = self.request.get_result
         self.get_meta = self.request.get_meta
@@ -81,17 +85,13 @@ class BaseAgent:
         self.async_start = self.async_get_data
 
     # Basic Methods
-    def set_settings(self, key: str, value: "SerializableValue"):
-        self.settings.set_settings(key, value)
-        return self
-
     def set_agent_prompt(
         self,
         key: "PromptStandardSlot | str",
         value: Any,
         mappings: dict[str, Any] | None = None,
     ):
-        self.prompt.set(key, value, mappings)
+        self.agent_prompt.set(key, value, mappings)
         return self
 
     def set_request_prompt(
@@ -104,7 +104,7 @@ class BaseAgent:
         return self
 
     def remove_agent_prompt(self, key: "PromptStandardSlot | str"):
-        self.prompt.set(key, None)
+        self.agent_prompt.set(key, None)
         return self
 
     def remove_request_prompt(self, key: "PromptStandardSlot | str"):
@@ -112,34 +112,34 @@ class BaseAgent:
         return self
 
     def reset_chat_history(self):
-        if "chat_history" in self.prompt:
-            self.prompt.set("chat_history", [])
+        if "chat_history" in self.agent_prompt:
+            self.agent_prompt.set("chat_history", [])
         return self
 
     def set_chat_history(self, chat_history: "list[dict[str, Any] | ChatMessage]"):
         self.reset_chat_history()
         if not isinstance(chat_history, list):
             chat_history = [chat_history]
-        self.prompt.set("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):
             chat_history = [chat_history]
-        self.prompt.set("chat_history", chat_history)
+        self.agent_prompt.set("chat_history", chat_history)
         return self
 
     def reset_action_results(self):
-        if "action_results" in self.prompt:
-            del self.prompt["action_results"]
+        if "action_results" in self.agent_prompt:
+            del self.agent_prompt["action_results"]
         return self
 
     def set_action_results(self, action_results: list[dict[str, Any]]):
-        self.prompt.set("action_results", action_results)
+        self.agent_prompt.set("action_results", action_results)
         return self
 
     def add_action_results(self, action: str, result: Any):
-        self.prompt.append("action_results", {action: result})
+        self.agent_prompt.append("action_results", {action: result})
         return self
 
     # Quick Prompt
@@ -151,7 +151,7 @@ class BaseAgent:
         always: bool = False,
     ):
         if always:
-            self.prompt.set("input", prompt, mappings)
+            self.agent_prompt.set("input", prompt, mappings)
         else:
             self.request.prompt.set("input", prompt, mappings)
         return self
@@ -164,8 +164,8 @@ class BaseAgent:
         always: bool = False,
     ):
         if always:
-            self.prompt.set("instruct", ["{system.rule} ARE IMPORTANT RULES YOU SHALL FOLLOW!"])
-            self.prompt.set("system.rule", prompt, mappings)
+            self.agent_prompt.set("instruct", ["{system.rule} ARE IMPORTANT RULES YOU SHALL FOLLOW!"])
+            self.agent_prompt.set("system.rule", prompt, mappings)
         else:
             self.request.prompt.set("instruct", ["{system.rule} ARE IMPORTANT RULES YOU SHALL FOLLOW!"])
             self.request.prompt.set("system.rule", prompt, mappings)
@@ -179,8 +179,8 @@ class BaseAgent:
         always: bool = False,
     ):
         if always:
-            self.prompt.set("instruct", ["YOU MUST REACT AND RESPOND AS {system.role}!"])
-            self.prompt.set("system.your_role", prompt, mappings)
+            self.agent_prompt.set("instruct", ["YOU MUST REACT AND RESPOND AS {system.role}!"])
+            self.agent_prompt.set("system.your_role", prompt, mappings)
         else:
             self.request.prompt.set("instruct", ["YOU MUST REACT AND RESPOND AS {system.role}!"])
             self.request.prompt.set("system.your_role", prompt, mappings)
@@ -194,8 +194,8 @@ class BaseAgent:
         always: bool = False,
     ):
         if always:
-            self.prompt.set("instruct", ["{system.user_info} IS IMPORTANT INFORMATION ABOUT USER!"])
-            self.prompt.set("system.user_info", prompt, mappings)
+            self.agent_prompt.set("instruct", ["{system.user_info} IS IMPORTANT INFORMATION ABOUT USER!"])
+            self.agent_prompt.set("system.user_info", prompt, mappings)
         else:
             self.request.prompt.set("instruct", ["{system.user_info} IS IMPORTANT INFORMATION ABOUT USER!"])
             self.request.prompt.set("system.user_info", prompt, mappings)
@@ -209,7 +209,7 @@ class BaseAgent:
         always: bool = False,
     ):
         if always:
-            self.prompt.set("input", prompt, mappings)
+            self.agent_prompt.set("input", prompt, mappings)
         else:
             self.request.prompt.set("input", prompt, mappings)
         return self
@@ -222,7 +222,7 @@ class BaseAgent:
         always: bool = False,
     ):
         if always:
-            self.prompt.set("info", prompt, mappings)
+            self.agent_prompt.set("info", prompt, mappings)
         else:
             self.request.prompt.set("info", prompt, mappings)
         return self
@@ -235,7 +235,7 @@ class BaseAgent:
         always: bool = False,
     ):
         if always:
-            self.prompt.set("instruct", prompt, mappings)
+            self.agent_prompt.set("instruct", prompt, mappings)
         else:
             self.request.prompt.set("instruct", prompt, mappings)
         return self
@@ -248,7 +248,7 @@ class BaseAgent:
         always: bool = False,
     ):
         if always:
-            self.prompt.set("examples", prompt, mappings)
+            self.agent_prompt.set("examples", prompt, mappings)
         else:
             self.request.prompt.set("examples", prompt, mappings)
         return self
@@ -266,11 +266,24 @@ class BaseAgent:
         always: bool = False,
     ):
         if always:
-            self.prompt.set("output", prompt, mappings)
+            self.agent_prompt.set("output", prompt, mappings)
         else:
             self.request.prompt.set("output", prompt, mappings)
         return self
 
+    def attachment(
+        self,
+        prompt: list[dict[str, Any]],
+        mappings: dict[str, Any] | None = None,
+        *,
+        always: bool = False,
+    ):
+        if always:
+            self.agent_prompt.set("attachment", prompt, mappings)
+        else:
+            self.request_prompt.set("attachment", prompt, mappings)
+        return self
+
     def options(
         self,
         options: dict[str, Any],
@@ -278,7 +291,34 @@ class BaseAgent:
         always: bool = False,
     ):
         if always:
-            self.prompt.set("options", options)
+            self.agent_prompt.set("options", options)
         else:
             self.request.prompt.set("options", options)
         return self
+
+    # Prompt
+    def get_prompt_text(self):
+        return self.request_prompt.to_text()[6:][:-11]
+
+    def get_json_prompt(self):
+        prompt_data = {
+            ".agent": self.agent_prompt.to_serializable_prompt_data(),
+            ".request": self.request_prompt.to_serializable_prompt_data(),
+        }
+        return json.dumps(
+            prompt_data,
+            indent=2,
+            ensure_ascii=False,
+        )
+
+    def get_yaml_prompt(self):
+        prompt_data = {
+            ".agent": self.agent_prompt.to_serializable_prompt_data(),
+            ".request": self.request_prompt.to_serializable_prompt_data(),
+        }
+        return yaml.safe_dump(
+            prompt_data,
+            indent=2,
+            allow_unicode=True,
+            sort_keys=False,
+        )

agently/core/ModelRequest.py

@@ -22,12 +22,13 @@ ContentKindTuple: TypeAlias = Literal["all", "delta", "original"]
 ContentKindStreaming: TypeAlias = Literal["instant", "streaming_parse"]
 
 from agently.core import Prompt, ExtensionHandlers
-from agently.utils import Settings, FunctionShifter, DataFormatter
+from agently.utils import Settings, FunctionShifter, DataFormatter, DataLocator
 
 if TYPE_CHECKING:
     from agently.core import PluginManager
     from agently.types.data import AgentlyModelResponseMessage, PromptStandardSlot, StreamingData, SerializableValue
     from agently.types.plugins import ModelRequester, ResponseParser
+    from pydantic import BaseModel
 
 
 class ModelResponseResult:
@@ -39,6 +40,7 @@ class ModelResponseResult:
         response_generator: AsyncGenerator["AgentlyModelResponseMessage", None],
         plugin_manager: "PluginManager",
         settings: Settings,
+        extension_handlers: ExtensionHandlers,
     ):
         self.agent_name = agent_name
         self.plugin_manager = plugin_manager
@@ -50,19 +52,145 @@ class ModelResponseResult:
                 str(self.settings["plugins.ResponseParser.activate"]),
             ),
         )
-        _response_parser = ResponseParser(agent_name, response_id, prompt, response_generator, self.settings)
+        self._response_id = response_id
+        self._extension_handlers = extension_handlers
+        self._response_parser = ResponseParser(agent_name, response_id, prompt, response_generator, self.settings)
         self.prompt = prompt
-        self.full_result_data = _response_parser.full_result_data
-        self.get_meta = _response_parser.get_meta
-        self.async_get_meta = _response_parser.async_get_meta
-        self.get_text = _response_parser.get_text
-        self.async_get_text = _response_parser.async_get_text
-        self.get_data = _response_parser.get_data
-        self.async_get_data = _response_parser.async_get_data
-        self.get_data_object = _response_parser.get_data_object
-        self.async_get_data_object = _response_parser.async_get_data_object
-        self.get_generator = _response_parser.get_generator
-        self.get_async_generator = _response_parser.get_async_generator
+        self.full_result_data = self._response_parser.full_result_data
+        self.get_meta = self._response_parser.get_meta
+        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
+        self.get_async_generator = self._response_parser.get_async_generator
+
+    @overload
+    async def async_get_data(
+        self,
+        *,
+        type: Literal['parsed'],
+        ensure_keys: list[str],
+        key_style: Literal["dot", "slash"] = "dot",
+        max_retries: int = 3,
+        raise_ensure_failure: bool = True,
+        _retry_count: int = 0,
+    ) -> dict[str, Any]: ...
+
+    @overload
+    async def async_get_data(
+        self,
+        *,
+        type: Literal['original', 'parsed', 'all'] = "parsed",
+        ensure_keys: list[str] | None = None,
+        key_style: Literal["dot", "slash"] = "dot",
+        max_retries: int = 3,
+        raise_ensure_failure: bool = True,
+        _retry_count: int = 0,
+    ) -> Any: ...
+
+    async def async_get_data(
+        self,
+        *,
+        type: Literal['original', 'parsed', 'all'] = "parsed",
+        ensure_keys: list[str] | None = None,
+        key_style: Literal["dot", "slash"] = "dot",
+        max_retries: int = 3,
+        raise_ensure_failure: bool = True,
+        _retry_count: int = 0,
+    ) -> Any:
+        if type == "parsed" and ensure_keys:
+            try:
+                data = await self._response_parser.async_get_data(type=type)
+                for ensure_key in ensure_keys:
+                    EMPTY = object()
+                    if DataLocator.locate_path_in_dict(data, ensure_key, key_style, default=EMPTY) is EMPTY:
+                        raise
+                return data
+            except:
+                from agently.base import async_system_message
+
+                await async_system_message(
+                    "MODEL_REQUEST",
+                    {
+                        "agent_name": self.agent_name,
+                        "response_id": self._response_id,
+                        "content": {
+                            "stage": "No Target Data in Response, Preparing Retry",
+                            "detail": f"\n[Response]: { await self.async_get_text() }\n"
+                            f"[Retried Times]: { _retry_count }",
+                        },
+                    },
+                    self.settings,
+                )
+
+                if _retry_count < max_retries:
+                    return await ModelResponse(
+                        self.agent_name,
+                        self.plugin_manager,
+                        self.settings,
+                        self.prompt,
+                        self._extension_handlers,
+                    ).result.async_get_data(
+                        type=type,
+                        ensure_keys=ensure_keys,
+                        key_style=key_style,
+                        max_retries=max_retries,
+                        raise_ensure_failure=raise_ensure_failure,
+                        _retry_count=_retry_count + 1,
+                    )
+                else:
+                    if raise_ensure_failure:
+                        raise ValueError(
+                            f"Can not generate ensure keys { ensure_keys } within { max_retries } retires."
+                        )
+                    else:
+                        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,
+        *,
+        ensure_keys: list[str],
+        key_style: Literal["dot", "slash"] = "dot",
+        max_retries: int = 3,
+        raise_ensure_failure: bool = True,
+    ) -> "BaseModel": ...
+
+    @overload
+    async def async_get_data_object(
+        self,
+        *,
+        ensure_keys: None,
+        key_style: Literal["dot", "slash"] = "dot",
+        max_retries: int = 3,
+        raise_ensure_failure: bool = True,
+    ) -> "BaseModel | None": ...
+
+    async def async_get_data_object(
+        self,
+        *,
+        ensure_keys: list[str] | None = None,
+        key_style: Literal["dot", "slash"] = "dot",
+        max_retries: int = 3,
+        raise_ensure_failure: bool = True,
+    ):
+        if ensure_keys:
+            await self.async_get_data(
+                ensure_keys=ensure_keys,
+                key_style=key_style,
+                max_retries=max_retries,
+                _retry_count=0,
+                raise_ensure_failure=raise_ensure_failure,
+            )
+            return await self._response_parser.async_get_data_object()
+        return await self._response_parser.async_get_data_object()
 
 
 class ModelResponse:
@@ -98,6 +226,7 @@ class ModelResponse:
             self._get_response_generator(),
             self.plugin_manager,
             self.settings,
+            self.extension_handlers,
         )
         self.get_meta = self.result.get_meta
         self.async_get_meta = self.result.async_get_meta
@@ -296,13 +425,15 @@ class ModelRequest:
             parent=parent_extension_handlers,
         )
 
+        self.set_settings = self.settings.set_settings
+
         self.get_meta = FunctionShifter.syncify(self.async_get_meta)
         self.get_text = FunctionShifter.syncify(self.async_get_text)
         self.get_data = FunctionShifter.syncify(self.async_get_data)
         self.get_data_object = FunctionShifter.syncify(self.async_get_data_object)
 
-    def set_settings(self, key: str, value: "SerializableValue"):
-        self.settings.set_settings(key, value)
+        self.start = self.get_data
+        self.async_start = self.async_get_data
 
     def set_prompt(
         self,
@@ -394,6 +525,15 @@ class ModelRequest:
         self.prompt.set("output", prompt, mappings)
         return self
 
+    def attachment(
+        self,
+        prompt: list[dict[str, Any]],
+        mappings: dict[str, Any] | None = None,
+    ):
+        self.prompt.set("attachment", prompt, mappings)
+        return self
+
+    # Response & Result
     def get_response(self):
         response = ModelResponse(
             self.agent_name,
@@ -418,68 +558,118 @@ class ModelRequest:
         self,
         *,
         type: Literal['original', 'parsed', 'all'] = "parsed",
+        ensure_keys: list[str] | None = None,
+        key_style: Literal["dot", "slash"] = "dot",
+        max_retries: int = 3,
+        raise_ensure_failure: bool = True,
     ):
-        return await self.get_response().async_get_data(type=type)
+        response = self.get_response()
+        return await response.async_get_data(
+            type=type,
+            ensure_keys=ensure_keys,
+            key_style=key_style,
+            max_retries=max_retries,
+            raise_ensure_failure=raise_ensure_failure,
+        )
 
-    async def async_get_data_object(self):
-        return await self.get_response().async_get_data_object()
+    async def async_get_data_object(
+        self,
+        *,
+        ensure_keys: list[str] | None = None,
+        key_style: Literal["dot", "slash"] = "dot",
+        max_retries: int = 3,
+        raise_ensure_failure: bool = True,
+    ):
+        response = self.get_response()
+        return await response.async_get_data_object(
+            ensure_keys=ensure_keys,
+            key_style=key_style,
+            max_retries=max_retries,
+            raise_ensure_failure=raise_ensure_failure,
+        )
 
     @overload
     def get_generator(
         self,
         type: Literal["instant", "streaming_parse"],
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> Generator["StreamingData", None, None]: ...
 
     @overload
     def get_generator(
         self,
         type: Literal["all"],
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> Generator[tuple[str, Any], None, None]: ...
 
     @overload
     def get_generator(
         self,
-        type: Literal["delta", "typed_delta", "original"],
+        type: Literal["delta", "specific", "original"],
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> Generator[str, None, None]: ...
 
     @overload
     def get_generator(
         self,
-        type: Literal["all", "original", "delta", "typed_delta", "instant", "streaming_parse"] | None = "delta",
+        type: Literal["all", "original", "delta", "specific", "instant", "streaming_parse"] | None = "delta",
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> Generator: ...
 
     def get_generator(
         self,
-        type: Literal["all", "original", "delta", "typed_delta", "instant", "streaming_parse"] | None = "delta",
+        type: Literal["all", "original", "delta", "specific", "instant", "streaming_parse"] | None = "delta",
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> Generator:
-        return self.get_response().get_generator(type=type)
+        return self.get_response().get_generator(
+            type=type,
+            specific=specific,
+        )
 
     @overload
     def get_async_generator(
         self,
         type: Literal["instant", "streaming_parse"],
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> AsyncGenerator["StreamingData", None]: ...
 
     @overload
     def get_async_generator(
         self,
         type: Literal["all"],
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> AsyncGenerator[tuple[str, Any], None]: ...
 
     @overload
     def get_async_generator(
         self,
-        type: Literal["delta", "typed_delta", "original"],
+        type: Literal["delta", "specific", "original"],
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> AsyncGenerator[str, None]: ...
 
     @overload
     def get_async_generator(
         self,
-        type: Literal["all", "original", "delta", "typed_delta", "instant", "streaming_parse"] | None = "delta",
+        type: Literal["all", "original", "delta", "specific", "instant", "streaming_parse"] | None = "delta",
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> AsyncGenerator: ...
 
     def get_async_generator(
         self,
-        type: Literal["all", "original", "delta", "typed_delta", "instant", "streaming_parse"] | None = "delta",
+        type: Literal["all", "original", "delta", "specific", "instant", "streaming_parse"] | None = "delta",
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> AsyncGenerator:
-        return self.get_response().get_async_generator(type=type)
+        return self.get_response().get_async_generator(
+            type=type,
+            specific=specific,
+        )

agently/core/PluginManager.py

@@ -36,6 +36,8 @@ class PluginManager:
             parent=parent.plugins if parent is not None else None,
         )
 
+        self.set_settings = self.settings.set_settings
+
     def register(
         self,
         plugin_type: AgentlyPluginType,