agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

ksadk/conversations/__init__.py

@@ -1,95 +1,88 @@
+"""Side-effect-free public exports for conversation preparation and persistence."""
+
 from __future__ import annotations
 
-from ksadk.conversations.context import (
-    CANONICAL_EVENT_TYPES,
-    build_history_from_events,
-    build_request_history,
-    canonical_event_type,
-    compacted_until_seq_id,
-    extract_event_text,
-    extract_text_from_event_parts,
-    group_events_by_api_round,
-    project_model_messages,
-    summarize_event_groups,
-)
-from ksadk.conversations.normalize import (
-    attachment_from_part,
-    attachment_prompt_text,
-    compact_attachment_for_session,
-    decode_inline_data,
-    display_content_from_parts,
-    extract_user_input_from_parts,
-    normalize_kop_message_content,
-    normalize_kop_messages,
-    normalize_parts_content,
-    normalize_responses_input,
-    resolve_attachment_storage_path,
-    resolve_uploads_dir,
-)
-from ksadk.conversations.runtime import (
-    CompactionPlan,
-    PreparedConversationTurn,
-    append_conversation_event,
-    append_context_checkpoint_event,
-    append_reasoning_event,
-    append_run_checkpoint_event,
-    append_run_resume_event,
-    append_run_status_event,
-    build_chat_completions_payload,
-    build_compaction_sse_event,
-    build_responses_payload,
-    build_run_input,
-    compact_conversation_history,
-    ensure_conversation_session,
-    extract_responses_resume_input,
-    invoke_conversation_once,
-    prime_session_metadata_for_user_turn,
-    preview_auto_compaction,
-    stream_conversation_turn,
-    stream_responses_conversation_turn,
-)
+from importlib import import_module
+from typing import Any
+
+
+def _exports(module: str, *names: str) -> dict[str, tuple[str, str]]:
+    return {name: (module, name) for name in names}
+
+
+_EXPORTS = {
+    **_exports(
+        "ksadk.conversations.attachments",
+        "decode_inline_data",
+        "resolve_attachment_storage_path",
+        "resolve_uploads_dir",
+    ),
+    **_exports(
+        "ksadk.conversations.context",
+        "CANONICAL_EVENT_TYPES",
+        "build_history_from_events",
+        "build_request_history",
+        "canonical_event_type",
+        "compacted_until_seq_id",
+        "extract_event_text",
+        "extract_text_from_event_parts",
+        "group_events_by_api_round",
+        "project_model_messages",
+        "summarize_event_groups",
+    ),
+    **_exports(
+        "ksadk.conversations.normalize",
+        "attachment_from_part",
+        "attachment_prompt_text",
+        "compact_attachment_for_session",
+        "display_content_from_parts",
+        "extract_user_input_from_parts",
+        "normalize_kop_message_content",
+        "normalize_kop_messages",
+        "normalize_parts_content",
+        "normalize_responses_input",
+    ),
+    **_exports(
+        "ksadk.conversations.runtime",
+        "CompactionPlan",
+        "PreparedConversationTurn",
+        "append_context_checkpoint_event",
+        "append_conversation_event",
+        "append_reasoning_event",
+        "append_run_checkpoint_event",
+        "append_run_resume_event",
+        "append_run_status_event",
+        "build_chat_completions_payload",
+        "build_compaction_sse_event",
+        "build_responses_payload",
+        "build_run_input",
+        "compact_conversation_history",
+        "ensure_conversation_session",
+        "extract_responses_resume_input",
+        "invoke_conversation_once",
+        "preview_auto_compaction",
+        "prime_session_metadata_for_user_turn",
+        "stream_conversation_turn",
+        "stream_responses_conversation_turn",
+    ),
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    if name == "runtime":
+        value = import_module("ksadk.conversations.runtime")
+        globals()[name] = value
+        return value
+    try:
+        module_name, attribute = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    value = getattr(import_module(module_name), attribute)
+    globals()[name] = value
+    return value
+
 
-__all__ = [
-    "CANONICAL_EVENT_TYPES",
-    "CompactionPlan",
-    "PreparedConversationTurn",
-    "append_conversation_event",
-    "append_context_checkpoint_event",
-    "append_reasoning_event",
-    "append_run_checkpoint_event",
-    "append_run_resume_event",
-    "append_run_status_event",
-    "attachment_from_part",
-    "attachment_prompt_text",
-    "build_chat_completions_payload",
-    "build_compaction_sse_event",
-    "build_history_from_events",
-    "build_request_history",
-    "build_responses_payload",
-    "build_run_input",
-    "canonical_event_type",
-    "compact_conversation_history",
-    "compact_attachment_for_session",
-    "compacted_until_seq_id",
-    "decode_inline_data",
-    "display_content_from_parts",
-    "ensure_conversation_session",
-    "extract_event_text",
-    "extract_text_from_event_parts",
-    "extract_user_input_from_parts",
-    "extract_responses_resume_input",
-    "group_events_by_api_round",
-    "invoke_conversation_once",
-    "prime_session_metadata_for_user_turn",
-    "normalize_kop_message_content",
-    "normalize_kop_messages",
-    "normalize_parts_content",
-    "normalize_responses_input",
-    "preview_auto_compaction",
-    "project_model_messages",
-    "resolve_attachment_storage_path",
-    "resolve_uploads_dir",
-    "stream_conversation_turn",
-    "stream_responses_conversation_turn",
-    "summarize_event_groups",
-]
+def __dir__() -> list[str]:
+    return sorted({*globals(), *__all__})

ksadk/conversations/attachment_storage.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import importlib
 import json
 import logging
 import mimetypes
@@ -81,8 +82,7 @@ def _download_hosted_attachment(file_uri: str) -> AttachmentBytes | None:
         data=content.data,
         display_name=display_name,
         mime_type=(
-            _content_type_without_params(content.content_type)
-            or guess_mime_type(display_name)
+            _content_type_without_params(content.content_type) or guess_mime_type(display_name)
         ),
     )
 
