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

agent_framework_devui/_server.py

@@ -7,7 +7,7 @@ import json
 import logging
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
-from typing import Any, get_origin
+from typing import Any
 
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.middleware.cors import CORSMiddleware
@@ -23,47 +23,6 @@ from .models._discovery_models import DiscoveryResponse, EntityInfo
 logger = logging.getLogger(__name__)
 
 
-def _extract_executor_message_types(executor: Any) -> list[Any]:
-    """Return declared input types for the given executor."""
-    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 _select_primary_input_type(message_types: list[Any]) -> Any | None:
-    """Choose the most user-friendly input type for rendering workflow inputs."""
-    if not message_types:
-        return None
-
-    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]
-
-
 class DevServer:
     """Development Server - OpenAI compatible API server for debugging agents."""
 
@@ -215,7 +174,7 @@ class DevServer:
 
         @app.get("/v1/entities/{entity_id}/info", response_model=EntityInfo)
         async def get_entity_info(entity_id: str) -> EntityInfo:
-            """Get detailed information about a specific entity."""
+            """Get detailed information about a specific entity (triggers lazy loading)."""
             try:
                 executor = await self._ensure_executor()
                 entity_info = executor.get_entity_info(entity_id)
@@ -223,86 +182,96 @@ class DevServer:
                 if not entity_info:
                     raise HTTPException(status_code=404, detail=f"Entity {entity_id} not found")
 
+                # Trigger lazy loading if entity not yet loaded
+                # This will import the module and enrich metadata
+                entity_obj = await executor.entity_discovery.load_entity(entity_id)
+
+                # Get updated entity info (may have been enriched during load)
+                entity_info = executor.get_entity_info(entity_id) or entity_info
+
                 # For workflows, populate additional detailed information
-                if entity_info.type == "workflow":
-                    entity_obj = executor.entity_discovery.get_entity_object(entity_id)
-                    if entity_obj:
-                        # Get workflow structure
-                        workflow_dump = None
-                        if hasattr(entity_obj, "to_dict") and callable(getattr(entity_obj, "to_dict", None)):
-                            try:
-                                workflow_dump = entity_obj.to_dict()  # type: ignore[attr-defined]
-                            except Exception:
-                                workflow_dump = None
-                        elif hasattr(entity_obj, "to_json") and callable(getattr(entity_obj, "to_json", None)):
-                            try:
-                                raw_dump = entity_obj.to_json()  # type: ignore[attr-defined]
-                            except Exception:
-                                workflow_dump = None
-                            else:
-                                if isinstance(raw_dump, (bytes, bytearray)):
-                                    try:
-                                        raw_dump = raw_dump.decode()
-                                    except Exception:
-                                        raw_dump = raw_dump.decode(errors="replace")
-                                if isinstance(raw_dump, str):
-                                    try:
-                                        parsed_dump = json.loads(raw_dump)
-                                    except Exception:
-                                        workflow_dump = raw_dump
-                                    else:
-                                        workflow_dump = parsed_dump if isinstance(parsed_dump, dict) else raw_dump
-                                else:
+                if entity_info.type == "workflow" and entity_obj:
+                    # Entity object already loaded by load_entity() above
+                    # Get workflow structure
+                    workflow_dump = None
+                    if hasattr(entity_obj, "to_dict") and callable(getattr(entity_obj, "to_dict", None)):
+                        try:
+                            workflow_dump = entity_obj.to_dict()  # type: ignore[attr-defined]
+                        except Exception:
+                            workflow_dump = None
+                    elif hasattr(entity_obj, "to_json") and callable(getattr(entity_obj, "to_json", None)):
+                        try:
+                            raw_dump = entity_obj.to_json()  # type: ignore[attr-defined]
+                        except Exception:
+                            workflow_dump = None
+                        else:
+                            if isinstance(raw_dump, (bytes, bytearray)):
+                                try:
+                                    raw_dump = raw_dump.decode()
+                                except Exception:
+                                    raw_dump = raw_dump.decode(errors="replace")
+                            if isinstance(raw_dump, str):
+                                try:
+                                    parsed_dump = json.loads(raw_dump)
+                                except Exception:
                                     workflow_dump = raw_dump
-                        elif hasattr(entity_obj, "__dict__"):
-                            workflow_dump = {k: v for k, v in entity_obj.__dict__.items() if not k.startswith("_")}
+                                else:
+                                    workflow_dump = parsed_dump if isinstance(parsed_dump, dict) else raw_dump
+                            else:
+                                workflow_dump = raw_dump
+                    elif hasattr(entity_obj, "__dict__"):
+                        workflow_dump = {k: v for k, v in entity_obj.__dict__.items() if not k.startswith("_")}
 
