agently 4.0.6.9__py3-none-any.whl → 4.0.6.11__py3-none-any.whl

agently/base.py

@@ -14,7 +14,7 @@
 
 from typing import Any, Literal, Type, TYPE_CHECKING, TypeVar, Generic, cast
 
-from agently.utils import Settings, create_logger, FunctionShifter
+from agently.utils import Settings, create_logger, FunctionShifter, DataFormatter
 from agently.core import PluginManager, EventCenter, Tool, Prompt, ModelRequest, BaseAgent
 from agently._default_init import _load_default_settings, _load_default_plugins, _hook_default_event_handlers
 
@@ -117,6 +117,8 @@ class AgentlyMain(Generic[A]):
         self.tool = tool
         self.AgentType = AgentType
 
+        self.set_settings = self.settings.set_settings
+
     def set_debug_console(self, debug_console_status: Literal["ON", "OFF"]):
         match debug_console_status:
             case "OFF":
@@ -130,10 +132,6 @@ class AgentlyMain(Generic[A]):
         self.logger.setLevel(log_level)
         return self
 
-    def set_settings(self, key: str, value: "SerializableValue"):
-        self.settings.set_settings(key, value)
-        return self
-
     def create_prompt(self, name: str = "agently_prompt") -> Prompt:
         return Prompt(
             self.plugin_manager,

agently/builtins/agent_extensions/ConfigurePromptExtension.py

@@ -21,6 +21,7 @@ from typing import Any
 from json import JSONDecodeError
 
 from agently.core import BaseAgent
+from agently.utils import DataLocator
 
 
 class ConfigurePromptExtension(BaseAgent):
@@ -168,46 +169,74 @@ class ConfigurePromptExtension(BaseAgent):
                                 variable_mappings,
                             )
 
-    def load_yaml_prompt(self, path_or_content: str, mappings: dict[str, Any] | None = None):
+    def load_yaml_prompt(
+        self,
+        path_or_content: str | Path,
+        mappings: dict[str, Any] | None = None,
+        *,
+        prompt_key_path: str | None = None,
+        encoding: str | None = "utf-8",
+    ):
         path = Path(path_or_content)
         if path.exists() and path.is_file():
             try:
-                with path.open("r", encoding="utf-8") as file:
+                with path.open("r", encoding=encoding) as file:
                     prompt = yaml.safe_load(file)
             except yaml.YAMLError as e:
                 raise ValueError(f"Cannot load YAML file '{ path_or_content }'.\nError: { e }")
         else:
             try:
-                prompt = yaml.safe_load(path_or_content)
+                prompt = yaml.safe_load(str(path_or_content))
             except yaml.YAMLError as e:
                 raise ValueError(f"Cannot load YAML content or file path not existed.\nError: { e }")
+        if not isinstance(prompt, dict):
+            raise TypeError(
+                "Cannot execute YAML prompt configures, expect prompt configures as a dictionary data but got:"
+                f"{ prompt }"
+            )
+        if prompt_key_path is not None:
+            prompt = DataLocator.locate_path_in_dict(prompt, prompt_key_path)
         if isinstance(prompt, dict):
             self._execute_prompt_configure(prompt, mappings)
         else:
             raise TypeError(
-                "Cannot execute YAML prompt configures, expect prompt configures as a dictionary data but got:"
+                f"Cannot execute YAML prompt configures, expect prompt configures{ ' from [' + prompt_key_path + '] ' if prompt_key_path is not None else '' } as a dictionary data but got:"
                 f"{ prompt }"
             )
         return self
 
-    def load_json_prompt(self, path_or_content: str, mappings: dict[str, Any] | None = None):
+    def load_json_prompt(
+        self,
+        path_or_content: str | Path,
+        mappings: dict[str, Any] | None = None,
+        *,
+        prompt_key_path: str | None = None,
+        encoding: str | None = "utf-8",
+    ):
         path = Path(path_or_content)
         if path.exists() and path.is_file():
             try:
-                with path.open("r", encoding="utf-8") as file:
+                with path.open("r", encoding=encoding) as file:
                     prompt = json5.load(file)
             except JSONDecodeError as e:
                 raise ValueError(f"Cannot load JSON file '{ path_or_content }'.\nError: { e }")
         else:
             try:
-                prompt = json5.loads(path_or_content)
-            except yaml.YAMLError as e:
+                prompt = json5.loads(str(path_or_content))
+            except JSONDecodeError as e:
                 raise ValueError(f"Cannot load JSON content or file path not existed.\nError: { e }")