@@ -222,7 +222,9 @@ class AttachmentStorageService:
                     return AttachmentBytes(
                         data=raw,
                         display_name=str(metadata.get("display_name") or local_path.name),
-                        mime_type=str(metadata.get("mime_type") or guess_mime_type(local_path.name)),
+                        mime_type=str(
+                            metadata.get("mime_type") or guess_mime_type(local_path.name)
+                        ),
                         local_path=local_path,
                     )
 
@@ -272,16 +274,17 @@ class AttachmentStorageService:
     async def _read_ks3_object(self, *, bucket: str, object_key: str) -> bytes:
         return await asyncio.to_thread(self._read_ks3_object_sync, bucket, object_key)
 
-    def _put_ks3_object_sync(self, bucket: str, object_key: str, data: bytes, mime_type: str) -> None:
+    def _put_ks3_object_sync(
+        self, bucket: str, object_key: str, data: bytes, mime_type: str
+    ) -> None:
         if not bucket:
             raise ValueError("KS3 bucket is not available")
-        from ks3.connection import Connection
-
         ak = os.getenv("KSYUN_ACCESS_KEY") or os.getenv("KS3_ACCESS_KEY")
         sk = os.getenv("KSYUN_SECRET_KEY") or os.getenv("KS3_SECRET_KEY")
         if not ak or not sk:
             raise ValueError("KS3 credentials are not configured")
