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

agently/utils/AGENT_UTILS_GUIDE.md

@@ -0,0 +1,175 @@
+# Agently Utils Guide (Agent-Readable)
+
+Use this as a compact, agent-oriented guide to the utilities in `agently/utils`. It is intentionally brief and practical.
+
+## Quick Map (TL;DR)
+- data shaping: `DataFormatter`, `RuntimeData`, `SerializableRuntimeData`, `Settings`
+- path and JSON helpers: `DataLocator`, `DataPathBuilder`, `StreamingJSONCompleter`, `StreamingJSONParser`
+- async/sync bridging: `FunctionShifter`, `GeneratorConsumer`
+- dynamic deps: `LazyImport`
+- storage: `Storage`, `AsyncStorage`
+- misc: `Logger`, `Messenger`, `PythonSandbox`
+- legacy: `old_RuntimeData` (avoid unless you must keep backward behavior)
+
+## Utilities
+
+### DataFormatter
+Purpose: normalize complex values into safe, serializable, or string forms, and do placeholder substitution.
+
+Key methods:
+- `sanitize(value, remain_type=False)`: convert complex objects into JSON-ish values. Handles `datetime`, `RuntimeData`, `pydantic.BaseModel`, and typing constructs like `list[T]`, `Union`, `Literal`.
+- `to_str_key_dict(value, value_format=None, default_key=None, default_value=None)`: ensure dict keys are strings and values optionally sanitized or stringified. If input is not a dict, can wrap with `default_key`.
+- `from_schema_to_kwargs_format(schema)`: convert JSON Schema object fields into Agently kwargs-style `(type, desc)` mapping.
+- `substitute_placeholder(obj, variable_mappings, placeholder_pattern=None)`: recursive replace `${key}` placeholders in strings, dicts, lists, sets, tuples.
+
+When to use:
+- Before logging/serialization.
+- When building structured prompts from schemas.
+- When injecting env variables into settings or prompts.
+
+### DataLocator
+Purpose: locate values by path, and extract JSON blocks from mixed text.
+
+Key methods:
+- `locate_path_in_dict(dict, path, style="dot"|"slash", default=None)`: safe deep lookup with `a.b[0]` or `/a/b/0` styles.
+- `locate_all_json(text)`: scan text and return all JSON-like blocks.
+- `locate_output_json(text, output_prompt_dict)`: pick the most likely JSON block matching your output schema.
+
+When to use:
+- Parsing LLM responses that mix text + JSON.
+- Robust extraction for streaming parsers.
+
+### DataPathBuilder
+Purpose: convert and reason about dot/slash paths, and extract expected parsing paths from a schema-like dict.
+
+Key methods:
+- `build_dot_path(keys)`, `build_slash_path(keys)`
+- `convert_dot_to_slash(dot_path)`, `convert_slash_to_dot(slash_path)`
+- `extract_possible_paths(schema, style="dot")`: find all possible paths.
+- `extract_parsing_key_orders(schema, style="dot")`: paths in definition order (used by streaming parser).
+- `get_value_by_path(data, path, style="dot")`: retrieve values, supports `[*]` wildcard expansion.
+
+When to use:
+- Streaming JSON parsing with ordered fields.
+- Mapping UI updates to schema paths.
+
+### FunctionShifter
+Purpose: bridge sync/async code and run async work safely from sync contexts.
+
+Key methods:
+- `syncify(func)`: wrap an async function so it can be called in sync code. Uses `asyncio.run` or a thread when a loop is running.
+- `asyncify(func)`: wrap a sync function so it can be awaited via `asyncio.to_thread`.
+- `future(func)`: return a `Future` for the function execution; ensures there is a loop.
+- `syncify_async_generator(async_gen)`: consume an async generator from sync code via a background thread.
+- `auto_options_func(func)`: drop extra kwargs that the function does not accept.
+
+When to use:
+- Tool functions that may be sync or async.
+- Adapters between streaming generators and sync APIs.
+
+### GeneratorConsumer
+Purpose: fan out a generator or async generator to multiple consumers, replay history, and handle errors.
+
+Usage:
+- Wrap a generator, then call `get_async_generator()` for multiple async consumers or `get_generator()` for sync.
+- `get_result()` waits for completion and returns full history.
+- `close()` cancels and notifies listeners.
+
+When to use:
+- Broadcast streaming output to multiple subscribers.
+- Merge history + live updates reliably.
+
+### LazyImport
+Purpose: import optional deps and optionally auto-install via pip with version constraints.
+
+Key methods:
+- `from_import(from_package, target_modules, auto_install=True, version_constraint=None, install_name=None)`
+- `import_package(package_name, auto_install=True, version_constraint=None, install_name=None)`
+
+Notes:
+- This prompts for installation in interactive use; plan for non-interactive runtime accordingly.
+
+### Logger
+Purpose: create a consistent logger with optional uvicorn integration.
+
+Key pieces:
+- `create_logger(app_name="Agently", log_level="INFO")` returns `AgentlyLogger` with `raise_error` helper.
+
+### Messenger
+Purpose: convenience wrapper for event center messaging.
+
+Key method:
+- `create_messenger(module_name)` delegates to `agently.base.event_center`.
+
+### PythonSandbox
+Purpose: execute small snippets safely with restricted builtins and whitelisted return types.
+
+Key behaviors:
+- `run(code)` executes in a sandbox; raises if a return type is not in `allowed_return_types`.
+- `preset_objects` are wrapped to block private attributes and enforce safe return types.
+
+When to use:
+- Run short user-defined expressions or filters with safety checks.
+
+### RuntimeData / RuntimeDataNamespace
+Purpose: runtime-scoped hierarchical data with inheritance, dot-path access, and merge-friendly set semantics.
+
+Key behaviors:
+- `get(key, default=None, inherit=True)`: inherited view by default.
+- `set` and `__setitem__` merge dict/list/set values rather than replace (unless you use `cover=True` internally).
+- dot-path access: `data["a.b.c"]`.
+- `namespace("path")` returns a namespace view.
+- `dump("json"|"yaml"|"toml")`, `load(...)` support.
+
+When to use:
+- Store workflow state, memo, runtime configs.
+
+### SerializableRuntimeData / SerializableRuntimeDataNamespace
+Purpose: same API as `RuntimeData` but value types restricted to JSON-serializable shapes.
+
+When to use:
+- Settings and serialized runtime state.
+
+### Settings / SettingsNamespace
+Purpose: settings with mapping shortcuts and env substitution.
+
+Key behaviors:
+- `register_path_mappings("short", "actual.path")`: alias keys.
+- `register_kv_mappings("key", "value", actual_settings)`: map a key+value to a settings dict.
+- `set_settings(key, value, auto_load_env=False)`: apply mappings and optionally expand `${ENV.X}`.
+
+When to use:
+- Global or per-agent configuration with shortcuts.
+
+### Storage / AsyncStorage
+Purpose: simple SQLModel-based persistence with sync/async APIs.
+
+Key behaviors:
+- requires `sqlmodel`, `sqlalchemy`, `aiosqlite` via `LazyImport`.
+- `set(obj|list)` merges into DB.
+- `get(model, where=..., first=False, limit=..., offset=..., order_by=...)`.
+- `create_tables()` calls `SQLModel.metadata.create_all`.
+
+When to use:
+- local state persistence for agents or tools.
+
+### StreamingJSONCompleter
+Purpose: complete partial JSON strings by closing open strings, comments, or brackets.
+
+Key method:
+- `append(data)` then `complete()` to get best-effort JSON.
+
+When to use:
+- streaming LLM output where JSON is partial.
+
+### StreamingJSONParser
+Purpose: parse streaming JSON and emit incremental updates (`delta`) and completion events (`done`).
+
+Key behaviors:
+- Uses `DataLocator` + `StreamingJSONCompleter` to find and parse JSON in noisy streams.
+- Tracks schema order via `DataPathBuilder.extract_parsing_key_orders`.
+- `parse_chunk(chunk)` yields `StreamingData` events.
+- `parse_stream(chunk_stream)` yields events and finalizes at end.
+
+When to use:
+- UI streaming updates for structured output.

