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

cloudbase_agent/server/healthz/models.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Health Check Data Models.
+
+This module defines the data models for health check configuration and responses.
+"""
+
+from typing import Any, Callable, Optional
+
+from pydantic import BaseModel, Field
+
+
+class HealthzConfig(BaseModel):
+    """Configuration for health check endpoint.
+
+    This class allows customization of the health check endpoint behavior,
+    including service metadata and custom health checks.
+
+    Attributes:
+        service_name: Name of the service (default: "Cloudbase Agent-python-server")
+        version: Service version (default: "1.0.0")
+        include_agent_info: Whether to include agent information in response
+        custom_checks: Optional async function that performs additional health checks
+                      Should return a dict of check results or raise an exception if unhealthy
+
+    Example:
+        Basic configuration::
+
+            config = HealthzConfig(
+                service_name="my-agent-service",
+                version="2.0.0"
+            )
+
+        With custom checks::
+
+            async def check_database():
+                # Check database connection
+                if not await db.is_connected():
+                    raise Exception("Database not connected")
+                return {"database": "connected"}
+
+            config = HealthzConfig(
+                service_name="my-service",
+                custom_checks=check_database
+            )
+    """
+
+    service_name: str = Field(default="Cloudbase Agent-python-server", description="Name of the service")
+
+    version: str = Field(default="1.0.0", description="Service version")
+
+    include_agent_info: bool = Field(default=False, description="Whether to include agent information in the response")
+
+    custom_checks: Optional[Callable[[], dict[str, Any]]] = Field(
+        default=None, description="Optional function that performs custom health checks"
+    )
+
+    class Config:
+        arbitrary_types_allowed = True
+
+
+class HealthzResponse(BaseModel):
+    """Health check response model.
+
+    This model defines the structure of health check responses,
+    following common health check patterns used in production systems.
+
+    Attributes:
+        status: Health status ("healthy" or "unhealthy")
+        timestamp: ISO 8601 timestamp of the health check
+        service: Service name
+        version: Service version
+        python_version: Python runtime version
+        base_path: Base path of the service
+        agent_info: Optional agent information (if enabled)
+        custom: Optional custom check results
+        error: Optional error message (if unhealthy)
+
+    Example:
+        Healthy response::
+
+            {
+                "status": "healthy",
+                "timestamp": "2024-01-01T00:00:00Z",
+                "service": "my-agent-service",
+                "version": "1.0.0",
+                "python_version": "3.11.0",
+                "base_path": "/api"
+            }
+
+        Unhealthy response::
+
+            {
+                "status": "unhealthy",
+                "timestamp": "2024-01-01T00:00:00Z",
+                "service": "my-agent-service",
+                "version": "1.0.0",
+                "python_version": "3.11.0",
+                "base_path": "/api",
+                "error": "Database connection failed"
+            }
+    """
+
+    status: str = Field(description="Health status: 'healthy' or 'unhealthy'")
+
+    timestamp: str = Field(description="ISO 8601 timestamp of the health check")
+
+    service: str = Field(description="Service name")
+
+    version: str = Field(description="Service version")
+
+    python_version: str = Field(description="Python runtime version")
+
+    base_path: str = Field(description="Base path of the service")
+
+    agent_info: Optional[dict[str, Any]] = Field(default=None, description="Optional agent information")
+
+    custom: Optional[dict[str, Any]] = Field(default=None, description="Optional custom check results")
+
+    error: Optional[str] = Field(default=None, description="Error message if unhealthy")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "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": "/",
+            }
+        }

cloudbase_agent/server/openai/__init__.py

@@ -0,0 +1,14 @@
+"""OpenAI Compatibility Module.
+
+This module provides OpenAI-compatible chat completions endpoint implementation,
+allowing Cloudbase Agent agents to be used as drop-in replacements for OpenAI models.
+
+Available Functions:
+    - create_adapter: Create a FastAPI endpoint adapter for chat/completions
+"""
+
+from .server import create_adapter
+
+__all__ = [
+    "create_adapter",
+]

cloudbase_agent/server/openai/converter.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""OpenAI Format Converter.
+
+This module provides conversion utilities between OpenAI API format
+and Cloudbase Agent native format.
+"""
+
+from uuid import uuid4
+
+from ..send_message.models import (
+    AssistantMessage,
+    RunAgentInput,
+    SystemMessage,
+    ToolMessage,
+    UserMessage,
+)
+from .models import OpenAIChatCompletionRequest
+
+
+def convert_openai_to_agkit(openai_request: OpenAIChatCompletionRequest) -> RunAgentInput:
+    """Convert OpenAI chat completion request to Cloudbase Agent format.
+
+    This function transforms OpenAI-compatible request format into Cloudbase Agent's
+    native RunAgentInput format, enabling OpenAI API compatibility.
+
+    Args:
+        openai_request: OpenAI-formatted chat completion request
+
+    Returns:
+        Cloudbase Agent formatted run agent input
+    """
+    # Convert messages
+    agkit_messages = []
+    for msg in openai_request.messages:
+        msg_id = str(uuid4())
+        if msg.role == "system":
+            agkit_messages.append(SystemMessage(id=msg_id, role="system", content=msg.content or ""))
+        elif msg.role == "user":
+            agkit_messages.append(UserMessage(id=msg_id, role="user", content=msg.content or ""))
+        elif msg.role == "assistant":
+            agkit_messages.append(
+                AssistantMessage(
+                    id=msg_id,
+                    role="assistant",
+                    content=msg.content,
+                    tool_calls=msg.tool_calls,
+                )
+            )
+        elif msg.role == "tool":
+            agkit_messages.append(
+                ToolMessage(
+                    id=msg_id,
+                    role="tool",
+                    content=msg.content or "",
+                    tool_call_id=msg.tool_call_id or "",
+                )
+            )
+
+    # Create Cloudbase Agent request
+    return RunAgentInput(
+        thread_id=str(uuid4()),  # Generate new thread ID
+        run_id=str(uuid4()),  # Generate new run ID
+        messages=agkit_messages,
+        tools=openai_request.tools or [],
+        context=[],
+        state={},
+        forwarded_props={},
+    )

