agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/conversations/message_projection.py

@@ -5,11 +5,11 @@ from typing import Any
 from urllib.parse import quote
 
 from ksadk.agui.a2ui_projection import project_a2ui_operations
-
-
-def _event_metadata(event: Mapping[str, Any]) -> Mapping[str, Any]:
-    metadata = event.get("Metadata")
-    return metadata if isinstance(metadata, Mapping) else {}
+from ksadk.conversations.message_projection_blocks import (
+    _event_metadata,
+    _event_text,
+    _project_interleaved_blocks,
+)
 
 
 def project_session_messages(
@@ -18,6 +18,7 @@ def project_session_messages(
     include_reasoning: bool = False,
     include_tool_events: bool = False,
     include_attachments: bool = True,
+    session_id: str | None = None,
 ) -> list[dict[str, Any]]:
     """Project persisted runtime events into the chat history contract.
 
@@ -53,7 +54,17 @@ def project_session_messages(
                 approval_responses=approval_responses,
             )
         )
-    return sorted(messages, key=lambda item: int(item.get("SeqId") or 0))
+    projected = sorted(messages, key=lambda item: int(item.get("SeqId") or 0))
+    if session_id:
+        for message in projected:
+            for attachment in message.get("Attachments") or []:
+                file_uri = str(attachment.get("file_uri") or "")
+                if file_uri.startswith(("ksadk-upload://", "ae-upload://")):
+                    attachment["url"] = (
+                        "/agentengine/api/v1/AttachmentContent?FileUri="
+                        f"{quote(file_uri, safe='')}&SessionId={quote(str(session_id), safe='')}"
+                    )
+    return projected
 
 
 def _project_event_group(
@@ -119,8 +130,11 @@ def _project_event_group(
             # emit a placeholder assistant message for them first.
             if has_pre_assistant_approvals and not assistant_seen:
                 anchor = next(
-                    (e for e in events
-                     if str(e.get("EventType") or "") == "approval_request"),
+                    (
+                        e for e in events
+                        if str(e.get("EventType") or "")
+                        in {"approval_request", "interaction.requested"}
+                    ),
                     events[0],
                 )
                 placeholder = _base_message(anchor, "assistant", content="")
@@ -139,7 +153,11 @@ def _project_event_group(
             if include_tool_events and post_assistant_tool_events:
                 message["ToolEvents"] = post_assistant_tool_events
             if include_reasoning:
-                blocks = _project_interleaved_blocks(events, tool_events=post_assistant_tool_events)
+                blocks = _project_interleaved_blocks(
+                    events,
+                    tool_events=post_assistant_tool_events,
+                    expected_text=message["Content"]["text"],
+                )
                 if blocks:
                     message["Blocks"] = blocks
             projected.append(message)
@@ -161,6 +179,7 @@ def _project_event_group(
                     "assistant_stream_snapshot",
                     "assistant_stream_delta",
                     "approval_request",
+                    "interaction.requested",
                     "tool_call",
                     "reasoning",
                     "a2ui.surface.begin",
@@ -182,7 +201,11 @@ def _project_event_group(
         if all_tool_events:
             message["ToolEvents"] = all_tool_events
         if include_reasoning:
-            blocks = _project_interleaved_blocks(events, tool_events=all_tool_events)
+            blocks = _project_interleaved_blocks(
+                events,
+                tool_events=all_tool_events,
+                expected_text=message["Content"]["text"],
+            )
             if blocks:
                 message["Blocks"] = blocks
         projected.append(message)
@@ -200,107 +223,6 @@ def _project_event_group(
     return projected
 
 
-def _project_interleaved_blocks(
-    events: Sequence[Mapping[str, Any]],
-    *,
-    tool_events: Sequence[Mapping[str, Any]],
-) -> list[dict[str, Any]]:
-    """Reconstruct ordered chat blocks from persisted streaming events.
-
-    ``assistant_stream_snapshot`` carries a cumulative text value.  The delta
-    relative to the prior snapshot is the text emitted at that point in the
-    event sequence.  Reasoning events written before that snapshot can
-    therefore be replayed as ``thinking → text → thinking → text`` instead of
-    being flattened into the legacy ``Reasoning`` and ``Content`` fields.
-
-    Older transcripts wrote all reasoning only at terminal time.  Their first
-    reasoning event appears after streamed text, so their original boundaries
-    are unknowable.  Return no blocks for those transcripts and let clients
-    use the existing best-effort compatibility projection.
-    """
-
-    blocks: list[dict[str, Any]] = []
-    latest_snapshot_text = ""
-    saw_stream_text = False
-    saw_reasoning_after_stream_text = False
-    tools_by_seq_id = {
-        int(tool.get("SeqId") or 0): tool
-        for tool in tool_events
-        if int(tool.get("SeqId") or 0) > 0
-    }
-
-    def append_text(text: str, seq_id: Any) -> None:
-        if not text:
-            return
-        if blocks and blocks[-1].get("Type") == "text":
-            blocks[-1]["Content"] = f"{blocks[-1].get('Content') or ''}{text}"
-            return
-        blocks.append({"Type": "text", "Content": text, "SeqId": seq_id})
-
-    def append_thinking(text: str, seq_id: Any) -> None:
-        if not text:
-            return
-        if blocks and blocks[-1].get("Type") == "thinking":
-            blocks[-1]["Content"] = f"{blocks[-1].get('Content') or ''}{text}"
-            return
-        blocks.append({"Type": "thinking", "Content": text, "SeqId": seq_id})
-
-    def append_tool(event: Mapping[str, Any]) -> None:
-        tool = tools_by_seq_id.get(int(event.get("SeqId") or 0))
-        if not tool:
-            return
-        blocks.append(
-            {
-                "Type": "tool",
-                "SeqId": tool.get("SeqId"),
-                "Name": tool.get("Name") or "tool",
-                "Args": tool.get("Args"),
-                "Result": tool.get("Result"),
-                "Status": tool.get("Status") or "completed",
-                "ToolCallId": tool.get("ToolCallId"),
-            }
-        )
-
-    for event in events:
-        event_type = str(event.get("EventType") or "")
-        text = _event_text(event)
-        seq_id = event.get("SeqId")
-
-        if event_type == "reasoning":
-            metadata = _event_metadata(event)
-            if saw_stream_text and metadata.get("stream_boundary") != "before_text":
-                saw_reasoning_after_stream_text = True
-            append_thinking(text, seq_id)
-            continue
-        if event_type == "tool_call":
-            append_tool(event)
-            continue
-        if event_type == "assistant_stream_delta":
-            append_text(text, seq_id)
-            saw_stream_text = saw_stream_text or bool(text)
-            continue
-        if event_type == "assistant_stream_snapshot":
-            if text.startswith(latest_snapshot_text):
-                append_text(text[len(latest_snapshot_text) :], seq_id)
-            elif text != latest_snapshot_text:
-                # A replacement snapshot has no safe incremental boundary.
-                # Keep the latest content as a standalone text block instead
-                # of duplicating already-replayed output.
-                append_text(text, seq_id)
-            latest_snapshot_text = text
-            saw_stream_text = saw_stream_text or bool(text)
-            continue
-        if event_type == "assistant_message":
-            if latest_snapshot_text and text.startswith(latest_snapshot_text):
-                append_text(text[len(latest_snapshot_text) :], seq_id)
-            elif not latest_snapshot_text:
-                append_text(text, seq_id)
-
-    if saw_reasoning_after_stream_text:
-        return []
-    return blocks
-
-
 def _base_message(
     event: Mapping[str, Any],
     role: str,
@@ -327,21 +249,6 @@ def _base_message(
     return message
 
 
-def _event_text(event: Mapping[str, Any]) -> str:
-    content = event.get("Content")
-    if isinstance(content, str):
-        return content
-    if not isinstance(content, Mapping):
-        return ""
-    if content.get("text") is not None:
-        return str(content.get("text") or "")
-    return "".join(
-        str(part.get("text") or "")
-        for part in content.get("parts") or []
-        if isinstance(part, Mapping)
-    )
-
-
 def _project_tool_events(
     events: Sequence[Mapping[str, Any]],
     *,
@@ -493,9 +400,7 @@ def _project_approval_events(
                         )
                         if not isinstance(first_action, Mapping):
                             first_action = {}
-                        interaction_id = runtime_event.get("interaction_id") or req.get(
-                            "call_id"
-                        )
+                        interaction_id = runtime_event.get("interaction_id") or req.get("call_id")
                         interrupt_info = {
                             "approval_request_id": interaction_id,
                             "id": interaction_id,
@@ -528,17 +433,11 @@ def _project_approval_events(
         # 这里统一提取，避免 Name fallback 成 "approval" 导致前端显示不对。
         action_requests = interrupt_info.get("action_requests")
         first_action = (
-            action_requests[0]
-            if isinstance(action_requests, list) and action_requests
-            else {}
+            action_requests[0] if isinstance(action_requests, list) and action_requests else {}
         )
         if not isinstance(first_action, Mapping):
             first_action = {}
-        tool_name = (
-            interrupt_info.get("tool_name")
-            or first_action.get("name")
-            or "approval"
-        )
+        tool_name = interrupt_info.get("tool_name") or first_action.get("name") or "approval"
         entry: dict[str, Any] = {
             "SeqId": request.get("SeqId"),
             "Type": "approval",
@@ -559,10 +458,7 @@ def _project_approval_events(
         )
         if arguments is not None:
             entry["Args"] = arguments
-        description = (
-            interrupt_info.get("description")
-            or first_action.get("description")
-        )
+        description = interrupt_info.get("description") or first_action.get("description")
         if description:
             entry["Description"] = str(description)
         review_configs = interrupt_info.get("review_configs")
@@ -721,7 +617,7 @@ def _normalize_canonical_event(
             initial = runtime_event.get("initial") or {}
             parts = initial.get("parts") if isinstance(initial, Mapping) else []
             data: Any = {}
-            for part in (parts or []):
+            for part in parts or []:
                 if isinstance(part, Mapping) and part.get("content_type") == "data":
                     data = part.get("data")
                     break
@@ -821,9 +717,7 @@ def _normalize_canonical_event(
             # 嵌在 action_requests[0] 里，detail 顶层没有，需要提取。
             action_requests = detail.get("action_requests")
             first_action = (
-                action_requests[0]
-                if isinstance(action_requests, list) and action_requests
-                else {}
+                action_requests[0] if isinstance(action_requests, list) and action_requests else {}
             )
             if not isinstance(first_action, Mapping):
                 first_action = {}
@@ -833,20 +727,16 @@ def _normalize_canonical_event(
             normalized_metadata["interrupt_info"] = {
                 "approval_request_id": interaction_id or call_id,
                 "id": interaction_id or call_id,
-                "tool_name": detail.get("tool_name")
-                or first_action.get("name")
-                or kind,
+                "tool_name": detail.get("tool_name") or first_action.get("name") or kind,
                 "arguments": detail.get("arguments")
                 or detail.get("args")
                 or first_action.get("args")
                 or first_action.get("arguments"),
-                "description": detail.get("description")
-                or first_action.get("description"),
+                "description": detail.get("description") or first_action.get("description"),
                 "review_configs": review_configs if isinstance(review_configs, list) else None,
                 "approval_level": detail.get("approval_level")
                 or first_action.get("approval_level"),
-                "approval_message": detail.get("message")
-                or first_action.get("description"),
+                "approval_message": detail.get("message") or first_action.get("description"),
             }
             # Preserve ag-ui protocol tag from source metadata.
             source = runtime_event.get("source") or {}
@@ -906,11 +796,17 @@ def _normalize_runtime_event(
     agui_invocations: set[str],
 ) -> Mapping[str, Any]:
     metadata = _event_metadata(event)
-    is_canonical = metadata.get("ksadk_canonical_runtime_event")
-    if not metadata.get("ksadk_runtime_event") and not is_canonical:
-        return event
     raw_content = event.get("Content")
     content = raw_content if isinstance(raw_content, Mapping) else {}
+    runtime_event = content.get("runtime_event")
+    is_canonical = metadata.get("ksadk_canonical_runtime_event") or (
+        metadata.get("ksadk_session_event_envelope") is True
+        and metadata.get("family") == "runtime"
+        and isinstance(runtime_event, Mapping)
+        and runtime_event.get("schema_version") == 2
+    )
+    if not metadata.get("ksadk_runtime_event") and not is_canonical:
+        return event
     if is_canonical:
         return _normalize_canonical_event(event, content, metadata)
     payload = content.get("payload")

ksadk/conversations/message_projection_blocks.py

@@ -0,0 +1,137 @@
+"""历史消息载荷解析与有序正文块投影。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def _event_metadata(event: Mapping[str, Any]) -> Mapping[str, Any]:
+    metadata = event.get("Metadata")
+    return metadata if isinstance(metadata, Mapping) else {}
+
+
+def _event_text(event: Mapping[str, Any]) -> str:
+    content = event.get("Content")
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, Mapping):
+        return ""
+    if content.get("text") is not None:
+        return str(content.get("text") or "")
+    return "".join(
+        str(part.get("text") or "")
+        for part in content.get("parts") or []
+        if isinstance(part, Mapping)
+    )
+
+
+def _project_interleaved_blocks(
+    events: Sequence[Mapping[str, Any]],
+    *,
+    tool_events: Sequence[Mapping[str, Any]],
+    expected_text: str | None = None,
+) -> list[dict[str, Any]]:
+    """Reconstruct ordered chat blocks from persisted streaming events.
+
+    ``assistant_stream_snapshot`` carries a cumulative text value.  The delta
+    relative to the prior snapshot is the text emitted at that point in the
+    event sequence.  Reasoning events written before that snapshot can
+    therefore be replayed as ``thinking → text → thinking → text`` instead of
+    being flattened into the legacy ``Reasoning`` and ``Content`` fields.
+
+    Older transcripts wrote all reasoning only at terminal time.  Their first
+    reasoning event appears after streamed text, so their original boundaries
+    are unknowable.  Return no blocks for those transcripts and let clients
+    use the existing best-effort compatibility projection.
+    """
+
+    blocks: list[dict[str, Any]] = []
+    latest_snapshot_text = ""
+    saw_stream_text = False
+    saw_reasoning_after_stream_text = False
+    tools_by_seq_id = {
+        int(tool.get("SeqId") or 0): tool for tool in tool_events if int(tool.get("SeqId") or 0) > 0
+    }
+
+    def append_text(text: str, seq_id: Any) -> None:
+        if not text:
+            return
+        if blocks and blocks[-1].get("Type") == "text":
+            blocks[-1]["Content"] = f"{blocks[-1].get('Content') or ''}{text}"
+            return
+        blocks.append({"Type": "text", "Content": text, "SeqId": seq_id})
+
+    def append_thinking(text: str, seq_id: Any) -> None:
+        if not text:
+            return
+        if blocks and blocks[-1].get("Type") == "thinking":
+            blocks[-1]["Content"] = f"{blocks[-1].get('Content') or ''}{text}"
+            return
+        blocks.append({"Type": "thinking", "Content": text, "SeqId": seq_id})
+
+    def append_tool(event: Mapping[str, Any]) -> None:
+        tool = tools_by_seq_id.get(int(event.get("SeqId") or 0))
+        if not tool:
+            return
+        blocks.append(
+            {
+                "Type": "tool",
+                "SeqId": tool.get("SeqId"),
+                "Name": tool.get("Name") or "tool",
+                "Args": tool.get("Args"),
+                "Result": tool.get("Result"),
+                "Status": tool.get("Status") or "completed",
+                "ToolCallId": tool.get("ToolCallId"),
+            }
+        )
+
+    for event in events:
+        event_type = str(event.get("EventType") or "")
+        text = _event_text(event)
+        seq_id = event.get("SeqId")
+
+        if event_type == "reasoning":
+            metadata = _event_metadata(event)
+            if saw_stream_text and metadata.get("stream_boundary") != "before_text":
+                saw_reasoning_after_stream_text = True
+            append_thinking(text, seq_id)
+            continue
+        if event_type == "tool_call":
+            append_tool(event)
+            continue
+        if event_type == "assistant_stream_delta":
+            append_text(text, seq_id)
+            latest_snapshot_text += text
+            saw_stream_text = saw_stream_text or bool(text)
+            continue
+        if event_type == "assistant_stream_snapshot":
+            if text.startswith(latest_snapshot_text):
+                append_text(text[len(latest_snapshot_text) :], seq_id)
+            elif text != latest_snapshot_text:
+                # A replacement snapshot has no safe incremental boundary.
+                # Keep the latest content as a standalone text block instead
+                # of duplicating already-replayed output.
+                append_text(text, seq_id)
+            latest_snapshot_text = text
+            saw_stream_text = saw_stream_text or bool(text)
+            continue
+        if event_type == "assistant_message":
+            if latest_snapshot_text and text.startswith(latest_snapshot_text):
+                append_text(text[len(latest_snapshot_text) :], seq_id)
+            elif not latest_snapshot_text:
+                append_text(text, seq_id)
+
+    if saw_reasoning_after_stream_text:
+        return []
+    # A run can contain multiple message items, and a terminal snapshot can
+    # replace streamed text. Without reliable boundaries, use the existing
+    # Content/Reasoning/ToolEvents projection instead of displaying stale or
+    # whole-run text for one message.
+    if (
+        expected_text is not None
+        and "".join(block["Content"] for block in blocks if block["Type"] == "text")
+        != expected_text
+    ):
+        return []
+    return blocks

