Python: DevUI - Internal Refactor, Conversations API support, and per… (#1235)

* Python: DevUI - Internal Refactor, Conversations API support, and performance improvements

Comprehensive refactor of DevUI package including samples relocation,
frontend reorganization, OpenAI Conversations API support, and critical
performance and code quality improvements.

Key Changes:

Architecture & Organization
- Moved DevUI samples to python/samples/getting_started/devui/
- Consolidated with other framework samples for better discoverability
- Added .env.example files and comprehensive README
- Restructured frontend components into feature-based folders (agent, workflow, gallery, layout)
- Created new OpenAI-compliant message renderers (devui should render oai responses types primarily)

New Features
- Added _conversations.py (467 lines) - Full conversation storage abstraction, replaces the /threads endpoint to better match oai conversations api
- Implements OpenAI Conversations API for thread management, Supports in-memory and extensible storage backends

API Simplification
- Use 'model' field as entity_id (agent/workflow name) instead of extra_body
- Use standard OpenAI 'conversation' field for conversation context.

Performance & Quality Improvements
- Improved context management in MessageMapper with bounded memory (~500KB max)
- Implemented hybrid LRU + cleanup approach to prevent unbounded memory growth
- General QOL improvement - Eliminated ~150 lines of dead/duplicate code, Consolidated helper functions into _utils.py, Extracted magic numbers to module-level constants, Optimized conversation item lookups with index-based approach

Testing
- Added test_conversations.py (13 tests)
- Added test_performance_fixes.py (9 tests)
- Updated existing tests for code consolidation
- 53 tests passing

Impact: 76 files changed: +4,106 insertions, -2,373 deletions
All linting and formatting checks passing. No breaking changes - backward compatible.

Migration: Samples moved to python/samples/getting_started/devui/

* readme lint fixes

* initial support for function approval and minor ui fixes

python/packages/devui/README.md

@@ -78,21 +78,65 @@ devui ./agents --tracing framework
 
 ## OpenAI-Compatible API
 
-For convenience, you can interact with the agents/workflows using the standard OpenAI API format. Just specify the `entity_id` in the `extra_body` field. This can be an `agent_id` or `workflow_id`.
+For convenience, DevUI provides an OpenAI Responses backend API. This means you can run the backend and also use the OpenAI client sdk to connect to it. Use **agent/workflow name as the model**, and set streaming to `True` as needed.
 
 ```bash
-# Standard OpenAI format
+# Simple - use your entity name as the model
 curl -X POST http://localhost:8080/v1/responses \
   -H "Content-Type: application/json" \
   -d @- << 'EOF'
 {
-  "model": "agent-framework",
-  "input": "Hello world",
-  "extra_body": {"entity_id": "weather_agent"}
+  "model": "weather_agent",
+  "input": "Hello world"
 }
-
 ```
 
+Or use the OpenAI Python SDK:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://localhost:8080/v1",
+    api_key="not-needed"  # API key not required for local DevUI
+)
+
+response = client.responses.create(
+    model="weather_agent",  # Your agent/workflow name
+    input="What's the weather in Seattle?"
+)
+
+# Extract text from response
+print(response.output[0].content[0].text)
+# Supports streaming with stream=True
+```
+
+### Multi-turn Conversations
+
+Use the standard OpenAI `conversation` parameter for multi-turn conversations:
+
+```python
+# Create a conversation
+conversation = client.conversations.create(
+    metadata={"agent_id": "weather_agent"}
+)
+
+# Use it across multiple turns
+response1 = client.responses.create(
+    model="weather_agent",
+    input="What's the weather in Seattle?",
+    conversation=conversation.id
+)
+
+response2 = client.responses.create(
+    model="weather_agent",
+    input="How about tomorrow?",
+    conversation=conversation.id  # Continues the conversation!
+)
+```
+
+**How it works:** DevUI automatically retrieves the conversation's message history from the stored thread and passes it to the agent. You don't need to manually manage message history - just provide the same `conversation` ID for follow-up requests.
+
 ## CLI Options
 
 ```bash
@@ -109,30 +153,79 @@ Options:
 
 ## Key Endpoints
 