+        if not isinstance(prompt, dict):
+            raise TypeError(
+                "Cannot execute JSON prompt configures, expect prompt configures as a dictionary data but got:"
+                f"{ prompt }"
+            )
+        if prompt_key_path is not None:
+            prompt = DataLocator.locate_path_in_dict(prompt, prompt_key_path)
         if isinstance(prompt, dict):
             self._execute_prompt_configure(prompt, mappings)
         else:
             raise TypeError(
-                "Cannot execute JSON prompt configures, expect prompt configures as a dictionary data but got:"
+                f"Cannot execute JSON prompt configures, expect prompt configures{ ' from [' + prompt_key_path + '] ' if prompt_key_path is not None else '' }as a dictionary data but got:"
                 f"{ prompt }"
             )
         return self

agently/builtins/hookers/SystemMessageHooker.py

@@ -17,6 +17,32 @@ from typing import TYPE_CHECKING
 
 from agently.types.plugins import EventHooker
 
+COLORS = {
+    "black": 30,
+    "red": 31,
+    "green": 32,
+    "yellow": 33,
+    "blue": 34,
+    "magenta": 35,
+    "cyan": 36,
+    "white": 37,
+    "gray": 90,
+}
+
+
+def color_text(text: str, color: str | None = None, bold: bool = False, underline: bool = False) -> str:
+    codes = []
+    if bold:
+        codes.append("1")
+    if underline:
+        codes.append("4")
+    if color and color in COLORS:
+        codes.append(str(COLORS[color]))
+    if not codes:
+        return text
+    return f"\x1b[{';'.join(codes)}m{text}\x1b[0m"
+
+
 if TYPE_CHECKING:
     from agently.types.data import EventMessage, AgentlySystemEvent
 
@@ -72,12 +98,18 @@ class SystemMessageHooker(EventHooker):
                             and SystemMessageHooker._current_meta["row_id"] == message_data["response_id"]
                             and SystemMessageHooker._current_meta["stage"] == content["stage"]
                         ):
-                            print(content["detail"], end="")
+                            print(color_text(content["detail"], color="gray"), end="", flush=True)
                         else:
-                            print(
-                                f"[Agent-{ message_data['agent_name'] }] - [Request-{ message_data['response_id'] }]\nStage: { content['stage'] }\nDetail:\n{ content['detail'] }",
-                                end="",
+                            header = color_text(
+                                f"[Agent-{ message_data['agent_name'] }] - [Request-{ message_data['response_id'] }]",
+                                color="blue",
+                                bold=True,
                             )
+                            stage_label = color_text("Stage:", color="cyan", bold=True)
+                            stage_val = color_text(content["stage"], color="yellow", underline=True)
+                            detail_label = color_text("Detail:\n", color="cyan", bold=True)
+                            detail = color_text(content["detail"], color="green")
+                            print(f"{header}\n{stage_label} {stage_val}\n{detail_label}{detail}", end="")
                             SystemMessageHooker._current_meta["table_name"] = message_data["agent_name"]
                             SystemMessageHooker._current_meta["row_id"] = message_data["response_id"]
                             SystemMessageHooker._current_meta["stage"] = content["stage"]
@@ -99,28 +131,40 @@ class SystemMessageHooker(EventHooker):
                         },
                     )
                     if settings["runtime.show_model_logs"]:
+                        header = color_text(
+                            f"[Agent-{ message_data['agent_name'] }] - [Response-{ message_data['response_id'] }]",
+                            color="blue",
+                            bold=True,
+                        )
+                        stage_label = color_text("Stage:", color="cyan", bold=True)
+                        stage_val = color_text(content["stage"], color="yellow", underline=True)
+                        detail_label = color_text("Detail:\n", color="cyan", bold=True)
+                        detail = color_text(f"{content['detail']}", color="gray")
                         await event_center.async_emit(
                             "log",
                             {
                                 "level": "INFO",
-                                "content": f"[Agent-{ message_data['agent_name'] }] - [Response-{ message_data['response_id'] }]\nStage: { content['stage'] }\nDetail:\n{ content['detail'] }",
+                                "content": f"{header}\n{stage_label} {stage_val}\n{detail_label}{detail}",
                             },
                         )
             case "TOOL":
                 if settings["runtime.show_tool_logs"]:
