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

ksadk/observability/trajectory.py

@@ -0,0 +1,105 @@
+"""Stable UI trajectory projection for canonical RuntimeEvents.
+
+The durable store owns only RuntimeEvent/v2 facts. This module derives its
+compact trajectory shape from the Studio v2 projection; it must not reach into
+the read-only RuntimeEvent/v1 compatibility model.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ksadk.events.canonical import RuntimeEvent, dump_runtime_event
+from ksadk.studio.run_service import project_runtime_event
+
+PROJECTION_VERSION = 1
+
+
+def _record_id(event: RuntimeEvent, event_type: str, data: dict[str, Any]) -> str:
+    if event_type.startswith(("message.", "thinking.")):
+        return f"assistant:{data.get('itemId') or event.scope_id}"
+    if event_type.startswith(("tool.", "command.")):
+        return f"tool:{data.get('callId') or data.get('itemId') or event.event_id}"
+    if event_type.startswith("approval."):
+        return f"approval:{data.get('approvalId') or data.get('itemId') or event.event_id}"
+    if event_type.startswith("checkpoint."):
+        return f"checkpoint:{data.get('checkpointId') or data.get('itemId') or event.event_id}"
+    if event_type.startswith("a2ui.surface."):
+        return f"surface:{data.get('surfaceId') or data.get('itemId') or event.event_id}"
+    if event_type.startswith("context.compaction."):
+        return f"context:{event.scope_id}:compaction"
+    return f"system:{event.event_id}"
+
+
+def _category(event_type: str) -> str:
+    if event_type.startswith(("message.", "thinking.")):
+        return "assistant"
+    if event_type.startswith(("tool.", "command.")):
+        return "tool"
+    if event_type.startswith("approval."):
+        return "approval"
+    if event_type.startswith("context.compaction."):
+        return "context"
+    if event_type.startswith("artifact."):
+        return "artifact"
+    return "system"
+
+
+def _status(event_type: str, data: dict[str, Any]) -> str | None:
+    value = data.get("status")
+    if isinstance(value, str) and value:
+        return value
+    if event_type.endswith((".started", ".delta", ".requested", ".progress")):
+        return "running"
+    if event_type.endswith((".completed", ".resolved")):
+        return "completed"
+    if event_type.endswith(".failed"):
+        return "failed"
+    if event_type.endswith(".cancelled"):
+        return "canceled"
+    if event_type.endswith(".interrupted"):
+        return "interrupted"
+    return None
+
+
+def _summary(event_type: str, data: dict[str, Any]) -> str:
+    if event_type.startswith(("message.", "thinking.")):
+        return "Message"
+    for key in ("tool", "command", "message", "reason", "error"):
+        value = data.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return event_type
+
+
+def project_trajectory_event(event: RuntimeEvent) -> dict[str, Any]:
+    """Project one immutable v2 fact into the stable trajectory display shape."""
+
+    event_type, data = project_runtime_event(event)
+    details = dict(data)
+    details.pop("runtimeEvent", None)
+    return {
+        "projectionVersion": PROJECTION_VERSION,
+        "seqId": event.seq,
+        "eventId": event.event_id,
+        "recordId": _record_id(event, event_type, details),
+        "type": event_type,
+        "category": _category(event_type),
+        "turnId": None,
+        "stepId": None,
+        "timestamp": event.timestamp,
+        "status": _status(event_type, details),
+        "durationMs": details.get("durationMs"),
+        "summary": _summary(event_type, details),
+        "details": details,
+        "source": dump_runtime_event(event),
+    }
+
+
+def encode_sse(value: dict[str, Any], *, event_id: int) -> str:
+    data = json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return f"id: {event_id}\nevent: runtime_event\ndata: {data}\n\n"
+
+
+__all__ = ["PROJECTION_VERSION", "encode_sse", "project_trajectory_event"]

ksadk/prompts/__init__.py

@@ -0,0 +1,71 @@
+"""Prompt 分区与编译数据模型（方案第 7 节）。
+
+第一个 PR 只导出稳定类型：``PromptSection`` / ``CompiledPrompt`` / ``PromptProjectionResult``。
+``PromptCompiler`` 的确定性编译、merge、hash、指令文件发现与预算留第二个 PR。
+"""
+
+from ksadk.prompts.compiler import (
+    InconsistentSectionError,
+    PromptCompiler,
+    ProtectedSectionOverrideError,
+    compile_prompt,
+)
+from ksadk.prompts.models import (
+    PROMPT_COMPILER_VERSION,
+    CompiledPrompt,
+    PromptMergePolicy,
+    PromptProjectionResult,
+    PromptSection,
+    PromptSectionKind,
+    PromptStability,
+    PromptTrustLevel,
+)
+from ksadk.prompts.resolved import (
+    RESOLVED_PROMPT_SOURCES_VERSION,
+    EnvPlatformPolicySource,
+    PlatformPolicySource,
+    ResolvedPromptSources,
+    compile_resolved_prompt_dict,
+    get_default_platform_policy_source,
+    sections_from_resolved_sources,
+)
+from ksadk.prompts.sources import (
+    PLATFORM_SAFETY_TEXT,
+    agent_identity_section,
+    agent_policy_section,
+    discover_instruction_files,
+    platform_safety_section,
+    request_instructions_section,
+    resource_manifest_section,
+    sections_from_instructions,
+)
+
+__all__ = [
+    "PLATFORM_SAFETY_TEXT",
+    "PROMPT_COMPILER_VERSION",
+    "RESOLVED_PROMPT_SOURCES_VERSION",
+    "CompiledPrompt",
+    "EnvPlatformPolicySource",
+    "InconsistentSectionError",
+    "PlatformPolicySource",
+    "PromptCompiler",
+    "PromptMergePolicy",
+    "PromptProjectionResult",
+    "PromptSection",
+    "PromptSectionKind",
+    "PromptStability",
+    "PromptTrustLevel",
+    "ProtectedSectionOverrideError",
+    "ResolvedPromptSources",
+    "agent_identity_section",
+    "agent_policy_section",
+    "compile_prompt",
+    "compile_resolved_prompt_dict",
+    "discover_instruction_files",
+    "get_default_platform_policy_source",
+    "platform_safety_section",
+    "request_instructions_section",
+    "resource_manifest_section",
+    "sections_from_instructions",
+    "sections_from_resolved_sources",
+]

ksadk/prompts/compiler.py

@@ -0,0 +1,215 @@
+"""PromptCompiler —— 确定性编译 Prompt 分区（方案第 7 节）。
+
+第一个 PR 只落地稳定数据模型；本（第二个）PR 实现 ``compile()`` 的确定性行为：排序、
+标准化、merge policy、protected 覆盖检测、SHA-256、section token 与 stable_prefix_hash。
+
+PR2 仍是 shadow：``CompiledPrompt`` 仅用于 hash/可观测/未来 projection，**不替换** Runner
+实际发送的 instructions→new_message/SystemMessage/base_instructions 拼装，线上行为不变。
+``CompiledPrompt.content`` 不保证等于 Runner 最终物理输入（方案 7.2）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, replace
+from typing import Iterable
+
+from ksadk.context_engine.tokenizer import get_default_token_counter
+from ksadk.prompts.models import (
+    PROMPT_COMPILER_VERSION,
+    CompiledPrompt,
+    PromptSection,
+    PromptSectionKind,
+)
+
+# canonical 顺序：按 priority 升序，priority 相同按 kind 字典序。同一 section_id 的
+# source/stability/merge_policy 必须固定，不因 Runner 遍历顺序变化（方案 7.3 第 8 条）。
+_KIND_ORDER: tuple[PromptSectionKind, ...] = (
+    "platform_safety",
+    "agent_identity",
+    "agent_policy",
+    "runtime_capabilities",
+    "resource_manifest",
+    "request_instructions",
+)
+
+
+def _section_sort_key(section: PromptSection) -> tuple[int, str, str]:
+    kind_rank = _KIND_ORDER.index(section.kind) if section.kind in _KIND_ORDER else len(_KIND_ORDER)
+    kind_key = _KIND_ORDER[kind_rank] if kind_rank < len(_KIND_ORDER) else section.kind
+    return (section.priority, kind_key, section.section_id)
+
+
+def _normalize_text(text: str) -> str:
+    """标准化换行与尾部空白，但不改变正文语义（方案 7.3 第 2 条）。
+
+    - CRLF/CR → LF
+    - 去除每行尾部空白
+    - 合并 3+ 连续空行为 1 行，去除首尾空白
+    """
+    if not text:
+        return ""
+    normalized = str(text).replace("\r\n", "\n").replace("\r", "\n")
+    lines = [line.rstrip() for line in normalized.split("\n")]
+    # 合并 2+ 连续空行 → 单空行（统一段落间距，不改变正文语义）
+    collapsed: list[str] = []
+    blank_run = 0
+    for line in lines:
+        if line == "":
+            blank_run += 1
+            if blank_run >= 2:
+                continue
+            collapsed.append(line)
+        else:
+            blank_run = 0
+            collapsed.append(line)
+    return "\n".join(collapsed).strip()
+
+
+def _content_sha256(text: str) -> str:
+    return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _wrap_section(section: PromptSection, content: str) -> str:
+    """用标签消除区段歧义，但不应把所有动态上下文拼成 XML（方案 7.3 推荐格式）。"""
+    body = content.strip()
+    if not body:
+        return ""
+    return f"<{section.kind}>\n{body}\n</{section.kind}>"
+
+
+def _merge_sections(sections: list[PromptSection]) -> list[PromptSection]:
+    """同 kind 多来源时执行显式 merge policy，禁止"最后写入悄悄覆盖"（方案 7.3 第 3 条）。
+
+    - ``replace``: 保留最后一条（同 section_id 之内）
+    - ``append``: 按顺序拼接
+    - ``merge_unique``: 去重拼接
+    - ``protected``: 不允许覆盖；发生覆盖尝试时抛 ``ProtectedSectionOverrideError``
+    """
+    grouped: dict[str, list[PromptSection]] = {}
+    order: list[str] = []
+    for section in sections:
+        if section.section_id not in grouped:
+            grouped[section.section_id] = []
+            order.append(section.section_id)
+        grouped[section.section_id].append(section)
+
+    merged: list[PromptSection] = []
+    for section_id in order:
+        bucket = grouped[section_id]
+        head = bucket[0]
+        if len(bucket) == 1:
+            merged.append(head)
+            continue
+        policy = head.merge_policy
+        # 同一 section_id 的来源/稳定性/merge_policy 必须固定（方案 7.3 第 8 条）。
+        inconsistent = any(
+            b.merge_policy != policy or b.stability != head.stability or b.kind != head.kind
+            for b in bucket[1:]
+        )
+        if inconsistent:
+            raise InconsistentSectionError(
+                f"section {section_id!r} 的来源/稳定性/merge_policy 不一致"
+            )
+        if policy == "replace":
+            merged.append(replace(head, content=bucket[-1].content))
+        elif policy == "protected":
+            # 任意两条同 section_id 内容不同即视为覆盖尝试。
+            contents = {b.content for b in bucket}
+            if len(contents) > 1:
+                raise ProtectedSectionOverrideError(
+                    f"protected section {section_id!r} 发生覆盖尝试"
+                )
+            merged.append(head)
+        elif policy == "merge_unique":
+            seen: set[str] = set()
+            parts: list[str] = []
+            for b in bucket:
+                for chunk in re.split(r"\n{2,}", b.content.strip()):
+                    chunk = chunk.strip()
+                    if chunk and chunk not in seen:
+                        seen.add(chunk)
+                        parts.append(chunk)
+            merged.append(replace(head, content="\n\n".join(parts)))
+        else:  # append
+            merged.append(
+                replace(
+                    head,
+                    content="\n\n".join(b.content.strip() for b in bucket if b.content.strip()),
+                )
+            )
+    return merged
+
+
+class ProtectedSectionOverrideError(RuntimeError):
+    """``protected`` section 被尝试覆盖。编译失败并产生审计事件，不静默忽略（方案 7.3 第 9 条）。"""
+
+
+class InconsistentSectionError(RuntimeError):
+    """同一 section_id 的来源/稳定性/merge_policy 不固定。"""
+
+
+@dataclass(frozen=True)
+class PromptCompiler:
+    """确定性 Prompt 编译器。
+
+    ``compile()`` 必须对相同输入产生相同输出（方案 7.3）。构造器无状态，可复用。
+    """
+
+    compiler_version: str = PROMPT_COMPILER_VERSION
+
+    def compile(self, sections: Iterable[PromptSection]) -> CompiledPrompt:
+        # 1. 排序（确定性）
+        ordered = sorted(sections, key=_section_sort_key)
+        # 2. merge（同 section_id 的多来源按 merge policy 合并）
+        merged = _merge_sections(ordered)
+        # 3. platform_safety 不允许被 request_instructions 覆盖（方案 7.3 第 4 条）。
+        #    protected/replace 在 _merge_sections 内已处理；这里额外校验跨 section_id 的
+        #    信任边界：request_instructions 不得声明 platform 的 kind。
+        for section in merged:
+            if (
+                section.kind == "platform_safety"
+                and section.trust_level in ("untrusted", "user")
+            ):
+                raise ProtectedSectionOverrideError(
+                    "platform_safety 不得由 untrusted/user 来源声明"
+                )
+
+        counter = get_default_token_counter()
+        # 4. 空 section 不输出占位文本（方案 7.3 第 5 条）。
+        section_hashes: dict[str, str] = {}
+        tokens_by_section: dict[str, int] = {}
+        wrapped_blocks: list[str] = []
+        for section in merged:
+            body = _normalize_text(section.content)
+            section_hashes[section.section_id] = _content_sha256(body)
+            tokens_by_section[section.section_id] = counter.count_text(body)
+            if body:
+                wrapped_blocks.append(_wrap_section(section, body))
+        canonical_content = "\n\n".join(block for block in wrapped_blocks if block).strip()
+
+        # 5. stable_prefix_hash：仅覆盖 stability="stable" 的 section（platform_safety /
+        #    agent_identity / agent_policy）。部署级/动态 section 不进稳定前缀（方案 7.4）。
+        stable_body = "\n\n".join(
+            _wrap_section(s, _normalize_text(s.content))
+            for s in merged
+            if s.stability == "stable" and _normalize_text(s.content)
+        ).strip()
+        stable_prefix_hash = _content_sha256(stable_body) if stable_body else ""
+
+        return CompiledPrompt(
+            sections=tuple(merged),
+            content=canonical_content,
+            content_hash=_content_sha256(canonical_content),
+            estimated_tokens=counter.count_text(canonical_content),
+            stable_prefix_hash=stable_prefix_hash,
+            section_hashes=section_hashes,
+            tokens_by_section=tokens_by_section,
+            compiler_version=self.compiler_version,
+        )
+
+
+def compile_prompt(sections: Iterable[PromptSection]) -> CompiledPrompt:
+    """便捷入口：用默认 compiler 编译。"""
+    return PromptCompiler().compile(sections)