ksadk/conversations/model_context.py

@@ -132,7 +132,7 @@ def _extract_input_modalities(raw_model: Mapping[str, Any]) -> list[str]:
     if not isinstance(architecture, Mapping):
         return []
     modalities = architecture.get("input_modalities")
-    if not isinstance(modalities, list):
+    if not isinstance(modalities, (list, tuple)):
         return []
 
     normalized: list[str] = []
@@ -144,11 +144,19 @@ def _extract_input_modalities(raw_model: Mapping[str, Any]) -> list[str]:
 
 
 def supports_native_image_input(model_metadata: Mapping[str, Any] | None) -> bool:
+    """Resolve the locked declaration once; explicit flags precede modalities.
+
+    Canonical capabilities take precedence over the legacy Studio spelling.
+    Unknown names or truthy non-booleans never grant image input. Frozen Build
+    tuples have the same meaning as the discovery payload's JSON arrays.
+    """
     if not isinstance(model_metadata, Mapping):
         return False
     capabilities = model_metadata.get("capabilities")
     if isinstance(capabilities, Mapping) and capabilities.get("multimodal_input_image") is not None:
-        return bool(capabilities.get("multimodal_input_image"))
+        return capabilities.get("multimodal_input_image") is True
+    if model_metadata.get("supports_image_input") is not None:
+        return model_metadata.get("supports_image_input") is True
     return "image" in _extract_input_modalities(model_metadata)
 
 
