agently 4.0.7.1__py3-none-any.whl → 4.0.7.3__py3-none-any.whl

agently/types/plugins/Session.py

@@ -0,0 +1,169 @@
+# Copyright 2023-2025 AgentEra(Agently.Tech)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from __future__ import annotations
+
+from typing import Any, Literal, Awaitable, Callable, TypeAlias, TYPE_CHECKING, Protocol
+from typing_extensions import TypedDict, NotRequired, Self
+
+if TYPE_CHECKING:
+    from agently.utils import Settings
+    from agently.types.data import SerializableData, SerializableValue, ChatMessage, ChatMessageDict
+
+MemoResizeType: TypeAlias = Literal["lite", "deep"] | str
+SessionMode: TypeAlias = Literal["lite", "memo"] | str
+ResizeForce: TypeAlias = Literal["lite", "deep", False, None] | str
+
+
+class SessionLimit(TypedDict, total=False):
+    chars: int
+    messages: int
+
+
+class SessionConfig(TypedDict, total=False):
+    mode: SessionMode
+    limit: SessionLimit
+    every_n_turns: int
+
+
+class MemoResizeDecision(TypedDict):
+    type: MemoResizeType
+    reason: NotRequired[str]
+    severity: NotRequired[int]
+    meta: NotRequired[dict[str, Any]]
+
+
+MemoResizePolicyResult: TypeAlias = "MemoResizeType | MemoResizeDecision | None"
+
+MemoResizePolicyHandler: TypeAlias = (
+    "Callable[[list[ChatMessage], list[ChatMessage], Settings], MemoResizePolicyResult | Awaitable[MemoResizePolicyResult]]"
+)
+
+MemoResizePolicyAsyncHandler: TypeAlias = (
+    "Callable[[list[ChatMessage], list[ChatMessage], Settings], Awaitable[MemoResizePolicyResult]]"
+)
+
+MemoResizeHandlerResult: TypeAlias = "tuple[list[ChatMessage], list[ChatMessage], SerializableData]"
+
+MemoResizeHandler: TypeAlias = (
+    "Callable[[list[ChatMessage], list[ChatMessage], SerializableData, Settings], MemoResizeHandlerResult | Awaitable[MemoResizeHandlerResult]]"
+)
+
+MemoResizeAsyncHandler: TypeAlias = (
+    "Callable[[list[ChatMessage], list[ChatMessage], SerializableData, Settings], Awaitable[MemoResizeHandlerResult]]"
+)
+
+MemoUpdateResult: TypeAlias = "dict[str, Any]"
+MemoUpdateHandler: TypeAlias = (
+    "Callable[[dict[str, Any], list[ChatMessage], list[AttachmentSummary], Settings], MemoUpdateResult | Awaitable[MemoUpdateResult]]"
+)
+MemoUpdateAsyncHandler: TypeAlias = (
+    "Callable[[dict[str, Any], list[ChatMessage], list[AttachmentSummary], Settings], Awaitable[MemoUpdateResult]]"
+)
+
+AttachmentSummary: TypeAlias = "dict[str, Any]"
+AttachmentSummaryHandler: TypeAlias = (
+    "Callable[[ChatMessage], list[AttachmentSummary] | Awaitable[list[AttachmentSummary]]]"
+)
+
+AttachmentSummaryAsyncHandler: TypeAlias = "Callable[[ChatMessage], Awaitable[list[AttachmentSummary]]]"
+
+
+class SessionProtocol(Protocol):
+    id: str
+    settings: "Settings"
+    memo: "SerializableData"
+    full_chat_history: "list[ChatMessage]"
+    current_chat_history: "list[ChatMessage]"
+
+    def __init__(
+        self,
+        *,
+        policy_handler: MemoResizePolicyHandler | None = None,
+        resize_handlers: dict[MemoResizeType, MemoResizeHandler] | None = None,
+        attachment_summary_handler: AttachmentSummaryHandler | None = None,
+        memo_update_handler: MemoUpdateHandler | None = None,
+        parent_settings: "Settings | None" = None,
+        agent: Any | None = None,
+    ): ...
+
+    def configure(
+        self,
+        *,
+        mode: SessionMode | None = None,
+        limit: SessionLimit | None = None,
+        every_n_turns: int | None = None,
+    ) -> Self: ...
+
+    def set_limit(
+        self,
+        *,
+        chars: int | None = None,
+        messages: int | None = None,
+    ) -> Self: ...
+
+    def use_lite(
+        self,
+        *,
+        chars: int | None = None,
+        messages: int | None = None,
+        every_n_turns: int | None = None,
+    ) -> Self: ...
+
+    def use_memo(
+        self,
+        *,
+        chars: int | None = None,
+        messages: int | None = None,
+        every_n_turns: int | None = None,
+    ) -> Self: ...
+
+    def append_message(self, message: "ChatMessage | ChatMessageDict") -> Self: ...
+
+    def set_settings(
+        self,
+        key: str,
+        value: "SerializableValue",
+        *,
+        auto_load_env: bool = False,
+    ) -> "Settings": ...
+
+    def judge_resize(self, force: ResizeForce = False) -> "MemoResizeDecision | None": ...
+
+    def resize(self, force: ResizeForce = False) -> "list[ChatMessage]": ...
+
+    def set_policy_handler(self, policy_handler: MemoResizePolicyHandler) -> Self: ...
+
+    def set_resize_handlers(
+        self,
+        resize_type: MemoResizeType,
+        resize_handler: MemoResizeHandler,
+    ) -> Self: ...
+
+    def set_attachment_summary_handler(self, attachment_summary_handler: AttachmentSummaryHandler) -> Self: ...
+
+    def set_memo_update_handler(self, memo_update_handler: MemoUpdateHandler) -> Self: ...
+
+    async def async_judge_resize(self, force: ResizeForce = False) -> "MemoResizeDecision | None": ...
+
+    async def async_resize(self, force: ResizeForce = False) -> "list[ChatMessage]": ...
+
+    def to_json(self) -> str: ...
+
+    def to_yaml(self) -> str: ...
+
+    def load_json(self, value: str) -> Self: ...
+
+    def load_yaml(self, value: str) -> Self: ...

