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

ksadk/builders/framework_requirements.py

@@ -4,30 +4,47 @@ from __future__ import annotations
 
 from typing import Iterable
 
-
-FASTAPI_REQUIREMENT = "fastapi>=0.100.0,<1.0.0"
+FASTAPI_REQUIREMENT = "fastapi>=0.136.0,<0.137.0"
+STARLETTE_REQUIREMENT = "starlette>=1.0,<1.4"
 
 ADK_REQUIREMENTS = (
-    "google-adk>=1.34.0,<2.0.0",
+    # goal-00: 与 ksadk 自身 adk extra 对齐,允许 1.34.x 与 2.x
+    "google-adk>=1.34.0,<3.0.0",
     "litellm>=1.0.0",
 )
 
 LANGCHAIN_ECOSYSTEM_REQUIREMENTS = (
-    "langchain>=1.3.0,<2.0.0",
-    "langchain-openai>=1.2.0,<2.0.0",
-    "langchain-core>=1.4.0,<2.0.0",
+    "langchain>=1.3.14,<2.0.0",
+    "langchain-openai>=1.4.0,<2.0.0",
+    "langchain-core>=1.5.0,<2.0.0",
     "langgraph>=1.2.0,<1.3.0",
 )
 
-DEEPAGENTS_REQUIREMENTS = (
-    "deepagents>=0.6.2,<1.0.0",
-)
+DEEPAGENTS_REQUIREMENTS = ("deepagents>=0.6.2,<1.0.0",)
+
+# codex runtime:openai-codex SDK(自带 codex CLI 二进制,见 PyPI cli-bin wheel)
+CODEX_REQUIREMENTS = ("openai-codex==0.144.4",)
+
+
+def code_requirements_for_framework(framework: str) -> list[str]:
+    """Dependencies safe to install into a portable Code artifact.
+
+    Codex carries a platform-selected executable package. ManagedRuntime code
+    bundles must remain system independent, so Codex is deliberately excluded
+    from this dependency policy.
+    """
+    normalized = (framework or "").strip().lower()
+    if normalized == "codex":
+        return []
+    return requirements_for_framework(normalized)
 
 
 def requirements_for_framework(framework: str) -> list[str]:
     normalized = (framework or "").strip().lower()
     if normalized == "adk":
         return list(ADK_REQUIREMENTS)
+    if normalized == "codex":
+        return list(CODEX_REQUIREMENTS)
     if normalized in {"langchain", "langgraph", "deepagents"}:
         requirements = list(LANGCHAIN_ECOSYSTEM_REQUIREMENTS)
         if normalized == "deepagents":
@@ -41,11 +58,13 @@ def minimal_requirements_for_framework(framework: str) -> list[str]:
     normalized = (framework or "").strip().lower()
     if normalized == "adk":
         return list(ADK_REQUIREMENTS)
+    if normalized == "codex":
+        return list(CODEX_REQUIREMENTS)
     if normalized in {"langchain", "langgraph", "deepagents"}:
         requirements = [
-            "langchain>=1.3.0,<2.0.0",
-            "langchain-openai>=1.2.0,<2.0.0",
-            "langchain-core>=1.4.0,<2.0.0",
+            "langchain>=1.3.14,<2.0.0",
+            "langchain-openai>=1.4.0,<2.0.0",
+            "langchain-core>=1.5.0,<2.0.0",
         ]
         if normalized in {"langgraph", "deepagents"}:
             requirements.append("langgraph>=1.2.0,<1.3.0")

ksadk/builders/ks3_uploader.py

@@ -5,13 +5,12 @@ KS3 上传模块 - 金山云对象存储上传
 import os
 import socket
 import time
-from pathlib import Path
 from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
 from typing import Optional
-import click
-
-from ks3.upload import UploadTask
 
+import click
+from ks3.upload import UploadTask  # type: ignore[import-untyped]
 
 from ksadk.common.constants import get_ks3_endpoints
 
@@ -28,9 +27,9 @@ class KS3Uploader:
     UPLOAD_TIMEOUT_PER_MB_SECONDS = 4.0
     UPLOAD_TIMEOUT_MAX_SECONDS = 3600
 
-    def __init__(self, region: str = "cn-beijing-6", bucket: str = None):
+    def __init__(self, region: str = "cn-beijing-6", bucket: Optional[str] = None):
         """初始化 KS3 上传器
-        
+
         Args:
             region: KS3 区域 (默认 cn-beijing-6)
             bucket: bucket 名称 (可选)
@@ -39,12 +38,12 @@ class KS3Uploader:
                    - 如果环境变量也未设置，默认使用 agentengine-{region}
         """
         self.region = region
