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

ksadk/configs/env_registry_pcm.py

@@ -0,0 +1,181 @@
+"""Prompt, Context and Memory environment-variable registry entries."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from ksadk.configs.env_var_spec import EnvVarSpec
+
+_PCM_ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
+    EnvVarSpec("KSADK_BASELINE_COLLECT", "context", "Enable PCM baseline collection.", "0"),
+    EnvVarSpec(
+        "KSADK_BASELINE_EXECUTION_TARGET", "context", "PCM baseline execution target label."
+    ),
+    EnvVarSpec(
+        "KSADK_BASELINE_FLUSH_EACH_TURN",
+        "context",
+        "Flush PCM baseline output after every turn.",
+        "0",
+    ),
+    EnvVarSpec("KSADK_BASELINE_PATH", "context", "PCM baseline JSONL output path."),
+    EnvVarSpec("KSADK_COMPACT_HARD_LIMIT_PCT", "context", "Hard compaction threshold percentage."),
+    EnvVarSpec(
+        "KSADK_COMPACT_HARD_LIMIT_PCT_DEFAULT",
+        "context",
+        "Default hard compaction threshold percentage.",
+    ),
+    EnvVarSpec("KSADK_COMPACT_SOFT_LIMIT_PCT", "context", "Soft compaction threshold percentage."),
+    EnvVarSpec(
+        "KSADK_COMPACT_SOFT_LIMIT_PCT_DEFAULT",
+        "context",
+        "Default soft compaction threshold percentage.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_CACHE_BREAK_OBSERVABILITY",
+        "context",
+        "Enable prompt cache-break diagnostics.",
+        "0",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_CONTRIBUTOR_ALLOW_PLATFORM_TRUST",
+        "context",
+        "Allow trusted platform context contributors.",
+        "0",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_CONTRIBUTOR_FAILURE_MODE",
+        "context",
+        "Context contributor failure policy.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_CONTRIBUTOR_TIMEOUT_MS",
+        "context",
+        "Context contributor timeout in milliseconds.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_EMERGENCY_KEEP_TAIL_GROUPS",
+        "context",
+        "Recent event groups retained during emergency compaction.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_ENGINE_V2_ENABLED", "context", "Enable the PCM context planner.", "0"
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_HARD_LIMIT_PERCENT",
+        "context",
+        "Hard request-context budget threshold percentage.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_KEEP_TAIL_GROUPS",
+        "context",
+        "Recent event groups retained during normal compaction.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_MAX_RETRY_AFTER_PTL",
+        "context",
+        "Maximum controlled retries after prompt-too-long.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_RULE_FILES_MAX_TOKENS", "context", "Combined rule-file token budget."
+    ),
+    EnvVarSpec("KSADK_CONTEXT_RULE_FILE_MAX_TOKENS", "context", "Per rule-file token budget."),
+    EnvVarSpec(
+        "KSADK_CONTEXT_SAFETY_BUFFER_TOKENS", "context", "Reserved context-window safety buffer."
+    ),
+    EnvVarSpec("KSADK_CONTEXT_SEMANTIC_ENABLED", "context", "Enable semantic compaction.", "0"),
+    EnvVarSpec(
+        "KSADK_CONTEXT_SEMANTIC_TIMEOUT_MS",
+        "context",
+        "Semantic compaction timeout in milliseconds.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_SOFT_LIMIT_PERCENT",
+        "context",
+        "Soft request-context budget threshold percentage.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_TOOL_RESULT_MAX_TOKENS",
+        "context",
+        "Maximum token budget for one tool result.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_WORKING_STATE_ENABLED",
+        "context",
+        "Enable structured working-state extraction.",
+        "0",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_WORKING_STATE_EXTRACTION_TIMEOUT_MS",
+        "context",
+        "Working-state extraction timeout in milliseconds.",
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_WORKING_STATE_MAX_TOKENS", "context", "Working-state token budget."
+    ),
+    EnvVarSpec(
+        "KSADK_CONTEXT_WORKING_STATE_MIN_TOKEN_GROWTH",
+        "context",
+        "Minimum growth before refreshing working state.",
+    ),
+    EnvVarSpec(
+        "KSADK_LTM_FORCE_INMEMORY",
+        "memory",
+        "Force in-memory long-term-memory backend for tests.",
+        "0",
+    ),
+    EnvVarSpec("KSADK_MEMORY_CORE_MAX_TOKENS", "memory", "Core-memory token budget."),
+    EnvVarSpec("KSADK_MEMORY_DB_PATH", "memory", "Local PCM memory database path."),
+    EnvVarSpec("KSADK_MEMORY_ENABLED", "memory", "Enable platform memory projection.", "0"),
+    EnvVarSpec(
+        "KSADK_MEMORY_FLUSH_BEFORE_COMPACTION",
+        "memory",
+        "Flush memory candidates before compaction.",
+        "0",
+    ),
+    EnvVarSpec("KSADK_MEMORY_FLUSH_ENABLED", "memory", "Enable memory candidate commit.", "0"),
+    EnvVarSpec("KSADK_MEMORY_MIN_SCORE", "memory", "Minimum memory recall relevance score."),
+    EnvVarSpec(
+        "KSADK_MEMORY_MAX_RECORDS",
+        "memory",
+        "Maximum retained records for the local PCM memory provider.",
+        "10000",
+    ),
+    EnvVarSpec("KSADK_MEMORY_PROVIDER", "memory", "Platform memory provider selector."),
+    EnvVarSpec("KSADK_MEMORY_RECALL_MAX_TOKENS", "memory", "Memory recall token budget."),
+    EnvVarSpec("KSADK_MEMORY_RECALL_TOP_K", "memory", "Maximum recalled memory items."),
+    EnvVarSpec(
+        "KSADK_MEMORY_RETENTION_DAYS",
+        "memory",
+        "Retention period in days for the local PCM memory provider.",
+        "90",
+    ),
+    EnvVarSpec(
+        "KSADK_MEMORY_WRITE_MODE",
+        "memory",
+        "Memory write mode: off, explicit-only, or candidate.",
+    ),
+    EnvVarSpec(
+        "KSADK_PLATFORM_SAFETY_TEXT",
+        "prompt",
+        "Platform safety rules injected by the prompt compiler.",
+    ),
+    EnvVarSpec(
+        "KSADK_PROMPT_AUTO_DISCOVERY", "prompt", "Enable project prompt-source discovery.", "0"
+    ),
+    EnvVarSpec(
+        "KSADK_PROMPT_COMPILER_ENABLED", "prompt", "Enable structured prompt compilation.", "0"
+    ),
+    EnvVarSpec(
+        "KSADK_TOKENIZER_PROVIDER", "context", "Tokenizer provider used for context accounting."
+    ),
+)
+
+# PCM rollout, budget and diagnostic environment variables are internal runtime
+# controls. Public users configure the same behavior through AgentSpec policies,
+# so these names intentionally do not expand the public environment reference.
+PCM_ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = tuple(
+    replace(item, documented=False) for item in _PCM_ENV_VAR_REGISTRY_ITEMS
+)
+
+
+__all__ = ["PCM_ENV_VAR_REGISTRY_ITEMS"]

ksadk/configs/env_var_spec.py

@@ -0,0 +1,18 @@
+"""Shared environment-variable registry value object."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class EnvVarSpec:
+    name: str
+    module: str
+    purpose: str
+    default: str = ""
+    sensitive: bool = False
+    documented: bool = True
+
+
+__all__ = ["EnvVarSpec"]