+                    tool_title = color_text("[Tool Using Result]:", color="blue", bold=True)
+                    tool_body = color_text(str(message.content["data"]), color="gray")
                     await event_center.async_emit(
                         "log",
                         {
                             "level": "INFO",
-                            "content": f"[Tool Using Result]:\n{ message.content['data'] }",
+                            "content": f"{tool_title}\n{tool_body}",
                         },
                     )
             case "TRIGGER_FLOW":
                 if settings["runtime.show_trigger_flow_logs"]:
+                    trigger = color_text(f"[TriggerFlow] { message.content['data'] }", color="yellow", bold=True)
                     await event_center.async_emit(
                         "log",
                         {
                             "level": "INFO",
-                            "content": f"[TriggerFlow] { message.content['data'] }",
+                            "content": trigger,
                         },
                     )

agently/builtins/plugins/ModelRequester/OpenAICompatible.py

@@ -45,6 +45,7 @@ if TYPE_CHECKING:
 class ContentMapping(TypedDict):
     id: str | None
     role: str | None
+    reasoning: str | None
     delta: str | None
     tool_calls: str | None
     done: str | None
@@ -114,6 +115,7 @@ class OpenAICompatible(ModelRequester):
         "content_mapping": {
             "id": "id",
             "role": "choices[0].delta.role",
+            "reasoning": "choices[0].delta.reasoning_content",
             "delta": "choices[0].delta.content",
             "tool_calls": "choices[0].delta.tool_calls",
             "done": None,
@@ -124,6 +126,7 @@ class OpenAICompatible(ModelRequester):
             },
             "extra_done": None,
         },
+        "yield_extra_content_separately": True,
         "content_mapping_style": "dot",
         "timeout": {
             "connect": 30.0,
@@ -146,6 +149,10 @@ class OpenAICompatible(ModelRequester):
         self.model_type = cast(str, self.plugin_settings.get("model_type"))
         self._messenger = event_center.create_messenger(self.name)
 
+        # check if has attachment prompt
+        if self.prompt["attachment"]:
+            self.plugin_settings["rich_content"] = True
+
     @staticmethod
     def _on_register():
         pass
@@ -501,6 +508,7 @@ class OpenAICompatible(ModelRequester):
     async def broadcast_response(self, response_generator: AsyncGenerator) -> "AgentlyResponseGenerator":
         meta = {}
         message_record = {}
+        reasoning_buffer = ""
         content_buffer = ""
 
         content_mapping = cast(
@@ -512,6 +520,7 @@ class OpenAICompatible(ModelRequester):
         )
         id_mapping = content_mapping["id"]
         role_mapping = content_mapping["role"]
+        reasoning_mapping = content_mapping["reasoning"]
         delta_mapping = content_mapping["delta"]
         tool_calls_mapping = content_mapping["tool_calls"]
         done_mapping = content_mapping["done"]
@@ -519,6 +528,7 @@ class OpenAICompatible(ModelRequester):
         finish_reason_mapping = content_mapping["finish_reason"]
         extra_delta_mapping = content_mapping["extra_delta"]
         extra_done_mapping = content_mapping["extra_done"]
+        yield_extra_content_separately = self.plugin_settings.get("yield_extra_content_separately", True)
 
         content_mapping_style = str(self.plugin_settings.get("content_mapping_style"))
         if content_mapping_style not in ("dot", "slash"):
@@ -548,6 +558,15 @@ class OpenAICompatible(ModelRequester):
                     )
                     if role:
                         meta.update({"role": role})
+                if reasoning_mapping:
+                    reasoning = DataLocator.locate_path_in_dict(
+                        loaded_message,
+                        reasoning_mapping,
+                        style=content_mapping_style,
+                    )
+                    if reasoning:
+                        reasoning_buffer += str(reasoning)
+                        yield "reasoning_delta", reasoning
                 if delta_mapping:
                     delta = DataLocator.locate_path_in_dict(
                         loaded_message,
@@ -574,6 +593,8 @@ class OpenAICompatible(ModelRequester):
                         )
                         if extra_value:
                             yield "extra", {extra_key: extra_value}
+                            if yield_extra_content_separately:
+                                yield extra_key, extra_value  # type: ignore
             else:
                 done_content = None
                 if self.model_type == "embeddings" and done_mapping is None:
@@ -589,6 +610,17 @@ class OpenAICompatible(ModelRequester):
                     yield "done", done_content
                 else:
                     yield "done", content_buffer