-        
+
         # 确定 bucket 名称 (优先级: 参数 > 环境变量 > 默认值)
         if bucket:
             self.bucket_name = bucket
-        elif os.getenv("KS3_BUCKET"):
-            self.bucket_name = os.getenv("KS3_BUCKET")
+        elif env_bucket := os.getenv("KS3_BUCKET"):
+            self.bucket_name = env_bucket
         else:
             # Bucket 名称格式: agentengine-{account_id}-{region}
             account_id = os.getenv("KSYUN_ACCOUNT_ID")
@@ -68,7 +67,7 @@ class KS3Uploader:
                     "   或设置 KS3_BUCKET 显式指定 bucket 名称"
                 )
             self.bucket_name = f"agentengine-{account_id}-{region}"
-        
+
         self.custom_domain = None  # 可选的自定义域名
 
     def get_endpoint(self) -> str:
@@ -100,8 +99,12 @@ class KS3Uploader:
                 pass
 
         size_mb = file_path.stat().st_size / (1024 * 1024)
-        calculated = self.UPLOAD_TIMEOUT_BASE_SECONDS + int(size_mb * self.UPLOAD_TIMEOUT_PER_MB_SECONDS)
-        return min(self.UPLOAD_TIMEOUT_MAX_SECONDS, max(self.UPLOAD_CONNECT_TIMEOUT_SECONDS, calculated))
+        calculated = self.UPLOAD_TIMEOUT_BASE_SECONDS + int(
+            size_mb * self.UPLOAD_TIMEOUT_PER_MB_SECONDS
+        )
+        return min(
+            self.UPLOAD_TIMEOUT_MAX_SECONDS, max(self.UPLOAD_CONNECT_TIMEOUT_SECONDS, calculated)
+        )
 
     def _probe_endpoint_latency(self, host: str) -> Optional[float]:
         started_at = time.monotonic()
@@ -137,12 +140,16 @@ class KS3Uploader:
         if mode == "internal":
             add_candidate(internal_endpoint, "内网")
             add_candidate(public_endpoint, "公网")
-            return candidates, f"强制优先内网 {candidates[0]['host']}" if candidates else "未找到可用 KS3 endpoint"
+            return candidates, (
+                f"强制优先内网 {candidates[0]['host']}" if candidates else "未找到可用 KS3 endpoint"
+            )
 
         if mode == "public":
             add_candidate(public_endpoint, "公网")
             add_candidate(internal_endpoint, "内网")
-            return candidates, f"强制优先公网 {candidates[0]['host']}" if candidates else "未找到可用 KS3 endpoint"
+            return candidates, (
+                f"强制优先公网 {candidates[0]['host']}" if candidates else "未找到可用 KS3 endpoint"
+            )
 
         add_candidate(internal_endpoint, "内网")
         add_candidate(public_endpoint, "公网")
@@ -192,12 +199,24 @@ class KS3Uploader:
                 bucket_exists = False
             else:
                 if "AccessDenied" in error_str or "403" in error_str:
-                    click.secho(f"   ⚠️  提示: Bucket '{self.bucket_name}' 名称冲突或无权限访问 (403)。", fg="yellow")
-                    click.secho("      注意: KS3 Bucket 名称在全网范围内是全局唯一的！", fg="yellow")
+                    click.secho(
+                        f"   ⚠️  提示: Bucket '{self.bucket_name}' 名称冲突或无权限访问 (403)。",
+                        fg="yellow",
+                    )
+                    click.secho(
+                        "      注意: KS3 Bucket 名称在全网范围内是全局唯一的！", fg="yellow"
+                    )
                     click.secho("      该名称已被其他用户占用，您无法使用。", fg="yellow")
                     click.secho("   👉 解决方案:", fg="cyan")
-                    click.secho("      1. (推荐) 在 .env 中设置 KSYUN_ACCOUNT_ID 为您的账户 ID (自动生成唯一名称)。", fg="cyan")
-                    click.secho("      2. 或者，在 .env 中设置 KS3_BUCKET 为一个没人用过的唯一名称。", fg="cyan")
+                    click.secho(
+                        "      1. (推荐) 在 .env 中设置 KSYUN_ACCOUNT_ID 为您的账户 ID "
+                        "(自动生成唯一名称)。",
+                        fg="cyan",
+                    )
+                    click.secho(
+                        "      2. 或者，在 .env 中设置 KS3_BUCKET 为一个没人用过的唯一名称。",
+                        fg="cyan",
+                    )
                 raise
 
         if not bucket_exists:
@@ -206,10 +225,20 @@ class KS3Uploader:
                 click.secho(f"   ✓ Bucket 创建成功: {self.bucket_name}", fg="green")
             except Exception as create_err:
                 create_err_str = str(create_err)
