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

ksadk/conversations/runtime_observability.py

@@ -0,0 +1,367 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager, nullcontext
+from typing import Any, Mapping, Sequence
+
+from ksadk.sessions import SessionEvent
+
+
+def _extract_deferred_tool_names(output: Any) -> list[str]:
+    if not isinstance(output, Mapping):
+        return []
+    raw_names = output.get("deferred_tool_names")
+    if not isinstance(raw_names, Sequence) or isinstance(raw_names, (str, bytes, bytearray)):
+        return []
+    names: list[str] = []
+    seen: set[str] = set()
+    for item in raw_names:
+        name = str(item or "").strip()
+        if not name or name in seen:
+            continue
+        seen.add(name)
+        names.append(name)
+    return names
+
+
+def _latest_deferred_tool_names(events: Sequence[SessionEvent]) -> list[str]:
+    for event in reversed(events):
+        if event.event_type != "run_status":
+            continue
+        metadata = event.metadata or {}
+        if metadata.get("detail") != "deferred_tools_selected":
+            continue
+        return _extract_deferred_tool_names(metadata)
+    return []
+
+
+def _normalize_usage_payload(usage: Mapping[str, Any] | None) -> dict[str, Any]:
+    if not isinstance(usage, Mapping):
+        return {}
+    normalized: dict[str, Any] = {}
+    for key in (
+        "input_tokens",
+        "output_tokens",
+        "total_tokens",
+        "prompt_tokens",
+        "completion_tokens",
+    ):
+        value = usage.get(key)
+        if value is None:
+            continue
+        try:
+            normalized[key] = int(value)
+        except (TypeError, ValueError):
+            continue
+    for key in ("input_token_details", "output_token_details"):
+        value = usage.get(key)
+        if isinstance(value, Mapping):
+            normalized[key] = dict(value)
+    prompt_details = usage.get("prompt_tokens_details")
+    if isinstance(prompt_details, Mapping):
+        normalized["prompt_tokens_details"] = dict(prompt_details)
+        cached_tokens = prompt_details.get("cached_tokens")
+        if cached_tokens is not None:
+            try:
+                normalized.setdefault("input_token_details", {})["cached"] = int(cached_tokens)
+            except (TypeError, ValueError):
+                pass
+    completion_details = usage.get("completion_tokens_details")
+    if isinstance(completion_details, Mapping):
+        normalized["completion_tokens_details"] = dict(completion_details)
+        reasoning_tokens = completion_details.get("reasoning_tokens")
+        if reasoning_tokens is not None:
+            try:
+                normalized.setdefault("output_token_details", {})["reasoning"] = int(
+                    reasoning_tokens
+                )
+            except (TypeError, ValueError):
+                pass
+    return normalized
+
+
+def _usage_from_metadata(metadata: Mapping[str, Any] | None) -> dict[str, Any]:
+    if not isinstance(metadata, Mapping):
+        return {}
+    return _normalize_usage_payload(metadata.get("usage"))
+
+
+def _responses_usage_payload(usage: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    normalized = _normalize_usage_payload(usage)
+    if not normalized:
+        return None
+    input_tokens = normalized.get("input_tokens", normalized.get("prompt_tokens", 0))
+    output_tokens = normalized.get("output_tokens", normalized.get("completion_tokens", 0))
+    total_tokens = normalized.get("total_tokens", input_tokens + output_tokens)
+    payload = {
+        "input_tokens": input_tokens,
+        "input_tokens_details": {"cached_tokens": 0},
+        "output_tokens": output_tokens,
+        "output_tokens_details": {"reasoning_tokens": 0},
+        "total_tokens": total_tokens,
+    }
+    input_details = normalized.get("input_token_details")
+    if isinstance(input_details, Mapping):
+        cached_tokens = input_details.get(
+            "cached_tokens",
+            input_details.get("cached", input_details.get("cache_read", 0)),
+        )
+        payload["input_tokens_details"]["cached_tokens"] = int(cached_tokens or 0)
+    output_details = normalized.get("output_token_details")
+    if isinstance(output_details, Mapping):
+        reasoning_tokens = output_details.get(
+            "reasoning_tokens",
+            output_details.get("reasoning", 0),
+        )
+        payload["output_tokens_details"]["reasoning_tokens"] = int(reasoning_tokens or 0)
+    return payload
+
+
+def _chat_usage_payload(usage: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    normalized = _normalize_usage_payload(usage)
+    if not normalized:
+        return None
+    prompt_tokens = normalized.get("prompt_tokens", normalized.get("input_tokens", 0))
+    completion_tokens = normalized.get("completion_tokens", normalized.get("output_tokens", 0))
+    total_tokens = normalized.get("total_tokens", prompt_tokens + completion_tokens)
+    payload = {
+        "prompt_tokens": prompt_tokens,
+        "completion_tokens": completion_tokens,
+        "total_tokens": total_tokens,
+    }
+    prompt_details = normalized.get("prompt_tokens_details")
+    if isinstance(prompt_details, Mapping):
+        payload["prompt_tokens_details"] = dict(prompt_details)
+    input_token_details = normalized.get("input_token_details")
+    if isinstance(input_token_details, Mapping) and input_token_details:
+        prompt_details = dict(payload.get("prompt_tokens_details") or {})
+        cached_tokens = input_token_details.get("cached")
+        if cached_tokens is not None:
+            try:
+                prompt_details["cached_tokens"] = int(cached_tokens)
+            except (TypeError, ValueError):
+                pass
+        if prompt_details:
+            payload["prompt_tokens_details"] = prompt_details
+    completion_details = normalized.get("completion_tokens_details")
+    if isinstance(completion_details, Mapping):
+        payload["completion_tokens_details"] = dict(completion_details)
+    output_token_details = normalized.get("output_token_details")
+    if isinstance(output_token_details, Mapping) and output_token_details:
+        completion_details = dict(payload.get("completion_tokens_details") or {})
+        reasoning_tokens = output_token_details.get("reasoning")
+        if reasoning_tokens is not None:
+            try:
+                completion_details["reasoning_tokens"] = int(reasoning_tokens)
+            except (TypeError, ValueError):
+                pass
+        if completion_details:
+            payload["completion_tokens_details"] = completion_details
+    return payload
+
+
+def _get_conversation_tracer() -> Any | None:
+    try:
+        from opentelemetry import trace
+
+        return trace.get_tracer("ksadk.conversations")
+    except Exception:
+        return None
+
+
+def _current_span_feedback_metadata() -> dict[str, str]:
+    try:
+        from opentelemetry import trace
+
+        span = trace.get_current_span()
+    except Exception:
+        return {}
+    return _span_feedback_metadata(span)
+
+
+def _span_feedback_metadata(span: Any | None) -> dict[str, str]:
+    if span is None:
+        return {}
+    try:
+        context = span.get_span_context()
+    except Exception:
+        return {}
+    if not getattr(context, "is_valid", False):
+        return {}
+    return {
+        "trace_id": format(context.trace_id, "032x"),
+        "root_span_id": format(context.span_id, "016x"),
+    }
+
+
+def _get_current_span() -> Any | None:
+    try:
+        from opentelemetry import trace
+
+        return trace.get_current_span()
+    except Exception:
+        return None
+
+
+def _span_current_context(span: Any | None):
+    if span is None:
+        return nullcontext()
+    try:
+        from opentelemetry.trace import use_span
+
+        return use_span(
+            span, end_on_exit=False, record_exception=False, set_status_on_exception=False
+        )
+    except Exception:
+        return nullcontext()
+
+
+@asynccontextmanager
+async def _conversation_span_scope(name: str, *, manual_end: bool = False):
+    tracer = _get_conversation_tracer()
+    if tracer is None:
+        yield None
+        return
+    if manual_end:
+        span = tracer.start_span(name)
+        try:
+            yield span
+        finally:
+            try:
+                span.end()
+            except Exception:
+                pass
+        return
+    span = tracer.start_span(name)
+    try:
+        yield span
+    finally:
+        try:
+            span.end()
+        except Exception:
+            pass
+
+
+def _set_span_attribute(span: Any | None, key: str, value: Any) -> None:
+    if span is None:
+        return
+    if value is None:
+        return
+    if isinstance(value, str):
+        value = value.strip()
+        if not value:
+            return
+    try:
+        span.set_attribute(key, value)
+    except Exception:
+        return
+
+
+def _set_conversation_input_attributes(span: Any | None, input_text: str | None) -> None:
+    text = " ".join(str(input_text or "").split())
+    if not text:
+        return
+    for key in (
+        "langfuse.trace.input",
+        "langfuse.observation.input",
+        "input.value",
+        "gen_ai.prompt",
+    ):
+        _set_span_attribute(span, key, text)
+
+
+def _set_conversation_output_attributes(span: Any | None, output_text: str | None) -> None:
+    text = " ".join(str(output_text or "").split())
+    if not text:
+        return
+    for key in (
+        "langfuse.trace.output",
+        "langfuse.observation.output",
+        "output.value",
+        "gen_ai.completion",
+    ):
+        _set_span_attribute(span, key, text)
+
+
+def _set_conversation_usage_attributes(
+    span: Any | None,
+    usage: Mapping[str, Any] | None,
+) -> None:
+    normalized = _normalize_usage_payload(usage)
+    if not normalized:
+        return
+
+    def _usage_int(value: Any) -> int:
+        try:
+            return int(value or 0)
+        except (TypeError, ValueError):
+            return 0
+
+    input_tokens = _usage_int(normalized.get("input_tokens"))
+    output_tokens = _usage_int(normalized.get("output_tokens"))
+    total_tokens = _usage_int(normalized.get("total_tokens") or (input_tokens + output_tokens))
+    input_details = normalized.get("input_token_details")
+    output_details = normalized.get("output_token_details")
+    cache_read_tokens = 0
+    reasoning_tokens = 0
+    if isinstance(input_details, Mapping):
+        cache_read_tokens = _usage_int(
+            input_details.get("cache_read")
+            or input_details.get("cached")
+            or input_details.get("cached_tokens")
+        )
+    if isinstance(output_details, Mapping):
+        reasoning_tokens = _usage_int(
+            output_details.get("reasoning") or output_details.get("reasoning_tokens")
+        )
+
+    attributes = {
+        "gen_ai.usage.input_tokens": input_tokens,
+        "gen_ai.usage.output_tokens": output_tokens,
+        "gen_ai.usage.total_tokens": total_tokens,
+        "llm.usage.prompt_tokens": input_tokens,
+        "llm.usage.completion_tokens": output_tokens,
+        "llm.usage.total_tokens": total_tokens,
+    }
+    if cache_read_tokens:
+        attributes["gen_ai.usage.cache_read.input_tokens"] = cache_read_tokens
+        attributes["llm.usage.cache_read.input_tokens"] = cache_read_tokens
+    if reasoning_tokens:
+        attributes["gen_ai.usage.reasoning.output_tokens"] = reasoning_tokens
+        attributes["llm.usage.reasoning_tokens"] = reasoning_tokens
+
+    for key, value in attributes.items():
+        if value:
+            _set_span_attribute(span, key, value)
+
+
+def _set_conversation_span_attributes(
+    span: Any,
+    *,
+    agent_id: str,
+    user_id: str,
+    session_id: str,
+    invocation_id: str,
+    runner_name: str,
+    model: str | None,
+    response_id: str | None = None,
+) -> None:
+    if span is None:
+        return
+    try:
+        span.set_attribute("ksadk.agent_id", agent_id)
+        span.set_attribute("ksadk.user_id", user_id)
+        span.set_attribute("ksadk.session_id", session_id)
+        span.set_attribute("ksadk.invocation_id", invocation_id)
+        span.set_attribute("ksadk.runner", runner_name)
+        span.set_attribute("langfuse.trace.name", runner_name)
+        span.set_attribute("langfuse.session.id", session_id)
+        span.set_attribute("session.id", session_id)
+        span.set_attribute("langfuse.user.id", user_id)
+        span.set_attribute("user.id", user_id)
+        if model:
+            span.set_attribute("llm.model_name", model)
+            span.set_attribute("gen_ai.request.model", model)
+        if response_id:
+            span.set_attribute("ksadk.response_id", response_id)
+    except Exception:
+        return

ksadk/conversations/runtime_payloads.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional, Sequence
+
+from ksadk.conversations.run_kinds import (
+    RUN_MODE_FOREGROUND,
+    RUN_TRIGGER_NEW_RUN,
+)
+from ksadk.conversations.runtime_observability import (
+    _chat_usage_payload,
+    _responses_usage_payload,
+    _usage_from_metadata,
+)
+from ksadk.sessions import SessionEvent
+
+
+@dataclass
+class PreparedConversationTurn:
+    """一次 turn 编排后的标准输入。
+
+    这个对象把“会话归属”“用户最新输入”“投影后的上下文 history”
+    和“附件/parts”等运行时所需信息收拢到一起，避免不同 endpoint
+    各自重新拼装。
+    """
+
+    session_id: str
+    invocation_id: str
+    user_input: str
+    user_display_input: str
+    history: list[dict[str, str]]
+    input_content: list[dict[str, Any]]
+    input_messages: list[dict[str, Any]]
+    user_parts: list[dict[str, Any]]
+    attachments: list[dict[str, Any]]
+    attachment_results: list[dict[str, Any]]
+    current_attachments: list[dict[str, Any]]
+    current_attachment_results: list[dict[str, Any]]
+    has_current_files: bool
+    model_metadata: dict[str, Any] = field(default_factory=dict)
+    model_options: dict[str, Any] = field(default_factory=dict)
+    instructions: str = ""
+    request_metadata: dict[str, Any] = field(default_factory=dict)
+    compaction_triggered: bool = False
+    compaction_trigger: str | None = None
+    compacted_until_seq_id: int | None = None
+    resume_input: dict[str, Any] | None = None
+    # 双维度 run 标识：run_mode=怎么跑（background/foreground），
+    # run_trigger=怎么开始（new_run/checkpoint_resume/approval_resume）
+    run_mode: str = RUN_MODE_FOREGROUND
+    run_trigger: str = RUN_TRIGGER_NEW_RUN
+    request_history: list[dict[str, str]] = field(default_factory=list)
+    request_responses_history: list[dict[str, Any]] = field(default_factory=list)
+    responses_history: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class CompactionPlan:
+    """一次 compaction 规划结果。
+
+    预览阶段和真正落 checkpoint 阶段都复用这份规划，避免 `/run_sse`
+    与 conversation runtime 各自写一套“是否需要压缩”的条件判断。
+    """
+
+    should_compact: bool
+    groups_to_compact: list[list[SessionEvent]]
+    total_chars: int
+    total_estimated_tokens: int
+    group_count: int
+    tail_groups: int
+    auto_compact_threshold_tokens: int | None = None
+    auto_compact_threshold_percentage: int | None = None
+    compacted_until_seq_id: int | None = None
+    pinned_group_indexes: list[int] = field(default_factory=list)
+    pinned_state: dict[str, Any] = field(default_factory=dict)
+
+
+def build_responses_payload(
+    *,
+    output_text: str,
+    model: Optional[str],
+    session_id: str,
+    response_id: str | None = None,
+    created_at: int | None = None,
+    status: str = "completed",
+    metadata: Mapping[str, Any] | None = None,
+    usage: Mapping[str, Any] | None = None,
+    incomplete_details: Mapping[str, Any] | None = None,
+    error: Mapping[str, Any] | None = None,
+    output_items: Sequence[Mapping[str, Any]] | None = None,
+) -> dict[str, Any]:
+    response_id = response_id or f"resp_{uuid.uuid4().hex}"
+    created_at = created_at or int(time.time())
+    message_id = f"msg_{uuid.uuid4().hex[:12]}"
+    output_item_status = "completed" if status == "completed" else status
+    message_item = {
+        "id": message_id,
+        "type": "message",
+        "status": output_item_status,
+        "role": "assistant",
+        "content": [{"type": "output_text", "text": output_text}],
+    }
+    normalized_output_items = [
+        dict(item) for item in list(output_items or []) if isinstance(item, Mapping)
+    ]
+    if normalized_output_items:
+        output = normalized_output_items
+        if not any(str(item.get("type") or "") == "message" for item in output):
+            output = [message_item, *output]
+    else:
+        output = [message_item]
+    usage_payload = _responses_usage_payload(usage or _usage_from_metadata(metadata))
+    return {
+        "id": response_id,
+        "object": "response",
+        "created_at": created_at,
+        "status": status,
+        "error": dict(error) if isinstance(error, Mapping) else None,
+        "incomplete_details": (
+            dict(incomplete_details) if isinstance(incomplete_details, Mapping) else None
+        ),
+        "instructions": None,
+        "metadata": dict(metadata or {}),
+        "model": model or "agent",
+        "parallel_tool_calls": True,
+        "temperature": None,
+        "top_p": None,
+        "tools": [],
+        "output": output,
+        "output_text": output_text,
+        "usage": usage_payload,
+        "session_id": session_id,
+    }
+
+
+def extract_responses_resume_input(input_payload: Any) -> dict[str, Any] | None:
+    """Extract OpenAI Responses approval resume input without exposing runner details."""
+    if isinstance(input_payload, Mapping):
+        candidates = [input_payload]
+    elif isinstance(input_payload, Sequence) and not isinstance(
+        input_payload, (str, bytes, bytearray)
+    ):
+        candidates = [item for item in input_payload if isinstance(item, Mapping)]
+    else:
+        return None
+
+    for item in candidates:
+        item_type = str(item.get("type") or "").strip()
+        if item_type == "agentengine.resume_checkpoint":
+            checkpoint_resume: dict[str, Any] = {"type": "agentengine.resume_checkpoint"}
+            for key in (
+                "run_id",
+                "checkpoint_id",
+                "resume_attempt_id",
+                "framework",
+                "framework_ref",
+            ):
+                if key in item:
+                    checkpoint_resume[key] = item.get(key)
+            return checkpoint_resume
+
+        if item_type == "mcp_approval_response":
+            approval_resume: dict[str, Any] = {"type": "mcp_approval_response"}
+            if item.get("id"):
+                approval_resume["id"] = str(item.get("id"))
+            approval_request_id = item.get("approval_request_id")
+            if approval_request_id:
+                approval_resume["approval_request_id"] = str(approval_request_id)
+            if "approve" in item:
+                approval_resume["approve"] = item.get("approve")
+            elif "approved" in item:
+                approval_resume["approve"] = item.get("approved")
+            if item.get("reason") is not None:
+                approval_resume["reason"] = str(item.get("reason") or "")
+            return approval_resume
+
+        if item_type == "function_call_output":
+            call_id = item.get("call_id")
+            if not call_id:
+                continue
+            function_resume: dict[str, Any] = {
+                "type": "function_call_output",
+                "call_id": str(call_id),
+                "output": item.get("output", ""),
+            }
+            if item.get("id"):
+                function_resume["id"] = str(item.get("id"))
+            return function_resume
+
+        if item_type in {"ksadk_resume", "ksadk.approval_response"}:
+            ksadk_resume: dict[str, Any] = {"type": "ksadk_resume"}
+            interrupt_id = (
+                item.get("interrupt_id") or item.get("approval_request_id") or item.get("id")
+            )
+            if interrupt_id:
+                ksadk_resume["interrupt_id"] = str(interrupt_id)
+            if "value" in item:
+                ksadk_resume["value"] = item.get("value")
+            elif "resume" in item:
+                ksadk_resume["value"] = item.get("resume")
+            else:
+                ksadk_resume["value"] = {
+                    key: value
+                    for key, value in item.items()
+                    if key not in {"type", "interrupt_id", "approval_request_id", "id"}
+                }
+            return ksadk_resume
+
+    return None
+
+
+def build_chat_completions_payload(
+    *,
+    output_text: str,
+    model: Optional[str],
+    session_id: str,
+    metadata: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    usage = _chat_usage_payload(_usage_from_metadata(metadata))
+    payload = {
+        "id": f"chatcmpl-{uuid.uuid4()}",
+        "object": "chat.completion",
+        "created": int(time.time()),
+        "model": model or "agent",
+        "choices": [
+            {
+                "index": 0,
+                "message": {"role": "assistant", "content": output_text},
+                "finish_reason": "stop",
+            }
+        ],
+        "usage": usage,
+        "session_id": session_id,
+    }
+    if isinstance(metadata, Mapping) and metadata:
+        payload["metadata"] = dict(metadata)
+    return payload
+
+
+def build_compaction_sse_event(
+    *,
+    phase: str,
+    trigger: str,
+    compacted_until_seq_id: int | None = None,
+    total_chars: int | None = None,
+    total_estimated_tokens: int | None = None,
+    group_count: int | None = None,
+    threshold_percentage: int | None = None,
+) -> str:
+    """统一生成 compaction 相关 SSE，方便不同入口保持同一语义。"""
+
+    payload: dict[str, Any] = {
+        "phase": phase,
+        "trigger": trigger,
+        "timestamp": int(time.time() * 1000),
+    }
+    if compacted_until_seq_id is not None:
+        payload["compacted_until_seq_id"] = compacted_until_seq_id
+    if total_chars is not None:
+        payload["total_chars"] = total_chars
+    if total_estimated_tokens is not None:
+        payload["total_estimated_tokens"] = total_estimated_tokens
+    if group_count is not None:
+        payload["group_count"] = group_count
+    if threshold_percentage is not None:
+        payload["threshold_percentage"] = threshold_percentage
+    return (
+        f"event: response.compaction.{phase}\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"
+    )