agentscope-runtime 1.0.0b2__py3-none-any.whl → 1.0.2__py3-none-any.whl

agentscope_runtime/engine/deployers/utils/k8s_utils.py

@@ -0,0 +1,241 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-nested-blocks,too-many-return-statements
+
+import logging
+import os
+from typing import Optional
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+def isLocalK8sEnvironment() -> bool:
+    """
+    Determine whether the current environment is a local Kubernetes setup.
+
+    This function uses multi-dimensional heuristics for detection:
+    1. Inspect kubeconfig context name
+    2. Inspect cluster server address
+    3. Check environment variables
+    4. Query Kubernetes API (if accessible)
+    5. Analyze network characteristics
+
+    Returns:
+        bool: True if running in a local cluster, False otherwise (
+        cloud/production)
+    """
+
+    # Results from various detection methods
+    detection_results = {
+        "kubeconfig_context": _check_kubeconfig_context(),
+        "k8s_api": _check_kubernetes_api(),
+    }
+
+    # Log detection results
+    logger.info(f"K8s environment detection results: {detection_results}")
+
+    # Voting: if majority of applicable checks indicate 'local', return True
+    local_votes = sum(
+        1 for result in detection_results.values() if result is True
+    )
+    total_votes = sum(
+        1 for result in detection_results.values() if result is not None
+    )
+
+    if total_votes == 0:
+        logger.warning(
+            "Unable to determine K8s environment type; defaulting to "
+            "cloud/remote",
+        )
+        return False
+
+    is_local = local_votes > (total_votes / 2)
+    logger.info(
+        f"Final verdict: "
+        f"{'Local environment' if is_local else 'Cloud/remote environment'} "
+        f"(votes: {local_votes}/{total_votes})",
+    )
+
+    return is_local
+
+
+def _check_kubeconfig_context() -> Optional[bool]:
+    """
+    Inspect kubeconfig current context name for local-cluster patterns.
+
+    Returns:
+        Optional[bool]: True=local, False=cloud, None=undetermined
+    """
+    try:
+        import yaml
+
+        kubeconfig_path = os.path.expanduser(
+            os.getenv("KUBECONFIG", "~/.kube/config"),
+        )
+
+        if not os.path.exists(kubeconfig_path):
+            logger.debug("kubeconfig file not found")
+            return None
+
+        with open(kubeconfig_path, "r", encoding="utf-8") as f:
+            config = yaml.safe_load(f)
+
+        if not config or "current-context" not in config:
+            return None
+
+        current_context = config["current-context"]
+
+        # Common context name patterns for local K8s tools
+        local_patterns = [
+            "minikube",
+            "kind-",
+            "k3s",
+            "k3d-",
+            "microk8s",
+            "docker-desktop",
+            "docker-for-desktop",
+            "localhost",
+            "rancher-desktop",
+            "colima",
+        ]
+
+        # Patterns commonly associated with cloud providers
+        cloud_patterns = [
+            "gke_",
+            "arn:aws:eks",
+            "aks-",
+            "do-",  # DigitalOcean
+            "prod-",
+            "production",
+        ]
+
+        current_context_lower = current_context.lower()
+
+        # Match local patterns
+        if any(pattern in current_context_lower for pattern in local_patterns):
+            logger.debug(f"Context '{current_context}' matches local pattern")
+            return True
+
+        # Match cloud patterns
+        if any(pattern in current_context_lower for pattern in cloud_patterns):
+            logger.debug(f"Context '{current_context}' matches cloud pattern")
+            return False
+
+        # Inspect cluster server URL in config
+        contexts = config.get("contexts", [])
+        clusters = config.get("clusters", [])
+
+        for ctx in contexts:
+            if ctx.get("name") == current_context:
+                cluster_name = ctx.get("context", {}).get("cluster")
+
+                for cluster in clusters:
+                    if cluster.get("name") == cluster_name:
+                        server = cluster.get("cluster", {}).get("server", "")
+
+                        # Check for localhost/loopback addresses
+                        if any(
+                            addr in server
+                            for addr in [
+                                "192.168.5.1",
+                                "127.0.0.1",
+                                "localhost",
+                                "0.0.0.0",
+                            ]
+                        ):
+                            logger.debug(
+                                f"Cluster server '{server}' points to "
+                                f"localhost",
+                            )
+                            return True
+        return None
+
+    except ImportError:
+        logger.warning(
+            "PyYAML not installed; cannot parse kubeconfig. "
+            "Install via: pip install pyyaml",
+        )
+        return None
+    except Exception as e:
+        logger.debug(f"Error checking kubeconfig: {e}")
+        return None
+
+
+def _check_kubernetes_api() -> Optional[bool]:
+    """
+    Query the Kubernetes API for local-environment signatures.
+
+    Returns:
+        Optional[bool]: True=local, False=cloud, None=undetermined
+    """
+    try:
+        from kubernetes import client, config
+
+        # Load config — in-cluster first, then kubeconfig
+        try:
+            config.load_incluster_config()
+        except Exception:
+            try:
+                config.load_kube_config()
+            except Exception:
+                logger.debug("Failed to load Kubernetes configuration")
+                return None
+
+        v1 = client.CoreV1Api()
+
+        # Check node info
+        nodes = v1.list_node()
+
+        if len(nodes.items) == 1:
+            node = nodes.items[0]
+            node_name = node.metadata.name.lower()
+
+            # Local node name patterns
+            local_node_patterns = [
+                "minikube",
+                "kind-",
+                "k3s",
+                "k3d-",
+                "docker-desktop",
+                "localhost",
+                "rancher-desktop",
+            ]
+
+            if any(pattern in node_name for pattern in local_node_patterns):
+                logger.debug(f"Node name '{node_name}' matches local pattern")
+                return True
+
+            # Check node labels
+            labels = node.metadata.labels or {}
+
+            if "minikube.k8s.io/name" in labels:
+                return True
+            if "node.kubernetes.io/instance-type" in labels:
+                instance_type = labels["node.kubernetes.io/instance-type"]
+                if instance_type in ["k3s", "k3d"]:
+                    return True
+
+        # Check namespaces for local-tool signatures
+        namespaces = v1.list_namespace()
+        namespace_names = [ns.metadata.name for ns in namespaces.items]
+
+        local_namespaces = [
+            "cattle-system",  # Rancher/K3s
+            "local-path-storage",  # Kind/K3s/MicroK8s
+        ]
+
+        if any(ns in namespace_names for ns in local_namespaces):
+            logger.debug("Detected local-environment namespace")
+            return True
+
+        return None
+
+    except ImportError:
+        logger.warning(
+            "kubernetes client not installed; API detection disabled. "
+            "Install via: pip install kubernetes",
+        )
+        return None
+    except Exception as e:
+        logger.debug(f"Error querying K8s API: {e}")
+        return None

