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

ksadk/runners/usage_accumulator.py

@@ -0,0 +1,38 @@
+"""usage 累加工具:逐字段求和(input/output/total + details 子键)。
+
+用于 runner 本轮内多次 LLM 调用的 usage 累积。input_tokens 各 provider 均含 cache
+(Gemini prompt_token_count 含 cached_content_token_count;OpenAI prompt_tokens 含
+cached_tokens;Anthropic 经 langchain_anthropic 转换后 input_tokens 含 cache_read+
+cache_creation),直接相加不重复;input_token_details 键名不统一(cached/cache_read/
+cache_creation),逐键求和作诊断明细。
+"""
+from __future__ import annotations
+
+from typing import Any
+
+_MAIN_FIELDS = ("input_tokens", "output_tokens", "total_tokens")
+_DETAIL_FIELDS = ("input_token_details", "output_token_details")
+
+
+def accumulate_usage(acc: dict[str, Any], delta: dict[str, Any]) -> dict[str, Any]:
+    """把 delta 累加进 acc,返回新 dict(不改 acc)。"""
+    if not delta:
+        return dict(acc)
+    result = dict(acc)
+    for key in _MAIN_FIELDS:
+        result[key] = int(result.get(key) or 0) + int(delta.get(key) or 0)
+    for detail_key in _DETAIL_FIELDS:
+        delta_details = delta.get(detail_key)
+        if not isinstance(delta_details, dict):
+            continue
+        merged = dict(result.get(detail_key) or {})
+        for k, v in delta_details.items():
+            if v is None:
+                continue
+            try:
+                merged[k] = int(merged.get(k) or 0) + int(v)
+            except (TypeError, ValueError):
+                continue
+        if merged:
+            result[detail_key] = merged
+    return result

ksadk/runners/utils/__init__.py

@@ -0,0 +1,19 @@
+"""
+Runner 公共工具模块
+"""
+
+from ksadk.runners.utils.langfuse import (
+    get_langfuse_callback,
+    get_langfuse_callbacks,
+    get_langfuse_metadata,
+    prepare_trace_metadata,
+)
+from ksadk.runners.utils.loader import load_agent_module
+
+__all__ = [
+    "get_langfuse_callback",
+    "get_langfuse_callbacks",
+    "get_langfuse_metadata",
+    "prepare_trace_metadata",
+    "load_agent_module",
+]

ksadk/runners/utils/langfuse.py