ksadk/configs/global_config.py

@@ -43,8 +43,13 @@ CONFIG_GROUPS = {
         # 嵌套对象，get_env_from_global_config 跳过它（不当 env-var），build 保留它
         "IDENTITY_CACHE",
     ],
+    "evaluation": [
+        "AGENT_EVAL_BASE_URL",
+        "AGENT_EVAL_API_TOKEN",
+        "AGENT_EVAL_ACCOUNT_ID",
+    ],
     # 未来可扩展更多分组
-    # "observability": ["LANGFUSE_PUBLIC_KEY", ...],
+    # "observability": ["OTEL_EXPORTER_OTLP_ENDPOINT", ...],
     # "plugins": {...},
 }
 

ksadk/configs/settings.py

@@ -11,8 +11,8 @@ AgentEngine 统一配置管理
     print(settings.model.api_key)
     print(settings.model.api_base)
 
-    # 访问 Langfuse 配置
-    print(settings.langfuse.public_key)
+    # 访问标准 OpenTelemetry 配置
+    print(settings.otel.otlp_endpoint)
 
     # 访问 Agent 运行时信息
     print(settings.agent.agent_id)
@@ -263,73 +263,6 @@ class ModelConfig:
         return result
 
 
-# =============================================================================
-# Langfuse 配置
-# =============================================================================
-
-
-@dataclass
-class LangfuseConfig:
-    """Langfuse 可观测性配置
-
-    标准环境变量 (Langfuse 官方):
-        LANGFUSE_PUBLIC_KEY   - API Public Key
-        LANGFUSE_SECRET_KEY   - API Secret Key
-        LANGFUSE_HOST         - Langfuse 服务地址
-
-    Serverless 平台扩展:
-        LANGFUSE_PROJECT_ID   - 项目 ID (区分用户)
-        LANGCHAIN_TRACING_V2  - 启用 LangChain 追踪
-    """
-
-    @property
-    def public_key(self) -> Optional[str]:
-        return os.getenv("LANGFUSE_PUBLIC_KEY")
-
-    @property
-    def secret_key(self) -> Optional[str]:
-        return os.getenv("LANGFUSE_SECRET_KEY")
-
-    @property
-    def host(self) -> str:
-        return (
-            _get_env(
-                "LANGFUSE_HOST",
-                "LANGFUSE_BASE_URL",
-                default="http://localhost:3000",
-            )
-            or "http://localhost:3000"
-        )
-
-    @property
-    def project_id(self) -> Optional[str]:
-        """Langfuse 项目 ID (Serverless 平台扩展)"""
-        return os.getenv("LANGFUSE_PROJECT_ID")
-
-    @property
-    def tracing_enabled(self) -> bool:
-        """是否启用 LangChain tracing"""
-        return os.getenv("LANGCHAIN_TRACING_V2", "").lower() == "true"
-
-    @property
-    def is_enabled(self) -> bool:
-        """是否启用 Langfuse (有 public_key 就启用)"""
-        return bool(self.public_key)
-
-    @property
-    def is_configured(self) -> bool:
-        """是否完整配置"""
-        return bool(self.public_key and self.secret_key)
-
-    def to_dict(self) -> dict:
-        """转换为字典"""
-        return {
-            "public_key": self.public_key,
-            "secret_key": self.secret_key,
-            "host": self.host,
-        }
-
-
 # =============================================================================
 # Agent 配置
 # =============================================================================
