cloudbase-agent-server 0.1.9__py3-none-any.whl

cloudbase_agent/__init__.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Cloudbase Agent Server Package.
+
+This package extends the base Cloudbase Agent package with server functionality.
+"""
+
+__all__ = []

cloudbase_agent/server/__init__.py

@@ -0,0 +1,91 @@
+"""Cloudbase Agent Server Package.
+
+This package provides server components for the Cloudbase Agent Python SDK,
+including FastAPI integration, request handling, streaming responses,
+and resource cleanup support.
+
+Core Capabilities (Primary Exports):
+    - create_send_message_adapter: Create adapter for Cloudbase Agent native send_message endpoint
+    - create_openai_adapter: Create adapter for OpenAI-compatible chat/completions endpoint
+
+Convenience Tools (Secondary Exports):
+    - AgentServiceApp: FastAPI application wrapper for quick server setup
+
+Data Models:
+    - RunAgentInput: Request model for send_message endpoint
+    - OpenAIChatCompletionRequest: Request model for OpenAI-compatible endpoint
+    - AgentCreatorResult: TypedDict for agent creator return type
+    - AgentCreator: Type alias for agent creator functions
+
+Example:
+    Using core capabilities (advanced users)::
+
+        from fastapi import FastAPI
+        from cloudbase_agent.server import create_send_message_adapter, create_openai_adapter
+        from cloudbase_agent.server import RunAgentInput, OpenAIChatCompletionRequest
+
+        def create_agent():
+            return {"agent": MyAgent()}
+
+        app = FastAPI()
+
+        @app.post("/custom/send-message")
+        async def send_message(request: RunAgentInput):
+            return await create_send_message_adapter(create_agent, request)
+
+        @app.post("/custom/chat/completions")
+        async def chat_completions(request: OpenAIChatCompletionRequest):
+            return await create_openai_adapter(create_agent, request)
+
+    Using convenience tool (quick start)::
+
+        from cloudbase_agent.server import AgentServiceApp
+
+        def create_agent():
+            return {"agent": MyAgent()}
+
+        AgentServiceApp().run(create_agent, port=8000)
+
+    With resource cleanup::
+
+        from cloudbase_agent.server import AgentServiceApp, AgentCreatorResult
+
+        def create_agent() -> AgentCreatorResult:
+            db = connect_database()
+            agent = MyAgent(db)
+
+            def cleanup():
+                db.close()
+                print("Resources cleaned up")
+
+            return {"agent": agent, "cleanup": cleanup}
+
+        AgentServiceApp().run(create_agent, port=8000)
+"""
+
+# Core capabilities (primary exports)
+# Convenience tool (secondary export)
+from .app import AgentServiceApp
+from .healthz.models import HealthzConfig, HealthzResponse
+from .openai.models import OpenAIChatCompletionRequest
+from .openai.server import create_adapter as create_openai_adapter
+
+# Data models
+from .send_message.models import RunAgentInput
+from .send_message.server import create_adapter as create_send_message_adapter
+from .utils.types import AgentCreator, AgentCreatorResult
+
+__all__ = [
+    # Core capabilities (primary)
+    "create_send_message_adapter",
+    "create_openai_adapter",
+    # Convenience tool (secondary)
+    "AgentServiceApp",
+    # Data models
+    "RunAgentInput",
+    "OpenAIChatCompletionRequest",
+    "HealthzConfig",
+    "HealthzResponse",
+    "AgentCreatorResult",
+    "AgentCreator",
+]

cloudbase_agent/server/app.py

@@ -0,0 +1,371 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Cloudbase Agent API Application.
+
+This module provides a convenient FastAPI application wrapper for Cloudbase Agent agents,
+offering both quick one-line startup and advanced customization options.
+"""
+
+import os
+from typing import Any, Optional
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from .healthz.handler import create_healthz_handler
+from .healthz.models import HealthzConfig
+from .openai.models import OpenAIChatCompletionRequest
+from .openai.server import create_adapter as create_openai_adapter
+from .send_message.models import RunAgentInput
+from .send_message.server import create_adapter as create_send_message_adapter
+from .utils.types import AgentCreator
+
+
+class AgentServiceApp:
+    r"""FastAPI Application Wrapper for Cloudbase Agent Agents.
+
+    This class provides a simple and flexible way to deploy Cloudbase Agent agents
+    as web services. It supports both quick one-line startup and advanced
+    customization through the build() method.
+
+    Key Features:
+        - One-line server startup with run()
+        - Flexible configuration with method chaining
+        - Advanced customization with build()
+        - Automatic environment detection (e.g., Tencent Cloud SCF)
+        - Resource cleanup support
+
+    Example:
+        Quick start (one line)::
+
+            AgentServiceApp().run(create_agent, port=8000)
+
+        With configuration (method chaining)::
+
+            AgentServiceApp() \
+                .set_cors_config(allow_origins=["*"]) \
+                .run(create_agent, port=8000, reload=True)
+
+        Advanced usage (build method)::
+
+            app = AgentServiceApp()
+            fastapi_app = app.build(create_agent, base_path="/api")
+
+            # Add custom routes
+            @fastapi_app.get("/custom")
+            def custom_route():
+                return {"custom": "data"}
+
+            # Run manually
+            import uvicorn
+            uvicorn.run(fastapi_app, port=8000)
+    """
+
+    def __init__(self, auto_detect_env: bool = True):
+        """Initialize the Cloudbase Agent API application.
+
+        :param auto_detect_env: Automatically detect runtime environment
+                               (e.g., Tencent Cloud SCF) and configure accordingly
+        :type auto_detect_env: bool
+        """
+        self._cors_config: Optional[dict[str, Any]] = None
+        self._base_path: str = ""
+
+        # Auto-detect environment if enabled
+        if auto_detect_env:
+            self._detect_environment()
+
+    def _detect_environment(self) -> None:
+        """Detect runtime environment and apply environment-specific configuration."""
+        # Tencent Cloud SCF
+        if os.getenv("TENCENTCLOUD_RUNENV") == "SCF":
+            self._base_path = "/v1/aibot/bots"
+
+    def set_cors_config(
+        self,
+        allow_origins: Optional[list[str]] = None,
+        allow_credentials: bool = True,
+        allow_methods: Optional[list[str]] = None,
+        allow_headers: Optional[list[str]] = None,
+        **kwargs: Any,
+    ) -> "AgentServiceApp":
+        r"""Set CORS configuration for the application.
+
+        :param allow_origins: List of allowed origins, defaults to ["*"]
+        :type allow_origins: Optional[list[str]]
+        :param allow_credentials: Whether to allow credentials, defaults to True
+        :type allow_credentials: bool
+        :param allow_methods: List of allowed HTTP methods, defaults to ["*"]
+        :type allow_methods: Optional[list[str]]
+        :param allow_headers: List of allowed headers, defaults to ["*"]
+        :type allow_headers: Optional[list[str]]
+        :param kwargs: Additional CORS configuration options
+        :type kwargs: Any
+        :return: Self for method chaining
+        :rtype: AgentServiceApp
+
+        Example:
+            Method chaining::
+
+                AgentServiceApp() \
+                    .set_cors_config(
+                        allow_origins=["https://example.com"],
+                        allow_credentials=True
+                    ) \
+                    .run(create_agent, port=8000)
+        """
+        self._cors_config = {
+            "allow_origins": allow_origins or ["*"],
+            "allow_credentials": allow_credentials,
+            "allow_methods": allow_methods or ["*"],
+            "allow_headers": allow_headers or ["*"],
+            **kwargs,
+        }
+        return self
+
+    def build(
+        self,
+        create_agent: AgentCreator,
+        base_path: str = "",
+        enable_cors: bool = True,
+        enable_openai_endpoint: bool = False,
+        enable_healthz: bool = True,
+        healthz_config: Optional[HealthzConfig] = None,
+        **fastapi_kwargs: Any,
+    ) -> FastAPI:
+        """Build and return a configured FastAPI application.
+
+        This method creates a FastAPI instance with all routes and middleware
+        configured. Use this when you need to customize the application before
+        running it (e.g., adding custom routes, middleware, or event handlers).
+
+        :param create_agent: Function that creates and returns agent with optional cleanup
+        :type create_agent: AgentCreator
+        :param base_path: Base path for agent routes (overrides environment-detected path)
+        :type base_path: str
+        :param enable_cors: Whether to enable CORS middleware
+        :type enable_cors: bool
+        :param enable_openai_endpoint: Whether to enable OpenAI-compatible /chat/completions endpoint
+        :type enable_openai_endpoint: bool
+        :param enable_healthz: Whether to enable health check endpoint (default: True)
+        :type enable_healthz: bool
+        :param healthz_config: Optional health check configuration
+        :type healthz_config: Optional[HealthzConfig]
+        :param fastapi_kwargs: Additional keyword arguments to pass to FastAPI constructor
+                              (e.g., title, description, version)
+        :type fastapi_kwargs: Any
+        :return: Configured FastAPI application
+        :rtype: FastAPI
+
+        Example:
+            Build and customize::
+
+                app = AgentServiceApp()
+                fastapi_app = app.build(
+                    create_agent,
+                    base_path="/api",
+                    title="My Agent API",
+                    version="1.0.0"
+                )
+
+                # Add custom routes
+                @fastapi_app.get("/custom")
+                def custom_route():
+                    return {"custom": "data"}
+
+                # Add custom middleware
+                @fastapi_app.middleware("http")
+                async def add_custom_header(request, call_next):
+                    response = await call_next(request)
+                    response.headers["X-Custom-Header"] = "value"
+                    return response
+
+                # Run the application
+                import uvicorn
+                uvicorn.run(fastapi_app, host="0.0.0.0", port=8000)
+
+            With custom health check::
+
+                from cloudbase_agent.server import HealthzConfig
+
+                def check_database():
+                    # Perform database health check
+                    if not db.is_connected():
+                        raise Exception("Database not connected")
+                    return {"database": "connected"}
+
+                config = HealthzConfig(
+                    service_name="my-agent-service",
+                    version="2.0.0",
+                    custom_checks=check_database
+                )
+
+                fastapi_app = AgentServiceApp().build(
+                    create_agent,
+                    healthz_config=config
+                )
+
+            Disable health check::
+
+                fastapi_app = AgentServiceApp().build(
+                    create_agent,
+                    enable_healthz=False  # No /healthz endpoint
+                )
+        """
+        # Create FastAPI instance
+        app = FastAPI(**fastapi_kwargs)
+
+        # Apply CORS middleware if enabled
+        if enable_cors:
+            cors_config = self._cors_config or {
+                "allow_origins": ["*"],
+                "allow_credentials": True,
+                "allow_methods": ["*"],
+                "allow_headers": ["*"],
+            }
+            app.add_middleware(CORSMiddleware, **cors_config)
+
+        # Determine final path (environment base path + user base path)
+        final_path = self._base_path + base_path
+
+        # Register send_message endpoint
+        @app.post(f"{final_path}/{{agent_id}}/send-message")
+        async def send_message_endpoint(agent_id: str, request: RunAgentInput):
+            """Main agent endpoint for processing messages with Cloudbase Agent native format.
+            
+            Args:
+                agent_id: Agent identifier (reserved for future use)
+                request: Message request payload
+            """
+            # agent_id parameter is reserved for future use
+            return await create_send_message_adapter(create_agent, request)
+
+        # Register health check endpoint if enabled
+        if enable_healthz:
+            healthz_handler = create_healthz_handler(
+                config=healthz_config,
+                base_path=final_path,
+            )
+
+            @app.get(f"{final_path}/healthz")
+            def healthz_endpoint() -> dict[str, Any]:
+                """Health check endpoint.
+
+                Returns server status and metadata for monitoring and diagnostics.
+                This endpoint is automatically added to all Cloudbase Agent servers and can
+                be used by load balancers, monitoring systems, and orchestration
+                platforms to verify service health.
+
+                The response includes:
+                - Service status (healthy/unhealthy)
+                - Timestamp of the check
+                - Service name and version
+                - Python runtime version
+                - Base path configuration
+                - Optional custom check results
+
+                Returns:
+                    dict: Health check response with status and metadata
+
+                Example Response:
+                    {
+                        "status": "healthy",
+                        "timestamp": "2024-01-01T00:00:00.000Z",
+                        "service": "Cloudbase Agent-python-server",
+                        "version": "1.0.0",
+                        "python_version": "3.11.0",
+                        "base_path": "/"
+                    }
+                """
+                return healthz_handler()
+
+        # Register OpenAI-compatible endpoint if enabled
+        if enable_openai_endpoint:
+
+            @app.post(f"{final_path}/chat/completions")
+            async def chat_completions_endpoint(request: OpenAIChatCompletionRequest):
+                """OpenAI-compatible chat completions endpoint.
+
+                This endpoint provides compatibility with OpenAI's chat completion API,
+                allowing Cloudbase Agent agents to be used as drop-in replacements for OpenAI models.
+                """
+                return await create_openai_adapter(create_agent, request)
+
+        return app
+
+    def run(
+        self,
+        create_agent: AgentCreator,
+        base_path: str = "",
+        host: str = "0.0.0.0",
+        port: int = 9000,
+        enable_openai_endpoint: bool = False,
+        enable_healthz: bool = True,
+        healthz_config: Optional[HealthzConfig] = None,
+        **uvicorn_kwargs: Any,
+    ) -> None:
+        r"""Build and run the FastAPI application (one-line startup).
+
+        This is the simplest way to start an Cloudbase Agent server. It builds the
+        FastAPI application and immediately starts the uvicorn server.
+
+        :param create_agent: Function that creates and returns agent with optional cleanup
+        :type create_agent: AgentCreator
+        :param base_path: Base path for agent routes
+        :type base_path: str
+        :param host: Server host address
+        :type host: str
+        :param port: Server port number
+        :type port: int
+        :param enable_openai_endpoint: Whether to enable OpenAI-compatible /chat/completions endpoint
+        :type enable_openai_endpoint: bool
+        :param enable_healthz: Whether to enable health check endpoint (default: True)
+        :type enable_healthz: bool
+        :param healthz_config: Optional health check configuration
+        :type healthz_config: Optional[HealthzConfig]
+        :param uvicorn_kwargs: Additional keyword arguments to pass to uvicorn.run
+                              Examples: reload=True, workers=4, log_level="debug"
+        :type uvicorn_kwargs: Any
+
+        Example:
+            Simplest usage::
+
+                AgentServiceApp().run(create_agent, port=8000)
+
+            With configuration::
+
+                AgentServiceApp() \
+                    .set_cors_config(allow_origins=["https://example.com"]) \
+                    .run(create_agent, port=8000, reload=True)
+
+            Development mode::
+
+                AgentServiceApp().run(
+                    create_agent,
+                    port=8000,
+                    reload=True,
+                    log_level="debug"
+                )
+
+            Production mode::
+
+                AgentServiceApp().run(
+                    create_agent,
+                    port=8000,
+                    workers=4,
+                    access_log=False
+                )
+        """
+        # Build the FastAPI application
+        app = self.build(
+            create_agent,
+            base_path,
+            enable_openai_endpoint=enable_openai_endpoint,
+            enable_healthz=enable_healthz,
+            healthz_config=healthz_config,
+        )
+
+        # Run the server
+        import uvicorn
+
+        uvicorn.run(app, host=host, port=port, **uvicorn_kwargs)