cloudbase_agent/server/openai/models.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""OpenAI-Compatible Data Models.
+
+This module defines data models for OpenAI-compatible API endpoints,
+enabling Cloudbase Agent agents to work with OpenAI client libraries.
+"""
+
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+from ..send_message.models import Tool, ToolCall
+
+
+class OpenAIMessage(BaseModel):
+    """OpenAI-compatible message model.
+
+    :param role: Message role (system, user, assistant, tool)
+    :type role: str
+    :param content: Message content
+    :type content: Optional[str]
+    :param tool_calls: Tool calls made by assistant
+    :type tool_calls: Optional[List[ToolCall]]
+    :param tool_call_id: ID of tool call (for tool role messages)
+    :type tool_call_id: Optional[str]
+    """
+
+    role: str
+    content: Optional[str] = None
+    tool_calls: Optional[List[ToolCall]] = None
+    tool_call_id: Optional[str] = None
+
+
+class OpenAIChatCompletionRequest(BaseModel):
+    """OpenAI-compatible chat completion request model.
+
+    :param model: Model identifier (ignored, uses configured agent)
+    :type model: str
+    :param messages: List of conversation messages
+    :type messages: List[OpenAIMessage]
+    :param stream: Whether to stream the response
+    :type stream: bool
+    :param tools: Optional list of available tools
+    :type tools: Optional[List[Tool]]
+    :param temperature: Sampling temperature (ignored)
+    :type temperature: Optional[float]
+    :param max_tokens: Maximum tokens to generate (ignored)
+    :type max_tokens: Optional[int]
+    """
+
+    model: str
+    messages: List[OpenAIMessage]
+    stream: bool = True
+    tools: Optional[List[Tool]] = None
+    temperature: Optional[float] = None
+    max_tokens: Optional[int] = None

cloudbase_agent/server/openai/server.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""OpenAI-Compatible Server Adapter.
+
+This module provides the server adapter for OpenAI-compatible chat/completions endpoint.
+"""
+
+from fastapi.responses import StreamingResponse
+
+from ..send_message.server import create_adapter as create_send_message_adapter
+from ..utils.types import AgentCreator
+from .converter import convert_openai_to_agkit
+from .models import OpenAIChatCompletionRequest
+
+
+async def create_adapter(create_agent: AgentCreator, request: OpenAIChatCompletionRequest) -> StreamingResponse:
+    """Create a FastAPI adapter for OpenAI-compatible chat/completions requests.
+
+    This function provides OpenAI API compatibility by converting OpenAI-formatted
+    requests to Cloudbase Agent format and delegating to the send_message adapter.
+
+    :param create_agent: Function that creates and returns agent with optional cleanup
+    :type create_agent: AgentCreator
+    :param request: OpenAI-formatted chat completion request
+    :type request: OpenAIChatCompletionRequest
+    :return: Streaming response with SSE-formatted events
+    :rtype: StreamingResponse
+
+    Example:
+        Using the adapter in a FastAPI route::
+
+            from fastapi import FastAPI
+            from cloudbase_agent.server.openai import create_adapter
+            from cloudbase_agent.server.openai.models import OpenAIChatCompletionRequest
+
+            app = FastAPI()
+
+            @app.post("/chat/completions")
+            async def chat_completions(request: OpenAIChatCompletionRequest):
+                return await create_adapter(create_agent, request)
+    """
+    # Convert OpenAI format to Cloudbase Agent format
+    agkit_request = convert_openai_to_agkit(request)
+
+    # Delegate to send_message adapter
+    return await create_send_message_adapter(create_agent, agkit_request)

