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

agently/core/TriggerFlow/TriggerFlow.py

@@ -51,6 +51,7 @@ class TriggerFlow:
         self._skip_exceptions = skip_exceptions
         self._executions: dict[str, "TriggerFlowExecution"] = {}
         self._start_process = TriggerFlowProcess(
+            flow_chunk=self.chunk,
             trigger_event="START",
             blue_print=self._blue_print,
             block_data=TriggerFlowBlockData(
@@ -60,6 +61,8 @@ class TriggerFlow:
 
         self.chunks = self._blue_print.chunks
 
+        self.set_settings = self.settings.set_settings
+
         self.get_flow_data = self._flow_data.get
         self.set_flow_data = FunctionShifter.syncify(self.async_set_flow_data)
         self.append_flow_data = FunctionShifter.syncify(self.async_append_flow_data)
@@ -74,10 +77,6 @@ class TriggerFlow:
         self.start_execution = FunctionShifter.syncify(self.async_start_execution)
         self.start = FunctionShifter.syncify(self.async_start)
 
-    def set_settings(self, key: str, value: "SerializableValue"):
-        self.settings.set_settings(key, value)
-        return self
-
     @overload
     def chunk(self, handler_or_name: "TriggerFlowHandler") -> TriggerFlowChunk: ...
 
@@ -100,13 +99,19 @@ class TriggerFlow:
             self._blue_print.chunks[handler_or_name.__name__] = chunk
             return chunk
 
-    def create_execution(self, *, skip_exceptions: bool | None = None):
+    def create_execution(
+        self,
+        *,
+        skip_exceptions: bool | None = None,
+        concurrency: int | None = None,
+    ):
         execution_id = uuid.uuid4().hex
         skip_exceptions = skip_exceptions if skip_exceptions is not None else self._skip_exceptions
         execution = self._blue_print.create_execution(
             self,
             execution_id=execution_id,
             skip_exceptions=skip_exceptions,
+            concurrency=concurrency,
         )
         self._executions[execution_id] = execution
         return execution
@@ -119,8 +124,14 @@ class TriggerFlow:
             if execution.id in self._executions:
                 del self._executions[execution.id]
 
-    async def async_start_execution(self, initial_value: Any, *, wait_for_result: bool = False):
-        execution = self.create_execution()
+    async def async_start_execution(
+        self,
+        initial_value: Any,
+        *,
+        wait_for_result: bool = False,
+        concurrency: int | None = None,
+    ):
+        execution = self.create_execution(concurrency=concurrency)
         await execution.async_start(initial_value, wait_for_result=wait_for_result)
         return execution
 
@@ -193,8 +204,9 @@ class TriggerFlow:
         *,
         wait_for_result: bool = True,
         timeout: int | None = 10,
+        concurrency: int | None = None,
     ):
-        execution = await self.async_start_execution(initial_value)
+        execution = await self.async_start_execution(initial_value, concurrency=concurrency)
         if wait_for_result:
             return await execution.async_get_result(timeout=timeout)
 
@@ -203,8 +215,9 @@ class TriggerFlow:
         initial_value: Any = None,
         *,
         timeout: int | None = 10,
+        concurrency: int | None = None,
     ):
-        execution = self.create_execution()
+        execution = self.create_execution(concurrency=concurrency)
         return execution.get_async_runtime_stream(
             initial_value,
             timeout=timeout,
@@ -215,8 +228,9 @@ class TriggerFlow:
         initial_value: Any = None,
         *,
         timeout: int | None = 10,
+        concurrency: int | None = None,
     ):