-                        # Get input schema information
-                        input_schema = {}
-                        input_type_name = "Unknown"
-                        start_executor_id = ""
+                    # Get input schema information
+                    input_schema = {}
+                    input_type_name = "Unknown"
+                    start_executor_id = ""
 
-                        try:
-                            from ._utils import generate_input_schema
+                    try:
+                        from ._utils import (
+                            extract_executor_message_types,
+                            generate_input_schema,
+                            select_primary_input_type,
+                        )
 
-                            start_executor = entity_obj.get_start_executor()
-                        except Exception as e:
-                            logger.debug(f"Could not extract input info for workflow {entity_id}: {e}")
-                        else:
-                            if start_executor:
-                                start_executor_id = getattr(start_executor, "executor_id", "") or getattr(
-                                    start_executor, "id", ""
-                                )
-
-                                message_types = _extract_executor_message_types(start_executor)
-                                input_type = _select_primary_input_type(message_types)
-
-                                if input_type:
-                                    input_type_name = getattr(input_type, "__name__", str(input_type))
-
-                                    # Generate schema using comprehensive schema generation
-                                    input_schema = generate_input_schema(input_type)
-
-                        if not input_schema:
-                            input_schema = {"type": "string"}
-                            if input_type_name == "Unknown":
-                                input_type_name = "string"
-
-                        # Get executor list
-                        executor_list = []
-                        if hasattr(entity_obj, "executors") and entity_obj.executors:
-                            executor_list = [getattr(ex, "executor_id", str(ex)) for ex in entity_obj.executors]
-
-                        # Create copy of entity info and populate workflow-specific fields
-                        update_payload: dict[str, Any] = {
-                            "workflow_dump": workflow_dump,
-                            "input_schema": input_schema,
-                            "input_type_name": input_type_name,
-                            "start_executor_id": start_executor_id,
-                        }
-                        if executor_list:
-                            update_payload["executors"] = executor_list
-                        return entity_info.model_copy(update=update_payload)
+                        start_executor = entity_obj.get_start_executor()
+                    except Exception as e:
+                        logger.debug(f"Could not extract input info for workflow {entity_id}: {e}")
+                    else:
+                        if start_executor:
+                            start_executor_id = getattr(start_executor, "executor_id", "") or getattr(
+                                start_executor, "id", ""
+                            )
+
+                            message_types = extract_executor_message_types(start_executor)
+                            input_type = select_primary_input_type(message_types)
+
+                            if input_type:
+                                input_type_name = getattr(input_type, "__name__", str(input_type))
+
+                                # Generate schema using comprehensive schema generation
+                                input_schema = generate_input_schema(input_type)
+
+                    if not input_schema:
+                        input_schema = {"type": "string"}
+                        if input_type_name == "Unknown":
+                            input_type_name = "string"
+
+                    # Get executor list
+                    executor_list = []
+                    if hasattr(entity_obj, "executors") and entity_obj.executors:
+                        executor_list = [getattr(ex, "executor_id", str(ex)) for ex in entity_obj.executors]
+
+                    # Create copy of entity info and populate workflow-specific fields
+                    update_payload: dict[str, Any] = {
+                        "workflow_dump": workflow_dump,
+                        "input_schema": input_schema,
+                        "input_type_name": input_type_name,
+                        "start_executor_id": start_executor_id,
+                    }
+                    if executor_list:
+                        update_payload["executors"] = executor_list
+                    return entity_info.model_copy(update=update_payload)
 
                 # For non-workflow entities, return as-is
                 return entity_info
@@ -313,70 +282,34 @@ class DevServer:
                 logger.error(f"Error getting entity info for {entity_id}: {e}")
                 raise HTTPException(status_code=500, detail=f"Failed to get entity info: {e!s}") from e
 