cloudbase_agent/server/healthz/__init__.py

@@ -0,0 +1,14 @@
+"""Health Check Module.
+
+This module provides health check functionality for Cloudbase Agent servers,
+automatically integrated into AgentServiceApp.
+"""
+
+from .handler import create_healthz_handler
+from .models import HealthzConfig, HealthzResponse
+
+__all__ = [
+    "HealthzConfig",
+    "HealthzResponse",
+    "create_healthz_handler",
+]

cloudbase_agent/server/healthz/handler.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Health Check Handler.
+
+This module provides the handler function for health check endpoints.
+"""
+
+import platform
+from datetime import datetime
+from typing import Any, Callable, Optional
+
+from .models import HealthzConfig
+
+
+def create_healthz_handler(
+    config: Optional[HealthzConfig] = None,
+    base_path: str = "",
+    agent_name: Optional[str] = None,
+) -> Callable[[], dict[str, Any]]:
+    """Create a health check handler function.
+
+    This function creates a handler that can be used as a FastAPI route handler
+    for health check endpoints. The handler performs basic health checks and
+    optionally executes custom health check logic.
+
+    :param config: Health check configuration
+    :type config: Optional[HealthzConfig]
+    :param base_path: Base path of the service
+    :type base_path: str
+    :param agent_name: Optional agent name to include in response
+    :type agent_name: Optional[str]
+    :return: Handler function that returns health check response
+    :rtype: Callable[[], dict[str, Any]]
+
+    Example:
+        Basic usage::
+
+            handler = create_healthz_handler()
+
+            @app.get("/healthz")
+            def healthz():
+                return handler()
+
+        With configuration::
+
+            config = HealthzConfig(
+                service_name="my-service",
+                version="2.0.0"
+            )
+            handler = create_healthz_handler(config, base_path="/api")
+
+            @app.get("/api/healthz")
+            def healthz():
+                return handler()
+
+        With custom checks::
+
+            async def check_redis():
+                if not redis.ping():
+                    raise Exception("Redis not available")
+                return {"redis": "connected"}
+
+            config = HealthzConfig(custom_checks=check_redis)
+            handler = create_healthz_handler(config)
+    """
+    # Use default config if not provided
+    if config is None:
+        config = HealthzConfig()
+
+    def handler() -> dict[str, Any]:
+        """Health check handler function.
+
+        This function performs health checks and returns a structured response.
+        If custom checks are configured and fail, it returns an unhealthy status.
+
+        :return: Health check response as dictionary
+        :rtype: dict[str, Any]
+        """
+        # Build base response
+        response_data = {
+            "status": "healthy",
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "service": config.service_name,
+            "version": config.version,
+            "python_version": platform.python_version(),
+            "base_path": base_path or "/",
+        }
+
+        # Add agent info if enabled
+        if config.include_agent_info and agent_name:
+            response_data["agent_info"] = {
+                "name": agent_name,
+                "endpoints": [
+                    f"{base_path}/send-message",
+                    f"{base_path}/healthz",
+                ],
+            }
+
+        # Execute custom checks if provided
+        if config.custom_checks:
+            try:
+                custom_results = config.custom_checks()
+                if custom_results:
+                    response_data["custom"] = custom_results
+            except Exception as e:
+                # Custom check failed, mark as unhealthy
+                response_data["status"] = "unhealthy"
+                response_data["error"] = str(e)
+
+        return response_data
+
+    return handler
+
+
+def create_async_healthz_handler(
+    config: Optional[HealthzConfig] = None,
+    base_path: str = "",
+    agent_name: Optional[str] = None,
+) -> Callable[[], dict[str, Any]]:
+    """Create an async health check handler function.
+
+    This is the async version of create_healthz_handler, supporting
+    async custom health check functions.
+
+    :param config: Health check configuration
+    :type config: Optional[HealthzConfig]
+    :param base_path: Base path of the service
+    :type base_path: str
+    :param agent_name: Optional agent name to include in response
+    :type agent_name: Optional[str]
+    :return: Async handler function that returns health check response
+    :rtype: Callable[[], dict[str, Any]]
+
+    Example:
+        With async custom checks::
+
+            async def check_database():
+                if not await db.is_connected():
+                    raise Exception("Database not connected")
+                return {"database": "connected"}
+
+            config = HealthzConfig(custom_checks=check_database)
+            handler = create_async_healthz_handler(config)
+
+            @app.get("/healthz")
+            async def healthz():
+                return await handler()
+    """
+    # Use default config if not provided
+    if config is None:
+        config = HealthzConfig()
+
+    async def handler() -> dict[str, Any]:
+        """Async health check handler function.
+
+        This function performs health checks asynchronously and returns
+        a structured response. If custom checks are configured and fail,
+        it returns an unhealthy status.
+
+        :return: Health check response as dictionary
+        :rtype: dict[str, Any]
+        """
+        # Build base response
+        response_data = {
+            "status": "healthy",
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "service": config.service_name,
+            "version": config.version,
+            "python_version": platform.python_version(),
+            "base_path": base_path or "/",
+        }
+
+        # Add agent info if enabled
+        if config.include_agent_info and agent_name:
+            response_data["agent_info"] = {
+                "name": agent_name,
+                "endpoints": [
+                    f"{base_path}/send-message",
+                    f"{base_path}/healthz",
+                ],
+            }
+
+        # Execute custom checks if provided
+        if config.custom_checks:
+            try:
+                # Support both sync and async custom checks
+                import inspect
+
+                if inspect.iscoroutinefunction(config.custom_checks):
+                    custom_results = await config.custom_checks()
+                else:
+                    custom_results = config.custom_checks()
+
+                if custom_results:
+                    response_data["custom"] = custom_results
+            except Exception as e:
+                # Custom check failed, mark as unhealthy
+                response_data["status"] = "unhealthy"
+                response_data["error"] = str(e)
+
+        return response_data
+
+    return handler