agentscope_runtime/engine/deployers/utils/package.py

@@ -16,7 +16,6 @@ import inspect
 import logging
 import os
 import shutil
-import tempfile
 import zipfile
 from pathlib import Path
 from typing import Optional, List, Tuple, Union
@@ -30,6 +29,44 @@ DEPLOYMENT_ZIP = "deployment.zip"
 TEMPLATES_DIR = Path(__file__).parent / "templates"
 DEFAULT_ENTRYPOINT_FILE = "runtime_main.py"
 
+# Default workspace for build artifacts
+DEFAULT_BUILD_WORKSPACE = Path(os.getcwd()) / ".agentscope_runtime" / "builds"
+
+
+def generate_build_directory(
+    platform: str = "unknown",
+    workspace: Optional[Path] = None,
+) -> Path:
+    """
+    Generate a platform-aware build directory with timestamp and random suffix.
+
+    Args:
+        platform: Deployment platform (k8s, modelstudio, agentrun, local, etc.)
+        workspace: Custom workspace directory (defaults to
+                DEFAULT_BUILD_WORKSPACE)
+
+    Returns:
+        Path: Generated build directory path
+
+    Example:
+        >>> build_dir = generate_build_directory("modelstudio")
+        >>> # Returns: .agentscope_runtime/builds/modelstudio_20251207_xxx
+    """
+    import random
+    import time
+
+    if workspace is None:
+        workspace = DEFAULT_BUILD_WORKSPACE
+
+    workspace.mkdir(parents=True, exist_ok=True)
+
+    # Generate timestamp-based name with random suffix
+    timestamp = time.strftime("%Y%m%d_%H%M%S")
+    random_suffix = "".join(random.choices("0123456789abcdef", k=6))
+    build_name = f"{platform}_{timestamp}_{random_suffix}"
+
+    return workspace / build_name
+
 
 def _get_template_env() -> Environment:
     """
@@ -254,7 +291,7 @@ def _auto_detect_entrypoint(project_dir: str) -> str:
     - app.py
     - main.py
     - __main__.py
-    - run.py
+    - chat.py
     - runner.py
 
     Args:
@@ -270,7 +307,7 @@ def _auto_detect_entrypoint(project_dir: str) -> str:
         "app.py",
         "main.py",
         "__main__.py",
-        "run.py",
+        "chat.py",
         "runner.py",
     ]
 
@@ -432,6 +469,7 @@ def _get_default_ignore_patterns() -> List[str]:
         ".vscode",
         "*.log",
         "logs",
+        ".agentscope_runtime",  # Ignore build workspace
     ]
 
 
@@ -547,6 +585,8 @@ def package(
     host: str = "0.0.0.0",
     port: int = 8090,
     extra_parameters: Optional[List[RuntimeParameter]] = None,
+    requirements: Optional[List[str]] = None,
+    platform: str = "unknown",
     **kwargs,
 ) -> Tuple[str, ProjectInfo]:
     """