ksadk/prompts/models.py

@@ -0,0 +1,82 @@
+"""Prompt 分区数据模型（方案第 7 节）。
+
+第一个 PR 只落地稳定数据结构，公开类型从第一批开始版本化。``compiler.py`` / ``sources.py``
+（确定性编译、merge、hash、指令文件发现）留第二个 PR；本模块不接管线，不改任何 Runner
+现有 instructions→new_message/SystemMessage/base_instructions 的拼装。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from ksadk.context_engine.capabilities import ContextAccuracy, ContextIntegrationMode
+
+PROMPT_COMPILER_VERSION = "v1"
+
+PromptSectionKind = Literal[
+    "platform_safety",
+    "agent_identity",
+    "agent_policy",
+    "runtime_capabilities",
+    "resource_manifest",
+    "request_instructions",
+]
+"""统一语义分区（方案 7.1）。动态历史、记忆和工具结果不属于 PromptSection。"""
+
+PromptTrustLevel = Literal["platform", "developer", "resource", "untrusted", "user"]
+PromptStability = Literal["stable", "deployment", "volatile"]
+PromptMergePolicy = Literal["replace", "append", "merge_unique", "protected"]
+
+
+@dataclass(frozen=True)
+class PromptSection:
+    """一个 Prompt 分区单元（方案 7.2）。"""
+
+    section_id: str
+    kind: PromptSectionKind
+    content: str
+    source: str
+    priority: int
+    trust_level: PromptTrustLevel
+    stability: PromptStability = "stable"
+    merge_policy: PromptMergePolicy = "append"
+    overridable: bool = False
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class CompiledPrompt:
+    """按确定规则编译后的稳定 Prompt（方案 7.2）。
+
+    ``content`` 是 canonical content，不保证等于 Runner 最终物理输入。``stable_prefix_hash``
+    覆盖稳定前缀（platform_safety / agent_identity / agent_policy），用于 Prompt Cache
+    失效诊断（第二个 PR 实现）。
+    """
+
+    sections: tuple[PromptSection, ...]
+    content: str
+    content_hash: str
+    estimated_tokens: int
+    stable_prefix_hash: str
+    section_hashes: dict[str, str]
+    tokens_by_section: dict[str, int]
+    compiler_version: str = PROMPT_COMPILER_VERSION
+
+
+@dataclass(frozen=True)
+class PromptProjectionResult:
+    """Runner 投影 Prompt 后的可审计结果（方案 7.2）。
+
+    第一个 PR 只保留类型信封，不接管线；由后续 PR 的 projection 逻辑填充。
+    """
+
+    projection_id: str
+    runner_type: str
+    integration_mode: ContextIntegrationMode
+    projection_version: str
+    section_hashes: tuple[str, ...]
+    projected_roles: tuple[str, ...]
+    accounting_accuracy: ContextAccuracy
+    estimated_tokens: int | None
+    warnings: tuple[str, ...] = ()

ksadk/prompts/projection.py

@@ -0,0 +1,89 @@
+"""Prompt Projection —— CompiledPrompt → 目标 Runner 的可审计投影（方案 §7.1 / §7.2）。
+
+Projection 把 ``CompiledPrompt`` 的 canonical section 按目标 Runner 的合法承载形式映射
+（Codex ``base_instructions``、ADK ``instruction``、LangGraph ``system_message``），并输出
+可审计的 ``PromptProjectionResult``。Projection 可以改变物理承载形式，但必须保留 section
+source、hash、信任级别和覆盖决策；不得改变安全优先级与信任边界（方案 §7.1）。
+
+PR B 之前 Projection 仅用于可观测/审计，不替换 Runner 实际发送的 instructions。
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from ksadk.context_engine.capabilities import ContextAccuracy, ContextIntegrationMode
+from ksadk.prompts.models import CompiledPrompt, PromptProjectionResult
+
+PROJECTION_VERSION = "v1"
+
+# 各 integration_mode 的合法投影承载形式（方案 §6.2 / §7.1）。
+_PROJECTION_ROLES: dict[ContextIntegrationMode, tuple[str, ...]] = {
+    "ksadk_hosted": ("system_message", "instruction"),
+    "framework_assisted": ("system_message", "state", "instruction", "session", "memory_service"),
+    "native_runtime": ("base_instructions", "thread"),
+}
+
+
+def project_compiled_prompt(
+    compiled: CompiledPrompt,
+    *,
+    runner_type: str,
+    integration_mode: ContextIntegrationMode,
+    accounting_accuracy: ContextAccuracy,
+    warnings: tuple[str, ...] = (),
+) -> PromptProjectionResult:
+    """投影 CompiledPrompt 到目标 Runner，输出可审计结果（方案 §7.2）。
+
+    只读 ``compiled``，不改 Runner 输入。``projected_roles`` 反映该 integration_mode 的合法承载
+    形式集合；``section_hashes`` 直接取自编译结果，保证投影前后 hash 一致、可校验顺序漂移。
+    """
+    roles = _PROJECTION_ROLES.get(integration_mode, ())
+    if not roles:
+        warnings = (*warnings, f"unknown_integration_mode:{integration_mode}")
+    # 校验安全优先级未被投影改变：platform_safety 必须存在且 trust_level=platform（若编译含它）。
+    safety_sections = [s for s in compiled.sections if s.kind == "platform_safety"]
+    for s in safety_sections:
+        if s.trust_level != "platform":
+            warnings = (*warnings, f"platform_safety_wrong_trust:{s.trust_level}")
+    return PromptProjectionResult(
+        projection_id=f"pj_{uuid.uuid4().hex[:16]}",
+        runner_type=runner_type,
+        integration_mode=integration_mode,
+        projection_version=PROJECTION_VERSION,
+        section_hashes=tuple(
+            compiled.section_hashes.get(s.section_id, "") for s in compiled.sections
+        ),
+        projected_roles=roles,
+        accounting_accuracy=accounting_accuracy,
+        estimated_tokens=compiled.estimated_tokens,
+        warnings=warnings,
+    )
+
+
+def project_to_runner_payload(
+    compiled: CompiledPrompt,
+    *,
+    integration_mode: ContextIntegrationMode,
+) -> dict[str, Any]:
+    """把 CompiledPrompt.content 投影成目标 Runner 的 payload 字段（方案 §7.1）。
+
+    ksadk_hosted/framework_assisted(LangGraph 系) → ``{"system_message": content}``；
+    framework_assisted(ADK) → ``{"instruction": content}``；
+    native_runtime(Codex) → ``{"base_instructions": content}``。调用方据 capability 选字段。
+    """
+    if integration_mode == "native_runtime":
+        return {"base_instructions": compiled.content}
+    if integration_mode == "framework_assisted":
+        # ADK 用 instruction；LangGraph 用 system_message。两者都返回，调用方按 capability 选。
+        return {"instruction": compiled.content, "system_message": compiled.content}
+    # ksadk_hosted
+    return {"system_message": compiled.content, "instruction": compiled.content}
+
+
+__all__ = [
+    "PROJECTION_VERSION",
+    "project_compiled_prompt",
+    "project_to_runner_payload",
+]