+                reasoning_content = None
+                if reasoning_mapping:
+                    reasoning_content = DataLocator.locate_path_in_dict(
+                        message_record,
+                        reasoning_mapping,
+                        style=content_mapping_style,
+                    )
+                if reasoning_content:
+                    yield "reasoning_done", reasoning_content
+                else:
+                    yield "reasoning_done", reasoning_buffer
                 match self.model_type:
                     case "embeddings":
                         yield "original_done", message_record

agently/builtins/plugins/PromptGenerator/AgentlyPromptGenerator.py

@@ -725,10 +725,16 @@ class AgentlyPromptGenerator(PromptGenerator):
                             "$type": output_prompt_part[0],
                         }
                     case _:
-                        return {
-                            "$type": output_prompt_part[0],
-                            "$desc": ";".join(output_prompt_part[1:]),
-                        }
+                        desc_text = ";".join([item for item in output_prompt_part[1:] if item])
+                        if desc_text:
+                            return {
+                                "$type": output_prompt_part[0],
+                                "$desc": desc_text,
+                            }
+                        else:
+                            return {
+                                "$type": output_prompt_part[0],
+                            }
             else:
                 return list(output_prompt_part)
 

agently/builtins/plugins/ResponseParser/AgentlyResponseParser.py

@@ -282,8 +282,10 @@ class AgentlyResponseParser(ResponseParser):
 
     async def get_async_generator(
         self,
-        type: Literal['all', 'delta', 'typed_delta', 'original', 'instant', 'streaming_parse'] | None = "delta",
-        content: Literal['all', 'delta', 'typed_delta', 'original', 'instant', 'streaming_parse'] | None = "delta",
+        type: Literal['all', 'delta', 'specific', 'original', 'instant', 'streaming_parse'] | None = "delta",
+        content: Literal['all', 'delta', 'specific', 'original', 'instant', 'streaming_parse'] | None = "delta",
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> AsyncGenerator:
         await self._ensure_consumer()
         parsed_generator = cast(GeneratorConsumer, self._response_consumer).get_async_generator()
@@ -300,11 +302,13 @@ class AgentlyResponseParser(ResponseParser):
                 case "delta":
                     if event == "delta":
                         yield data
-                case "typed_delta":
-                    if event == "delta":
-                        yield "delta", data
-                    elif event == "tool_calls":
-                        yield "tool_calls", data
+                case "specific":
+                    if specific is None:
+                        specific = ["delta"]
+                    elif isinstance(specific, str):
+                        specific = [specific]
+                    if event in specific:
+                        yield event, data
                 case "instant" | "streaming_parse":
                     if self._streaming_json_parser is not None:
                         streaming_parsed = None
@@ -325,8 +329,10 @@ class AgentlyResponseParser(ResponseParser):
 
     def get_generator(
         self,
-        type: Literal['all', 'delta', 'typed_delta', 'original', 'instant', 'streaming_parse'] | None = "delta",
-        content: Literal['all', 'delta', 'typed_delta', 'original', 'instant', 'streaming_parse'] | None = "delta",
+        type: Literal['all', 'delta', 'specific', 'original', 'instant', 'streaming_parse'] | None = "delta",
+        content: Literal['all', 'delta', 'specific', 'original', 'instant', 'streaming_parse'] | None = "delta",
+        *,
+        specific: list[str] | str | None = ["reasoning_delta", "delta", "reasoning_done", "done", "tool_calls"],
     ) -> Generator:
         asyncio.run(self._ensure_consumer())
         parsed_generator = cast(GeneratorConsumer, self._response_consumer).get_generator()
@@ -343,11 +349,13 @@ class AgentlyResponseParser(ResponseParser):
                 case "delta":
                     if event == "delta":
                         yield data
-                case "typed_delta":
-                    if event == "delta":
-                        yield "delta", data
-                    elif event == "tool_calls":
-                        yield "tool_calls", data
+                case "specific":
+                    if specific is None:
+                        specific = ["delta"]
+                    elif isinstance(specific, str):
+                        specific = [specific]
+                    if event in specific:
+                        yield event, data
                 case "instant" | "streaming_parse":
                     if self._streaming_json_parser is not None:
                         streaming_parsed = None

agently/core/Agent.py

@@ -66,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
@@ -83,10 +85,6 @@ 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",
@@ -273,6 +271,19 @@ class BaseAgent:
             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],

agently/core/ModelRequest.py

@@ -425,14 +425,13 @@ 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)
-
     def set_prompt(
         self,
         key: "PromptStandardSlot | str",
@@ -523,6 +522,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,
@@ -581,58 +589,84 @@ class ModelRequest:
     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,