@@ -387,9 +395,9 @@ def normalize_model_metadata(raw_model: Mapping[str, Any] | str | None) -> dict[
         **dict(base.get("capabilities") or {}),
     }
     if input_modalities:
-        capabilities["multimodal_input_image"] = "image" in input_modalities
         capabilities["multimodal_input_video"] = "video" in input_modalities
         capabilities["multimodal_input_file"] = "file" in input_modalities
+    capabilities["multimodal_input_image"] = supports_native_image_input(base)
     limits = {
         **DEFAULT_MODEL_LIMITS,
         **dict(base.get("limits") or {}),

ksadk/conversations/normalize.py

@@ -290,7 +290,9 @@ def compact_attachment_for_session(attachment: Dict[str, Any]) -> Dict[str, Any]
     }
 
 
-def attachment_from_part(part: Part) -> Optional[Dict[str, Any]]:
+def attachment_from_part(
+    part: Part, *, owner_scope_ref: str | None = None
+) -> Optional[Dict[str, Any]]:
     inline = part.inlineData
     if inline and inline.data:
         display_name = inline.displayName or "uploaded_file"
@@ -312,7 +314,9 @@ def attachment_from_part(part: Part) -> Optional[Dict[str, Any]]:
     if file_data and (file_data.fileUri or file_data.displayName):
         display_name = file_data.displayName or file_data.fileUri or "uploaded_file"
         mime_type = (file_data.mimeType or "").strip() or "application/octet-stream"
