chore: import upstream snapshot with attribution

python/packages/devui/agent_framework_devui/models/__init__.py

@@ -0,0 +1,94 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Agent Framework DevUI Models - OpenAI-compatible types and custom extensions."""
+
+# Import discovery models
+# Import all OpenAI types directly from the openai package
+from openai.types.conversations import Conversation, ConversationDeletedResource
+from openai.types.conversations.conversation_item import ConversationItem
+from openai.types.responses import (
+    Response,
+    ResponseCompletedEvent,
+    ResponseErrorEvent,
+    ResponseFunctionCallArgumentsDeltaEvent,
+    ResponseFunctionToolCall,
+    ResponseFunctionToolCallOutputItem,
+    ResponseInputParam,
+    ResponseOutputItemAddedEvent,
+    ResponseOutputItemDoneEvent,
+    ResponseOutputMessage,
+    ResponseOutputText,
+    ResponseReasoningTextDeltaEvent,
+    ResponseStreamEvent,
+    ResponseTextDeltaEvent,
+    ResponseUsage,
+    ToolParam,
+)
+from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
+from openai.types.shared import Metadata, ResponsesModel
+
+from ._discovery_models import Deployment, DeploymentConfig, DeploymentEvent, DiscoveryResponse, EntityInfo
+from ._openai_custom import (
+    AgentFrameworkRequest,
+    CustomResponseOutputItemAddedEvent,
+    CustomResponseOutputItemDoneEvent,
+    ExecutorActionItem,
+    MetaResponse,
+    OpenAIError,
+    ResponseFunctionResultComplete,
+    ResponseOutputData,
+    ResponseOutputFile,
+    ResponseOutputImage,
+    ResponseTraceEvent,
+    ResponseTraceEventComplete,
+    ResponseWorkflowEventComplete,
+)
+
+# Type alias for compatibility
+OpenAIResponse = Response
+
+# Export all types for easy importing
+__all__ = [
+    "AgentFrameworkRequest",
+    "Conversation",
+    "ConversationDeletedResource",
+    "ConversationItem",
+    "CustomResponseOutputItemAddedEvent",
+    "CustomResponseOutputItemDoneEvent",
+    "Deployment",
+    "DeploymentConfig",
+    "DeploymentEvent",
+    "DiscoveryResponse",
+    "EntityInfo",
+    "ExecutorActionItem",
+    "InputTokensDetails",
+    "MetaResponse",
+    "Metadata",
+    "OpenAIError",
+    "OpenAIResponse",
+    "OutputTokensDetails",
+    "Response",
+    "ResponseCompletedEvent",
+    "ResponseErrorEvent",
+    "ResponseFunctionCallArgumentsDeltaEvent",
+    "ResponseFunctionResultComplete",
+    "ResponseFunctionToolCall",
+    "ResponseFunctionToolCallOutputItem",
+    "ResponseInputParam",
+    "ResponseOutputData",
+    "ResponseOutputFile",
+    "ResponseOutputImage",
+    "ResponseOutputItemAddedEvent",
+    "ResponseOutputItemDoneEvent",
+    "ResponseOutputMessage",
+    "ResponseOutputText",
+    "ResponseReasoningTextDeltaEvent",
+    "ResponseStreamEvent",
+    "ResponseTextDeltaEvent",
+    "ResponseTraceEvent",
+    "ResponseTraceEventComplete",
+    "ResponseUsage",
+    "ResponseWorkflowEventComplete",
+    "ResponsesModel",
+    "ToolParam",
+]

python/packages/devui/agent_framework_devui/models/_discovery_models.py

@@ -0,0 +1,204 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Discovery API models for entity information."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Any, cast
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class EnvVarRequirement(BaseModel):
+    """Environment variable requirement for an entity."""
+
+    name: str
+    description: str
+    required: bool = True
+    example: str | None = None
+
+
+class EntityInfo(BaseModel):
+    """Entity information for discovery and detailed views."""
+
+    # Always present (core entity data)
+    id: str
+    type: str  # "agent", "workflow"
+    name: str
+    description: str | None = None
+    framework: str
+    tools: list[str | dict[str, Any]] | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    # Source information
+    source: str = "directory"  # "directory" or "in_memory"
+
+    # Environment variable requirements
+    required_env_vars: list[EnvVarRequirement] | None = None
+
+    # Deployment support
+    deployment_supported: bool = False  # Whether entity can be deployed
+    deployment_reason: str | None = None  # Explanation of why/why not entity can be deployed
+
+    # Agent-specific fields (optional, populated when available)
+    instructions: str | None = None
+    model: str | None = None
+    chat_client_type: str | None = None
+    context_provider: list[str] | None = None
+    middleware: list[str] | None = None
+
+    # Workflow-specific fields (populated only for detailed info requests)
+    executors: list[str] | None = None
+    workflow_dump: dict[str, Any] | None = None
+    input_schema: dict[str, Any] | None = None
+    input_type_name: str | None = None
+    start_executor_id: str | None = None
+
+
+class DiscoveryResponse(BaseModel):
+    """Response model for entity discovery."""
+
+    entities: list[EntityInfo] = Field(default_factory=cast(Callable[..., list[EntityInfo]], list))
+
+
+# ============================================================================
+# Deployment Models
+# ============================================================================
+
+
+class DeploymentConfig(BaseModel):
+    """Configuration for deploying an entity."""
+
+    entity_id: str = Field(description="Entity ID to deploy")
+    resource_group: str = Field(description="Azure resource group name")
+    app_name: str = Field(description="Azure Container App name")
+    region: str = Field(default="eastus", description="Azure region")
+    ui_mode: str = Field(default="user", description="UI mode (user or developer)")
+    ui_enabled: bool = Field(default=True, description="Whether to enable web interface")
+    stream: bool = Field(default=True, description="Stream deployment events")
+
+    @field_validator("app_name")
+    @classmethod
+    def validate_app_name(cls, v: str) -> str:
+        """Validate Azure Container App name format.
+
+        Azure Container App names must:
+        - Be 3-32 characters long
+        - Contain only lowercase letters, numbers, and hyphens
+        - Start with a lowercase letter
+        - End with a lowercase letter or number
+        - Not contain consecutive hyphens
+        """
+        if not v:
+            raise ValueError("app_name cannot be empty")
+
+        if len(v) < 3 or len(v) > 32:
+            raise ValueError("app_name must be between 3 and 32 characters")
+
+        if not re.match(r"^[a-z][a-z0-9-]*[a-z0-9]$", v):
+            raise ValueError(
+                "app_name must start with a lowercase letter, "
+                "end with a letter or number, and contain only lowercase letters, numbers, and hyphens"
+            )
+
+        if "--" in v:
+            raise ValueError("app_name cannot contain consecutive hyphens")
+
+        return v
+
+    @field_validator("resource_group")
+    @classmethod
+    def validate_resource_group(cls, v: str) -> str:
+        """Validate Azure resource group name format.
+
+        Azure resource group names must:
+        - Be 1-90 characters long
+        - Contain only alphanumeric, underscore, parentheses, hyphen, period (except at end)
+        - Not end with a period
+        """
+        if not v:
+            raise ValueError("resource_group cannot be empty")
+
+        if len(v) > 90:
+            raise ValueError("resource_group must be 90 characters or less")
+
+        if not re.match(r"^[a-zA-Z0-9._()-]+$", v):
+            raise ValueError(
+                "resource_group can only contain alphanumeric characters, "
+                "underscores, hyphens, periods, and parentheses"
+            )
+
+        if v.endswith("."):
+            raise ValueError("resource_group cannot end with a period")
+
+        return v
+
+    @field_validator("region")
+    @classmethod
+    def validate_region(cls, v: str) -> str:
+        """Validate Azure region format.
+
+        Validates that the region string is a reasonable format.
+        Does not validate against the full list of Azure regions (which changes).
+        """
+        if not v:
+            raise ValueError("region cannot be empty")
+
+        if len(v) > 50:
+            raise ValueError("region name too long")
+
+        # Azure regions are typically lowercase with no spaces (e.g., eastus, westeurope)
+        if not re.match(r"^[a-z0-9]+$", v):
+            raise ValueError("region must contain only lowercase letters and numbers (e.g., eastus, westeurope)")
+
+        return v
+
+    @field_validator("entity_id")
+    @classmethod
+    def validate_entity_id(cls, v: str) -> str:
+        """Validate entity_id format to prevent injection attacks."""
+        if not v:
+            raise ValueError("entity_id cannot be empty")
+
+        if len(v) > 256:
+            raise ValueError("entity_id too long")
+
+        # Allow alphanumeric, hyphens, underscores, and periods
+        if not re.match(r"^[a-zA-Z0-9._-]+$", v):
+            raise ValueError("entity_id contains invalid characters")
+
+        return v
+
+    @field_validator("ui_mode")
+    @classmethod
+    def validate_ui_mode(cls, v: str) -> str:
+        """Validate ui_mode is one of the allowed values."""
+        if v not in ("user", "developer"):
+            raise ValueError("ui_mode must be 'user' or 'developer'")
+
+        return v
+
+
+class DeploymentEvent(BaseModel):
+    """Real-time deployment event (SSE)."""
+
+    type: str = Field(description="Event type (e.g., deploy.validating, deploy.building)")
+    message: str = Field(description="Human-readable message")
+    url: str | None = Field(default=None, description="Deployment URL (on completion)")
+    auth_token: str | None = Field(default=None, description="Auth token (on completion, shown once)")
+
+
+class Deployment(BaseModel):
+    """Deployment record."""
+
+    id: str = Field(description="Deployment ID (UUID)")
+    entity_id: str = Field(description="Entity ID that was deployed")
+    resource_group: str = Field(description="Azure resource group")
+    app_name: str = Field(description="Azure Container App name")
+    region: str = Field(description="Azure region")
+    url: str = Field(description="Deployment URL")
+    status: str = Field(description="Deployment status (deploying, deployed, failed)")
+    created_at: str = Field(description="ISO 8601 timestamp")
+    error: str | None = Field(default=None, description="Error message if failed")

python/packages/devui/agent_framework_devui/models/_openai_custom.py

@@ -0,0 +1,413 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Custom OpenAI-compatible event types for Agent Framework extensions.
+
+These are custom event types that extend beyond the standard OpenAI Responses API
+to support Agent Framework specific features like workflows and traces.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+# Custom Agent Framework OpenAI event types for structured data
+
+
+# Agent lifecycle events - simple and clear
+class AgentStartedEvent:
+    """Event emitted when an agent starts execution."""
+
+    pass
+
+
+class AgentCompletedEvent:
+    """Event emitted when an agent completes execution successfully."""
+
+    pass
+
+
+@dataclass
+class AgentFailedEvent:
+    """Event emitted when an agent fails during execution."""
+
+    error: Exception | None = None
+
+
+class ExecutorActionItem(BaseModel):
+    """Custom item type for workflow executor actions.
+
+    This is a DevUI-specific extension to represent workflow executors as output items.
+    Since OpenAI's ResponseOutputItemAddedEvent only accepts specific item types,
+    and executor actions are not part of the standard, we need this custom type.
+    """
+
+    type: Literal["executor_action"] = "executor_action"
+    id: str
+    executor_id: str
+    status: Literal["in_progress", "completed", "failed", "cancelled"] = "in_progress"
+    metadata: dict[str, Any] | None = None
+    result: Any | None = None
+    error: dict[str, Any] | None = None
+
+
+class CustomResponseOutputItemAddedEvent(BaseModel):
+    """Custom version of ResponseOutputItemAddedEvent that accepts any item type.
+
+    This allows us to emit executor action items while maintaining the same
+    event structure as OpenAI's standard.
+    """
+
+    type: Literal["response.output_item.added"] = "response.output_item.added"
+    output_index: int
+    sequence_number: int
+    item: dict[str, Any] | ExecutorActionItem | Any  # Flexible item type
+    created_at: float | None = None  # Unix timestamp; used by frontend for accurate workflow timings
+
+
+class CustomResponseOutputItemDoneEvent(BaseModel):
+    """Custom version of ResponseOutputItemDoneEvent that accepts any item type.
+
+    This allows us to emit executor action items while maintaining the same
+    event structure as OpenAI's standard.
+    """
+
+    type: Literal["response.output_item.done"] = "response.output_item.done"
+    output_index: int
+    sequence_number: int
+    item: dict[str, Any] | ExecutorActionItem | Any  # Flexible item type
+    created_at: float | None = None  # Unix timestamp; used by frontend for accurate workflow timings
+
+
+class ResponseWorkflowEventComplete(BaseModel):
+    """Complete workflow event data.
+
+    DevUI extension for workflow execution events (debugging/observability).
+    Uses past-tense 'completed' to follow OpenAI's event naming pattern.
+
+    Workflow events are shown in the debug panel for monitoring execution flow,
+    not in main chat. Use response.output_item.added for user-facing content.
+    """
+
+    type: Literal["response.workflow_event.completed"] = "response.workflow_event.completed"
+    data: dict[str, Any]  # Complete event data, not delta
+    executor_id: str | None = None
+    item_id: str
+    output_index: int = 0
+    sequence_number: int
+
+
+class ResponseTraceEventComplete(BaseModel):
+    """Complete trace event data.
+
+    DevUI extension for non-displayable debugging/metadata events.
+    Uses past-tense 'completed' to follow OpenAI's event naming pattern
+    (e.g., response.completed, response.output_item.added).
+
+    Trace events are shown in the Traces debug panel, not in main chat.
+    Use response.output_item.added for user-facing content.
+    """
+
+    type: Literal["response.trace.completed"] = "response.trace.completed"
+    data: dict[str, Any]  # Complete trace data, not delta
+    span_id: str | None = None
+    item_id: str
+    output_index: int = 0
+    sequence_number: int
+
+
+class ResponseFunctionResultComplete(BaseModel):
+    """DevUI extension: Stream function execution results.
+
+    This is a DevUI extension because:
+    - OpenAI Responses API doesn't stream function results (clients execute functions)
+    - Agent Framework executes functions server-side, so we stream results for debugging visibility
+    - ResponseFunctionToolCallOutputItem exists in OpenAI SDK but isn't in ResponseOutputItem union
+      (it's for Conversations API input, not Responses API streaming output)
+
+    This event provides the same structure as OpenAI's function output items but wrapped
+    in a custom event type since standard events don't support streaming function results.
+    """
+
+    type: Literal["response.function_result.complete"] = "response.function_result.complete"
+    call_id: str
+    output: str
+    status: Literal["in_progress", "completed", "incomplete"]
+    item_id: str
+    output_index: int = 0
+    sequence_number: int
+    timestamp: str | None = None  # Optional timestamp for UI display
+
+
+class ResponseRequestInfoEvent(BaseModel):
+    """DevUI extension: Workflow requests human input.
+
+    This is a DevUI extension because:
+    - OpenAI Responses API doesn't have a concept of workflow human-in-the-loop pausing
+    - Agent Framework workflows can pause via RequestInfoExecutor to collect external information
+    - Clients need to render forms and submit responses to continue workflow execution
+
+    When a workflow emits this event, it enters IDLE_WITH_PENDING_REQUESTS state.
+    Client should render a form based on request_schema and submit responses via
+    a new request with workflow_hil_response content type.
+    """
+
+    type: Literal["response.request_info.requested"] = "response.request_info.requested"
+    request_id: str
+    """Unique identifier for correlating this request with the response."""
+
+    source_executor_id: str
+    """ID of the executor that is waiting for this response."""
+
+    request_type: str
+    """Fully qualified type name of the request (e.g., 'module.path:ClassName')."""
+
+    request_data: dict[str, Any]
+    """Current data from the RequestInfoMessage (may contain defaults/context)."""
+
+    request_schema: dict[str, Any]
+    """JSON schema describing the request data structure (what the workflow is asking about)."""
+
+    response_schema: dict[str, Any] | None = None
+    """JSON schema describing the expected response structure for form rendering (what user should provide)."""
+
+    item_id: str
+    """OpenAI item ID for correlation."""
+
+    output_index: int = 0
+    """Output index for OpenAI compatibility."""
+
+    sequence_number: int
+    """Sequence number for ordering events."""
+
+    timestamp: str
+    """ISO timestamp when the request was made."""
+
+
+# DevUI Output Content Types - for agent-generated media/data
+# These extend ResponseOutputItem to support rich content outputs that OpenAI's API doesn't natively support
+
+
+class ResponseOutputImage(BaseModel):
+    """DevUI extension: Agent-generated image output.
+
+    This is a DevUI extension because:
+    - OpenAI Responses API only supports text output in ResponseOutputMessage.content
+    - ImageGenerationCall exists but is for tool calls (generating images), not returning existing images
+    - Agent Framework agents can return images via DataContent/UriContent that need proper display
+
+    This type allows images to be displayed inline in chat rather than hidden in trace logs.
+    """
+
+    id: str
+    """The unique ID of the image output."""
+
+    image_url: str
+    """The URL or data URI of the image (e.g., data:image/png;base64,...)"""
+
+    type: Literal["output_image"] = "output_image"
+    """The type of the output. Always `output_image`."""
+
+    alt_text: str | None = None
+    """Optional alt text for accessibility."""
+
+    mime_type: str = "image/png"
+    """The MIME type of the image (e.g., image/png, image/jpeg)."""
+
+
+class ResponseOutputFile(BaseModel):
+    """DevUI extension: Agent-generated file output.
+
+    This is a DevUI extension because:
+    - OpenAI Responses API only supports text output in ResponseOutputMessage.content
+    - Agent Framework agents can return files via DataContent/UriContent that need proper display
+    - Supports PDFs, audio files, and other media types
+
+    This type allows files to be displayed inline in chat with appropriate renderers.
+    """
+
+    id: str
+    """The unique ID of the file output."""
+
+    filename: str
+    """The filename (used to determine rendering and download)."""
+
+    type: Literal["output_file"] = "output_file"
+    """The type of the output. Always `output_file`."""
+
+    file_url: str | None = None
+    """Optional URL to the file."""
+
+    file_data: str | None = None
+    """Optional base64-encoded file data."""
+
+    mime_type: str = "application/octet-stream"
+    """The MIME type of the file (e.g., application/pdf, audio/mp3)."""
+
+
+class ResponseOutputData(BaseModel):
+    """DevUI extension: Agent-generated generic data output.
+
+    This is a DevUI extension because:
+    - OpenAI Responses API only supports text output in ResponseOutputMessage.content
+    - Agent Framework agents can return arbitrary structured data that needs display
+    - Useful for debugging and displaying non-text content
+
+    This type allows generic data to be displayed inline in chat.
+    """
+
+    id: str
+    """The unique ID of the data output."""
+
+    data: str
+    """The data payload (string representation)."""
+
+    type: Literal["output_data"] = "output_data"
+    """The type of the output. Always `output_data`."""
+
+    mime_type: str
+    """The MIME type of the data."""
+
+    description: str | None = None
+    """Optional description of the data."""
+
+
+# Agent Framework extension fields
+class AgentFrameworkExtraBody(BaseModel):
+    """Agent Framework specific routing fields for OpenAI requests."""
+
+    entity_id: str
+    # input_data removed - now using standard input field for all data
+
+    model_config = ConfigDict(extra="allow")
+
+
+# Agent Framework Request Model - Extending real OpenAI types
+class AgentFrameworkRequest(BaseModel):
+    """OpenAI ResponseCreateParams with Agent Framework routing.
+
+    This properly extends the real OpenAI API request format.
+    - Uses 'model' field as entity_id (agent/workflow name)
+    - Uses 'conversation' field for conversation context (OpenAI standard)
+    """
+
+    # All OpenAI fields from ResponseCreateParams
+    model: str | None = None
+    input: str | list[Any] | dict[str, Any]  # ResponseInputParam + dict for workflow structured input
+    stream: bool | None = False
+
+    # OpenAI conversation parameter (standard!)
+    conversation: str | dict[str, Any] | None = None  # Union[str, {"id": str}]
+
+    # Common OpenAI optional fields
+    instructions: str | None = None
+    metadata: dict[str, Any] | None = None
+    temperature: float | None = None
+    max_output_tokens: int | None = None
+    top_p: float | None = None
+    tools: list[dict[str, Any]] | None = None
+
+    # Reasoning parameters (for o-series models)
+    reasoning: dict[str, Any] | None = None  # {"effort": "low" | "medium" | "high" | "minimal"}
+
+    # Optional extra_body for advanced use cases
+    extra_body: dict[str, Any] | None = None
+
+    model_config = ConfigDict(extra="allow")
+
+    def get_entity_id(self) -> str | None:
+        """Get entity_id from metadata.entity_id.
+
+        In DevUI, entity_id is specified in metadata for routing.
+        """
+        if self.metadata:
+            return self.metadata.get("entity_id")
+        return None
+
+    def _get_conversation_id(self) -> str | None:
+        """Extract conversation_id from conversation parameter.
+
+        Supports both string and object forms:
+        - conversation: "conv_123"
+        - conversation: {"id": "conv_123"}
+        """
+        if isinstance(self.conversation, str):
+            return self.conversation
+        if isinstance(self.conversation, dict):
+            return self.conversation.get("id")
+        return None
+
+    def to_openai_params(self) -> dict[str, Any]:
+        """Convert to dict for OpenAI client compatibility."""
+        return self.model_dump(exclude_none=True)
+
+
+# Error handling
+class ResponseTraceEvent(BaseModel):
+    """Trace event for execution tracing."""
+
+    type: Literal["trace_event"] = "trace_event"
+    data: dict[str, Any]
+    timestamp: str
+
+
+class OpenAIError(BaseModel):
+    """OpenAI standard error response model."""
+
+    error: dict[str, Any]
+
+    @classmethod
+    def create(cls, message: str, type: str = "invalid_request_error", code: str | None = None) -> OpenAIError:
+        """Create a standard OpenAI error response."""
+        error_data = {"message": message, "type": type, "code": code}
+        return cls(error=error_data)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the error payload as a plain mapping."""
+        return {"error": dict(self.error)}
+
+    def to_json(self) -> str:
+        """Return the error payload serialized to JSON."""
+        return self.model_dump_json()
+
+
+class MetaResponse(BaseModel):
+    """Server metadata response for /meta endpoint.
+
+    Provides information about the DevUI server configuration and capabilities.
+    """
+
+    ui_mode: Literal["developer", "user"] = "developer"
+    """UI interface mode - 'developer' shows debug tools, 'user' shows simplified interface."""
+
+    version: str
+    """DevUI version string."""
+
+    framework: str = "agent_framework"
+    """Backend framework identifier."""
+
+    runtime: Literal["python", "dotnet"] = "python"
+    """Backend runtime/language - 'python' or 'dotnet' for deployment guides and feature availability."""
+
+    capabilities: dict[str, bool] = {}
+    """Server capabilities (e.g., instrumentation, openai_proxy)."""
+
+    auth_required: bool = False
+    """Whether the server requires Bearer token authentication."""
+
+
+# Export all custom types
+__all__ = [
+    "AgentFrameworkRequest",
+    "MetaResponse",
+    "OpenAIError",
+    "ResponseFunctionResultComplete",
+    "ResponseOutputData",
+    "ResponseOutputFile",
+    "ResponseOutputImage",
+    "ResponseTraceEvent",
+    "ResponseTraceEventComplete",
+    "ResponseWorkflowEventComplete",
+]