-        @app.post("/v1/entities/add")
-        async def add_entity(request: dict[str, Any]) -> dict[str, Any]:
-            """Add entity from URL."""
-            try:
-                url = request.get("url")
-                metadata = request.get("metadata", {})
-
-                if not url:
-                    raise HTTPException(status_code=400, detail="URL is required")
+        @app.post("/v1/entities/{entity_id}/reload")
+        async def reload_entity(entity_id: str) -> dict[str, Any]:
+            """Hot reload entity (clears cache, will reimport on next access).
 
-                logger.info(f"Attempting to add entity from URL: {url}")
-                executor = await self._ensure_executor()
-                entity_info, error_msg = await executor.entity_discovery.fetch_remote_entity(url, metadata)
-
-                if not entity_info:
-                    # Sanitize error message - only return safe, user-friendly errors
-                    logger.error(f"Failed to fetch or validate entity from {url}: {error_msg}")
-                    safe_error = error_msg if error_msg else "Failed to fetch or validate entity"
-                    raise HTTPException(status_code=400, detail=safe_error)
-
-                logger.info(f"Successfully added entity: {entity_info.id}")
-                return {"success": True, "entity": entity_info.model_dump()}
-
-            except HTTPException:
-                raise
-            except Exception as e:
-                logger.error(f"Error adding entity: {e}", exc_info=True)
-                # Don't expose internal error details to client
-                raise HTTPException(
-                    status_code=500, detail="An unexpected error occurred while adding the entity"
-                ) from e
-
-        @app.delete("/v1/entities/{entity_id}")
-        async def remove_entity(entity_id: str) -> dict[str, Any]:
-            """Remove entity by ID."""
+            This enables hot reload during development - edit entity code, call this endpoint,
+            and the next execution will use the updated code without server restart.
+            """
             try:
                 executor = await self._ensure_executor()
 
-                # Cleanup entity resources before removal
-                try:
-                    entity_obj = executor.entity_discovery.get_entity_object(entity_id)
-                    if entity_obj and hasattr(entity_obj, "chat_client"):
-                        client = entity_obj.chat_client
-                        if hasattr(client, "close") and callable(client.close):
-                            if inspect.iscoroutinefunction(client.close):
-                                await client.close()
-                            else:
-                                client.close()
-                            logger.info(f"Closed client for entity: {entity_id}")
-                except Exception as e:
-                    logger.warning(f"Error closing entity {entity_id} during removal: {e}")
+                # Check if entity exists
+                entity_info = executor.get_entity_info(entity_id)
+                if not entity_info:
+                    raise HTTPException(status_code=404, detail=f"Entity {entity_id} not found")
 
-                # Remove entity from registry
-                success = executor.entity_discovery.remove_remote_entity(entity_id)
+                # Invalidate cache
+                executor.entity_discovery.invalidate_entity(entity_id)
 
-                if success:
-                    return {"success": True}
-                raise HTTPException(status_code=404, detail="Entity not found or cannot be removed")
+                return {
+                    "success": True,
+                    "message": f"Entity '{entity_id}' cache cleared. Will reload on next access.",
+                }
 
             except HTTPException:
                 raise
             except Exception as e:
-                logger.error(f"Error removing entity {entity_id}: {e}")
-                raise HTTPException(status_code=500, detail=f"Failed to remove entity: {e!s}") from e
+                logger.error(f"Error reloading entity {entity_id}: {e}")
+                raise HTTPException(status_code=500, detail=f"Failed to reload entity: {e!s}") from e
 
         @app.post("/v1/responses")
         async def create_response(request: AgentFrameworkRequest, raw_request: Request) -> Any:
@@ -421,112 +354,161 @@ class DevServer:
                 error = OpenAIError.create(f"Execution failed: {e!s}")
                 return JSONResponse(status_code=500, content=error.to_dict())
 
-        @app.post("/v1/threads")
-        async def create_thread(request_data: dict[str, Any]) -> dict[str, Any]:
-            """Create a new thread for an agent."""
+        # ========================================
+        # OpenAI Conversations API (Standard)
+        # ========================================
+
+        @app.post("/v1/conversations")
+        async def create_conversation(request_data: dict[str, Any]) -> dict[str, Any]:
+            """Create a new conversation - OpenAI standard."""
             try:
-                agent_id = request_data.get("agent_id")
-                if not agent_id:
-                    raise HTTPException(status_code=400, detail="agent_id is required")
+                metadata = request_data.get("metadata")
+                executor = await self._ensure_executor()
+                conversation = executor.conversation_store.create_conversation(metadata=metadata)
+                return conversation.model_dump()
+            except HTTPException:
+                raise
+            except Exception as e:
+                logger.error(f"Error creating conversation: {e}")
+                raise HTTPException(status_code=500, detail=f"Failed to create conversation: {e!s}") from e
 
+        @app.get("/v1/conversations")
+        async def list_conversations(agent_id: str | None = None) -> dict[str, Any]:
+            """List conversations, optionally filtered by agent_id."""
+            try:
                 executor = await self._ensure_executor()