-        storage_path = resolve_attachment_storage_path(file_data.fileUri or "")
+        storage_path = resolve_attachment_storage_path(
+            file_data.fileUri or "", owner_scope_ref=owner_scope_ref
+        )
         try:
             size_bytes = (
                 storage_path.stat().st_size if storage_path and storage_path.exists() else None
@@ -357,9 +361,15 @@ def display_content_from_parts(parts: List[Part]) -> str:
     return "\n\n".join(blocks).strip()
 
 
-def normalize_parts_content(parts: List[Part]) -> dict[str, Any]:
+def normalize_parts_content(
+    parts: List[Part], *, owner_scope_ref: str | None = None
+) -> dict[str, Any]:
     attachments = [
-        attachment for attachment in (attachment_from_part(part) for part in parts) if attachment
+        attachment
+        for attachment in (
+            attachment_from_part(part, owner_scope_ref=owner_scope_ref) for part in parts
+        )
+        if attachment
     ]
     attachment_results = build_attachment_results(attachments)
     display_content = display_content_from_parts(parts)
@@ -383,7 +393,9 @@ def normalize_parts_content(parts: List[Part]) -> dict[str, Any]:
     }
 
 
-def normalize_kop_message_content(content: Any) -> dict[str, Any]:
+def normalize_kop_message_content(
+    content: Any, *, owner_scope_ref: str | None = None
+) -> dict[str, Any]:
     input_content = canonical_input_content_from_message_content(content)
     if isinstance(content, list):
         parts: List[Part] = []