-                if "Conflict" in create_err_str or "409" in create_err_str or "BucketAlreadyExists" in create_err_str:
-                    click.secho(f"   ⚠️  提示: Bucket '{self.bucket_name}' 名称已被其他用户占用。", fg="yellow")
+                if (
+                    "Conflict" in create_err_str
+                    or "409" in create_err_str
+                    or "BucketAlreadyExists" in create_err_str
+                ):
+                    click.secho(
+                        f"   ⚠️  提示: Bucket '{self.bucket_name}' 名称已被其他用户占用。",
+                        fg="yellow",
+                    )
                     click.secho("      注意: KS3 Bucket 名称是全局唯一的。", fg="yellow")
-                    click.secho("   👉 解决方法: 修改 .env 中的 KS3_BUCKET，换一个更复杂的名字再试。", fg="cyan")
+                    click.secho(
+                        "   👉 解决方法: 修改 .env 中的 KS3_BUCKET，换一个更复杂的名字再试。",
+                        fg="cyan",
+                    )
                 raise
 
         return bucket
@@ -229,7 +258,7 @@ class KS3Uploader:
         return record_dir / f"{safe_key}.ks3resume"
 
     def _upload_via_host(self, file_path: Path, object_key: str, host: str) -> bool:
-        from ks3.connection import Connection
+        from ks3.connection import Connection  # type: ignore[import-untyped]
 
         ak = os.environ.get("KSYUN_ACCESS_KEY") or os.environ.get("KS3_ACCESS_KEY")
         sk = os.environ.get("KSYUN_SECRET_KEY") or os.environ.get("KS3_SECRET_KEY")
@@ -299,7 +328,9 @@ class KS3Uploader:
             return None
 
         click.echo(f"   KS3 Endpoint 策略: {selection_summary}")
-        click.echo(f"   上传文件: {file_path.name} ({file_path.stat().st_size / (1024 * 1024):.2f} MB)")
+        click.echo(
+            f"   上传文件: {file_path.name} ({file_path.stat().st_size / (1024 * 1024):.2f} MB)"
+        )
         click.echo(f"   上传超时: {self._upload_timeout_seconds(file_path)} 秒")
 
         # 临时禁用系统代理 (ClashX 等会导致 KS3 上传走代理而失败)
@@ -369,17 +400,17 @@ class KS3Uploader:
     async def upload_with_url(self, file_path: Path, presigned_url: str) -> bool:
         """使用预签名 URL 上传文件 (不依赖本地 AK/SK)"""
         import httpx
-        
-        click.echo(f"   上传中 (使用预签名 URL)...")
-        
+
+        click.echo("   上传中 (使用预签名 URL)...")
+
         try:
             async with httpx.AsyncClient() as client:
-                with open(file_path, 'rb') as f:
+                with open(file_path, "rb") as f:
                     response = await client.put(
-                        presigned_url, 
+                        presigned_url,
                         content=f.read(),
                         headers={"Content-Type": "application/octet-stream"},
-                        timeout=300.0
+                        timeout=300.0,
                     )
                     response.raise_for_status()
                     click.secho("   ✓ 上传成功", fg="green")

ksadk/builders/managed_runtime_builder.py