-        conn = Connection(ak, sk, host=self._endpoint())
+        connection_class = importlib.import_module("ks3.connection").Connection
+        conn = connection_class(ak, sk, host=self._endpoint())
         ks3_bucket = self._ensure_bucket(conn, bucket)
         key = ks3_bucket.new_key(object_key)
         key.set_contents_from_string(
@@ -292,17 +295,19 @@ class AttachmentStorageService:
     def _read_ks3_object_sync(self, bucket: str, object_key: str) -> bytes:
         if not bucket or not object_key:
             raise FileNotFoundError(object_key)
-        from ks3.connection import Connection
-
         ak = os.getenv("KSYUN_ACCESS_KEY") or os.getenv("KS3_ACCESS_KEY")
         sk = os.getenv("KSYUN_SECRET_KEY") or os.getenv("KS3_SECRET_KEY")
         if not ak or not sk:
             raise ValueError("KS3 credentials are not configured")
-        conn = Connection(ak, sk, host=self._endpoint())
+        connection_class = importlib.import_module("ks3.connection").Connection
+        conn = connection_class(ak, sk, host=self._endpoint())
         key = conn.get_bucket(bucket).get_key(object_key)
         if key is None:
             raise FileNotFoundError(object_key)
-        return key.get_contents_as_string()
+        content = key.get_contents_as_string()
+        if not isinstance(content, bytes):
+            raise TypeError("KS3 object content must be bytes")
+        return content
 
     @staticmethod
     def _ensure_bucket(conn: Any, bucket_name: str):

ksadk/conversations/attachments.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
 import base64
+import importlib
 import io
-import json
 import mimetypes
 import zipfile
 from pathlib import Path, PurePosixPath
@@ -168,7 +168,9 @@ def resolve_attachment_storage_path(file_uri: str) -> Optional[Path]:
     return None
 
 
-def read_attachment_bytes(storage_path: Optional[Path], *, size_limit: Optional[int] = None) -> Optional[bytes]:
+def read_attachment_bytes(
+    storage_path: Optional[Path], *, size_limit: Optional[int] = None
+) -> Optional[bytes]:
     if storage_path is None or not storage_path.is_file():
         return None
 
@@ -272,12 +274,7 @@ def build_attachment_prompt_text(result: Mapping[str, Any]) -> str:
 
     size_bytes = result.get("size_bytes")
     if size_bytes is not None:
-        return (
-            "[上传文件: "
-            f"{display_name}, "
-            f"mime={mime_type}, "
-            f"bytes={size_bytes}]"
-        )
+        return "[上传文件: " f"{display_name}, " f"mime={mime_type}, " f"bytes={size_bytes}]"
 
     return f"[上传文件引用: {display_name}, mime={mime_type}]"
 
@@ -353,9 +350,11 @@ def _build_attachment_result_from_raw(
     if raw is None:
         result["status"] = "partial" if size_bytes else "failed"
         result["warnings"] = [
-            "附件原始内容不可用，当前仅保留元数据摘要。"
-            if size_bytes
-            else "附件内容无法读取，请重新上传或检查文件句柄是否仍可访问。"
+            (
+                "附件原始内容不可用，当前仅保留元数据摘要。"
+                if size_bytes
+                else "附件内容无法读取，请重新上传或检查文件句柄是否仍可访问。"
+            )
         ]
         return result
 
@@ -420,7 +419,9 @@ def _extract_document_attachment(result: dict[str, Any], raw: bytes) -> dict[str
         if text:
             return _with_text(result, text=text, extraction_method=extractor[1])
         result["status"] = "failed"
-        result["warnings"] = [f"{suffix.lstrip('.').upper()} 文档抽取失败，请检查文件是否损坏或重新导出后重试。"]
+        result["warnings"] = [
+            f"{suffix.lstrip('.').upper()} 文档抽取失败，请检查文件是否损坏或重新导出后重试。"
+        ]
         result["extraction_method"] = extractor[1]
         return result
 
@@ -435,7 +436,9 @@ def _extract_document_attachment(result: dict[str, Any], raw: bytes) -> dict[str
 
 
 def _extract_image_attachment(result: dict[str, Any], raw: bytes) -> dict[str, Any]:
-    ocr = perform_ocr(raw, str(result.get("mime_type") or ""), str(result.get("display_name") or ""))
+    ocr = perform_ocr(
+        raw, str(result.get("mime_type") or ""), str(result.get("display_name") or "")
+    )
     result["image"] = {"ocr_engine": ocr.get("engine") or ""}
     if ocr.get("text"):
         return _with_text(result, text=ocr["text"], extraction_method="image_ocr")
@@ -524,9 +527,7 @@ def _extract_archive_attachment(result: dict[str, Any], raw: bytes) -> dict[str,
                 }
             )
             if child_result.get("text"):
-                extracted_chunks.append(
-                    f"[{normalized_path}]\n{child_result['text']}"
-                )
+                extracted_chunks.append(f"[{normalized_path}]\n{child_result['text']}")
 
     result["archive"] = {
         "entries": entries,
@@ -578,9 +579,11 @@ def _load_attachment_bytes(attachment: Mapping[str, Any]) -> Optional[bytes]:
             return None
         return raw if len(raw) <= _MAX_PROCESS_BYTES else None
 
-    raw = read_attachment_uri_bytes(attachment.get("file_uri"), size_limit=_MAX_PROCESS_BYTES)
-    if raw is not None:
-        return raw
+    stored_raw = read_attachment_uri_bytes(
+        attachment.get("file_uri"), size_limit=_MAX_PROCESS_BYTES
+    )
+    if stored_raw is not None:
+        return stored_raw
     return None
 
 
@@ -621,7 +624,11 @@ def _extract_xlsx_text(raw: bytes) -> str:
                 shared_strings = []
 
         rows: list[str] = []
-        for name in sorted(item for item in archive.namelist() if item.startswith("xl/worksheets/") and item.endswith(".xml")):
+        for name in sorted(
+            item
+            for item in archive.namelist()
+            if item.startswith("xl/worksheets/") and item.endswith(".xml")
+        ):
             try:
                 root = ET.fromstring(archive.read(name))
             except Exception:
@@ -648,7 +655,9 @@ def _extract_xlsx_text(raw: bytes) -> str:
                             if isinstance(child.tag, str) and child.tag.endswith("}t")
                         )
                     else:
-                        value_text = next((child.text or "" for child in cell if child.tag.endswith("}v")), "")
+                        value_text = next(
+                            (child.text or "" for child in cell if child.tag.endswith("}v")), ""
+                        )
                     if value_text.strip():
                         values.append(value_text.strip())
                 if values:
@@ -679,17 +688,19 @@ def _extract_xml_text_from_zip(raw: bytes, *, prefixes: tuple[str, ...]) -> str:
     texts: list[str] = []
     with archive:
         for name in sorted(
-            item for item in archive.namelist() if item.endswith(".xml") and item.startswith(prefixes)
+            item
+            for item in archive.namelist()
+            if item.endswith(".xml") and item.startswith(prefixes)
         ):
             try:
                 root = ET.fromstring(archive.read(name))
             except Exception:
                 continue
-            fragment = [
-                node.text.strip()
-                for node in root.iter()
-                if isinstance(node.tag, str) and node.tag.endswith("}t") and (node.text or "").strip()
-            ]
+            fragment = []
+            for node in root.iter():
+                text = node.text or ""
+                if isinstance(node.tag, str) and node.tag.endswith("}t") and text.strip():
+                    fragment.append(text.strip())
             if fragment:
                 texts.append("\n".join(fragment))
     return "\n\n".join(texts)
@@ -710,22 +721,18 @@ def _pdf_text_quality_is_poor(text: str) -> bool:
     normalized = "".join(ch for ch in text if not ch.isspace())
     if len(normalized) < 20:
         return True
-    readable = sum(
-        1
-        for ch in normalized
-        if ch.isalnum() or ("\u4e00" <= ch <= "\u9fff")
-    )
+    readable = sum(1 for ch in normalized if ch.isalnum() or ("\u4e00" <= ch <= "\u9fff"))
     return readable / max(len(normalized), 1) < 0.5
 
 
 def _perform_rapidocr(raw: bytes) -> str:
     try:
-        from rapidocr_onnxruntime import RapidOCR
+        rapidocr_module = importlib.import_module("rapidocr_onnxruntime")
     except Exception:
         return ""
 
     try:
-        engine = RapidOCR()
+        engine = rapidocr_module.RapidOCR()
         result, _ = engine(raw)
     except Exception:
         return ""
@@ -741,7 +748,8 @@ def _perform_rapidocr(raw: bytes) -> str:
 def _perform_tesseract_ocr(raw: bytes) -> str:
     try:
         from PIL import Image
-        import pytesseract
+
+        pytesseract = importlib.import_module("pytesseract")
     except Exception:
         return ""
 
@@ -755,7 +763,7 @@ def _perform_tesseract_ocr(raw: bytes) -> str:
             text = pytesseract.image_to_string(image, lang=lang)
         except Exception:
             continue
-        if text and text.strip():
+        if isinstance(text, str) and text.strip():
             return text.strip()
     return ""
 

ksadk/conversations/compaction_pipeline.py

@@ -87,9 +87,7 @@ def _bool_env(name: str, default: bool) -> bool:
 def candidate_tokens(groups: Sequence[Sequence[SessionEvent]]) -> int:
     """估算 candidate groups 的总 token(用于 pipeline 渐进停止判断)。"""
     return sum(
-        estimate_text_tokens(extract_event_text(event))
-        for group in groups
-        for event in group
+        estimate_text_tokens(extract_event_text(event)) for group in groups for event in group
     )
 
 
@@ -108,12 +106,7 @@ def _tool_signature(event: SessionEvent) -> str | None:
         return None
     content = event.content or {}
     metadata = event.metadata or {}
-    name = str(
-        metadata.get("tool_name")
-        or content.get("name")
-        or content.get("tool_name")
-        or ""
-    )
+    name = str(metadata.get("tool_name") or content.get("name") or content.get("tool_name") or "")
     # 参数优先取 metadata.tool_args(真实 runtime),回退 content.arguments(合成/历史)。
     arguments = (
         metadata.get("tool_args")
@@ -264,8 +257,14 @@ def microcompact_cold_groups(
 
     # 尾部 N 组保留(它们可能还被模型需要),更早的组视为冷组。
     cold_rounds = _microcompact_cold_rounds()
-    cold_groups = list(groups[:-cold_rounds]) if cold_rounds < len(groups) else []
-    tail_groups = list(groups[-cold_rounds:]) if cold_rounds < len(groups) else list(groups)
+    cold_groups = (
+        [list(group) for group in groups[:-cold_rounds]] if cold_rounds < len(groups) else []
+    )
+    tail_groups = (
+        [list(group) for group in groups[-cold_rounds:]]
+        if cold_rounds < len(groups)
+        else [list(group) for group in groups]
+    )
 
     if not cold_groups:
         return MicrocompactResult(
@@ -323,7 +322,8 @@ def build_working_set_metadata(
 ) -> dict[str, Any]:
     """L5 working set 恢复(保守版):只记 metadata,不读文件内容。
 
-    recent_files: 调用方从 workspace_state 取最近 N 个文件的 {path, mtime_ns, size_bytes, read_range}。
+    recent_files: 调用方从 workspace_state 取最近 N 个文件的
+        {path, mtime_ns, size_bytes, read_range}。
     active_tools: 调用方从 describe_agentengine_tools 取 enabled 工具名。
     下一轮 prompt 注入时只提示"这些文件最近读过",不注入内容(避免 token 膨胀)。
     """

ksadk/conversations/compaction_prompt.py

@@ -92,10 +92,12 @@ def build_compaction_prompt_messages(
     不把 prompt 字符串散落到 runtime 编排里。
     """
 
-    groups_text = "\n\n".join(
-        _format_group(group, index=index + 1)
-        for index, group in enumerate(groups_to_compact)
-    ).strip() or "无可压缩内容"
+    groups_text = (
+        "\n\n".join(
+            _format_group(group, index=index + 1) for index, group in enumerate(groups_to_compact)
+        ).strip()
+        or "无可压缩内容"
+    )
     user_prompt = _SUMMARY_USER_PROMPT.format(
         model_metadata=json.dumps(dict(model_metadata or {}), ensure_ascii=False, indent=2),
         previous_summary=previous_summary.strip() or "无",
@@ -115,7 +117,9 @@ def extract_summary_text(response_text: str) -> str:
     if not raw:
         return ""
 
-    summary_match = re.search(r"<summary>\s*(.*?)\s*</summary>", raw, flags=re.DOTALL | re.IGNORECASE)
+    summary_match = re.search(
+        r"<summary>\s*(.*?)\s*</summary>", raw, flags=re.DOTALL | re.IGNORECASE
+    )
     if summary_match:
         return summary_match.group(1).strip()