agent-framework-devui 1.0.0b251007__py3-none-any.whl → 1.0.0b251028__py3-none-any.whl

agent_framework_devui/_utils.py

@@ -6,10 +6,159 @@ import inspect
 import json
 import logging
 from dataclasses import fields, is_dataclass
-from typing import Any, get_args, get_origin
+from types import UnionType
+from typing import Any, Union, get_args, get_origin
+
+from agent_framework import ChatMessage
 
 logger = logging.getLogger(__name__)
 
+# ============================================================================
+# Agent Metadata Extraction
+# ============================================================================
+
+
+def extract_agent_metadata(entity_object: Any) -> dict[str, Any]:
+    """Extract agent-specific metadata from an entity object.
+
+    Args:
+        entity_object: Agent Framework agent object
+
+    Returns:
+        Dictionary with agent metadata: instructions, model, chat_client_type,
+        context_providers, and middleware
+    """
+    metadata = {
+        "instructions": None,
+        "model": None,
+        "chat_client_type": None,
+        "context_providers": None,
+        "middleware": None,
+    }
+
+    # Try to get instructions
+    if hasattr(entity_object, "chat_options") and hasattr(entity_object.chat_options, "instructions"):
+        metadata["instructions"] = entity_object.chat_options.instructions
+
+    # Try to get model - check both chat_options and chat_client
+    if (
+        hasattr(entity_object, "chat_options")
+        and hasattr(entity_object.chat_options, "model_id")
+        and entity_object.chat_options.model_id
+    ):
+        metadata["model"] = entity_object.chat_options.model_id
+    elif hasattr(entity_object, "chat_client") and hasattr(entity_object.chat_client, "model_id"):
+        metadata["model"] = entity_object.chat_client.model_id
+
+    # Try to get chat client type
+    if hasattr(entity_object, "chat_client"):
+        metadata["chat_client_type"] = entity_object.chat_client.__class__.__name__
+
+    # Try to get context providers
+    if (
+        hasattr(entity_object, "context_provider")
+        and entity_object.context_provider
+        and hasattr(entity_object.context_provider, "__class__")
+    ):
+        metadata["context_providers"] = [entity_object.context_provider.__class__.__name__]  # type: ignore
+
+    # Try to get middleware
+    if hasattr(entity_object, "middleware") and entity_object.middleware:
+        middleware_list: list[str] = []
+        for m in entity_object.middleware:
+            # Try multiple ways to get a good name for middleware
+            if hasattr(m, "__name__"):  # Function or callable
+                middleware_list.append(m.__name__)
+            elif hasattr(m, "__class__"):  # Class instance
+                middleware_list.append(m.__class__.__name__)
+            else:
+                middleware_list.append(str(m))
+        metadata["middleware"] = middleware_list  # type: ignore
+
+    return metadata
+
+
+# ============================================================================
+# Workflow Input Type Utilities
+# ============================================================================
+
+
+def extract_executor_message_types(executor: Any) -> list[Any]:
+    """Extract declared input types for the given executor.
+
+    Args:
+        executor: Workflow executor object
+
+    Returns:
+        List of message types that the executor accepts
+    """
+    message_types: list[Any] = []
+
+    try:
+        input_types = getattr(executor, "input_types", None)
+    except Exception as exc:  # pragma: no cover - defensive logging path
+        logger.debug(f"Failed to access executor input_types: {exc}")
+    else:
+        if input_types:
+            message_types = list(input_types)
+
+    if not message_types and hasattr(executor, "_handlers"):
+        try:
+            handlers = executor._handlers
+            if isinstance(handlers, dict):
+                message_types = list(handlers.keys())
+        except Exception as exc:  # pragma: no cover - defensive logging path
+            logger.debug(f"Failed to read executor handlers: {exc}")
+
+    return message_types
+
+
+def _contains_chat_message(type_hint: Any) -> bool:
+    """Check whether the provided type hint directly or indirectly references ChatMessage."""
+    if type_hint is ChatMessage:
+        return True
+
+    origin = get_origin(type_hint)
+    if origin in (list, tuple):
+        return any(_contains_chat_message(arg) for arg in get_args(type_hint))
+
+    if origin in (Union, UnionType):
+        return any(_contains_chat_message(arg) for arg in get_args(type_hint))
+
+    return False
+
+
+def select_primary_input_type(message_types: list[Any]) -> Any | None:
+    """Choose the most user-friendly input type for workflow inputs.
+
+    Prefers ChatMessage (or containers thereof) and then falls back to primitives.
+
+    Args:
+        message_types: List of possible message types
+
+    Returns:
+        Selected primary input type, or None if list is empty
+    """
+    if not message_types:
+        return None
+
+    for message_type in message_types:
+        if _contains_chat_message(message_type):
+            return ChatMessage
+
+    preferred = (str, dict)
+
+    for candidate in preferred:
+        for message_type in message_types:
+            if message_type is candidate:
+                return candidate
+            origin = get_origin(message_type)
+            if origin is candidate:
+                return candidate
+
+    return message_types[0]
+
+
 # ============================================================================
 # Type System Utilities
 # ============================================================================

