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

ksadk/conversations/context.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, Iterable, List
+
+from ksadk.sessions.base import SessionEvent
+
+CANONICAL_EVENT_TYPES = {
+    "user_message",
+    "assistant_message",
+    "tool_call",
+    "tool_result",
+    "approval_request",
+    "approval_response",
+    "attachment_ref",
+    "reasoning",
+    "run_status",
+    "run_checkpoint",
+    "run_resume",
+    "context_checkpoint",
+    "compaction_boundary",
+}
+
+TRANSCRIPT_EVENT_TYPES = {
+    "user_message",
+    "assistant_message",
+    "tool_call",
+    "tool_result",
+    "approval_request",
+    "approval_response",
+    "attachment_ref",
+    "context_checkpoint",
+}
+
+DATA_URL_RE = re.compile(
+    r"data:(?P<mime>[A-Za-z0-9.+-]+/[A-Za-z0-9.+-]+);base64,[A-Za-z0-9+/=_-]+"
+)
+BASE64_FIELD_RE = re.compile(
+    r"(?P<prefix>['\"](?P<field>file_data|data|bytes|base64)['\"]\s*:\s*['\"])(?P<value>[A-Za-z0-9+/=_-]{512,})(?P<suffix>['\"])",
+    re.IGNORECASE,
+)
+
+
+def sanitize_event_text_for_context(text: Any) -> str:
+    """Return a compact text view for history/compaction without inline binaries."""
+    value = str(text or "")
+    if not value:
+        return ""
+
+    def _replace_data_url(match: re.Match[str]) -> str:
+        mime = match.group("mime")
+        media_type = "image" if mime.startswith("image/") else "file"
+        return f"[{media_type}: {mime} data-url omitted]"
+
+    value = DATA_URL_RE.sub(_replace_data_url, value)
+    value = BASE64_FIELD_RE.sub(
+        lambda match: (
+            f"{match.group('prefix')}[base64 {match.group('field')} omitted]"
+            f"{match.group('suffix')}"
+        ),
+        value,
+    )
+    return value
+
+
+def extract_event_text(event: SessionEvent) -> str:
+    """从结构化事件里提取最适合喂给模型的文本视图。
+
+    这里优先取 `agent_input`，因为它通常比展示给 UI 的 display text 更接近
+    真实 prompt；如果没有，再退回到 parts/text。
+    """
+    metadata = event.metadata or {}
+    if metadata.get("agent_input"):
+        return sanitize_event_text_for_context(metadata["agent_input"])
+
+    content = event.content or {}
+    text = content.get("text")
+    if text:
+        return sanitize_event_text_for_context(text)
+
+    return sanitize_event_text_for_context(extract_text_from_event_parts(content.get("parts") or []))
+
+
+def canonical_event_type(
+    event_type: str | None,
+    *,
+    author: str = "",
+    role: str = "",
+) -> str:
+    raw = str(event_type or "").strip().lower()
+    if raw in CANONICAL_EVENT_TYPES:
+        return raw
+    if raw in {"tool_use", "function_call"}:
+        return "tool_call"
+    if raw in {"tool_response", "function_response"}:
+        return "tool_result"
+    if raw in {"approval", "interrupt"}:
+        return "approval_request"
+    if raw in {"attachment", "file_ref", "file_reference"}:
+        return "attachment_ref"
+    if raw in {"checkpoint", "context_checkpoint"}:
+        return "context_checkpoint"
+    if raw in {"boundary", "compaction_boundary"}:
+        return "compaction_boundary"
+    if raw in {"status", "run_status"}:
+        return "run_status"
+    if raw in {"run_checkpoint", "runtime_checkpoint"}:
+        return "run_checkpoint"
+    if raw in {"run_resume", "runtime_resume"}:
+        return "run_resume"
+    if raw in {"assistant", "model"} or role in {"assistant", "model"} or author in {"assistant", "model"}:
+        return "assistant_message"
+    return "user_message"
+
+
+def extract_text_from_event_parts(parts: List[Dict[str, Any]]) -> str:
+    segments: List[str] = []
+    for part in parts or []:
+        if isinstance(part, dict) and part.get("text"):
+            segments.append(_stringify_part_text(part["text"]))
+    return "\n".join(segments)
+
+
+def _stringify_part_text(value: Any) -> str:
+    if isinstance(value, dict):
+        preview = (
+            value.get("stdout")
+            or value.get("stderr")
+            or value.get("text")
+            or value.get("content")
+            or value.get("preview")
+            or ""
+        )
+        persisted = value.get("persisted")
+        if isinstance(persisted, dict) and persisted.get("path"):
+            mime_type = str(persisted.get("mime_type") or "text/plain")
+            suffix = f"\n[persisted-output] {persisted['path']} ({mime_type})"
+            return f"{preview}{suffix}".strip()
+        return json.dumps(value, ensure_ascii=False, sort_keys=True)
+    return str(value)
+
+
+def build_request_history(messages: Iterable[Dict[str, Any]]) -> List[Dict[str, str]]:
+    history: List[Dict[str, str]] = []
+    for message in messages or []:
+        role = str(message.get("role") or "")
+        if role in {"assistant", "model"}:
+            role = "model"
+        elif role not in {"user", "model"}:
+            continue
+        content = str(message.get("content") or "")
+        if content:
+            history.append({"role": role, "content": content})
+    return history
+
+
+def compacted_until_seq_id(events: List[SessionEvent]) -> int:
+    """读取最新 checkpoint 覆盖到哪一个 seq_id。"""
+    checkpoints = [event for event in events if canonical_event_type(event.event_type) == "context_checkpoint"]
+    if not checkpoints:
+        return 0
+    latest = checkpoints[-1]
+    return int((latest.metadata or {}).get("compacted_until_seq_id") or 0)
+
+
+def group_events_by_api_round(events: List[SessionEvent]) -> List[List[SessionEvent]]:
+    """按 invocation/轮次分组，保证压缩和 PTL 截断不会打断一整轮对话。"""
+    groups: List[List[SessionEvent]] = []
+    current_key: str | None = None
+    for event in events:
+        key = str(event.invocation_id or f"seq:{event.seq_id}")
+        if key != current_key:
+            groups.append([])
+            current_key = key
+        groups[-1].append(event)
+    return groups
+
+
+def summarize_event_groups(
+    groups: List[List[SessionEvent]],
+    *,
+    previous_summary: str = "",
+) -> str:
+    """把要折叠的旧轮次压成一段 checkpoint 文本。
+
+    这里没有直接照搬 Claude Code 的 LLM summarizer，而是先落一个可预测、
+    可恢复的结构化摘要骨架，后续再替换成真正的 summarize agent 也不需要改
+    event contract。
+    """
+    lines: List[str] = []
+    if previous_summary:
+        lines.append(previous_summary)
+    lines.append("Earlier conversation summary:")
+    for group in groups:
+        snippets: List[str] = []
+        for event in group:
+            event_type = canonical_event_type(
+                event.event_type,
+                author=event.author,
+                role=str((event.content or {}).get("role") or ""),
+            )
+            if event_type not in TRANSCRIPT_EVENT_TYPES or event_type == "context_checkpoint":
+                continue
+            text = extract_event_text(event)
+            if not text:
+                continue
+            if event_type in {"assistant_message", "tool_call"}:
+                role = "assistant"
+            else:
+                role = "user"
+            snippets.append(f"{role}: {text[:180]}")
+        if snippets:
+            lines.append(" | ".join(snippets))
+    return "\n".join(line for line in lines if line).strip()
+
+
+def project_model_messages(
+    events: List[SessionEvent],
+    *,
+    assistant_role: str = "model",
+) -> List[Dict[str, str]]:
+    """把 append-only transcript 投影成运行时 history。
+
+    核心原则：
+    1. `context_checkpoint` 之前的正文不再重复展开。
+    2. `run_status` 这类 transport/control 事件不进入模型上下文。
+    3. tool/approval/attachment 仍保留成可解释的文本占位，避免状态丢失。
+    """
+    projected: List[Dict[str, str]] = []
+    compacted_until = compacted_until_seq_id(events)
+    checkpoint = next(
+        (
+            event
+            for event in reversed(events)
+            if canonical_event_type(event.event_type) == "context_checkpoint"
+        ),
+        None,
+    )
+    if checkpoint:
+        summary_text = extract_event_text(checkpoint)
+        if summary_text:
+            projected.append(
+                {
+                    "role": assistant_role,
+                    "content": summary_text,
+                }
+            )
+
+    for event in events:
+        event_type = canonical_event_type(
+            event.event_type,
+            author=event.author,
+            role=str((event.content or {}).get("role") or ""),
+        )
+        if event.seq_id <= compacted_until and event_type != "context_checkpoint":
+            continue
+        if event_type not in TRANSCRIPT_EVENT_TYPES:
+            continue
+        if event_type in {"context_checkpoint", "compaction_boundary"}:
+            continue
+
+        text = extract_event_text(event)
+        if not text:
+            continue
+
+        if event_type == "assistant_message":
+            role = assistant_role
+        elif event_type == "tool_call":
+            role = assistant_role
+            text = f"[tool_call] {text}"
+        elif event_type == "tool_result":
+            role = "user"
+            text = f"[tool_result] {text}"
+        elif event_type == "approval_request":
+            role = assistant_role
+            text = f"[approval_request] {text}"
+        elif event_type == "approval_response":
+            role = "user"
+            text = f"[approval_response] {text}"
+        elif event_type == "attachment_ref":
+            role = "user"
+            text = f"[attachment] {text}"
+        else:
+            role = "user"
+
+        if projected and projected[-1]["role"] == role:
+            projected[-1]["content"] = f"{projected[-1]['content']}\n{text}".strip()
+        else:
+            projected.append({"role": role, "content": text})
+
+    return projected
+
+
+def build_history_from_events(events: List[SessionEvent]) -> List[Dict[str, str]]:
+    """本地 runner 使用的最终 history 视图。"""
+    history: List[Dict[str, str]] = []
+    for message in project_model_messages(events, assistant_role="model"):
+        role = str(message.get("role") or "")
+        content = str(message.get("content") or "")
+        if role in {"user", "model"} and content:
+            history.append({"role": role, "content": content})
+    return history