@@ -0,0 +1,173 @@
+"""System-independent manifest bundles for platform-managed runtimes."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import zipfile
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ksadk.builders.base import BaseBuilder, BuildResult
+
+RUNTIME_MANIFEST_SCHEMA = "runtime-manifest/v1"
+_MANIFEST_KEYS = (
+    "name",
+    "version",
+    "framework",
+    "artifact_type",
+    "runtime",
+    "model",
+    "models",
+    "prompt",
+    "skills",
+    "mcp_servers",
+    "sandbox",
+    "approval_mode",
+)
+
+
+class _RuntimeManifestDumper(yaml.SafeDumper):
+    """Keep multi-line prompts readable while preserving deterministic bytes."""
+
+
+def _represent_manifest_string(dumper: yaml.SafeDumper, value: str):
+    style = "|" if "\n" in value else None
+    return dumper.represent_scalar("tag:yaml.org,2002:str", value, style=style)
+
+
+_RuntimeManifestDumper.add_representer(str, _represent_manifest_string)
+
+
+def serialize_managed_runtime_manifest(manifest: dict[str, Any]) -> bytes:
+    """Serialize the canonical ManagedRuntime manifest used by every client."""
+
+    return yaml.dump(
+        manifest,
+        Dumper=_RuntimeManifestDumper,
+        allow_unicode=True,
+        sort_keys=False,
+        default_flow_style=False,
+    ).encode("utf-8")
+
+
+class ManagedRuntimeBuilder(BaseBuilder):
+    """Build a deterministic YAML-only deployment artifact.
+
+    Runtime dependencies and local credentials intentionally never enter this
+    artifact. The managed runtime image supplies executable dependencies while
+    AgentEngine injects deployment-time credentials.
+    """
+
+    def __init__(
+        self,
+        project_dir: Path,
+        config: dict[str, Any] | None = None,
+        *,
+        runtime_version: str | None = None,
+    ) -> None:
+        super().__init__(project_dir, config)
+        self.runtime_version = str(runtime_version or "").strip()
+        self.build_dir = self.project_dir / ".agentengine" / "managed_runtime"
+
+    def build(self) -> BuildResult:
+        # An explicitly supplied snapshot is authoritative.  Studio can keep
+        # more than one Agent manifest in a workspace, so falling back to the
+        # root agentengine.yaml here would silently build the wrong Agent.
+        config = dict(self.config) if self.config else self._load_config()
+        error = self._validate_config(config)
+        if error:
+            return BuildResult(success=False, error_message=error)
+
+        runtime = dict(config.get("runtime") or {})
+        version = self.runtime_version or str(runtime.get("version") or "").strip()
+        if not version:
+            return BuildResult(
+                success=False,
+                error_message=(
+                    "ManagedRuntime 构建需要已解析的 runtime.version；"
+                    "请显式配置版本或连接 AgentEngine 获取服务端默认版本"
+                ),
+            )
+
+        runtime_name = str(runtime.get("name") or config.get("framework") or "").strip().lower()
+        runtime = {"name": runtime_name, "version": version}
+        manifest = self._normalized_manifest(config, runtime)
+        manifest_bytes = serialize_managed_runtime_manifest(manifest)
+        manifest_sha256 = hashlib.sha256(manifest_bytes).hexdigest()
+        lock = {
+            "schema_version": RUNTIME_MANIFEST_SCHEMA,
+            "runtime": runtime,
+            "manifest_sha256": manifest_sha256,
+        }
+        lock_bytes = (
+            json.dumps(lock, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+        ).encode("utf-8")
+
+        self.build_dir.mkdir(parents=True, exist_ok=True)
+        name = str(config.get("name") or self.project_dir.name).strip() or self.project_dir.name
+        project_version = str(config.get("version") or "1.0.0").strip() or "1.0.0"
+        artifact_path = self.build_dir / f"{name}-{project_version}-runtime.zip"
+        self._write_bundle(
+            artifact_path,
+            {
+                "agentengine.yaml": manifest_bytes,
+                "runtime-lock.json": lock_bytes,
+            },
+        )
+        return BuildResult(
+            success=True,
+            artifact_path=artifact_path,
+            artifact_size=artifact_path.stat().st_size,
+            metadata={
+                "agent_name": name,
+                "framework": str(config.get("framework") or ""),
+                "artifact_type": "ManagedRuntime",
+                "runtime_name": runtime_name,
+                "runtime_version": version,
+                "manifest_sha256": manifest_sha256,
+            },
+        )
+
+    @staticmethod
+    def _validate_config(config: dict[str, Any]) -> str | None:
+        framework = str(config.get("framework") or "").strip().lower()
+        artifact_type = str(config.get("artifact_type") or "").strip().lower()
+        runtime = config.get("runtime")
+        if framework != "codex":
+            return "当前 ManagedRuntime v1 仅支持 framework: codex"
+        if artifact_type != "managedruntime":
+            return "ManagedRuntime 项目必须配置 artifact_type: ManagedRuntime"
+        if not isinstance(runtime, dict):
+            return "ManagedRuntime 项目必须配置 runtime.name"
+        runtime_name = str(runtime.get("name") or "").strip().lower()
+        if runtime_name != "codex":
+            return "当前 ManagedRuntime v1 仅支持 runtime.name: codex"
+        return None
+
+    @staticmethod
+    def _normalized_manifest(
+        config: dict[str, Any],
+        runtime: dict[str, str],
+    ) -> dict[str, Any]:
+        normalized: dict[str, Any] = {}
+        for key in _MANIFEST_KEYS:
+            if key == "runtime":
+                normalized[key] = runtime
+            elif key == "artifact_type":
+                normalized[key] = "ManagedRuntime"
+            elif key in config:
+                normalized[key] = config[key]
+        return normalized
+
+    @staticmethod
+    def _write_bundle(path: Path, files: dict[str, bytes]) -> None:
+        with zipfile.ZipFile(path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+            for name in sorted(files):
+                info = zipfile.ZipInfo(name)
+                info.date_time = (1980, 1, 1, 0, 0, 0)
+                info.compress_type = zipfile.ZIP_DEFLATED
+                info.external_attr = 0o100644 << 16
+                archive.writestr(info, files[name])