agent_framework_devui/models/__init__.py

@@ -4,11 +4,18 @@
 
 # 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,
@@ -23,16 +30,14 @@ from openai.types.shared import Metadata, ResponsesModel
 from ._discovery_models import DiscoveryResponse, EntityInfo
 from ._openai_custom import (
     AgentFrameworkRequest,
+    CustomResponseOutputItemAddedEvent,
+    CustomResponseOutputItemDoneEvent,
+    ExecutorActionItem,
     OpenAIError,
     ResponseFunctionResultComplete,
-    ResponseFunctionResultDelta,
     ResponseTraceEvent,
     ResponseTraceEventComplete,
-    ResponseTraceEventDelta,
-    ResponseUsageEventComplete,
-    ResponseUsageEventDelta,
     ResponseWorkflowEventComplete,
-    ResponseWorkflowEventDelta,
 )
 
 # Type alias for compatibility
@@ -41,19 +46,29 @@ OpenAIResponse = Response
 # Export all types for easy importing
 __all__ = [
     "AgentFrameworkRequest",
+    "Conversation",
+    "ConversationDeletedResource",
+    "ConversationItem",
+    "CustomResponseOutputItemAddedEvent",
+    "CustomResponseOutputItemDoneEvent",
     "DiscoveryResponse",
     "EntityInfo",
+    "ExecutorActionItem",
     "InputTokensDetails",
     "Metadata",
     "OpenAIError",
     "OpenAIResponse",
     "OutputTokensDetails",
     "Response",
+    "ResponseCompletedEvent",
     "ResponseErrorEvent",
     "ResponseFunctionCallArgumentsDeltaEvent",
     "ResponseFunctionResultComplete",
-    "ResponseFunctionResultDelta",
+    "ResponseFunctionToolCall",
+    "ResponseFunctionToolCallOutputItem",
     "ResponseInputParam",
+    "ResponseOutputItemAddedEvent",
+    "ResponseOutputItemDoneEvent",
     "ResponseOutputMessage",
     "ResponseOutputText",
     "ResponseReasoningTextDeltaEvent",
@@ -61,12 +76,8 @@ __all__ = [
     "ResponseTextDeltaEvent",
     "ResponseTraceEvent",
     "ResponseTraceEventComplete",
-    "ResponseTraceEventDelta",
     "ResponseUsage",
-    "ResponseUsageEventComplete",
-    "ResponseUsageEventDelta",
     "ResponseWorkflowEventComplete",
-    "ResponseWorkflowEventDelta",
     "ResponsesModel",
     "ToolParam",
 ]

agent_framework_devui/models/_discovery_models.py

@@ -31,8 +31,7 @@ class EntityInfo(BaseModel):
     metadata: dict[str, Any] = Field(default_factory=dict)
 
     # Source information
-    source: str = "directory"  # "directory", "in_memory", "remote_gallery"
-    original_url: str | None = None
+    source: str = "directory"  # "directory" or "in_memory"
 
     # Environment variable requirements
     required_env_vars: list[EnvVarRequirement] | None = None

agent_framework_devui/models/_openai_custom.py

@@ -3,11 +3,12 @@
 """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, traces, and function results.
+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
@@ -15,59 +16,75 @@ from pydantic import BaseModel, ConfigDict
 # Custom Agent Framework OpenAI event types for structured data
 
 
-class ResponseWorkflowEventDelta(BaseModel):
-    """Structured workflow event with completion tracking."""
+# Agent lifecycle events - simple and clear
+class AgentStartedEvent:
+    """Event emitted when an agent starts execution."""
 
-    type: Literal["response.workflow_event.delta"] = "response.workflow_event.delta"
-    delta: dict[str, Any]
-    executor_id: str | None = None
-    is_complete: bool = False  # Track if this is the final part
-    item_id: str
-    output_index: int = 0
-    sequence_number: int
+    pass
 
 
-class ResponseWorkflowEventComplete(BaseModel):
-    """Complete workflow event data."""
+class AgentCompletedEvent:
+    """Event emitted when an agent completes execution successfully."""
 
-    type: Literal["response.workflow_event.complete"] = "response.workflow_event.complete"
-    data: dict[str, Any]  # Complete event data, not delta
-    executor_id: str | None = None
-    item_id: str
-    output_index: int = 0
-    sequence_number: int
+    pass
 
 
-class ResponseFunctionResultDelta(BaseModel):
-    """Structured function result with completion tracking."""
+@dataclass
+class AgentFailedEvent:
+    """Event emitted when an agent fails during execution."""
 
-    type: Literal["response.function_result.delta"] = "response.function_result.delta"
-    delta: dict[str, Any]
-    call_id: str
-    is_complete: bool = False
-    item_id: str
-    output_index: int = 0
+    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
 
 
-class ResponseFunctionResultComplete(BaseModel):
-    """Complete function result data."""
+class CustomResponseOutputItemDoneEvent(BaseModel):
+    """Custom version of ResponseOutputItemDoneEvent that accepts any item type.
 
-    type: Literal["response.function_result.complete"] = "response.function_result.complete"
-    data: dict[str, Any]  # Complete function result data, not delta
-    call_id: str
-    item_id: str
-    output_index: int = 0
+    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
 
 
-class ResponseTraceEventDelta(BaseModel):
-    """Structured trace event with completion tracking."""
+class ResponseWorkflowEventComplete(BaseModel):
+    """Complete workflow event data."""
 
-    type: Literal["response.trace.delta"] = "response.trace.delta"
-    delta: dict[str, Any]
-    span_id: str | None = None
-    is_complete: bool = False
+    type: Literal["response.workflow_event.complete"] = "response.workflow_event.complete"
+    data: dict[str, Any]  # Complete event data, not delta
+    executor_id: str | None = None
     item_id: str
     output_index: int = 0
     sequence_number: int
@@ -84,25 +101,27 @@ class ResponseTraceEventComplete(BaseModel):
     sequence_number: int
 
 
-class ResponseUsageEventDelta(BaseModel):
-    """Structured usage event with completion tracking."""
-
-    type: Literal["response.usage.delta"] = "response.usage.delta"
-    delta: dict[str, Any]
-    is_complete: bool = False
-    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)
 