cloudbase_agent/server/send_message/__init__.py

@@ -0,0 +1,20 @@
+"""Send Message Module.
+
+This module provides the Cloudbase Agent native send_message endpoint implementation,
+including request models, event handlers, and server adapters.
+
+Available Functions:
+    - create_adapter: Create a FastAPI endpoint adapter for send_message
+
+Available Models:
+    - RunAgentInput: Standard input format for agent requests
+    - Event types: TextMessageContentEvent, ToolCallStartEvent, etc.
+"""
+
+from .models import RunAgentInput
+from .server import create_adapter
+
+__all__ = [
+    "create_adapter",
+    "RunAgentInput",
+]

cloudbase_agent/server/send_message/handler.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""HTTP Request Handler for Send Message.
+
+This module provides HTTP protocol-level mapping and request handling
+for the Cloudbase Agent send_message endpoint. It processes incoming requests,
+converts between client and internal message formats, and manages agent
+execution with real-time event streaming support.
+"""
+
+import logging
+from typing import Any, AsyncGenerator
+
+from ag_ui.core.events import EventType
+
+from .models import (
+    Event,
+    TextMessageContentEvent,
+    ToolCallStartEvent,
+    ToolCallArgsEvent,
+    ToolCallEndEvent,
+    ToolCallResultEvent,
+    RunErrorEvent,
+    RunAgentInput,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def handler(input_data: RunAgentInput, agent: Any) -> AsyncGenerator[Event, None]:
+    """Handle HTTP requests and process agent execution with streaming.
+
+    This function serves as the main request handler for the send_message endpoint.
+    It processes agent events and streams back properly formatted events conforming
+    to ag_ui_protocol standards.
+
+    Args:
+        input_data: Standard run agent input containing messages and config
+        agent: The agent instance to execute (must have a 'run' method)
+
+    Yields:
+        Standard protocol events (TEXT_MESSAGE_CONTENT, TOOL_CALL_*, etc.)
+
+    Raises:
+        RuntimeError: When agent execution or message processing fails
+    """
+    try:
+        logger.info("Agent run started: run_id=%s thread_id=%s", input_data.run_id, input_data.thread_id)
+        
+        event_count = 0
+
+        async for event in agent.run(input_data):
+            event_count += 1
+            
+            # Handle different event types with raw_event tracking for delta extraction
+            if event.type == EventType.TEXT_MESSAGE_CONTENT:
+                # Extract delta from framework-specific raw event structure
+                # Priority: raw_event (for framework compatibility) -> event.delta (standard fallback)
+                content = None
+                
+                if event.raw_event:
+                    raw_data = event.raw_event.get("data", {})
+                    chunk = raw_data.get("chunk", {})
+                    content = chunk.get("content")
+                
+                # Fallback to event.delta if raw_event extraction failed
+                if content is None:
+                    content = getattr(event, "delta", None)
+
+                if content:
+                    yield TextMessageContentEvent(
+                        message_id=event.message_id,
+                        delta=content,
+                    )
+
+            elif event.type == EventType.TEXT_MESSAGE_CHUNK:
+                # Handle text chunk events with fallback to event.delta
+                # Priority: raw_event (for framework compatibility) -> event.delta (standard fallback)
+                content = None
+                
+                if event.raw_event:
+                    raw_data = event.raw_event.get("data", {})
+                    chunk = raw_data.get("chunk", {})
+                    content = chunk.get("content")
+                
+                # Fallback to event.delta if raw_event extraction failed
+                if content is None:
+                    content = getattr(event, "delta", None)
+
+                if content:
+                    yield TextMessageContentEvent(
+                        message_id=event.message_id,
+                        delta=content,
+                    )
+
+            elif event.type == EventType.TOOL_CALL_START:
+                # Emit tool call start event
+                yield ToolCallStartEvent(
+                    tool_call_id=event.tool_call_id,
+                    tool_call_name=event.tool_call_name,  # ✓ Correct field name
+                )
+
+                # Some frameworks provide initial args in start event
+                start_delta = None
+                if event.raw_event is not None:
+                    start_delta = (
+                        event.raw_event.get("data", {})
+                        .get("chunk", {})
+                        .get("tool_call_chunks", [{}])[0]
+                        .get("args")
+                    )
+
+                if start_delta is not None:
+                    yield ToolCallArgsEvent(
+                        tool_call_id=event.tool_call_id,
+                        delta=start_delta,
+                    )
+
+            elif event.type in (EventType.TOOL_CALL_ARGS, EventType.TOOL_CALL_CHUNK):
+                # Handle streaming tool arguments
+                yield ToolCallArgsEvent(
+                    tool_call_id=event.tool_call_id,
+                    delta=event.delta,
+                )
+
+            elif event.type == EventType.TOOL_CALL_END:
+                # Tool call arguments complete
+                yield ToolCallEndEvent(
+                    tool_call_id=event.tool_call_id,
+                )
+
+            elif event.type == EventType.TOOL_CALL_RESULT:
+                # Tool execution result
+                yield ToolCallResultEvent(
+                    tool_call_id=event.tool_call_id,
+                    result=event.content,
+                )
+
+            # Note: CUSTOM events for interrupts are handled by ag_ui_protocol internally
+
+        logger.info("Agent run completed: run_id=%s total_events=%d", input_data.run_id, event_count)
+
+    except Exception as e:
+        logger.error("Agent run failed: run_id=%s error=%s", input_data.run_id, str(e))
+        yield RunErrorEvent(run_id=input_data.run_id, message=str(e))
+        raise RuntimeError(f"Failed to process agent request: {str(e)}") from e

cloudbase_agent/server/send_message/models.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Send Message Data Models.
+
+This module re-exports standard types from ag_ui_protocol for HTTP communication.
+All types conform to ag_ui_protocol standards for interoperability.
+"""
+
+from ag_ui.core import (
+    # Input types
+    RunAgentInput,
+    Message,
+    Tool,
+    Context,
+    # Event types
+    Event,
+    TextMessageContentEvent,
+    ToolCallStartEvent,
+    ToolCallArgsEvent,
+    ToolCallEndEvent,
+    ToolCallResultEvent,
+    RunErrorEvent,
+    RunStartedEvent,
+    RunFinishedEvent,
+    # Supporting types
+    ToolCall,
+    FunctionCall,
+    # Message types
+    SystemMessage,
+    UserMessage,
+    ToolMessage,
+    AssistantMessage,
+)
+
+# Legacy compatibility types (will be removed in future versions)
+from typing import Union
+
+ClientMessage = Union[SystemMessage, UserMessage, ToolMessage, AssistantMessage]
+
+# Re-export for convenience
+__all__ = [
+    "RunAgentInput",
+    "Message",
+    "Tool",
+    "Context",
+    "Event",
+    "TextMessageContentEvent",
+    "ToolCallStartEvent",
+    "ToolCallArgsEvent",
+    "ToolCallEndEvent",
+    "ToolCallResultEvent",
+    "RunErrorEvent",
+    "RunStartedEvent",
+    "RunFinishedEvent",
+    "ToolCall",
+    "FunctionCall",
+    "SystemMessage",
+    "UserMessage",
+    "ToolMessage",
+    "AssistantMessage",
+    "ClientMessage",
+]

