Merge pull request #7 from UABGH-Emerging-Technologies/feature/responses-api-migration

feat: add GPT-5 Responses API support

Author: rlmelvin

UMLBot/config/config.py

@@ -3,7 +3,9 @@
 import logging
 import logging.config
 import os
+import re
 from pathlib import Path
+from re import Pattern
 
 
 def _load_env_file(path: Path) -> None:
@@ -34,6 +36,14 @@ def _load_env_file(path: Path) -> None:
 _load_env_file(Path(__file__).resolve().parents[2] / ".env")
 
 
+_GPT5_PATTERN: Pattern[str] = re.compile(r"^gpt-?5", re.IGNORECASE)
+
+
+def is_responses_api_model(model_name: str) -> bool:
+    """Return True if the model should use the OpenAI Responses API."""
+    return bool(_GPT5_PATTERN.match(model_name))
+
+
 class UMLBotConfig:
     """
     Configuration class for UMLBot.
@@ -88,6 +98,11 @@ class UMLBotConfig:
     )
     DIAGRAM_SUCCESS_MSG = "Diagram generated successfully using LLM."
 
+    # Responses API reasoning effort for GPT-5 series models.
+    # Valid values: "none" (gpt-5.2+), "minimal" (< gpt-5.2), "low", "medium",
+    # "high", or None (model default).
+    REASONING_EFFORT: str | None = os.getenv("REASONING_EFFORT", "low")
+
     # PlantUML JAR rendering
     PLANTUML_JAR_PATH = os.getenv(
         "UMLBOT_PLANTUML_JAR_PATH",

UMLBot/services/diagram_service.py

@@ -12,7 +12,7 @@
 
 from PIL import Image, ImageDraw, ImageFont
 
-from UMLBot.config.config import UMLBotConfig
+from UMLBot.config.config import UMLBotConfig, is_responses_api_model
 from UMLBot.diagram_handlers import (
     C4DraftHandler,
     ERDraftHandler,
@@ -235,11 +235,14 @@ def _generate_from_description(
         openai_compatible_model: str,
     ) -> DiagramGenerationResult:
         """Shared diagram generation pipeline with per-request LLM credentials."""
+        _use_responses: bool = is_responses_api_model(openai_compatible_model)
         handler._init_openai(
             openai_compatible_endpoint=openai_compatible_endpoint,
             openai_compatible_key=openai_compatible_key,
             openai_compatible_model=openai_compatible_model,
             name="UMLBot",
+            use_responses_api=_use_responses,
+            reasoning_effort=UMLBotConfig.REASONING_EFFORT if _use_responses else None,
         )
 
         try:

docker-compose.yml

@@ -4,6 +4,7 @@ services:
     environment:
       PYTHONUNBUFFERED: 1
       UMLBOT_PLANTUML_JAR_PATH: /opt/plantuml/plantuml.jar
+      REASONING_EFFORT: ${REASONING_EFFORT:-low}
     ports:
       - "8000:8000"
     healthcheck:
@@ -13,3 +14,16 @@ services:
       retries: 10
       start_period: 30s
     restart: unless-stopped
+
+  streamlit:
+    build: .
+    command: ["streamlit", "run", "streamlit_app.py", "--server.port=8501", "--server.address=0.0.0.0"]
+    environment:
+      PYTHONUNBUFFERED: 1
+      UMLBOT_ENDPOINT: http://umlbot:8000
+    ports:
+      - "8501:8501"
+    depends_on:
+      umlbot:
+        condition: service_healthy
+    restart: unless-stopped

docs/env_var_config_pattern.md

@@ -0,0 +1,112 @@
+# Environment Variable Configuration Pattern
+
+This document describes the pattern for using environment variables to override
+application configuration values.  The goal is a **single name** that appears
+identically in the Python config class, the Docker Compose `environment:`
+block, the Azure Container App configuration screen, and any `.env` files.
+
+## Core rule
+
+> **The Python constant name and the environment variable name MUST be
+> identical.**
+
+When an operator sets `REASONING_EFFORT=medium` on an Azure container, they
+should be able to grep the codebase for that exact string and land on the
+config class attribute that consumes it.  No prefix translation, no casing
+changes.
+
+## How to add a new overridable config value
+
+### 1. Add the class attribute with `os.getenv`
+
+```python
+# UMLBot/config/config.py
+class UMLBotConfig:
+    # <short comment explaining the setting and valid values>
+    MY_NEW_SETTING: str = os.getenv("MY_NEW_SETTING", "default_value")
+```
+
+- The first argument to `os.getenv` is the **same string** as the attribute name.
+- Always provide a sensible default so the app runs without any env vars set.
+- Use a type annotation on the attribute.
+
+### 2. Add it to `docker-compose.yml`
+
+```yaml
+services:
+  umlbot:
+    environment:
+      MY_NEW_SETTING: ${MY_NEW_SETTING:-default_value}
+```
+
+The `${VAR:-default}` syntax lets the host's env override the compose default,
+which in turn overrides the Python default.  Use the **same default** in both
+places to avoid surprises.
+
+### 3. Add it to `.env.example`
+
+```bash
+# Description of the setting (default: default_value)
+# MY_NEW_SETTING=default_value
+```
+
+Keep entries commented out so a bare `cp .env.example .env` produces a
+working configuration that matches the Python defaults.
+
+### 4. Reference it in code
+
+```python
+from UMLBot.config.config import UMLBotConfig
+
+value = UMLBotConfig.MY_NEW_SETTING
+```
+
+Never call `os.getenv` a second time elsewhere in the code.  All env var
+reads are centralized in the config class.
+
+## Naming conventions
+
+| Scope | Convention | Example |
+|-------|-----------|---------|
+| UMLBot-specific infrastructure | `UMLBOT_` prefix | `UMLBOT_PLANTUML_JAR_PATH` |
+| LLM / API behaviour settings | Descriptive, no prefix | `REASONING_EFFORT` |
+| Cross-service URLs | `UMLBOT_` prefix | `UMLBOT_ENDPOINT` |
+
+The prefix is useful when an env var might collide with another service's
+variable in a shared container group.  For settings that are clearly
+domain-specific (like `REASONING_EFFORT` for OpenAI's Responses API), a prefix
+adds noise without reducing ambiguity.
+
+Use your judgement, but when in doubt, match the name the external API or
+documentation already uses.
+
+## Current inventory
+
+| Python constant | Env var | Default | Location |
+|----------------|---------|---------|----------|
+| `UMLBOT_PLANTUML_JAR_PATH` | `UMLBOT_PLANTUML_JAR_PATH` | `/opt/plantuml/plantuml.jar` | `UMLBotConfig` |
+| `UMLBOT_DATA_DIR`* | `UMLBOT_DATA_DIR` | `/data` | `UMLBotConfig` |
+| `REASONING_EFFORT` | `REASONING_EFFORT` | `low` | `UMLBotConfig` |
+| `UMLBOT_ENDPOINT`** | `UMLBOT_ENDPOINT` | `http://localhost:8000` | `streamlit_app.py` |
+
+\* `UMLBOT_DATA_DIR` is consumed as `DATA_DIR` in the config class today.
+This is a legacy inconsistency that should be aligned in a future PR.
+
+\** `UMLBOT_ENDPOINT` lives in `streamlit_app.py` as `API_BASE_URL` rather
+than in `UMLBotConfig`.  This is another legacy inconsistency to align.
+
+## Anti-patterns
+
+- **Different names for the same thing.** Don't name the attribute
+  `JAR_PATH` and the env var `UMLBOT_PLANTUML_JAR_PATH`.  An operator
+  reading the Azure config screen should be able to find the code with a
+  single search.
+
+- **Scattered `os.getenv` calls.** Every env-var read should be in
+  `UMLBotConfig` (or the equivalent config module for other projects).
+  Duplicate reads in service code make it hard to audit what the app
+  depends on.
+
+- **Missing defaults.** If a setting doesn't have a default, the app crashes
+  on startup when the env var is absent.  If a value is truly required (like
+  an API key), use `manage_sensitive()` instead of `os.getenv`.

pyproject.toml

@@ -7,6 +7,8 @@ dependencies = [
     # Runtime ---------------------------------------------------------------
     "aiweb-common @ git+https://github.com/UABPeriopAI/llm_utils.git@develop",
     "fastapi>=0.118.3",
+    "langchain-openai>=1.1.0",
+    "openai>=2.20.0",
     "Pillow",
     "python-multipart>=0.0.20",
     "rich>=14.2.0",

streamlit_app.py

@@ -48,9 +48,7 @@
 MODEL_TO_USE: str = "gpt-5.2"
 
 # Backend URL from environment with localhost fallback for local dev
-API_BASE_URL: str = os.environ.get(
-    "UMLBOT_ENDPOINT", "http://localhost:8000"
-)
+API_BASE_URL: str = os.environ.get("UMLBOT_ENDPOINT", "http://localhost:8000")
 
 DEFAULT_TIMEOUT: int = 120
 
@@ -94,9 +92,7 @@ def _fetch_remote_config() -> Dict[str, Any]:
     if _remote_config is not None:
         return _remote_config
     try:
-        resp = requests.get(
-            f"{API_BASE_URL.rstrip('/')}/v01/config", timeout=10
-        )
+        resp = requests.get(f"{API_BASE_URL.rstrip('/')}/v01/config", timeout=10)
         resp.raise_for_status()
         _remote_config = resp.json()
         return _remote_config
@@ -259,9 +255,7 @@ def api_render(
     render_path: str = ENDPOINT_MAP[mode][1]
     payload: Dict[str, Any] = {"plantuml_code": plantuml_code}
     try:
-        resp = requests.post(
-            _build_url(render_path), json=payload, timeout=60
-        )
+        resp = requests.post(_build_url(render_path), json=payload, timeout=60)
         resp.raise_for_status()
         data = resp.json()
         return {
@@ -393,9 +387,7 @@ def _init_session_state(config: Dict[str, Any]) -> None:
     if "theme" not in st.session_state:
         st.session_state["theme"] = ""
     if "uml_subtype" not in st.session_state:
-        st.session_state["uml_subtype"] = config.get(
-            "default_diagram_type", "Use Case"
-        )
+        st.session_state["uml_subtype"] = config.get("default_diagram_type", "Use Case")
 
 
 # ---------------------------------------------------------------------------
@@ -458,9 +450,7 @@ def _handle_chat_input(
     else:
         st.session_state[error_key] = result.get("message", "Generation failed.")
         st.session_state[status_key] = ""
-        history.append(
-            {"role": "assistant", "content": f"Error: {result.get('message', '')}"}
-        )
+        history.append({"role": "assistant", "content": f"Error: {result.get('message', '')}"})
 
     st.session_state[history_key] = history
 
@@ -498,18 +488,12 @@ def _render_mode_tab(mode: str, config: Dict[str, Any]) -> None:
     error_key: str = _state_key(mode, "error_message")
 
     # UML sub-type dropdown (only for uml mode)
-    diagram_types: List[str] = config.get(
-        "diagram_types", ["Use Case", "Class", "Sequence"]
-    )
+    diagram_types: List[str] = config.get("diagram_types", ["Use Case", "Class", "Sequence"])
     if mode == "uml":
         current_subtype: str = st.session_state.get(
             "uml_subtype", config.get("default_diagram_type", "Use Case")
         )
-        idx: int = (
-            diagram_types.index(current_subtype)
-            if current_subtype in diagram_types
-            else 0
-        )
+        idx: int = diagram_types.index(current_subtype) if current_subtype in diagram_types else 0
         st.session_state["uml_subtype"] = st.selectbox(
             "UML Diagram Type",
             options=diagram_types,
@@ -627,17 +611,15 @@ def show_umlbot_page() -> None:
     apply_uab_font()
 
     st.title(f"{page_icon} {page_title}")
-    st.markdown(
-        """
+    st.markdown("""
         **Interactive diagram generation powered by LLM + PlantUML**
 
         Describe what you want in plain language and the AI will generate
         PlantUML code and render it.  You can iterate on the diagram through
         the chat, or edit the code directly and re-render.
 
         ---
-        """
-    )
+        """)
 
     config: Dict[str, Any] = _fetch_remote_config()
     _init_session_state(config)