-class ResponseUsageEventComplete(BaseModel):
-    """Complete usage event data."""
+    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.usage.complete"] = "response.usage.complete"
-    data: dict[str, Any]  # Complete usage data, not delta
+    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
 
 
 # Agent Framework extension fields
@@ -110,25 +129,28 @@ class AgentFrameworkExtraBody(BaseModel):
     """Agent Framework specific routing fields for OpenAI requests."""
 
     entity_id: str
-    thread_id: str | None = None
-    input_data: dict[str, Any] | None = None
+    # 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 extensions.
+    """OpenAI ResponseCreateParams with Agent Framework routing.
 
-    This properly extends the real OpenAI API request format while adding
-    our custom routing fields in extra_body.
+    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
-    input: str | list[Any]  # ResponseInputParam
+    model: str  # Used as entity_id in DevUI!
+    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
@@ -136,32 +158,35 @@ class AgentFrameworkRequest(BaseModel):
     max_output_tokens: int | None = None
     tools: list[dict[str, Any]] | None = None
 
-    # Agent Framework extension - strongly typed
-    extra_body: AgentFrameworkExtraBody | None = None
-
-    entity_id: str | None = None  # Allow entity_id as top-level field
+    # 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 either top-level field or extra_body."""
-        # Priority 1: Top-level entity_id field
-        if self.entity_id:
-            return self.entity_id
-
-        # Priority 2: entity_id in extra_body
-        if self.extra_body and hasattr(self.extra_body, "entity_id"):
-            return self.extra_body.entity_id
-
+    def get_entity_id(self) -> str:
+        """Get entity_id from model field.
+
+        In DevUI, model IS the entity_id (agent/workflow name).
+        Simple and clean!
+        """
+        return self.model
+
+    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."""
-        data = self.model_dump(exclude={"extra_body", "entity_id"}, exclude_none=True)
-        if self.extra_body:
-            # Don't merge extra_body into main params to keep them separate
-            data["extra_body"] = self.extra_body
-        return data
+        return self.model_dump(exclude_none=True)
 
 
 # Error handling
@@ -198,12 +223,7 @@ __all__ = [
     "AgentFrameworkRequest",
     "OpenAIError",
     "ResponseFunctionResultComplete",
-    "ResponseFunctionResultDelta",
     "ResponseTraceEvent",
     "ResponseTraceEventComplete",
-    "ResponseTraceEventDelta",
-    "ResponseUsageEventComplete",
-    "ResponseUsageEventDelta",
     "ResponseWorkflowEventComplete",
-    "ResponseWorkflowEventDelta",
 ]