agently/types/plugins/__init__.py

@@ -18,3 +18,24 @@ from .PromptGenerator import PromptGenerator
 from .ModelRequester import ModelRequester
 from .ResponseParser import ResponseParser
 from .ToolManager import ToolManager
+from .BuiltInTool import BuiltInTool
+from .Session import (
+    SessionProtocol,
+    SessionMode,
+    SessionLimit,
+    SessionConfig,
+    MemoResizePolicyHandler,
+    MemoResizePolicyAsyncHandler,
+    MemoResizePolicyResult,
+    MemoResizeHandler,
+    MemoResizeAsyncHandler,
+    MemoResizeHandlerResult,
+    MemoResizeType,
+    MemoResizeDecision,
+    MemoUpdateHandler,
+    MemoUpdateAsyncHandler,
+    MemoUpdateResult,
+    AttachmentSummaryHandler,
+    AttachmentSummaryAsyncHandler,
+    AttachmentSummary,
+)

agently/types/plugins/base.py

@@ -14,7 +14,7 @@
 
 from typing import Any, Literal, Protocol, runtime_checkable
 
-AgentlyPluginType = Literal["PromptGenerator", "ModelRequester", "ResponseParser", "ToolManager"]
+AgentlyPluginType = Literal["PromptGenerator", "ModelRequester", "ResponseParser", "ToolManager", "Session"]
 
 
 @runtime_checkable

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

@@ -242,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 = (
@@ -253,6 +255,8 @@ class DataFormatter:
                         else ""
                     )
                     kwargs_format["<*>"] = (additional_type, additional_desc)
+                else:
+                    kwargs_format["<*>"] = (Any, "")
 
             return kwargs_format or None
 

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