@@ -0,0 +1,230 @@
+"""
+Langfuse 集成工具
+
+提供 LangChain/LangGraph Runner 共用的 Langfuse 集成功能
+"""
+
+import logging
+import os
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# 全局缓存
+_langfuse_callback = None
+_cloud_monitor_langfuse_callback = None
+
+
+def _env_flag_enabled(name: str) -> bool:
+    return os.getenv(name, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _env_flag_disabled(name: str) -> bool:
+    return os.getenv(name, "").strip().lower() in {"0", "false", "no", "off", "disabled"}
+
+
+def _first_env(*names: str) -> str:
+    for name in names:
+        value = os.getenv(name, "").strip()
+        if value:
+            return value
+    return ""
+
+
+def _create_langfuse_callback(
+    *,
+    label: str,
+    public_key: str,
+    secret_key: str = "",
+    host: str = "",
+) -> Any | None:
+    try:
+        from langfuse import Langfuse
+        from langfuse.langchain import CallbackHandler
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+
+        resource_attributes = {}
+        service_name = os.getenv("OTEL_SERVICE_NAME", "").strip()
+        if service_name:
+            resource_attributes["service.name"] = service_name
+        tracer_provider = TracerProvider(resource=Resource.create(resource_attributes))
+        Langfuse(
+            public_key=public_key,
+            secret_key=secret_key or None,
+            base_url=host or None,
+            tracer_provider=tracer_provider,
+        )
+        try:
+            handler = CallbackHandler(public_key=public_key)
+        except TypeError:
+            handler = CallbackHandler()
+        logger.info(
+            "%s Langfuse CallbackHandler initialized "
+            "(host: %s public_key_present=%s secret_key_present=%s isolated_provider=True)",
+            label,
+            host or "default",
+            bool(public_key),
+            bool(secret_key),
+        )
+        return handler
+    except ImportError as e:
+        logger.warning("Langfuse not installed for %s callback: %s", label, e)
+        return None
+    except Exception as e:
+        logger.error("Failed to create %s Langfuse CallbackHandler: %s", label, e)
+        return None
+
+
+def get_langfuse_callback():
+    """获取 Langfuse CallbackHandler
+
+    Returns:
+        CallbackHandler 实例，未配置时返回 None
+    """
+    global _langfuse_callback
+
+    if not _env_flag_enabled("LANGFUSE_USE_CALLBACK"):
+        logger.debug("Langfuse CallbackHandler disabled; using OTLP direct exporter by default")
+        return None
+
+    if _langfuse_callback is not None:
+        return _langfuse_callback
+
+    # 检查是否配置了 Langfuse
+    public_key = os.getenv("LANGFUSE_PUBLIC_KEY", "").strip()
+    if not public_key:
+        return None
+
+    _langfuse_callback = _create_langfuse_callback(
+        label="Primary",
+        public_key=public_key,
+        secret_key=os.getenv("LANGFUSE_SECRET_KEY", "").strip(),
+        host=_first_env("LANGFUSE_HOST", "LANGFUSE_BASE_URL"),
+    )
+    return _langfuse_callback
+
+
+def get_cloud_monitor_langfuse_callback():
+    """获取云监控 Langfuse SDK CallbackHandler。"""
+    global _cloud_monitor_langfuse_callback
+
+    if not _env_flag_enabled("LANGFUSE_USE_CALLBACK"):
+        return None
+    if _env_flag_disabled("CLOUD_MONITOR_LANGFUSE_ENABLED"):
+        logger.info(
+            "CloudMonitor Langfuse CallbackHandler disabled by CLOUD_MONITOR_LANGFUSE_ENABLED"
+        )
+        return None
+    if _cloud_monitor_langfuse_callback is not None:
+        return _cloud_monitor_langfuse_callback
+
+    public_key = os.getenv("CLOUD_MONITOR_LANGFUSE_PUBLIC_KEY", "").strip()
+    secret_key = os.getenv("CLOUD_MONITOR_LANGFUSE_SECRET_KEY", "").strip()
+    host = _first_env("CLOUD_MONITOR_LANGFUSE_HOST", "CLOUD_MONITOR_OTLP_ENDPOINT")
+    if not public_key and not secret_key and not host:
+        return None
+    if not public_key or not secret_key or not host:
+        logger.warning(
+            "CloudMonitor Langfuse CallbackHandler skipped: public_key_present=%s "
+            "secret_key_present=%s host_present=%s",
+            bool(public_key),
+            bool(secret_key),
+            bool(host),
+        )
+        return None
+
+    _cloud_monitor_langfuse_callback = _create_langfuse_callback(
+        label="CloudMonitor",
+        public_key=public_key,
+        secret_key=secret_key,
+        host=host,
+    )
+    return _cloud_monitor_langfuse_callback
+
+
+def get_langfuse_callbacks() -> list[Any]:
+    """获取所有 Langfuse CallbackHandler，原平台和云监控各自独立。"""
+    callbacks = []
+    primary = get_langfuse_callback()
+    if primary:
+        callbacks.append(primary)
+
+    cloud_monitor = get_cloud_monitor_langfuse_callback()
+    if cloud_monitor:
+        callbacks.append(cloud_monitor)
+
+    return callbacks
+
+
+def get_langfuse_metadata(session_id: str = None) -> dict:
+    """获取 Langfuse 的 metadata 字典
+
+    通过 metadata 字段传递 trace 属性:
+    - langfuse_user_id
+    - langfuse_session_id
+    - langfuse_tags
+
+    Args:
+        session_id: 会话 ID (可选)
+
+    Returns:
+        包含 Langfuse 属性的 metadata 字典
+    """
+    metadata = {}
+
+    if session_id:
+        metadata["langfuse_session_id"] = session_id
+
+    try:
+        from ksadk.configs import settings
+
+        agent_config = settings.agent
+
+        if agent_config.user_id:
+            metadata["langfuse_user_id"] = agent_config.user_id
+
+        if not session_id and agent_config.session_id:
+            metadata["langfuse_session_id"] = agent_config.session_id
+
+        tags = list(agent_config.tags or [])
+        if agent_config.environment and agent_config.environment not in tags:
+            tags.append(agent_config.environment)
+        if agent_config.agent_name and agent_config.agent_name not in tags:
+            tags.append(agent_config.agent_name)
+        if tags:
+            metadata["langfuse_tags"] = tags
+
+    except (ImportError, Exception):
+        pass
+
+    return metadata
+
+
+def prepare_trace_metadata(session_id: str = None) -> tuple:
+    """准备 Trace 元数据
+
+    Returns:
+        (user_id, tags, version, agent_name) 元组
+    """
+    user_id = None
+    tags = []
+    version = None
+    agent_name = None
+
+    try:
+        from ksadk.configs import settings
+
+        agent_config = settings.agent
+        user_id = agent_config.user_id
+        tags = list(agent_config.tags or [])
+        version = agent_config.version
+        agent_name = agent_config.agent_name
+
+        if agent_config.environment and agent_config.environment not in tags:
+            tags.append(agent_config.environment)
+
+    except (ImportError, Exception):
+        pass
+
+    return user_id, tags, version, agent_name

ksadk/runners/utils/loader.py

@@ -0,0 +1,62 @@
+"""
+模块加载工具
+
+提供通用的 Agent 模块加载逻辑
+"""
+
+import importlib
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def load_agent_module(
+    project_dir: str,
+    entry_point: str,
+    agent_variable: str,
+    *,
+    force_reload: bool = False,
+) -> Any:
+    """加载 Agent 模块
+    
+    Args:
+        project_dir: 项目目录
+        entry_point: 入口文件 (e.g., "agent.py")
+        agent_variable: Agent 变量名 (e.g., "root_agent", "graph")
+    
+    Returns:
+        加载的 Agent 对象
+    
+    Raises:
+        ImportError: 模块导入失败
+        AttributeError: 未找到 Agent 变量
+    """
+    project_path = Path(project_dir).resolve()
+    
+    # 添加项目目录到 Python 路径
+    if str(project_path) not in sys.path:
+        sys.path.insert(0, str(project_path))
+    src_path = project_path / "src"
+    if src_path.is_dir() and str(src_path) not in sys.path:
+        sys.path.insert(0, str(src_path))
+    
+    # 确定模块名
+    if entry_point.endswith(".py"):
+        module_name = entry_point[:-3]
+    else:
+        module_name = entry_point
+    
+    # 路径转换为模块路径
+    module_name = module_name.replace("/", ".").replace("\\", ".")
+    
+    try:
+        if force_reload and module_name in sys.modules:
+            module = importlib.reload(sys.modules[module_name])
+        else:
+            module = importlib.import_module(module_name)
+        agent = getattr(module, agent_variable)
+        return agent, module
+    except ImportError as e:
+        raise ImportError(f"无法导入模块 {module_name}: {e}")
+    except AttributeError:
+        raise AttributeError(f"模块 {module_name} 中未找到 {agent_variable}")

ksadk/runtime_context.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from typing import Any, Iterator
+
+
+@dataclass
+class PlatformInvocationContext:
+    agent_id: str
+    user_id: str
+    session_id: str
+    history: list[dict[str, Any]]
+    input_content: list[dict[str, Any]]
+    input_messages: list[dict[str, Any]]
+    input_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
+    runner_type: str
+    account_id: str = ""
+    model: str | None = None
+    model_options: dict[str, Any] | None = None
+    kb_context: dict[str, Any] | None = None
+    memory_context: dict[str, Any] | None = None
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "agent_id": self.agent_id,
+            "user_id": self.user_id,
+            "account_id": self.account_id,
+            "session_id": self.session_id,
+            "history": list(self.history or []),
+            "input_content": list(self.input_content or []),
+            "input_messages": list(self.input_messages or []),
+            "input_parts": list(self.input_parts or []),
+            "attachments": list(self.attachments or []),
+            "attachment_results": list(self.attachment_results or []),
+            "current_attachments": list(self.current_attachments or []),
+            "current_attachment_results": list(self.current_attachment_results or []),
+            "has_current_files": self.has_current_files,
+            "runner_type": self.runner_type,
+            "model": self.model,
+            "model_options": dict(self.model_options or {}),
+        }
+
+
+@dataclass
+class ToolExecutionContext:
+    session_id: str = ""
+    run_id: str = ""
+    invocation_id: str = ""
+
+
+_CURRENT_PLATFORM_INVOCATION_CONTEXT: ContextVar[PlatformInvocationContext | None] = ContextVar(
+    "ksadk_platform_invocation_context",
+    default=None,
+)
+
+_CURRENT_TOOL_EXECUTION_CONTEXT: ContextVar[ToolExecutionContext | None] = ContextVar(
+    "ksadk_tool_execution_context",
+    default=None,
+)
+
+
+def get_current_invocation_context() -> PlatformInvocationContext | None:
+    return _CURRENT_PLATFORM_INVOCATION_CONTEXT.get()
+
+
+def get_current_invocation_context_or_default() -> PlatformInvocationContext:
+    context = get_current_invocation_context()
+    if context is not None:
+        return context
+    return PlatformInvocationContext(
+        agent_id="",
+        user_id="",
+        account_id="",
+        session_id="",
+        history=[],
+        input_content=[],
+        input_messages=[],
+        input_parts=[],
+        attachments=[],
+        attachment_results=[],
+        current_attachments=[],
+        current_attachment_results=[],
+        has_current_files=False,
+        runner_type="",
+    )
+
+
+def get_current_tool_execution_context_or_default() -> ToolExecutionContext:
+    context = _CURRENT_TOOL_EXECUTION_CONTEXT.get()
+    if context is not None:
+        return context
+    return ToolExecutionContext()
+
+
+def get_current_user_id(default: str = "") -> str:
+    context = get_current_invocation_context()
+    if context is None:
+        return default
+    return str(context.user_id or default)
+
+
+def get_current_account_id(default: str = "") -> str:
+    context = get_current_invocation_context()
+    if context is None:
+        return default
+    return str(context.account_id or default)
+
+
+def set_current_invocation_context(
+    context: PlatformInvocationContext | None,
+) -> Token[PlatformInvocationContext | None]:
+    return _CURRENT_PLATFORM_INVOCATION_CONTEXT.set(context)
+
+
+def reset_current_invocation_context(
+    token: Token[PlatformInvocationContext | None],
+) -> None:
+    _CURRENT_PLATFORM_INVOCATION_CONTEXT.reset(token)
+
+
+def set_current_tool_execution_context(
+    context: ToolExecutionContext | None,
+) -> Token[ToolExecutionContext | None]:
+    return _CURRENT_TOOL_EXECUTION_CONTEXT.set(context)
+
+
+def reset_current_tool_execution_context(
+    token: Token[ToolExecutionContext | None],
+) -> None:
+    _CURRENT_TOOL_EXECUTION_CONTEXT.reset(token)
+
+
+@contextmanager
+def platform_invocation_scope(
+    context: PlatformInvocationContext | None,
+) -> Iterator[PlatformInvocationContext | None]:
+    token = set_current_invocation_context(context)
+    try:
+        yield context
+    finally:
+        reset_current_invocation_context(token)
+
+
+@contextmanager
+def tool_execution_scope(
+    session_id: str,
+    run_id: str | None = None,
+    invocation_id: str | None = None,
+) -> Iterator[ToolExecutionContext]:
+    context = ToolExecutionContext(
+        session_id=str(session_id or ""),
+        run_id=str(run_id or ""),
+        invocation_id=str(invocation_id or ""),
+    )
+    token = set_current_tool_execution_context(context)
+    try:
+        yield context
+    finally:
+        reset_current_tool_execution_context(token)