@@ -438,39 +371,6 @@ class AgentConfig:
         """是否有 Agent 信息"""
         return bool(self.agent_id or self.agent_name)
 
-    # ------------------
-    # Langfuse 集成方法
-    # ------------------
-
-    def to_langfuse_params(self) -> dict:
-        """转换为 Langfuse trace() 方法的原生参数"""
-        params: Dict[str, Any] = {}
-        if self.session_id:
-            params["session_id"] = self.session_id
-        if self.user_id:
-            params["user_id"] = self.user_id
-        if self.tags:
-            params["tags"] = self.tags
-        if self.version:
-            params["version"] = self.version
-        return params
-
-    def to_langfuse_metadata(self) -> dict:
-        """转换为 Langfuse metadata 字段"""
-        metadata = {}
-        if self.agent_id:
-            metadata["agent_id"] = self.agent_id
-        if self.agent_name:
-            metadata["agent_name"] = self.agent_name
-        if self.tenant_id:
-            metadata["tenant_id"] = self.tenant_id
-        if self.environment:
-            metadata["environment"] = self.environment
-        if self.extra_metadata:
-            metadata.update(self.extra_metadata)
-        return metadata
-
-
 # =============================================================================
 # 金山云配置
 # =============================================================================
@@ -594,16 +494,15 @@ class Settings:
         if settings.model.is_configured:
             llm = LiteLLM(api_key=settings.model.api_key)
 