-                thread_id = executor.create_thread(agent_id)
+
+                if agent_id:
+                    # Filter by agent_id metadata
+                    conversations = executor.conversation_store.list_conversations_by_metadata({"agent_id": agent_id})
+                else:
+                    # Return all conversations (for InMemoryStore, list all)
+                    # Note: This assumes list_conversations_by_metadata({}) returns all
+                    conversations = executor.conversation_store.list_conversations_by_metadata({})
 
                 return {
-                    "id": thread_id,
-                    "object": "thread",
-                    "created_at": int(__import__("time").time()),
-                    "metadata": {"agent_id": agent_id},
+                    "object": "list",
+                    "data": [conv.model_dump() for conv in conversations],
+                    "has_more": False,
                 }
             except HTTPException:
                 raise
             except Exception as e:
-                logger.error(f"Error creating thread: {e}")
-                raise HTTPException(status_code=500, detail=f"Failed to create thread: {e!s}") from e
+                logger.error(f"Error listing conversations: {e}")
+                raise HTTPException(status_code=500, detail=f"Failed to list conversations: {e!s}") from e
 
-        @app.get("/v1/threads")
-        async def list_threads(agent_id: str) -> dict[str, Any]:
-            """List threads for an agent."""
+        @app.get("/v1/conversations/{conversation_id}")
+        async def retrieve_conversation(conversation_id: str) -> dict[str, Any]:
+            """Get conversation - OpenAI standard."""
             try:
                 executor = await self._ensure_executor()
-                thread_ids = executor.list_threads_for_agent(agent_id)
-
-                # Convert thread IDs to thread objects
-                threads = []
-                for thread_id in thread_ids:
-                    threads.append({"id": thread_id, "object": "thread", "agent_id": agent_id})
-
-                return {"object": "list", "data": threads}
+                conversation = executor.conversation_store.get_conversation(conversation_id)
+                if not conversation:
+                    raise HTTPException(status_code=404, detail="Conversation not found")
+                return conversation.model_dump()
+            except HTTPException:
+                raise
             except Exception as e:
-                logger.error(f"Error listing threads: {e}")
-                raise HTTPException(status_code=500, detail=f"Failed to list threads: {e!s}") from e
+                logger.error(f"Error getting conversation {conversation_id}: {e}")
+                raise HTTPException(status_code=500, detail=f"Failed to get conversation: {e!s}") from e
 
-        @app.get("/v1/threads/{thread_id}")
-        async def get_thread(thread_id: str) -> dict[str, Any]:
-            """Get thread information."""
+        @app.post("/v1/conversations/{conversation_id}")
+        async def update_conversation(conversation_id: str, request_data: dict[str, Any]) -> dict[str, Any]:
+            """Update conversation metadata - OpenAI standard."""
             try:
                 executor = await self._ensure_executor()
-
-                # Check if thread exists
-                thread = executor.get_thread(thread_id)
-                if not thread:
-                    raise HTTPException(status_code=404, detail="Thread not found")
-
-                # Get the agent that owns this thread
-                agent_id = executor.get_agent_for_thread(thread_id)
-
-                return {"id": thread_id, "object": "thread", "agent_id": agent_id}
+                metadata = request_data.get("metadata", {})
+                conversation = executor.conversation_store.update_conversation(conversation_id, metadata=metadata)
+                return conversation.model_dump()
+            except ValueError as e:
+                raise HTTPException(status_code=404, detail=str(e)) from e
             except HTTPException:
                 raise
             except Exception as e:
-                logger.error(f"Error getting thread {thread_id}: {e}")
-                raise HTTPException(status_code=500, detail=f"Failed to get thread: {e!s}") from e
+                logger.error(f"Error updating conversation {conversation_id}: {e}")
+                raise HTTPException(status_code=500, detail=f"Failed to update conversation: {e!s}") from e
 
-        @app.delete("/v1/threads/{thread_id}")
-        async def delete_thread(thread_id: str) -> dict[str, Any]:
-            """Delete a thread."""
+        @app.delete("/v1/conversations/{conversation_id}")
+        async def delete_conversation(conversation_id: str) -> dict[str, Any]:
+            """Delete conversation - OpenAI standard."""
             try:
                 executor = await self._ensure_executor()
-                success = executor.delete_thread(thread_id)
-
-                if not success:
-                    raise HTTPException(status_code=404, detail="Thread not found")
-
-                return {"id": thread_id, "object": "thread.deleted", "deleted": True}
+                result = executor.conversation_store.delete_conversation(conversation_id)
+                return result.model_dump()
+            except ValueError as e:
+                raise HTTPException(status_code=404, detail=str(e)) from e
             except HTTPException:
                 raise
             except Exception as e:
-                logger.error(f"Error deleting thread {thread_id}: {e}")
-                raise HTTPException(status_code=500, detail=f"Failed to delete thread: {e!s}") from e
+                logger.error(f"Error deleting conversation {conversation_id}: {e}")
+                raise HTTPException(status_code=500, detail=f"Failed to delete conversation: {e!s}") from e
 
-        @app.get("/v1/threads/{thread_id}/messages")
-        async def get_thread_messages(thread_id: str) -> dict[str, Any]:
-            """Get messages from a thread."""
+        @app.post("/v1/conversations/{conversation_id}/items")
+        async def create_conversation_items(conversation_id: str, request_data: dict[str, Any]) -> dict[str, Any]:
+            """Add items to conversation - OpenAI standard."""
             try:
                 executor = await self._ensure_executor()
+                items = request_data.get("items", [])
+                conv_items = await executor.conversation_store.add_items(conversation_id, items=items)
+                return {"object": "list", "data": [item.model_dump() for item in conv_items]}
+            except ValueError as e:
+                raise HTTPException(status_code=404, detail=str(e)) from e
+            except HTTPException:
+                raise
+            except Exception as e:
+                logger.error(f"Error adding items to conversation {conversation_id}: {e}")
+                raise HTTPException(status_code=500, detail=f"Failed to add items: {e!s}") from e
+
+        @app.get("/v1/conversations/{conversation_id}/items")
+        async def list_conversation_items(
+            conversation_id: str, limit: int = 100, after: str | None = None, order: str = "asc"
+        ) -> dict[str, Any]:
+            """List conversation items - OpenAI standard."""
+            try:
+                executor = await self._ensure_executor()
+                items, has_more = await executor.conversation_store.list_items(
+                    conversation_id, limit=limit, after=after, order=order
+                )
+                return {
+                    "object": "list",
+                    "data": [item.model_dump() for item in items],
+                    "has_more": has_more,
+                }
+            except ValueError as e:
+                raise HTTPException(status_code=404, detail=str(e)) from e
+            except HTTPException:
+                raise
+            except Exception as e:
+                logger.error(f"Error listing items for conversation {conversation_id}: {e}")
+                raise HTTPException(status_code=500, detail=f"Failed to list items: {e!s}") from e
 
-                # Check if thread exists
-                thread = executor.get_thread(thread_id)
-                if not thread:
-                    raise HTTPException(status_code=404, detail="Thread not found")
-
-                # Get messages from thread
-                messages = await executor.get_thread_messages(thread_id)
-
-                return {"object": "list", "data": messages, "thread_id": thread_id}
+        @app.get("/v1/conversations/{conversation_id}/items/{item_id}")
+        async def retrieve_conversation_item(conversation_id: str, item_id: str) -> dict[str, Any]:
+            """Get specific conversation item - OpenAI standard."""
+            try:
+                executor = await self._ensure_executor()
+                item = executor.conversation_store.get_item(conversation_id, item_id)
+                if not item:
+                    raise HTTPException(status_code=404, detail="Item not found")
+                return item.model_dump()
             except HTTPException:
                 raise
             except Exception as e:
-                logger.error(f"Error getting messages for thread {thread_id}: {e}")
-                raise HTTPException(status_code=500, detail=f"Failed to get thread messages: {e!s}") from e
+                logger.error(f"Error getting item {item_id} from conversation {conversation_id}: {e}")
+                raise HTTPException(status_code=500, detail=f"Failed to get item: {e!s}") from e
 
     async def _stream_execution(
         self, executor: AgentFrameworkExecutor, request: AgentFrameworkRequest
     ) -> AsyncGenerator[str, None]:
         """Stream execution directly through executor."""
         try:
-            # Direct call to executor - simple and clean
+            # Collect events for final response.completed event
+            events = []
+
+            # Stream all events
             async for event in executor.execute_streaming(request):
+                events.append(event)
+
                 # IMPORTANT: Check model_dump_json FIRST because to_json() can have newlines (pretty-printing)
                 # which breaks SSE format. model_dump_json() returns single-line JSON.
                 if hasattr(event, "model_dump_json"):
@@ -544,6 +526,17 @@ class DevServer:
                     payload = json.dumps(str(event))
                 yield f"data: {payload}\n\n"
 
+            # Aggregate to final response and emit response.completed event (OpenAI standard)
+            from .models import ResponseCompletedEvent
+
+            final_response = await executor.message_mapper.aggregate_to_response(events, request)
+            completed_event = ResponseCompletedEvent(
+                type="response.completed",
+                response=final_response,
+                sequence_number=len(events),
+            )
+            yield f"data: {completed_event.model_dump_json()}\n\n"
+
             # Send final done event
             yield "data: [DONE]\n\n"