cloudbase_agent/server/send_message/server.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Send Message Server Adapter.
+
+This module provides the server adapter for the send_message endpoint,
+handling request processing, streaming responses, and resource cleanup.
+"""
+
+import inspect
+import json
+import logging
+from typing import AsyncGenerator
+
+from fastapi.responses import StreamingResponse
+from pydantic import ValidationError
+
+from ..utils.sse import async_generator_from_string
+from ..utils.types import AgentCreator
+from .handler import handler
+from .models import RunAgentInput
+
+logger = logging.getLogger(__name__)
+
+
+async def create_adapter(create_agent: AgentCreator, request: RunAgentInput) -> StreamingResponse:
+    """Create a FastAPI adapter for send_message requests with streaming support.
+
+    This function creates a streaming HTTP response adapter that processes
+    send_message requests and returns Server-Sent Events (SSE) formatted responses.
+
+    Args:
+        create_agent: Function that creates and returns agent with optional cleanup
+        request: The validated request input containing messages and tools
+
+    Returns:
+        Streaming response with SSE-formatted events and proper headers
+
+    Raises:
+        ValidationError: When request validation fails
+        Exception: When agent processing fails or other errors occur
+    """
+    try:
+        # Create agent and get optional cleanup function
+        result = create_agent()
+        if inspect.iscoroutine(result):
+            result = await result
+
+        agent = result["agent"]
+        cleanup = result.get("cleanup")
+
+        async def create_sse_stream() -> AsyncGenerator[str, None]:
+            """Create Server-Sent Events stream with cleanup support.
+
+            Yields:
+                SSE-formatted event strings
+            """
+            try:
+                async for event in handler(request, agent):
+                    # Use by_alias=True for camelCase conversion
+                    sse_chunk = f"data: {event.model_dump_json(by_alias=True, exclude_none=True)}\n\n"
+                    yield sse_chunk
+
+                yield "data: [DONE]\n\n"
+            finally:
+                # Ensure cleanup is called even if errors occur
+                if cleanup:
+                    if inspect.iscoroutinefunction(cleanup):
+                        await cleanup()
+                    else:
+                        cleanup()
+
+        return StreamingResponse(
+            create_sse_stream(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache, no-transform",
+                "Connection": "keep-alive",
+            },
+        )
+
+    except ValidationError as e:
+        logger.error("Request validation failed: %s", str(e))
+        error_stream = async_generator_from_string(
+            f"data: {json.dumps({'error': 'Validation failed', 'details': str(e)})}\n\n"
+        )
+        return StreamingResponse(error_stream, media_type="text/event-stream")
+
+    except Exception as e:
+        logger.error("Server error occurred: %s", str(e))
+        error_stream = async_generator_from_string(
+            f"data: {json.dumps({'error': 'Server error', 'details': str(e)})}\n\n"
+        )
+        return StreamingResponse(error_stream, media_type="text/event-stream")

cloudbase_agent/server/utils/__init__.py

@@ -0,0 +1,21 @@
+"""Utility Functions Package.
+
+This package provides common utility functions and types used across
+the Cloudbase Agent server implementation.
+
+Available Modules:
+    - types: Type definitions for agent creators and results
+    - sse: Server-Sent Events utilities
+    - converters: Utility functions for JSON validation
+"""
+
+from .converters import is_valid_json
+from .sse import async_generator_from_string
+from .types import AgentCreator, AgentCreatorResult
+
+__all__ = [
+    "AgentCreator",
+    "AgentCreatorResult",
+    "is_valid_json",
+    "async_generator_from_string",
+]

cloudbase_agent/server/utils/converters.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Message and Tool Format Converters.
+
+This module provides utility functions for working with ag_ui_protocol types.
+Most conversion functions have been removed as ag_ui_protocol provides native types.
+"""
+
+import json
+
+
+def is_valid_json(json_str: str) -> bool:
+    """Check if string is valid JSON.
+
+    Args:
+        json_str: String to validate
+
+    Returns:
+        True if valid JSON, False otherwise
+    """
+    try:
+        json.loads(json_str)
+        return True
+    except json.JSONDecodeError:
+        return False