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

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",
+]

ksadk/prompts/resolved.py

@@ -0,0 +1,137 @@
+"""Prompt Source Contract —— ResolvedPromptSources + PlatformPolicySource（PR A）。
+
+把 Studio agent 的 instructions.system/task 与 request_instructions 聚合成统一来源，
+编译真实 ``CompiledPrompt``（带稳定 section hash），用于 hash/trace/future projection。
+
+PR A **不改 Runner 输入**：``payload["instructions"]`` 仍由 request 级 instructions 决定。
+``compiled_prompt`` 只挂在 ``PreparedConversationTurn`` 供可观测与后续 PR B 投影。
+
+platform_safety 暂不注入生产：``PlatformPolicySource`` 接口存在，``EnvPlatformPolicySource``
+仅本地 dev override（``KSADK_PLATFORM_SAFETY_TEXT``），未设时不产 platform_safety section。
+当前硬编码 ``PLATFORM_SAFETY_TEXT`` 只作测试/shadow fixture。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from ksadk.prompts.compiler import PromptCompiler
+from ksadk.prompts.models import PromptSection
+from ksadk.prompts.sources import (
+    agent_identity_section,
+    agent_policy_section,
+    platform_safety_section,
+    request_instructions_section,
+)
+
+RESOLVED_PROMPT_SOURCES_VERSION = "v1"
+
+
+class PlatformPolicySource(Protocol):
+    """可信平台安全规则来源接口（方案 7.5 / 评测 PCM-PROMPT-001）。
+
+    生产实现应由部署级配置提供（带版本与来源标识）。未提供可信来源时返回 ``None``，
+    不产 ``platform_safety`` section——不硬编码生产安全文本。
+    """
+
+    source: str
+    version: str
+
+    def resolve(self) -> str | None: ...
+
+
+@dataclass(frozen=True)
+class EnvPlatformPolicySource:
+    """本地开发 override：从 env ``KSADK_PLATFORM_SAFETY_TEXT`` 读平台安全文本。
+
+    仅用于本地 dev / 测试。未设 env 时 ``resolve()`` 返回 ``None``。
+    生产环境应替换为部署级 ``PlatformPolicySource`` 实现。
+    """
+
+    env_var: str = "KSADK_PLATFORM_SAFETY_TEXT"
+    source: str = "env_local_dev"
+    version: str = "env"
+
+    def resolve(self) -> str | None:
+        text = (os.environ.get(self.env_var, "") or "").strip()
+        return text or None
+
+
+def get_default_platform_policy_source() -> PlatformPolicySource | None:
+    """返回默认 PlatformPolicySource（EnvPlatformPolicySource）。
+
+    当前唯一实现是 env override；生产实现留后续 PR。返回值供
+    ``compile_resolved_prompt_dict`` 决定是否产 platform_safety。
+    """
+    return EnvPlatformPolicySource()
+
+
+@dataclass(frozen=True)
+class ResolvedPromptSources:
+    """一次模型调用的 Prompt 来源聚合（方案 7.6）。
+
+    ``agent_system`` / ``agent_task`` 来自 Studio agent 配置（``Instructions.system/task``），
+    ``request_instructions`` 来自 API request 级 instructions，
+    ``platform_policy_source`` 为可信平台安全来源（可空）。
+    """
+
+    agent_system: str = ""
+    agent_task: str = ""
+    request_instructions: str = ""
+    platform_policy_source: PlatformPolicySource | None = None
+    version: str = RESOLVED_PROMPT_SOURCES_VERSION
+
+
+def sections_from_resolved_sources(sources: ResolvedPromptSources) -> list[PromptSection]:
+    """把 ResolvedPromptSources 投影成 PromptSection 列表（canonical 顺序）。
+
+    空 content 的 section 跳过。platform_safety 仅在可信来源返回非空文本时产生。
+    """
+    sections: list[PromptSection] = []
+    if sources.agent_system.strip():
+        sections.append(agent_identity_section(sources.agent_system.strip()))
+    if sources.agent_task.strip():
+        sections.append(agent_policy_section(sources.agent_task.strip()))
+    if sources.request_instructions.strip():
+        sections.append(request_instructions_section(sources.request_instructions.strip()))
+    policy_source = sources.platform_policy_source
+    if policy_source is not None:
+        policy_text = policy_source.resolve()
+        if policy_text:
+            sections.append(
+                platform_safety_section(content=policy_text, source=policy_source.source)
+            )
+    return sections
+
+
+def compile_resolved_prompt_dict(sources: ResolvedPromptSources) -> dict[str, Any] | None:
+    """编译真实 CompiledPrompt 的 plain dict 投影（PR A，shadow/trace 用）。
+
+    返回 ``None`` 表示无任何非空 section（agent_system/agent_task/request_instructions
+    全空且无 platform_policy）。键名沿用 ``compile_shadow_prompt_dict`` 的 ``prompt_*``
+    前缀，保证可被 ``build_shadow_context_plan_dict`` 直接 spread，且
+    ``_set_prompt_cache_attributes`` 自动拿到真实 hash。
+    """
+    sections = sections_from_resolved_sources(sources)
+    if not sections:
+        return None
+    compiled = PromptCompiler().compile(sections)
+    policy_source = sources.platform_policy_source
+    policy_active = bool(policy_source is not None and policy_source.resolve())
+    return {
+        "prompt_content_hash": compiled.content_hash,
+        "prompt_stable_prefix_hash": compiled.stable_prefix_hash,
+        "prompt_section_hashes": dict(compiled.section_hashes),
+        "prompt_tokens_by_section": dict(compiled.tokens_by_section),
+        "prompt_estimated_tokens": compiled.estimated_tokens,
+        "prompt_section_count": len(compiled.sections),
+        "prompt_compiler_version": compiled.compiler_version,
+        "prompt_resolved_sources_version": sources.version,
+        "prompt_platform_policy_version": (policy_source.version if policy_active else None),
+        "prompt_platform_policy_source": (policy_source.source if policy_active else None),
+        # PR B：真实正文。供接管注入读 ``prepared.compiled_prompt["prompt_content"]``。
+        # 注意：含明文，**不得**进 shadow plan/trace（build_shadow_context_plan_dict 会剥离）。
+        "prompt_content": compiled.content,
+    }