@@ -562,6 +602,13 @@ def package(
     2. Generate a new main.py that imports and runs the app/runner
     3. Package the project with the generated main.py as entrypoint
 
+    Build directory naming:
+    - When output_dir=None (default), creates workspace directory with
+                platform-aware naming
+    - Directory format: cwd/.agentscope_runtime/builds/<platform>_
+                 <timestamp>_<code>/
+    - Explicit output_dir uses the provided path
+
     Args:
         app: AgentApp instance (for object-style deployment)
         runner: Runner instance (for object-style deployment)
@@ -570,6 +617,8 @@ def package(
         host: Default host for the service (default: "0.0.0.0")
         port: Default port for the service (default: 8090)
         extra_parameters: Additional runtime parameters to expose via CLI
+        requirements: Additional pip requirements
+        platform: Deployment platform (k8s, modelstudio, agentrun, local)
         **kwargs: Additional keyword arguments (ignored)
 
     Returns:
@@ -597,7 +646,7 @@ def package(
         ...         help="Number of worker threads"
         ...     ),
         ... ]
-        >>> package(app=my_app, extra_parameters=extra_params)
+        >>> package(app=my_app, extra_parameters=extra_params, platform="k8s")
     """
     # Determine project info and target object
     target_obj = None
@@ -613,9 +662,10 @@ def package(
 
     logger.info(f"Packaging project from: {project_info.project_dir}")
 
-    # Create output directory
+    # Create output directory with platform-aware naming
     if output_dir is None:
-        output_dir = tempfile.mkdtemp(prefix="agentscope_package_")
+        output_dir = str(generate_build_directory(platform))
+        os.makedirs(output_dir, exist_ok=True)
     else:
         os.makedirs(output_dir, exist_ok=True)
 

agentscope_runtime/engine/deployers/utils/service_utils/fastapi_factory.py

@@ -470,13 +470,27 @@ class FastAPIAppFactory:
             }
 
         # Mode-specific endpoints
-        if mode == DeploymentMode.DETACHED_PROCESS:
-            FastAPIAppFactory._add_process_control_endpoints(app)
+        FastAPIAppFactory._add_process_control_endpoints(app)
 
     @staticmethod
     def _add_process_control_endpoints(app: FastAPI):
         """Add process control endpoints for detached mode."""
 
+        @app.post("/shutdown")
+        async def shutdown_process_simple():
+            """Gracefully shutdown the process (simple endpoint)."""
+            # Import here to avoid circular imports
+            import os
+            import signal
+
+            # Schedule shutdown after response
+            async def delayed_shutdown():
+                await asyncio.sleep(0.5)
+                os.kill(os.getpid(), signal.SIGTERM)
+
+            asyncio.create_task(delayed_shutdown())
+            return {"status": "shutting down"}
+
         @app.post("/admin/shutdown")
         async def shutdown_process():
             """Gracefully shutdown the process."""
@@ -693,9 +707,32 @@ class FastAPIAppFactory:
         parsing."""
         is_async_gen = inspect.isasyncgenfunction(handler)
 
+        # NOTE:
+        # -----
+        # FastAPI >= 0.123.5 uses Dependant.is_coroutine_callable, which in
+        # turn unwraps callables via inspect.unwrap() and then inspects the
+        # unwrapped target to decide whether it is a coroutine function /
+        # generator / async generator.
+        #
+        # If we decorate an async-generator handler with
+        # functools.wraps(handler), FastAPI will unwrap back to the original
+        # async-generator function and *misclassify* the endpoint as
+        # non-coroutine. It will then call our async wrapper *without awaiting
+        # it*, and later try to JSON-encode the resulting coroutine object,
+        # causing errors like:
+        # TypeError("'coroutine' object is not iterable")
+        #
+        # To avoid that, we deliberately do NOT use functools.wraps() here.
+        # Instead, we manually copy the key metadata (name, qualname, doc,
+        # module, and signature) from the original handler, but we do NOT set
+        # __wrapped__. This ensures:
+        #   * FastAPI sees the wrapper itself as the callable (an async def),
+        #     so Dependant.is_coroutine_callable is True, and it is properly
+        #     awaited.
+        #   * FastAPI still sees the correct signature for parameter parsing.
+
         if is_async_gen:
 
-            @functools.wraps(handler)
             async def wrapped_handler(*args, **kwargs):
                 async def generate():
                     try:
@@ -720,12 +757,8 @@ class FastAPIAppFactory:
                     media_type="text/event-stream",
                 )
 