ksadk/conversations/message_projection.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+from urllib.parse import quote
+
+
+def project_session_messages(
+    events: Sequence[Mapping[str, Any]],
+    *,
+    include_reasoning: bool = False,
+    include_tool_events: bool = False,
+    include_attachments: bool = True,
+) -> list[dict[str, Any]]:
+    """Project persisted runtime events into the chat history contract."""
+
+    groups: dict[str, list[Mapping[str, Any]]] = {}
+    for event in sorted(events, key=lambda item: int(item.get("SeqId") or 0)):
+        invocation_id = str(event.get("InvocationId") or f"seq:{event.get('SeqId')}")
+        groups.setdefault(invocation_id, []).append(event)
+
+    messages: list[dict[str, Any]] = []
+    for group in groups.values():
+        messages.extend(
+            _project_event_group(
+                group,
+                include_reasoning=include_reasoning,
+                include_tool_events=include_tool_events,
+                include_attachments=include_attachments,
+            )
+        )
+    return sorted(messages, key=lambda item: int(item.get("SeqId") or 0))
+
+
+def _project_event_group(
+    events: Sequence[Mapping[str, Any]],
+    *,
+    include_reasoning: bool,
+    include_tool_events: bool,
+    include_attachments: bool,
+) -> list[dict[str, Any]]:
+    reasoning = [
+        {"text": _event_text(event), "SeqId": event.get("SeqId")}
+        for event in events
+        if event.get("EventType") == "reasoning" and _event_text(event)
+    ]
+    tool_events = _project_tool_events(events) if include_tool_events else []
+    projected: list[dict[str, Any]] = []
+    assistant_seen = False
+
+    for event in events:
+        event_type = str(event.get("EventType") or "")
+        if event_type == "user_message":
+            message = _base_message(event, "user")
+            if include_attachments:
+                attachments = _event_attachments(event)
+                if attachments:
+                    message["Attachments"] = attachments
+            projected.append(message)
+        elif event_type == "assistant_message":
+            message = _base_message(event, "assistant")
+            if include_reasoning and reasoning:
+                message["Reasoning"] = reasoning
+            if tool_events:
+                message["ToolEvents"] = tool_events
+            projected.append(message)
+            assistant_seen = True
+
+    if not assistant_seen and (reasoning or tool_events):
+        anchor = next(
+            (
+                event
+                for event in reversed(events)
+                if event.get("EventType")
+                in {"assistant_stream_snapshot", "approval_request", "tool_call", "reasoning"}
+            ),
+            events[-1],
+        )
+        message = _base_message(anchor, "assistant", content="")
+        if include_reasoning and reasoning:
+            message["Reasoning"] = reasoning
+        if tool_events:
+            message["ToolEvents"] = tool_events
+        projected.append(message)
+
+    return projected
+
+
+def _base_message(
+    event: Mapping[str, Any],
+    role: str,
+    *,
+    content: str | None = None,
+) -> dict[str, Any]:
+    metadata = event.get("Metadata") if isinstance(event.get("Metadata"), Mapping) else {}
+    message: dict[str, Any] = {
+        "MessageId": event.get("EventId"),
+        "Role": role,
+        "Content": {"text": _event_text(event) if content is None else content},
+        "Timestamp": event.get("Timestamp"),
+        "SeqId": event.get("SeqId"),
+        "InvocationId": event.get("InvocationId"),
+    }
+    for target, *sources in (
+        ("ResponseId", "response_id", "ResponseId"),
+        ("TraceId", "trace_id", "TraceId"),
+        ("RootSpanId", "root_span_id", "rootSpanId", "RootSpanId"),
+    ):
+        value = next((metadata.get(source) for source in sources if metadata.get(source)), None)
+        if value:
+            message[target] = str(value)
+    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]]) -> list[dict[str, Any]]:
+    projected: list[dict[str, Any]] = []
+    pending_calls: list[tuple[Mapping[str, Any], dict[str, Any]]] = []
+
+    for event in events:
+        event_type = str(event.get("EventType") or "")
+        metadata = event.get("Metadata") if isinstance(event.get("Metadata"), Mapping) else {}
+        if event_type == "tool_call":
+            entry = _tool_event_from_call(event, metadata)
+            projected.append(entry)
+            pending_calls.append((event, entry))
+            continue
+        if event_type != "tool_result":
+            continue
+
+        name = str(metadata.get("tool_name") or "tool")
+        match = next(
+            (
+                item
+                for item in reversed(pending_calls)
+                if item[1]["Name"] == name and item[1]["Status"] == "running"
+            ),
+            None,
+        )
+        if match is None:
+            entry = _tool_event_from_call(event, metadata)
+            projected.append(entry)
+        else:
+            entry = match[1]
+        output = metadata.get("tool_output", _event_text(event))
+        entry["Status"] = (
+            "failed" if isinstance(output, Mapping) and output.get("ok") is False else "completed"
+        )
+        entry["Result"] = output
+        entry["ResultSeqId"] = event.get("SeqId")
+
+    projected.extend(_project_approval_events(events))
+    return projected
+
+
+def _tool_event_from_call(
+    event: Mapping[str, Any], metadata: Mapping[str, Any]
+) -> dict[str, Any]:
+    tool_receipt = metadata.get("tool_receipt")
+    call_id = metadata.get("call_id") or metadata.get("run_id")
+    if not call_id and isinstance(tool_receipt, Mapping):
+        call_id = tool_receipt.get("tool_call_id")
+    return {
+        "SeqId": event.get("SeqId"),
+        "Type": "tool_call",
+        "Name": str(metadata.get("tool_name") or "tool"),
+        "Args": metadata.get("tool_args"),
+        "Status": "running",
+        "ToolCallId": call_id,
+    }
+
+
+def _project_approval_events(events: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    responses: dict[str, Mapping[str, Any]] = {}
+    for event in events:
+        if event.get("EventType") != "approval_response":
+            continue
+        metadata = event.get("Metadata") if isinstance(event.get("Metadata"), Mapping) else {}
+        resume_input = metadata.get("resume_input")
+        if not isinstance(resume_input, Mapping):
+            continue
+        request_id = str(
+            resume_input.get("approval_request_id")
+            or resume_input.get("interrupt_id")
+            or resume_input.get("id")
+            or ""
+        )
+        responses[request_id] = event
+
+    approvals: list[dict[str, Any]] = []
+    for request in events:
+        if request.get("EventType") != "approval_request":
+            continue
+        metadata = request.get("Metadata") if isinstance(request.get("Metadata"), Mapping) else {}
+        interrupt_info = metadata.get("interrupt_info")
+        if not isinstance(interrupt_info, Mapping):
+            interrupt_info = {}
+        request_id = str(
+            interrupt_info.get("approval_request_id") or interrupt_info.get("id") or ""
+        )
+        response = responses.get(request_id)
+        response_metadata = (
+            response.get("Metadata")
+            if response is not None and isinstance(response.get("Metadata"), Mapping)
+            else {}
+        )
+        resume_input = response_metadata.get("resume_input")
+        if not isinstance(resume_input, Mapping):
+            resume_input = {}
+        status = "paused" if response is None else (
+            "approved"
+            if resume_input.get("approve") or resume_input.get("approved")
+            else "denied"
+        )
+        entry: dict[str, Any] = {
+            "SeqId": request.get("SeqId"),
+            "Type": "approval",
+            "Name": str(interrupt_info.get("tool_name") or "approval"),
+            "Status": status,
+            "ApprovalRequestId": request_id or None,
+        }
+        arguments = (
+            interrupt_info.get("arguments")
+            or interrupt_info.get("tool_args")
+            or interrupt_info.get("args")
+        )
+        if arguments is not None:
+            entry["Args"] = arguments
+        approvals.append(entry)
+    return approvals
+
+
+def _event_attachments(event: Mapping[str, Any]) -> list[dict[str, Any]]:
+    metadata = event.get("Metadata") if isinstance(event.get("Metadata"), Mapping) else {}
+    attachments: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for item in metadata.get("attachments") or []:
+        if not isinstance(item, Mapping):
+            continue
+        file_uri = str(item.get("file_uri") or item.get("fileUri") or "")
+        if not file_uri or file_uri in seen:
+            continue
+        mime = str(item.get("mime_type") or item.get("mimeType") or "")
+        attachments.append(
+            {
+                "file_uri": file_uri,
+                "name": str(item.get("display_name") or item.get("displayName") or ""),
+                "mime": mime,
+                "size": int(item.get("size_bytes") or item.get("sizeBytes") or 0),
+                "is_image": mime.startswith("image/"),
+                "url": "/agentengine/api/v1/AttachmentContent?FileUri=" + quote(file_uri, safe=""),
+            }
+        )
+        seen.add(file_uri)
+    return attachments