-        execution = self.create_execution()
+        execution = self.create_execution(concurrency=concurrency)
         return execution.get_runtime_stream(
             initial_value,
             timeout=timeout,

agently/core/TriggerFlow/process/BaseProcess.py

@@ -14,10 +14,10 @@
 
 
 import uuid
-from asyncio import Event
+from asyncio import Event, Semaphore
 from threading import Lock
 
-from typing import Any, Literal, TYPE_CHECKING, overload
+from typing import Callable, Any, Literal, TYPE_CHECKING, overload, cast
 from typing_extensions import Self
 
 
@@ -31,15 +31,18 @@ from agently.types.trigger_flow import TriggerFlowBlockData
 
 
 class TriggerFlowBaseProcess:
+
     def __init__(
         self,
         *,
+        flow_chunk,
         trigger_event: str,
         blue_print: "TriggerFlowBluePrint",
         block_data: "TriggerFlowBlockData",
         trigger_type: Literal["event", "runtime_data", "flow_data"] = "event",
         **options,
     ):
+        self._flow_chunk = flow_chunk
         self.trigger_event = trigger_event
         self.trigger_type: Literal["event", "runtime_data", "flow_data"] = trigger_type
         self._blue_print = blue_print
@@ -55,6 +58,7 @@ class TriggerFlowBaseProcess:
         **options,
     ):
         return type(self)(
+            flow_chunk=self._flow_chunk,
             trigger_event=trigger_event,
             trigger_type=trigger_type,
             blue_print=blue_print,
@@ -112,8 +116,12 @@ class TriggerFlowBaseProcess:
         if isinstance(trigger_or_triggers, TriggerFlowChunk):
             trigger_or_triggers = trigger_or_triggers.trigger
         if isinstance(trigger_or_triggers, str):
+            if trigger_or_triggers in self._blue_print.chunks:
+                trigger = self._blue_print.chunks[trigger_or_triggers].trigger
+            else:
+                trigger = trigger_or_triggers
             return self._new(
-                trigger_event=trigger_or_triggers,
+                trigger_event=trigger,
                 trigger_type="event",
                 blue_print=self._blue_print,
                 block_data=TriggerFlowBlockData(
@@ -225,9 +233,10 @@ class TriggerFlowBaseProcess:
         elif isinstance(chunk, tuple):
             chunk_name = chunk[0]
             chunk_func = chunk[1]
-            chunk = TriggerFlowChunk(chunk_func, name=chunk_name)
+            chunk = self._flow_chunk(chunk_name)(chunk_func)
         else:
-            chunk = TriggerFlowChunk(chunk, name=name) if callable(chunk) else chunk
+            chunk = self._flow_chunk(name or chunk.__name__)(chunk) if callable(chunk) else chunk
+        assert isinstance(chunk, TriggerFlowChunk)
         self._blue_print.add_handler(
             self.trigger_type,
             self.trigger_event,
@@ -257,11 +266,13 @@ class TriggerFlowBaseProcess:
         self,
         *chunks: "TriggerFlowChunk | TriggerFlowHandler | tuple[str, TriggerFlowHandler]",
         side_branch: bool = False,
+        concurrency: int | None = None,
     ):
         batch_trigger = f"Batch-{ uuid.uuid4().hex }"
         results = {}
         triggers_to_wait = {}
         trigger_to_chunk_name = {}
+        semaphore = Semaphore(concurrency) if concurrency and concurrency > 0 else None
 
         async def wait_all_chunks(data: "TriggerFlowEventData"):
             if data.event in triggers_to_wait:
@@ -280,16 +291,24 @@ class TriggerFlowBaseProcess:
             if isinstance(chunk, tuple):
                 chunk_name = chunk[0]
                 chunk_func = chunk[1]
-                chunk = TriggerFlowChunk(chunk_func, name=chunk_name)
+                chunk = self._flow_chunk(chunk_name)(chunk_func)
             else:
-                chunk = TriggerFlowChunk(chunk) if callable(chunk) else chunk
+                chunk = self._flow_chunk(chunk.__name__)(chunk) if callable(chunk) else 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
+            else:
+                async def handler(data: "TriggerFlowEventData", _chunk=chunk):
+                    async with semaphore:
+                        return await _chunk.async_call(data)
+
             self._blue_print.add_handler(
                 self.trigger_type,
                 self.trigger_event,
-                chunk.async_call,
+                handler,
             )
             self._blue_print.add_event_handler(chunk.trigger, wait_all_chunks)
 

agently/core/TriggerFlow/process/ForEachProcess.py

@@ -22,7 +22,7 @@ from agently.utils import RuntimeDataNamespace
 
 
 class TriggerFlowForEachProcess(TriggerFlowBaseProcess):
-    def for_each(self):
+    def for_each(self, *, concurrency: int | None = None):
         for_each_id = uuid.uuid4().hex
         for_each_block_data = TriggerFlowBlockData(
             outer_block=self._block_data,
@@ -31,6 +31,7 @@ class TriggerFlowForEachProcess(TriggerFlowBaseProcess):
             },
         )
         send_item_trigger = f"ForEach-{ for_each_id }-Send"
+        semaphore = asyncio.Semaphore(concurrency) if concurrency and concurrency > 0 else None
 
         async def send_items(data: "TriggerFlowEventData"):
             data.layer_in()
@@ -38,33 +39,38 @@ class TriggerFlowForEachProcess(TriggerFlowBaseProcess):
             assert for_each_instance_id is not None
 
             send_tasks = []
-            if not isinstance(data.value, str) and isinstance(data.value, Sequence):
-                items = list(data.value)
-                for item in items:
-                    data.layer_in()
-                    item_id = data.layer_mark
-                    assert item_id is not None
-                    data._system_runtime_data.set(f"for_each_results.{ for_each_instance_id }.{ item_id }", EMPTY)
-                    send_tasks.append(
-                        data.async_emit(
-                            send_item_trigger,
-                            item,
-                            data._layer_marks.copy(),
-                        )
-                    )
-                    data.layer_out()
-                await asyncio.gather(*send_tasks)
-            else:
+            def prepare_item(item):
                 data.layer_in()
                 item_id = data.layer_mark
                 assert item_id is not None
+                layer_marks = data._layer_marks.copy()
                 data._system_runtime_data.set(f"for_each_results.{ for_each_instance_id }.{ item_id }", EMPTY)
-                await data.async_emit(
-                    send_item_trigger,
-                    data.value,
-                    data._layer_marks.copy(),
-                )
                 data.layer_out()
+                return item_id, layer_marks, item
+
+            async def emit_item(item, layer_marks):
+                if semaphore is None:
+                    await data.async_emit(
+                        send_item_trigger,
+                        item,
+                        layer_marks,
+                    )
+                else:
+                    async with semaphore:
+                        await data.async_emit(
+                            send_item_trigger,
+                            item,
+                            layer_marks,
+                        )
+            if not isinstance(data.value, str) and isinstance(data.value, Sequence):
+                items = list(data.value)
+                for item in items:
+                    _, layer_marks, item_value = prepare_item(item)
+                    send_tasks.append(emit_item(item_value, layer_marks))
+                await asyncio.gather(*send_tasks)
+            else:
+                _, layer_marks, item_value = prepare_item(data.value)
+                await emit_item(item_value, layer_marks)
 
         self.to(send_items)
 

agently/integrations/chromadb.py

@@ -1,3 +1,18 @@
+# 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 agently.utils import LazyImport
 
 LazyImport.import_package("chromadb")

agently/types/data/response.py

@@ -24,7 +24,16 @@ if TYPE_CHECKING:
     from agently.types.data.serializable import SerializableValue
 
 AgentlyModelResponseEvent = Literal[
-    "error", "original_delta", "delta", "tool_calls", "original_done", "done", "meta", "extra"
+    "error",
+    "original_delta",
+    "reasoning_delta",
+    "delta",
+    "tool_calls",
+    "original_done",
+    "reasoning_done",
+    "done",
+    "meta",
+    "extra",
 ]
 
 AgentlyModelResponseMessage: TypeAlias = tuple[AgentlyModelResponseEvent, Any]

agently/types/plugins/ResponseParser.py

@@ -77,29 +77,39 @@ class ResponseParser(AgentlyPlugin, Protocol):
     def get_async_generator(
         self,
         type: Literal["instant", "streaming_parse"],
+        *,
+        specific: list[str] | str | None = None,
     ) -> AsyncGenerator["StreamingData", None]: ...
 
     @overload
     def get_async_generator(
         self,
         type: Literal["all"],
+        *,
+        specific: list[str] | str | None = None,
     ) -> 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 = None,
     ) -> 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 = None,
     ) -> 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 = None,
     ) -> AsyncGenerator:
         """
         'instant' is Agently v3 compatible for 'streaming_parse'
@@ -110,29 +120,39 @@ class ResponseParser(AgentlyPlugin, Protocol):
     def get_generator(
         self,
         type: Literal["instant", "streaming_parse"],
+        *,
+        specific: list[str] | str | None = None,
     ) -> Generator["StreamingData", None, None]: ...
 
     @overload
     def get_generator(
         self,
         type: Literal["all"],
+        *,
+        specific: list[str] | str | None = None,
     ) -> 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 = None,
     ) -> 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 = None,
     ) -> 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 = None,
     ) -> Generator:
         """
         'instant' is Agently v3 compatible for 'streaming_parse'