-        # Langfuse 配置
-        if settings.langfuse.is_enabled:
-            setup_tracing(langfuse_config=settings.langfuse.to_dict())
+        # 标准 OTLP 配置
+        if settings.otel.is_enabled:
+            setup_tracing()
 
         # Agent 信息
         print(settings.agent.agent_id)
     """
 
     model: ModelConfig = field(default_factory=ModelConfig)
-    langfuse: LangfuseConfig = field(default_factory=LangfuseConfig)
     agent: AgentConfig = field(default_factory=AgentConfig)
     cloud: KingsoftCloudConfig = field(default_factory=KingsoftCloudConfig)
     code: CodeModeConfig = field(default_factory=CodeModeConfig)
@@ -615,8 +514,6 @@ class Settings:
         lines.append(
             f"  Model:    {'✅ Configured' if self.model.is_configured else '❌ Not configured'}"
         )
-        lines.append(f"  Langfuse: {'✅ Enabled' if self.langfuse.is_enabled else '⚪ Disabled'}")
-
         agent_info = self.agent.agent_id or self.agent.agent_name
         lines.append(f"  Agent:    {'✅ ' + agent_info if agent_info else '⚪ No info'}")
 

ksadk/context_engine/__init__.py

@@ -0,0 +1,98 @@
+"""Context Engine —— Prompt/Context/Memory 的运行时上下文协调层。
+
+数据模型、capability 合同与 shadow 可观测基线已落地；后续 PR 新增 planner / assembler /
+policies / contributors 的实际逻辑。本模块导出稳定类型与运行时合同。
+"""
+
+from ksadk.context_engine.assembler import AssembledInput, ContextAssembler, assemble
+from ksadk.context_engine.capabilities import (
+    DEFAULT_CONTEXT_CAPABILITIES,
+    CapabilityCircuitOpen,
+    ContextAccuracy,
+    ContextCapabilities,
+    ContextIntegrationMode,
+    ContextOwner,
+    DeploymentMode,
+    adk_context_capabilities,
+    assert_capability_not_circuit_open,
+    capabilities_for_runner,
+    capabilities_for_runtime_type,
+    capability_hash,
+    codex_context_capabilities,
+    deepagents_context_capabilities,
+    detect_capability_mismatch,
+    is_capability_circuit_open,
+    langchain_context_capabilities,
+    langgraph_context_capabilities,
+    mark_capability_mismatch,
+    reset_capability_circuit,
+)
+from ksadk.context_engine.models import (
+    CONTEXT_POLICY_VERSION,
+    ContextBudget,
+    ContextDecision,
+    ContextItem,
+    ContextKind,
+    ContextPlan,
+)
+from ksadk.context_engine.planner import ContextPlanner, build_budget
+from ksadk.context_engine.policies import (
+    ContextBudgetPolicy,
+    ContextPolicy,
+    SectionBudget,
+    compute_budget_tokens,
+)
+from ksadk.context_engine.projection import PROJECTION_VERSION, ProjectionResult
+from ksadk.context_engine.tokenizer import (
+    HEURISTIC_TOKENIZER_NAME,
+    HeuristicTokenCounter,
+    TokenCounter,
+    get_default_token_counter,
+)
+
+__all__ = [
+    "AssembledInput",
+    "CONTEXT_POLICY_VERSION",
+    "ContextAssembler",
+    "ContextAccuracy",
+    "ContextBudget",
+    "ContextBudgetPolicy",
+    "ContextCapabilities",
+    "ContextDecision",
+    "ContextIntegrationMode",
+    "ContextItem",
+    "ContextKind",
+    "ContextOwner",
+    "ContextPlan",
+    "ContextPlanner",
+    "ContextPolicy",
+    "DEFAULT_CONTEXT_CAPABILITIES",
+    "DeploymentMode",
+    "HEURISTIC_TOKENIZER_NAME",
+    "HeuristicTokenCounter",
+    "PROJECTION_VERSION",
+    "ProjectionResult",
+    "SectionBudget",
+    "TokenCounter",
+    "adk_context_capabilities",
+    "assemble",
+    "build_budget",
+    "capabilities_for_runner",
+    "capabilities_for_runtime_type",
+    "capability_hash",
+    "codex_context_capabilities",
+    "compute_budget_tokens",
+    "deepagents_context_capabilities",
+    "detect_capability_mismatch",
+    "get_default_token_counter",
+    "is_capability_circuit_open",
+    "langchain_context_capabilities",
+    "langgraph_context_capabilities",
+    "mark_capability_mismatch",
+    "reset_capability_circuit",
+    "assert_capability_not_circuit_open",
+    "CapabilityCircuitOpen",
+    "allowed_ownership_choices",
+    "validate_ownership_for_runtime",
+    "resolve_ownership",
+]

ksadk/context_engine/assembler.py

@@ -0,0 +1,176 @@
+"""Context Assembler —— 把 ContextPlan.selected 投影成 messages/responses 输入（方案 §8）。
+
+Assembler 是 KsADK-owned（``ksadk_hosted``）路径的最终输入组装器：把 ``ContextPlan.selected``
+按方案 §7.4 的稳定前缀→部署级→动态后缀顺序投影成 Chat/Responses 格式。assisted/native 路径
+不调用本模块，由 RuntimeAdapter 自行投影（方案 §6.2）。
+
+第一个版本只实现 Chat messages 与 Responses items 两种合法投影，不含模型调用；actual_token
+由调用方在收到 usage 后回填 ``ContextPlan.runtime_reported_input_tokens``。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from ksadk.context_engine.models import ContextItem, ContextPlan
+
+ProjectionFormat = Literal["chat", "responses"]
+
+
+@dataclass(frozen=True)
+class AssembledInput:
+    """组装后的模型输入（shadow/可观测用，不直接发模型）。"""
+
+    format: ProjectionFormat
+    system: str
+    messages: list[dict[str, Any]]
+    responses_items: list[dict[str, Any]]
+    estimated_tokens: int
+    warnings: tuple[str, ...] = ()
+
+
+def _item_text(item: ContextItem) -> str:
+    content = item.content
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for part in content:
+            if isinstance(part, str):
+                parts.append(part)
+            elif isinstance(part, dict):
+                t = part.get("text") or part.get("content")
+                if isinstance(t, str):
+                    parts.append(t)
+        return "\n".join(parts)
+    return str(content or "")
+
+
+def _split_prompt_and_rest(selected: list[ContextItem]) -> tuple[str, list[ContextItem]]:
+    """稳定前缀（compiled_prompt）单独提为 system，其余按顺序进入 messages。"""
+    prompt_text = ""
+    rest: list[ContextItem] = []
+    for item in selected:
+        if item.kind == "compiled_prompt":
+            prompt_text = (
+                (prompt_text + "\n\n" + _item_text(item)).strip("\n\n")
+                if prompt_text
+                else _item_text(item)
+            )
+        else:
+            rest.append(item)
+    return prompt_text, rest
+
+
+def _role_for(item: ContextItem) -> str:
+    if item.kind == "current_input":
+        return "user"
+    if item.kind == "history_round":
+        # history_round 的 content 形如 {"role": "...", "content": ...} 或带 role metadata
+        role = item.metadata.get("role")
+        if isinstance(role, str):
+            return role
+        return "assistant"
+    if item.kind == "tool_result":
+        return "tool"
+    return "assistant"
+
+
+def _current_input_last(items: list[ContextItem]) -> list[ContextItem]:
+    """Keep the canonical current input at the end of Chat chronology.
+
+    Planner order represents retention priority, not physical message order. If
+    ``current_input`` is projected before selected history, the runner can treat
+    it as history and inject it again as the new input. Preserve every other
+    item's relative order and move only ``current_input`` to the end.
+    """
+
+    return [item for item in items if item.kind != "current_input"] + [
+        item for item in items if item.kind == "current_input"
+    ]
+
+
+class ContextAssembler:
+    """把 ContextPlan 投影成 Chat/Responses 输入（方案 §8）。
+
+    纯函数式、无副作用。``assemble_chat`` 输出 OpenAI Chat 风格 messages；
+    ``assemble_responses`` 输出 Responses API items。两者共用同一 selected 顺序。
+    """
+
+    def assemble_chat(self, plan: ContextPlan) -> AssembledInput:
+        system, rest = _split_prompt_and_rest(plan.selected)
+        rest = _current_input_last(rest)
+        messages: list[dict[str, Any]] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        warnings: list[str] = []
+        for item in rest:
+            role = _role_for(item)
+            content = _item_text(item)
+            if item.metadata.get("truncated_to_tokens") is not None:
+                warnings.append(f"{item.item_id}:truncated")
+            if item.metadata.get("replaced_with_artifact_summary"):
+                warnings.append(f"{item.item_id}:artifact_summary")
+            messages.append({"role": role, "content": content, "name": item.metadata.get("name")})
+        return AssembledInput(
+            format="chat",
+            system=system,
+            messages=messages,
+            responses_items=[],
+            estimated_tokens=plan.planned_input_tokens,
+            warnings=tuple(warnings),
+        )
+
+    def assemble_responses(self, plan: ContextPlan) -> AssembledInput:
+        system, rest = _split_prompt_and_rest(plan.selected)
+        rest = _current_input_last(rest)
+        items: list[dict[str, Any]] = []
+        if system:
+            items.append(
+                {
+                    "type": "message",
+                    "role": "system",
+                    "content": [{"type": "input_text", "text": system}],
+                }
+            )
+        warnings: list[str] = []
+        for item in rest:
+            role = _role_for(item)
+            content = _item_text(item)
+            if item.metadata.get("truncated_to_tokens") is not None:
+                warnings.append(f"{item.item_id}:truncated")
+            if item.kind == "tool_result":
+                # Responses function_call_output
+                call_id = str(
+                    item.metadata.get("call_id") or item.metadata.get("tool_call_id") or ""
+                )
+                items.append(
+                    {"type": "function_call_output", "call_id": call_id, "output": content}
+                )
+            else:
+                item_type = "input_text" if role == "user" else "output_text"
+                items.append(
+                    {
+                        "type": "message",
+                        "role": role,
+                        "content": [{"type": item_type, "text": content}],
+                    }
+                )
+        return AssembledInput(
+            format="responses",
+            system=system,
+            messages=[],
+            responses_items=items,
+            estimated_tokens=plan.planned_input_tokens,
+            warnings=tuple(warnings),
+        )
+
+
+def assemble(plan: ContextPlan, *, fmt: ProjectionFormat = "chat") -> AssembledInput:
+    """便捷入口。"""
+    asm = ContextAssembler()
+    return asm.assemble_chat(plan) if fmt == "chat" else asm.assemble_responses(plan)
+
+
+__all__ = ["AssembledInput", "ContextAssembler", "ProjectionFormat", "assemble"]