+## API Mapping
+
+Given that DevUI offers an OpenAI Responses API, it internally maps messages and events from Agent Framework to OpenAI Responses API events (in `_mapper.py`). For transparency, this mapping is shown below:
+
+| Agent Framework Content         | OpenAI Event/Type                        | Status   |
+| ------------------------------- | ---------------------------------------- | -------- |
+| `TextContent`                   | `response.output_text.delta`             | Standard |
+| `TextReasoningContent`          | `response.reasoning.delta`               | Standard |
+| `FunctionCallContent` (initial) | `response.output_item.added`             | Standard |
+| `FunctionCallContent` (args)    | `response.function_call_arguments.delta` | Standard |
+| `FunctionResultContent`         | `response.function_result.complete`      | DevUI    |
+| `ErrorContent`                  | `response.error`                         | Standard |
+| `UsageContent`                  | Final `Response.usage` field (not streamed) | Standard |
+| `WorkflowEvent`                 | `response.workflow_event.complete`       | DevUI    |
+| `DataContent`, `UriContent`     | `response.trace.complete`                | DevUI    |
+
+- **Standard** = OpenAI Responses API spec
+- **DevUI** = Custom extensions for Agent Framework features (workflows, traces, function results)
+
+### OpenAI Responses API Compliance
+
+DevUI follows the OpenAI Responses API specification for maximum compatibility:
+
+**Standard OpenAI Types Used:**
+- `ResponseOutputItemAddedEvent` - Output item notifications (function calls)
+- `Response.usage` - Token usage (in final response, not streamed)
+- All standard text, reasoning, and function call events
+
+**Custom DevUI Extensions:**
+- `response.function_result.complete` - Function execution results (DevUI executes functions, OpenAI doesn't)
+- `response.workflow_event.complete` - Agent Framework workflow events
+- `response.trace.complete` - Execution traces for debugging
+
+These custom extensions are clearly namespaced and can be safely ignored by standard OpenAI clients.
+
+### Entity Management
+
 - `GET /v1/entities` - List discovered agents/workflows
 - `GET /v1/entities/{entity_id}/info` - Get detailed entity information
 - `POST /v1/entities/add` - Add entity from URL (for gallery samples)
 - `DELETE /v1/entities/{entity_id}` - Remove remote entity
+
+### Execution (OpenAI Responses API)
+
 - `POST /v1/responses` - Execute agent/workflow (streaming or sync)
+
+### Conversations (OpenAI Standard)
+
+- `POST /v1/conversations` - Create conversation
+- `GET /v1/conversations/{id}` - Get conversation
+- `POST /v1/conversations/{id}` - Update conversation metadata
+- `DELETE /v1/conversations/{id}` - Delete conversation
+- `GET /v1/conversations?agent_id={id}` - List conversations _(DevUI extension)_
+- `POST /v1/conversations/{id}/items` - Add items to conversation
+- `GET /v1/conversations/{id}/items` - List conversation items
+- `GET /v1/conversations/{id}/items/{item_id}` - Get conversation item
+
+### Health
+
 - `GET /health` - Health check
-- `POST /v1/threads` - Create thread for agent (optional)
-- `GET /v1/threads?agent_id={id}` - List threads for agent
-- `GET /v1/threads/{thread_id}` - Get thread info
-- `DELETE /v1/threads/{thread_id}` - Delete thread
-- `GET /v1/threads/{thread_id}/messages` - Get thread messages
 
 ## Implementation
 
 - **Discovery**: `agent_framework_devui/_discovery.py`
 - **Execution**: `agent_framework_devui/_executor.py`
 - **Message Mapping**: `agent_framework_devui/_mapper.py`
-- **Session Management**: `agent_framework_devui/_session.py`
+- **Conversations**: `agent_framework_devui/_conversations.py`
 - **API Server**: `agent_framework_devui/_server.py`
 - **CLI**: `agent_framework_devui/_cli.py`
 
 ## Examples
 
-See `samples/` for working agent and workflow implementations.
+See working implementations in `python/samples/getting_started/devui/`
 
 ## License