agently/utils/DataFormatter.py

@@ -56,15 +56,21 @@ class DataFormatter:
             if issubclass(value, BaseModel):
                 extracted_value = {}
                 for name, field in value.model_fields.items():
+                    annotation = field.annotation
+                    if hasattr(field, "rebuild_annotation"):
+                        try:
+                            annotation = field.rebuild_annotation()
+                        except Exception:
+                            annotation = field.annotation
                     extracted_value.update(
                         {
                             name: (
                                 (
-                                    DataFormatter.sanitize(field.annotation, remain_type=remain_type),
+                                    DataFormatter.sanitize(annotation, remain_type=remain_type),
                                     field.description,
                                 )
                                 if field.description
-                                else (DataFormatter.sanitize(field.annotation, remain_type=remain_type),)
+                                else (DataFormatter.sanitize(annotation, remain_type=remain_type),)
                             )
                         }
                     )
@@ -236,9 +242,11 @@ class DataFormatter:
 
             if "additionalProperties" in input_schema:
                 additional_properties = input_schema["additionalProperties"]
-                if additional_properties is True or additional_properties is None:
+                if additional_properties is False:
+                    pass
+                elif additional_properties is True or additional_properties is None:
                     kwargs_format["<*>"] = (Any, "")
-                else:
+                elif isinstance(additional_properties, dict):
                     additional_type = additional_properties.pop("type", Any)
                     additional_properties.pop("title", None)
                     additional_desc = (
@@ -247,6 +255,8 @@ class DataFormatter:
                         else ""
                     )
                     kwargs_format["<*>"] = (additional_type, additional_desc)
+                else:
+                    kwargs_format["<*>"] = (Any, "")
 
             return kwargs_format or None
 

agently/utils/DataLocator.py

@@ -21,6 +21,101 @@ if TYPE_CHECKING:
 
 
 class DataLocator:
+    @staticmethod
+    def _locate_path_parts(
+        result: Any,
+        path_parts: list[str],
+        *,
+        style: Literal["dot", "slash"],
+        default: Any,
+    ):
+        if not path_parts:
+            return result
+        path_part = path_parts[0]
+        remaining = path_parts[1:]
+        if style == "dot":
+            if "[" in path_part:
+                path_key_and_index = path_part.split("[")
+                path_key = path_key_and_index[0]
+                path_index = path_key_and_index[1][:-1]
+                if isinstance(result, Mapping):
+                    result = result.get(path_key, default)
+                else:
+                    return default
+                if path_index in ("*", ""):
+                    if not isinstance(result, str) and isinstance(result, Sequence):
+                        values = []
+                        for item in result:
+                            value = DataLocator._locate_path_parts(
+                                item,
+                                remaining,
+                                style=style,
+                                default=default,
+                            )
+                            if value is default:
+                                return default
+                            values.append(value)
+                        return values
+                    return default
+                try:
+                    index = int(path_index)
+                except Exception:
+                    return default
+                if not isinstance(result, str) and isinstance(result, Sequence):
+                    try:
+                        return DataLocator._locate_path_parts(
+                            result[index],
+                            remaining,
+                            style=style,
+                            default=default,
+                        )
+                    except Exception:
+                        return default
+                return default
+            else:
+                if isinstance(result, Mapping):
+                    return DataLocator._locate_path_parts(
+                        result.get(path_part, default),
+                        remaining,
+                        style=style,
+                        default=default,
+                    )
+                return default
+        else:
+            if path_part == "*":
+                if not isinstance(result, str) and isinstance(result, Sequence):
+                    values = []
+                    for item in result:
+                        value = DataLocator._locate_path_parts(
+                            item,
+                            remaining,
+                            style=style,
+                            default=default,
+                        )
+                        if value is default:
+                            return default
+                        values.append(value)
+                    return values
+                return default
+            if isinstance(result, Mapping):
+                return DataLocator._locate_path_parts(
+                    result.get(path_part, default),
+                    remaining,
+                    style=style,
+                    default=default,
+                )
+            if not isinstance(result, str) and isinstance(result, Sequence):
+                try:
+                    return DataLocator._locate_path_parts(
+                        result[int(path_part)],
+                        remaining,
+                        style=style,
+                        default=default,
+                    )
+                except Exception:
+                    return default
+            return default
+
     @staticmethod
     def locate_path_in_dict(
         original_dict: dict,
@@ -34,42 +129,24 @@ class DataLocator:
         match style:
             case "dot":
                 try:
-                    result = original_dict
                     path_parts = path.split(".")
-                    for path_part in path_parts:
-                        if "[" in path_part:
-                            path_key_and_index = path_part.split("[")
-                            path_key = path_key_and_index[0]
-                            path_index = int(path_key_and_index[1][:-1])
-                            if isinstance(result, Mapping):
-                                result = result[path_key]
-                            else:
-                                return default
-                            if not isinstance(result, str) and isinstance(result, Sequence):
-                                result = result[path_index]
-                            else:
-                                return default
-                        else:
-                            if isinstance(result, Mapping):
-                                result = result[path_part]
-                            else:
-                                return default
-                    return result
+                    return DataLocator._locate_path_parts(
+                        original_dict,
+                        path_parts,
+                        style="dot",
+                        default=default,
+                    )
                 except Exception:
                     return default
             case "slash":
-                result = original_dict
-                path_parts = path.split("/")
                 try:
-                    for path_part in path_parts:
-                        if path_part:
-                            if isinstance(result, Mapping):
-                                result = result[path_part]
-                            elif not isinstance(result, str) and isinstance(result, Sequence):
-                                result = result[int(path_part)]
-                            else:
-                                return default
-                    return result
+                    path_parts = [part for part in path.split("/") if part]
+                    return DataLocator._locate_path_parts(
+                        original_dict,
+                        path_parts,
+                        style="slash",
+                        default=default,
+                    )
                 except Exception:
                     return default
 

agently/utils/FunctionShifter.py

@@ -76,8 +76,9 @@ class FunctionShifter:
 
         @wraps(func)
         async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
-            assert inspect.isfunction(func)
-            return await asyncio.to_thread(func, *args, **kwargs)
+            if not callable(func):
+                raise TypeError(f"Expected a callable, got {type(func)}")
+            return await asyncio.to_thread(func, *args, **kwargs)  # type: ignore
 
         return wrapper
 

agently/utils/TimeInfo.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 datetime import datetime
+
+
+class TimeInfo:
+    @staticmethod
+    def get_current_time():
+        return datetime.now().strftime("%Y-%m-%d %H:%M:%S %A")

agently/utils/__init__.py

@@ -28,3 +28,4 @@ from .GeneratorConsumer import GeneratorConsumer
 from .StreamingJSONCompleter import StreamingJSONCompleter
 from .StreamingJSONParser import StreamingJSONParser
 from .PythonSandbox import PythonSandbox
+from .TimeInfo import TimeInfo