agentengine-sdk-python 0.6.2__py3-none-any.whl → 0.6.9__py3-none-any.whl

ksadk/runners/base_runner.py

@@ -0,0 +1,305 @@
+"""
+BaseRunner - 运行时基类
+
+所有框架 Runner 的抽象基类，定义统一接口
+"""
+
+import inspect
+import os
+from abc import ABC, abstractmethod
+from typing import Any, AsyncIterator, Dict, Mapping, Optional
+
+from ksadk.sessions.continuity import RunnerSessionAdapter, TranscriptReplayAdapter
+
+
+class BaseRunner(ABC):
+    """运行时基类"""
+
+    def __init__(self, detection_result: Any, project_dir: str):
+        self.detection_result = detection_result
+        self.project_dir = project_dir
+        self._agent = None
+
+    @abstractmethod
+    def load_agent(self) -> None:
+        """加载 Agent"""
+        pass
+
+    @abstractmethod
+    async def invoke(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """同步调用 Agent
+
+        Args:
+            input_data: 输入数据，通常包含 {"input": "用户消息"}
+
+        Returns:
+            输出数据，通常包含 {"output": "Agent 回复"}
+        """
+        pass
+
+    @abstractmethod
+    async def stream(self, input_data: Dict[str, Any]) -> AsyncIterator[Dict[str, Any]]:
+        """流式调用 Agent
+
+        Args:
+            input_data: 输入数据
+
+        Yields:
+            流式输出的数据块
+        """
+        pass
+
+    @staticmethod
+    def normalize_requested_model(model: Optional[str]) -> Optional[str]:
+        if not isinstance(model, str):
+            return None
+        normalized = model.strip()
+        return normalized or None
+
+    @classmethod
+    def sync_process_model_env(cls, model: Optional[str]) -> Optional[str]:
+        normalized = cls.normalize_requested_model(model)
+        if normalized is None:
+            return None
+        os.environ["OPENAI_MODEL_NAME"] = normalized
+        os.environ["MODEL_NAME"] = normalized
+        return normalized
+
+    def prepare_for_request(self, model: Optional[str]) -> None:
+        """在请求进入实际 runner 前同步模型或做必要刷新。"""
+        self.sync_process_model_env(model)
+
+    def request_cancel(self, invocation_id: str) -> str:
+        """请求取消指定调用。
+
+        返回值用于 API 层区分真实取消、未命中和不支持取消的边界。
+        子类可返回 ``accepted``、``not_found`` 或 ``unsupported``。
+        """
+        return "unsupported"
+
+    def describe_checkpoint_capability(self) -> dict[str, Any]:
+        """描述框架级 checkpoint 能力。
+
+        默认 runner 只具备语义续聊，不声明可枚举/可回档的框架 checkpoint。
+        """
+        return {
+            "Supported": False,
+            "Backend": "none",
+            "Scope": "unknown",
+            "Durable": False,
+            "SharedAcrossPods": False,
+            "Reason": "runner does not expose framework checkpoints",
+        }
+
+    def get_runtime_capabilities(self) -> dict[str, Any]:
+        """返回控制台可消费的运行时能力声明。"""
+        detection_type = getattr(getattr(self, "detection_result", None), "type", None)
+        framework = str(getattr(detection_type, "value", detection_type) or "").strip().lower()
+        checkpoint = self.describe_checkpoint_capability()
+        checkpoint_supported = bool(checkpoint.get("Supported"))
+        checkpoint_reason = str(checkpoint.get("Reason") or "").strip()
+        cancel_supported = type(self).request_cancel is not BaseRunner.request_cancel
+        return {
+            "Framework": framework or self.__class__.__name__,
+            "CancelRun": {
+                "Supported": cancel_supported,
+                "RequestResults": (
+                    ["accepted", "not_found", "unsupported"]
+                    if cancel_supported
+                    else ["unsupported"]
+                ),
+                "Reason": ""
+                if cancel_supported
+                else "runner does not implement cooperative cancellation",
+            },
+            "Checkpoint": checkpoint,
+            "ResumeRun": {
+                "Supported": checkpoint_supported,
+                "ResumeMode": str(checkpoint.get("ResumeMode") or "none"),
+                "Reason": checkpoint_reason
+                if not checkpoint_supported
+                else str(checkpoint.get("ResumeReason") or ""),
+            },
+            "SessionContinuity": {
+                "Supported": True,
+                "Type": "semantic_replay",
+                "Level": "semantic",
+                "Reason": "conversation transcript can be replayed, but exact runtime checkpoint resume is not available",
+            },
+        }
+
+    async def close(self) -> None:
+        """释放 runner 持有的运行期资源。"""
+        return None
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        await self.close()
+        return False
+
+    def get_session_adapter(self) -> RunnerSessionAdapter:
+        return TranscriptReplayAdapter()
+
+    @staticmethod
+    def _callable_accepts_keyword(callable_obj: Any, keyword: str) -> bool:
+        try:
+            signature = inspect.signature(callable_obj)
+        except (TypeError, ValueError):
+            return False
+
+        for parameter in signature.parameters.values():
+            if parameter.kind == inspect.Parameter.VAR_KEYWORD:
+                return True
+        return keyword in signature.parameters
+
+    @classmethod
+    def _build_optional_call_kwargs(
+        cls,
+        callable_obj: Any,
+        *,
+        config: Optional[dict[str, Any]] = None,
+        context: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {}
+        if config is not None and cls._callable_accepts_keyword(callable_obj, "config"):
+            kwargs["config"] = config
+        if context is not None and cls._callable_accepts_keyword(callable_obj, "context"):
+            kwargs["context"] = context
+        return kwargs
+
+    @staticmethod
+    def build_native_context(platform_context: Any) -> dict[str, Any] | None:
+        if not isinstance(platform_context, dict):
+            return None
+        native_context = {
+            key: platform_context[key]
+            for key in ("agent_id", "user_id", "session_id")
+            if platform_context.get(key) is not None
+        }
+        return native_context or None
+
+    @staticmethod
+    def _int_usage_value(value: Any) -> int:
+        try:
+            return int(value or 0)
+        except (TypeError, ValueError):
+            return 0
+
+    @classmethod
+    def _message_usage(cls, message: Any) -> dict[str, Any]:
+        usage_metadata = getattr(message, "usage_metadata", None)
+        if isinstance(usage_metadata, Mapping):
+            input_tokens = cls._int_usage_value(usage_metadata.get("input_tokens"))
+            output_tokens = cls._int_usage_value(usage_metadata.get("output_tokens"))
+            input_token_details = usage_metadata.get("input_token_details")
+            output_token_details = usage_metadata.get("output_token_details")
+            if not any(
+                key in usage_metadata
+                for key in ("input_tokens", "output_tokens", "total_tokens")
+            ) and not (
+                isinstance(input_token_details, Mapping) and input_token_details
+            ) and not (
+                isinstance(output_token_details, Mapping) and output_token_details
+            ):
+                return {}
+            return {
+                "input_tokens": input_tokens,
+                "output_tokens": output_tokens,
+                "total_tokens": cls._int_usage_value(
+                    usage_metadata.get("total_tokens") or (input_tokens + output_tokens)
+                ),
+                "input_token_details": (
+                    dict(input_token_details) if isinstance(input_token_details, Mapping) else {}
+                ),
+                "output_token_details": (
+                    dict(output_token_details) if isinstance(output_token_details, Mapping) else {}
+                ),
+            }
+
+        response_metadata = getattr(message, "response_metadata", None)
+        if isinstance(response_metadata, Mapping):
+            token_usage = response_metadata.get("token_usage")
+            if isinstance(token_usage, Mapping):
+                input_tokens = cls._int_usage_value(token_usage.get("prompt_tokens"))
+                output_tokens = cls._int_usage_value(token_usage.get("completion_tokens"))
+                input_token_details: dict[str, Any] = {}
+                prompt_details = token_usage.get("prompt_tokens_details")
+                if isinstance(prompt_details, Mapping):
+                    cached_tokens = prompt_details.get("cached_tokens")
+                    if cached_tokens is not None:
+                        input_token_details["cached"] = cls._int_usage_value(cached_tokens)
+
+                output_token_details: dict[str, Any] = {}
+                completion_details = token_usage.get("completion_tokens_details")
+                if isinstance(completion_details, Mapping):
+                    reasoning_tokens = completion_details.get("reasoning_tokens")
+                    if reasoning_tokens is not None:
+                        output_token_details["reasoning"] = cls._int_usage_value(reasoning_tokens)
+                if not any(
+                    key in token_usage
+                    for key in ("prompt_tokens", "completion_tokens", "total_tokens")
+                ) and not input_token_details and not output_token_details:
+                    return {}
+                return {
+                    "input_tokens": input_tokens,
+                    "output_tokens": output_tokens,
+                    "total_tokens": cls._int_usage_value(
+                        token_usage.get("total_tokens") or (input_tokens + output_tokens)
+                    ),
+                    "input_token_details": input_token_details,
+                    "output_token_details": output_token_details,
+                }
+        return {}
+
+    @classmethod
+    def _extract_usage(cls, result: Any) -> dict[str, Any]:
+        if isinstance(result, Mapping):
+            direct_usage = result.get("usage")
+            if isinstance(direct_usage, Mapping):
+                return dict(direct_usage)
+
+            messages = result.get("messages")
+            if isinstance(messages, list):
+                for message in reversed(messages):
+                    usage = cls._message_usage(message)
+                    if usage:
+                        return usage
+
+        usage = cls._message_usage(result)
+        if usage:
+            return usage
+        return {}
+
+    @classmethod
+    def _extract_last_usage(cls, result: Any) -> dict[str, Any]:
+        """取最后一次 LLM 调用的 usage 快照(作 last_usage,窗口占用=input_tokens)。
+
+        方案 C:累积值走 stream on_chain_end 逐 event;invoke 非流式拿不到中间 call,
+        last_usage 作窗口占用(末次 input = 当前上下文占用)。优先 metadata.last_usage
+        (ADK 透传),否则 messages 末个。
+        """
+        if isinstance(result, Mapping):
+            metadata = result.get("metadata")
+            if isinstance(metadata, Mapping):
+                last_usage = metadata.get("last_usage")
+                if isinstance(last_usage, Mapping) and last_usage:
+                    return dict(last_usage)
+            messages = result.get("messages")
+            if isinstance(messages, list):
+                for message in reversed(messages):
+                    usage = cls._message_usage(message)
+                    if usage:
+                        return usage
+        usage = cls._message_usage(result)
+        return usage if usage else {}
+
+
+    def run_server(self, port: int = 8000) -> None:
+        """启动 HTTP Server"""
+        from ksadk.server import app, set_runner
+        import uvicorn
+
+        set_runner(self)
+        uvicorn.run(app, host="0.0.0.0", port=port)

ksadk/runners/deepagents_runner.py

@@ -0,0 +1,13 @@
+"""
+DeepAgentsRunner - DeepAgents 框架运行时
+
+DeepAgents 的 create_deep_agent 返回 LangGraph CompiledStateGraph，
+因此运行时复用 LangGraphRunner 逻辑，保持原生能力和行为一致。
+"""
+
+from ksadk.runners.langgraph_runner import LangGraphRunner
+
+
+class DeepAgentsRunner(LangGraphRunner):
+    """DeepAgents 运行时（复用 LangGraphRunner）"""
+

ksadk/runners/factory.py

@@ -0,0 +1,73 @@
+"""
+Runner Factory - 根据检测结果创建对应的 Runner
+"""
+
+import importlib
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+from ksadk.detection import DetectionResult, FrameworkType
+from ksadk.runners.base_runner import BaseRunner
+
+if TYPE_CHECKING:
+    pass
+
+
+def create_runner(detection_result: DetectionResult, project_dir: str) -> BaseRunner:
+    """根据检测结果创建对应的 Runner
+    
+    Args:
+        detection_result: 框架检测结果
+        project_dir: 项目目录
+    
+    Returns:
+        对应框架的 Runner 实例
+    """
+    # Apply langchain patch for reasoning_content support
+    try:
+        from ksadk.runners.patch_langchain import apply_patch
+
+        apply_patch()
+    except ImportError:
+        pass
+
+    custom_runner_class = str(getattr(detection_result, "runner_class", "") or "").strip()
+    if custom_runner_class:
+        project_path = Path(project_dir).resolve()
+        for candidate in (project_path, project_path / "src"):
+            if candidate.is_dir() and str(candidate) not in sys.path:
+                sys.path.insert(0, str(candidate))
+        module_name, separator, class_name = custom_runner_class.rpartition(".")
+        if not separator or not module_name or not class_name:
+            raise ValueError(
+                "runner_class must use a fully-qualified class path, "
+                "for example 'agent.CustomRunner'"
+            )
+        try:
+            module = importlib.import_module(module_name)
+            runner_class = getattr(module, class_name)
+        except (ImportError, AttributeError) as exc:
+            raise ValueError(f"无法加载自定义 Runner: {custom_runner_class}") from exc
+        if not isinstance(runner_class, type) or not issubclass(runner_class, BaseRunner):
+            raise TypeError(f"自定义 Runner 必须继承 BaseRunner: {custom_runner_class}")
+        runner = runner_class(detection_result, project_dir)
+        return runner
+
+    if detection_result.type == FrameworkType.ADK:
+        from ksadk.runners.adk_runner import ADKRunner
+        return ADKRunner(detection_result, project_dir)
+    
+    elif detection_result.type == FrameworkType.LANGGRAPH:
+        from ksadk.runners.langgraph_runner import LangGraphRunner
+        return LangGraphRunner(detection_result, project_dir)
+    
+    elif detection_result.type == FrameworkType.LANGCHAIN:
+        from ksadk.runners.langchain_runner import LangChainRunner
+        return LangChainRunner(detection_result, project_dir)
+
+    elif detection_result.type == FrameworkType.DEEPAGENTS:
+        from ksadk.runners.deepagents_runner import DeepAgentsRunner
+        return DeepAgentsRunner(detection_result, project_dir)
+    
+    else:
+        raise ValueError(f"不支持的框架类型: {detection_result.type}")