agently/utils/DataFormatter.py

@@ -12,12 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import re
 import datetime
 import warnings
 from typing import (
     Any,
     Literal,
     Mapping,
+    Sequence,
     Union,
     get_origin,
     get_args,
@@ -29,9 +31,12 @@ from pydantic import BaseModel
 
 if TYPE_CHECKING:
     from agently.types.data import SerializableValue, KwargsType
+    from re import Pattern
 
 T = TypeVar("T")
 
+DEFAULT_PLACEHOLDER_PATTERN = re.compile(r"\$\{\s*([^}]+?)\s*\}")
+
 
 class DataFormatter:
     @staticmethod
@@ -246,3 +251,75 @@ class DataFormatter:
             return kwargs_format or None
 
         return None
+
+    @staticmethod
+    def substitute_placeholder(
+        obj: T,
+        variable_mappings: dict[str, Any],
+        *,
+        placeholder_pattern: "Pattern | None" = None,
+    ) -> T | Any:
+        if placeholder_pattern is None:
+            placeholder_pattern = DEFAULT_PLACEHOLDER_PATTERN
+
+        if not isinstance(variable_mappings, dict):
+            raise TypeError(f"Variable mappings require a dictionary but got: { variable_mappings }")
+
+        if isinstance(obj, str):
+            full_match = placeholder_pattern.fullmatch(obj)
+            if full_match:
+                key = full_match.group(1).strip()
+                return variable_mappings.get(key, obj)
+            else:
+
+                def replacer(match):
+                    key = match.group(1).strip()
+                    return str(variable_mappings.get(key, match.group(0)))
+
+                return placeholder_pattern.sub(replacer, obj)
+
+        if isinstance(obj, Mapping):
+            return {
+                DataFormatter.substitute_placeholder(
+                    key,
+                    variable_mappings,
+                    placeholder_pattern=placeholder_pattern,
+                ): DataFormatter.substitute_placeholder(
+                    value,
+                    variable_mappings,
+                    placeholder_pattern=placeholder_pattern,
+                )
+                for key, value in obj.items()
+            }
+
+        if isinstance(obj, Sequence) and not isinstance(obj, (str, bytes, bytearray)):
+            if isinstance(obj, tuple):
+                return tuple(
+                    DataFormatter.substitute_placeholder(
+                        value,
+                        variable_mappings,
+                        placeholder_pattern=placeholder_pattern,
+                    )
+                    for value in obj
+                )
+            else:
+                return [
+                    DataFormatter.substitute_placeholder(
+                        value,
+                        variable_mappings,
+                        placeholder_pattern=placeholder_pattern,
+                    )
+                    for value in obj
+                ]
+
+        if isinstance(obj, set):
+            return {
+                DataFormatter.substitute_placeholder(
+                    value,
+                    variable_mappings,
+                    placeholder_pattern=placeholder_pattern,
+                )
+                for value in obj
+            }
+
+        return obj

agently/utils/PythonSandbox.py

@@ -0,0 +1,101 @@
+# 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 types import MappingProxyType
+from typing import Any
+
+SAFE_BUILTINS = {
+    "abs": abs,
+    "min": min,
+    "max": max,
+    "sum": sum,
+    "len": len,
+    "range": range,
+    "enumerate": enumerate,
+    "list": list,
+    "dict": dict,
+    "set": set,
+    "tuple": tuple,
+    "print": print,
+    "sorted": sorted,
+    "str": str,
+    "int": int,
+    "float": float,
+    "list": list,
+    "dict": dict,
+    "bool": bool,
+}
+
+SAFE_TYPES = [int, float, str, list, dict, set, tuple, bool, type(None)]
+
+
+class PythonSandbox:
+    def __init__(
+        self,
+        preset_objects: dict[str, object] | None = None,
+        base_vars: dict[str, Any] | None = None,
+        allowed_return_types: list[type] = SAFE_TYPES,
+    ):
+        self.preset_objects = preset_objects or {}
+        self.base_vars = base_vars or {}
+        self.allowed_return_types = allowed_return_types
+
+        self.safe_globals = MappingProxyType(
+            {
+                "__builtins__": SAFE_BUILTINS,
+                **self.preset_objects,
+                **self.base_vars,
+            }
+        )
+
+    def _check_safe_value(self, value):
+        if isinstance(value, tuple(self.allowed_return_types)):
+            return value
+        raise ValueError(f"Type of return '{ type(value) }' can not be used in Python Sandbox.")
+
+    def _wrap_obj(self, obj):
+        sandbox = self
+
+        class ObjectWrapper:
+            def __init__(self, obj):
+                self._obj = obj
+
+            def __getattr__(self, name):
+                if name.startswith("_"):
+                    raise AttributeError(f"Can not access private attribute '{name}'.")
+                attr = getattr(self._obj, name)
+                if callable(attr):
+
+                    def method(*args, **kwargs):
+                        result = attr(*args, **kwargs)
+                        return sandbox._check_safe_value(result)
+
+                    return method
+                return sandbox._check_safe_value(attr)
+
+        self.allowed_return_types.append(ObjectWrapper)
+
+        return ObjectWrapper(obj)
+
+    def run(self, code: str):
+        safe_objects = {k: self._wrap_obj(v) for k, v in self.preset_objects.items()}
+        globals_dict = dict(self.safe_globals)
+        globals_dict.update(safe_objects)
+
+        local_vars = {}
+        exec(code, globals_dict, local_vars)
+        for k, v in local_vars.items():
+            self._check_safe_value(v)
+        return local_vars

agently/utils/Settings.py

@@ -12,11 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import re
 import json
 import yaml
 import toml
 from typing import TYPE_CHECKING, Literal, cast
-from agently.utils import SerializableRuntimeData, SerializableRuntimeDataNamespace
+from .SerializableRuntimeData import SerializableRuntimeData, SerializableRuntimeDataNamespace
+from .LazyImport import LazyImport
+from .DataFormatter import DataFormatter
 
 if TYPE_CHECKING:
     from agently.types.data import SerializableData, SerializableValue
@@ -114,7 +117,21 @@ class Settings(SerializableRuntimeData):
         else:
             raise TypeError(f"[Agently Settings] Cannot load parsed data, expect dictionary type, got: { type(data) }")
 
-    def set_settings(self, key: str, value: "SerializableValue"):
+    def set_settings(self, key: str, value: "SerializableValue", *, auto_load_env: bool = False):
+        if auto_load_env:
+            import os
+
+            LazyImport.import_package("dotenv")
+            from dotenv import load_dotenv, find_dotenv
+
+            load_dotenv(find_dotenv())
+
+            environ = dict(os.environ)
+            value = DataFormatter.substitute_placeholder(
+                value,
+                environ,
+                placeholder_pattern=re.compile(r"\$\{\s*ENV\.([^}]+?)\s*\}"),
+            )
         if key in self._path_mappings:
             self.update({str(self._path_mappings[key]): value})
             return self

agently/utils/__init__.py

@@ -27,3 +27,4 @@ from .DataLocator import DataLocator
 from .GeneratorConsumer import GeneratorConsumer
 from .StreamingJSONCompleter import StreamingJSONCompleter
 from .StreamingJSONParser import StreamingJSONParser
+from .PythonSandbox import PythonSandbox

{agently-4.0.6.10.dist-info → agently-4.0.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agently
-Version: 4.0.6.10
+Version: 4.0.7
 Summary: 
 License: Apache-2.0
 License-File: LICENSE