-            wrapped_handler.__signature__ = inspect.signature(handler)
-            return wrapped_handler
-
         else:
 
-            @functools.wraps(handler)
             def wrapped_handler(*args, **kwargs):
                 def generate():
                     try:
@@ -748,8 +781,34 @@ class FastAPIAppFactory:
                     media_type="text/event-stream",
                 )
 
-            wrapped_handler.__signature__ = inspect.signature(handler)
-            return wrapped_handler
+        # Manually propagate essential metadata without creating a __wrapped__
+        # chain that would confuse FastAPI's unwrap logic.
+        wrapped_handler.__name__ = getattr(
+            handler,
+            "__name__",
+            wrapped_handler.__name__,
+        )
+        wrapped_handler.__qualname__ = getattr(
+            handler,
+            "__qualname__",
+            wrapped_handler.__qualname__,
+        )
+        wrapped_handler.__doc__ = getattr(
+            handler,
+            "__doc__",
+            wrapped_handler.__doc__,
+        )
+        wrapped_handler.__module__ = getattr(
+            handler,
+            "__module__",
+            wrapped_handler.__module__,
+        )
+        wrapped_handler.__signature__ = inspect.signature(handler)
+
+        # Make sure FastAPI doesn't see any stale __wrapped__ pointing back to
+        # the original async-generator; if present, remove it.
+
+        return wrapped_handler
 
     @staticmethod
     def _add_custom_endpoints(app: FastAPI):

agentscope_runtime/engine/deployers/utils/service_utils/process_manager.py

@@ -19,6 +19,8 @@ class ProcessManager:
             shutdown_timeout: Timeout in seconds for graceful shutdown
         """
         self.shutdown_timeout = shutdown_timeout
+        self._log_file = None
+        self._log_file_handle = None
 
     async def start_detached_process(
         self,
@@ -47,7 +49,25 @@ class ProcessManager:
             if env:
                 process_env.update(env)
 
-            # Start detached process
+            # Create log file path with timestamp and child process PID
+            # We'll update the filename after process starts
+            log_dir = "/tmp/agentscope_runtime_logs"
+            os.makedirs(log_dir, exist_ok=True)
+
+            # Use a temporary name first, will rename after getting PID
+            import time
+
+            timestamp = time.strftime("%Y%m%d_%H%M%S")
+            temp_log_file = os.path.join(
+                log_dir,
+                f"process_temp_{timestamp}_{os.getpid()}.log",
+            )
+
+            # Open log file (don't use 'with' to keep it open for the
+            # subprocess)
+            log_f = open(temp_log_file, "w", encoding="utf-8")
+
+            # Start detached process with log file
             process = subprocess.Popen(
                 [
                     "python",
@@ -57,22 +77,63 @@ class ProcessManager:
                     "--port",
                     str(port),
                 ],
-                stdout=subprocess.DEVNULL,
-                stderr=subprocess.DEVNULL,
+                stdout=log_f,
+                stderr=subprocess.STDOUT,  # Redirect stderr to stdout
                 stdin=subprocess.DEVNULL,
                 start_new_session=True,  # Create new process group
                 env=process_env,
                 cwd=os.path.dirname(script_path),
             )
 
+            # Rename log file with actual process PID
+            log_file = os.path.join(log_dir, f"process_{process.pid}.log")
+            log_f.close()  # Close temp file
+            os.rename(temp_log_file, log_file)
+
+            # Reopen with the correct name
+            log_f = open(log_file, "a", encoding="utf-8")
+
+            # Store log file path and handle for later retrieval
+            self._log_file = log_file
+            self._log_file_handle = log_f
+
             # Verify process started successfully
-            await asyncio.sleep(0.1)  # Give process time to start
+            await asyncio.sleep(
+                0.5,
+            )  # Give process time to start and write logs
             if process.poll() is not None:
-                raise RuntimeError("Process failed to start")
+                # Process failed to start, wait a bit more for logs to be
+                # flushed
+                await asyncio.sleep(0.2)
+                # Read logs and print them
+                logs = self.get_process_logs(max_lines=50)
+                import logging
+
+                logger = logging.getLogger(__name__)
+                logger.error(
+                    f"Process failed to start immediately.\n\n"
+                    f"Process logs:\n{logs}",
+                )
+                raise RuntimeError(
+                    "Process failed to start. Check logs above.",
+                )
 
             return process.pid
 
+        except RuntimeError:
+            # Re-raise RuntimeError with logs already included
+            raise
         except Exception as e:
+            # For other exceptions, try to include logs if available
+            if self._log_file:
+                logs = self.get_process_logs(max_lines=50)
+                import logging
+
+                logger = logging.getLogger(__name__)
+                logger.error(
+                    f"Failed to start detached process: {e}\n\n"
+                    f"Process logs:\n{logs}",
+                )
             raise RuntimeError(f"Failed to start detached process: {e}") from e
 
     async def stop_process_gracefully(
@@ -125,6 +186,9 @@ class ProcessManager:
             raise RuntimeError(
                 f"Failed to terminate process {pid}: {e}",
             ) from e
+        finally:
+            # Close log file handle if open
+            self._close_log_file()
 
     def is_process_running(self, pid: int) -> bool:
         """Check if a process is running.