ksadk/runtime_state.py

@@ -0,0 +1,25 @@
+"""Runtime-safe helpers for reading local AgentEngine state."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+STATE_FILE_NAME = ".agentengine.state"
+
+
+def load_state(project_dir: Path) -> dict[str, Any]:
+    """Load .agentengine.state without importing deployment-only modules."""
+
+    state_file = Path(project_dir) / STATE_FILE_NAME
+    if not state_file.exists():
+        return {}
+
+    try:
+        with state_file.open("r", encoding="utf-8") as handle:
+            return yaml.safe_load(handle) or {}
+    except Exception:
+        return {}

ksadk/sandbox/__init__.py

@@ -0,0 +1,28 @@
+from ksadk.sandbox.backends.e2b import E2BSandboxBackend, E2BSandboxSession
+from ksadk.sandbox.backends.local_process import LocalProcessSandboxBackend, LocalProcessSandboxSession
+from ksadk.sandbox.base import (
+    SandboxBackend,
+    SandboxCommandResult,
+    SandboxError,
+    SandboxInputFile,
+    SandboxSession,
+    SandboxSpec,
+    SandboxType,
+)
+from ksadk.sandbox.factory import create_sandbox_backend, sandbox_spec_from_env
+
+__all__ = [
+    "E2BSandboxBackend",
+    "E2BSandboxSession",
+    "LocalProcessSandboxBackend",
+    "LocalProcessSandboxSession",
+    "SandboxBackend",
+    "SandboxCommandResult",
+    "SandboxError",
+    "SandboxInputFile",
+    "SandboxSession",
+    "SandboxSpec",
+    "SandboxType",
+    "create_sandbox_backend",
+    "sandbox_spec_from_env",
+]

ksadk/sandbox/backends/__init__.py

@@ -0,0 +1,9 @@
+from ksadk.sandbox.backends.e2b import E2BSandboxBackend, E2BSandboxSession
+from ksadk.sandbox.backends.local_process import LocalProcessSandboxBackend, LocalProcessSandboxSession
+
+__all__ = [
+    "E2BSandboxBackend",
+    "E2BSandboxSession",
+    "LocalProcessSandboxBackend",
+    "LocalProcessSandboxSession",
+]