@@ -397,7 +409,7 @@ def normalize_kop_message_content(content: Any) -> dict[str, Any]:
                 parts.append(Part.model_validate(payload))
             except Exception:
                 continue
-        normalized = normalize_parts_content(parts)
+        normalized = normalize_parts_content(parts, owner_scope_ref=owner_scope_ref)
         normalized["input_content"] = input_content
         return normalized
     text = str(content or "")
@@ -411,11 +423,15 @@ def normalize_kop_message_content(content: Any) -> dict[str, Any]:
     }
 
 
-def normalize_kop_messages(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+def normalize_kop_messages(
+    messages: List[Dict[str, Any]], *, owner_scope_ref: str | None = None
+) -> List[Dict[str, Any]]:
     normalized: List[Dict[str, Any]] = []
     for message in messages or []:
         role = str(message.get("role") or "user")
-        normalized_content = normalize_kop_message_content(message.get("content", ""))
+        normalized_content = normalize_kop_message_content(
+            message.get("content", ""), owner_scope_ref=owner_scope_ref
+        )
         normalized.append(
             {
                 "role": role,
@@ -430,7 +446,9 @@ def normalize_kop_messages(messages: List[Dict[str, Any]]) -> List[Dict[str, Any
     return normalized
 
 
-def normalize_responses_input(input_payload: Any) -> List[Dict[str, Any]]:
+def normalize_responses_input(
+    input_payload: Any, *, owner_scope_ref: str | None = None
+) -> List[Dict[str, Any]]:
     if isinstance(input_payload, str):
         return [
             {
@@ -446,5 +464,5 @@ def normalize_responses_input(input_payload: Any) -> List[Dict[str, Any]]:
             }
         ]
     if isinstance(input_payload, list):
-        return normalize_kop_messages(input_payload)
+        return normalize_kop_messages(input_payload, owner_scope_ref=owner_scope_ref)
     return []