@@ -271,6 +335,92 @@ class ProcessManager:
 
         return False
 
+    def get_process_logs(self, max_lines: int = 50) -> str:
+        """Get the last N lines of process logs.
+
+        Args:
+            max_lines: Maximum number of lines to return
+
+        Returns:
+            Log content as string
+        """
+        if not self._log_file or not os.path.exists(self._log_file):
+            return "No log file available"
+
+        try:
+            # Flush the log file handle if it's still open
+            if self._log_file_handle and not self._log_file_handle.closed:
+                self._log_file_handle.flush()
+
+            with open(self._log_file, "r", encoding="utf-8") as f:
+                lines = f.readlines()
+                if not lines:
+                    return (
+                        "Log file is empty (process may not have written "
+                        "any output yet)"
+                    )
+                # Return last N lines
+                return "".join(lines[-max_lines:])
+        except Exception as e:
+            return f"Failed to read log file: {e}"
+
+    def _close_log_file(self):
+        """Close log file handle if open."""
+        if self._log_file_handle and not self._log_file_handle.closed:
+            try:
+                self._log_file_handle.close()
+            except Exception:
+                pass  # Ignore errors when closing
+
+    def cleanup_log_file(self, keep_file: bool = False):
+        """Clean up log file.
+
+        Args:
+            keep_file: If True, keep the log file on disk but close the handle.
+                      If False, delete the log file.
+        """
+        self._close_log_file()
+
+        if not keep_file and self._log_file and os.path.exists(self._log_file):
+            try:
+                os.remove(self._log_file)
+            except Exception:
+                pass  # Ignore cleanup errors
+
+        self._log_file = None
+        self._log_file_handle = None
+
+    @staticmethod
+    def cleanup_old_logs(max_age_hours: int = 24):
+        """Clean up old log files.
+
+        Args:
+            max_age_hours: Remove log files older than this many hours
+        """
+        import time
+
+        log_dir = "/tmp/agentscope_runtime_logs"
+        if not os.path.exists(log_dir):
+            return
+
+        current_time = time.time()
+        max_age_seconds = max_age_hours * 3600
+
+        try:
+            for filename in os.listdir(log_dir):
+                if filename.startswith("process_") and filename.endswith(
+                    ".log",
+                ):
+                    filepath = os.path.join(log_dir, filename)
+                    try:
+                        file_age = current_time - os.path.getmtime(filepath)
+                        if file_age > max_age_seconds:
+                            os.remove(filepath)
+                    except Exception:
+                        pass  # Ignore errors for individual files
+        except Exception:
+            pass  # Ignore errors during cleanup
+
     @staticmethod
     def _normalize_host_for_check(host: str) -> str:
         """Normalize host for connection check.