fix

README.md

@@ -1,12 +1,3 @@
----
-title: Aceup Transcript Analysis
-colorFrom: blue
-colorTo: gray
-sdk: docker
-app_port: 7860
-short_description: Transcript analysis API and Gradio interface.
----
-
 # ml-tech-assessment
 
 ## Environment Setup
@@ -37,12 +28,10 @@ short_description: Transcript analysis API and Gradio interface.
 ## Environment Variables
 
 1. Create a `.env` file in the root directory of the project
-2. Copy the contents of the provided `.env` file into your local `.env` file
-
-Required values:
+2. Add the OpenAI API key and optional model:
 
-```bash
-OPENAI_API_KEY=<your-openai-api-key>
+```env
+OPENAI_API_KEY=your-openai-api-key
 OPENAI_MODEL=gpt-4o-2024-08-06
 ```
 
@@ -91,7 +80,7 @@ http://127.0.0.1:8000/docs
 The Gradio frontend is available at:
 
 ```text
-http://127.0.0.1:8000
+http://127.0.0.1:8000/
 ```
 
 Analyze one transcript:
@@ -117,25 +106,6 @@ curl -X POST "http://127.0.0.1:8000/analyses/batch" \
 
 Analysis results are stored in memory, so they reset when the API process restarts.
 
-## Hugging Face Spaces Deployment
-
-This repository is configured as a Docker Space. The container serves FastAPI and the mounted Gradio UI through Uvicorn on port `7860`. Hugging Face opens the Space at `/`, where the Gradio app is served directly.
-
-Set `OPENAI_API_KEY` as a Hugging Face Space Secret. Optionally set `OPENAI_MODEL` as a Space Variable if you want to override the default model.
-
-Build and run the container locally:
-
-```bash
-docker build -t aceup-transcript-analysis .
-docker run --rm -p 7860:7860 --env-file .env aceup-transcript-analysis
-```
-
-Then open:
-
-```text
-http://127.0.0.1:7860
-```
-
 ## OpenAI Adapter Integration Test
 
 The live OpenAI adapter test is skipped by default so local test runs do not require network access or credentials. To run it explicitly:

app/configurations.py

@@ -1,10 +1,17 @@
+from pathlib import Path
+
 import pydantic_settings
 
 
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+
 class EnvConfigs(pydantic_settings.BaseSettings):
-    model_config =pydantic_settings.SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+    model_config = pydantic_settings.SettingsConfigDict(
+        env_file=PROJECT_ROOT / ".env",
+        env_file_encoding="utf-8",
+    )
 
     OPENAI_API_KEY: str
     OPENAI_MODEL: str = "gpt-4o-2024-08-06"
 
-

app/errors.py

@@ -10,5 +10,9 @@ class AnalysisNotFoundError(TranscriptAnalysisError):
     pass
 
 
+class ConfigurationError(TranscriptAnalysisError):
+    pass
+
+
 class LLMCompletionError(TranscriptAnalysisError):
     pass

app/frontend.py

@@ -1,13 +1,90 @@
 from collections.abc import Callable
+from html import escape
 
 import gradio as gr
 
 from app.domain import TranscriptAnalysis
-from app.errors import AnalysisNotFoundError, InvalidTranscriptError, LLMCompletionError
+from app.errors import (
+    AnalysisNotFoundError,
+    ConfigurationError,
+    InvalidTranscriptError,
+    LLMCompletionError,
+)
 from app.services import TranscriptAnalysisService
 
 ServiceFactory = Callable[[], TranscriptAnalysisService]
 FrontendResult = tuple[str, str, str]
+LoadingFrontendResult = tuple[dict[str, object], dict[str, object], str, dict[str, object]]
+AnalysisFrontendResult = tuple[dict[str, object], str]
+CleanupFrontendResult = tuple[dict[str, object], dict[str, object]]
+FailureFrontendResult = tuple[dict[str, object], dict[str, object], str, dict[str, object]]
+
+APP_CSS = """
+.analysis-status {
+    margin-top: 0.75rem;
+    width: 100%;
+}
+
+.analysis-status__content {
+    align-items: center;
+    background: var(--background-fill-secondary);
+    border: 1px solid var(--border-color-primary);
+    border-radius: 8px;
+    color: var(--body-text-color);
+    display: flex;
+    font-size: 0.95rem;
+    gap: 0.65rem;
+    line-height: 1.35;
+    min-height: 2.75rem;
+    padding: 0.7rem 0.9rem;
+    white-space: normal;
+    width: 100%;
+}
+
+.analysis-status__spinner {
+    animation: analysis-spin 0.8s linear infinite;
+    border: 2px solid var(--border-color-primary);
+    border-top-color: var(--button-primary-background-fill);
+    border-radius: 999px;
+    flex: 0 0 auto;
+    height: 1rem;
+    width: 1rem;
+}
+
+.analysis-status--error .analysis-status__content {
+    border-color: var(--error-border-color, #d33);
+    color: var(--error-text-color, #b00020);
+}
+
+@keyframes analysis-spin {
+    to {
+        transform: rotate(360deg);
+    }
+}
+
+.analysis-result {
+    background: var(--background-fill-primary);
+    border: 1px solid var(--border-color-primary);
+    border-radius: 8px;
+    margin-top: 1rem;
+    padding: 1rem 1.125rem;
+}
+
+.analysis-result h3 {
+    font-size: 1rem;
+    font-weight: 650;
+    margin: 1rem 0 0.35rem;
+}
+
+.analysis-result h3:first-child {
+    margin-top: 0;
+}
+
+.analysis-result p,
+.analysis-result ol {
+    margin-top: 0;
+}
+"""
 
 
 def build_gradio_app(service_factory: ServiceFactory) -> gr.Blocks:
@@ -22,65 +99,221 @@ def build_gradio_app(service_factory: ServiceFactory) -> gr.Blocks:
             )
             analyze_button = gr.Button("Analyze", variant="primary")
 
-            analysis_id_output = gr.Textbox(label="Analysis ID", interactive=False)
-            summary_output = gr.Textbox(label="Summary", lines=5, interactive=False)
-            action_items_output = gr.Textbox(
-                label="Suggested Next Steps",
-                lines=6,
-                interactive=False,
+            analysis_status_output = gr.HTML(
+                visible=False,
+                elem_classes=["analysis-status"],
             )
+            with gr.Group(visible=False, elem_classes=["analysis-result"]) as analysis_result_group:
+                analysis_result_output = gr.Markdown(
+                    container=False,
+                    line_breaks=True,
+                    buttons=["copy"],
+                )
 
-            analyze_button.click(
-                fn=lambda transcript: analyze_transcript(transcript, service_factory),
+            analyze_event = analyze_button.click(
+                fn=show_analyze_loading,
+                outputs=[
+                    analysis_status_output,
+                    analysis_result_group,
+                    analysis_result_output,
+                    analyze_button,
+                ],
+            ).then(
+                fn=lambda transcript: analyze_transcript_for_ui(transcript, service_factory),
                 inputs=transcript_input,
-                outputs=[analysis_id_output, summary_output, action_items_output],
+                outputs=[
+                    analysis_result_group,
+                    analysis_result_output,
+                ],
+            )
+            analyze_event.success(
+                fn=hide_analyze_loading,
+                outputs=[analysis_status_output, analyze_button],
+            )
+            analyze_event.failure(
+                fn=show_analyze_failure,
+                outputs=[
+                    analysis_status_output,
+                    analysis_result_group,
+                    analysis_result_output,
+                    analyze_button,
+                ],
             )
 
         with gr.Tab("Lookup"):
             analysis_id_input = gr.Textbox(label="Analysis ID")
             lookup_button = gr.Button("Lookup", variant="primary")
 
-            lookup_id_output = gr.Textbox(label="Analysis ID", interactive=False)
-            lookup_summary_output = gr.Textbox(label="Summary", lines=5, interactive=False)
-            lookup_action_items_output = gr.Textbox(
-                label="Suggested Next Steps",
-                lines=6,
-                interactive=False,
+            lookup_status_output = gr.HTML(
+                visible=False,
+                elem_classes=["analysis-status"],
             )
+            with gr.Group(visible=False, elem_classes=["analysis-result"]) as lookup_result_group:
+                lookup_result_output = gr.Markdown(
+                    container=False,
+                    line_breaks=True,
+                    buttons=["copy"],
+                )
 
-            lookup_button.click(
-                fn=lambda analysis_id: lookup_analysis(analysis_id, service_factory),
+            lookup_event = lookup_button.click(
+                fn=show_lookup_loading,
+                outputs=[
+                    lookup_status_output,
+                    lookup_result_group,
+                    lookup_result_output,
+                    lookup_button,
+                ],
+            ).then(
+                fn=lambda analysis_id: lookup_analysis_for_ui(analysis_id, service_factory),
                 inputs=analysis_id_input,
-                outputs=[lookup_id_output, lookup_summary_output, lookup_action_items_output],
+                outputs=[
+                    lookup_result_group,
+                    lookup_result_output,
+                ],
+            )
+            lookup_event.success(
+                fn=hide_lookup_loading,
+                outputs=[lookup_status_output, lookup_button],
+            )
+            lookup_event.failure(
+                fn=show_lookup_failure,
+                outputs=[
+                    lookup_status_output,
+                    lookup_result_group,
+                    lookup_result_output,
+                    lookup_button,
+                ],
             )
 
     return frontend
 
 
+def show_analyze_loading() -> LoadingFrontendResult:
+    return show_loading("Analyzing transcript...", "Analyzing...")
+
+
+def show_lookup_loading() -> LoadingFrontendResult:
+    return show_loading("Looking up analysis...", "Looking up...")
+
+
+def show_loading(message: str, button_label: str) -> LoadingFrontendResult:
+    return (
+        gr.update(value=format_status_html(message), visible=True),
+        gr.update(visible=False),
+        "",
+        gr.update(value=button_label, interactive=False),
+    )
+
+
+def hide_analyze_loading() -> CleanupFrontendResult:
+    return hide_loading("Analyze")
+
+
+def hide_lookup_loading() -> CleanupFrontendResult:
+    return hide_loading("Lookup")
+
+
+def hide_loading(button_label: str) -> CleanupFrontendResult:
+    return gr.update(value="", visible=False), gr.update(value=button_label, interactive=True)
+
+
+def show_analyze_failure() -> FailureFrontendResult:
+    return show_failure("Analyze")
+
+
+def show_lookup_failure() -> FailureFrontendResult:
+    return show_failure("Lookup")
+
+
+def show_failure(button_label: str) -> FailureFrontendResult:
+    return (
+        gr.update(
+            value=format_status_html("Could not complete the request.", is_error=True),
+            visible=True,
+        ),
+        gr.update(visible=False),
+        "",
+        gr.update(value=button_label, interactive=True),
+    )
+
+
+def analyze_transcript_for_ui(
+    transcript: str,
+    service_factory: ServiceFactory,
+) -> AnalysisFrontendResult:
+    return show_result(*analyze_transcript(transcript, service_factory))
+
+
 def analyze_transcript(transcript: str, service_factory: ServiceFactory) -> FrontendResult:
     try:
         analysis = service_factory().analyze(transcript)
-    except (InvalidTranscriptError, LLMCompletionError) as exc:
+    except (ConfigurationError, InvalidTranscriptError, LLMCompletionError) as exc:
         raise gr.Error(str(exc)) from exc
 
     return format_analysis(analysis)
 
 
+def lookup_analysis_for_ui(
+    analysis_id: str,
+    service_factory: ServiceFactory,
+) -> AnalysisFrontendResult:
+    return show_result(*lookup_analysis(analysis_id, service_factory))
+
+
 def lookup_analysis(analysis_id: str, service_factory: ServiceFactory) -> FrontendResult:
     try:
         analysis = service_factory().get(analysis_id.strip())
-    except (AnalysisNotFoundError, InvalidTranscriptError, LLMCompletionError) as exc:
+    except (AnalysisNotFoundError, ConfigurationError, InvalidTranscriptError, LLMCompletionError) as exc:
         raise gr.Error(str(exc)) from exc
 
     return format_analysis(analysis)
 
 
+def show_result(
+    analysis_id: str,
+    summary: str,
+    action_items: str,
+) -> AnalysisFrontendResult:
+    return (
+        gr.update(visible=True),
+        format_result_markdown(analysis_id, summary, action_items),
+    )
+
+
 def format_analysis(analysis: TranscriptAnalysis) -> FrontendResult:
     return analysis.id, analysis.summary, format_action_items(analysis.action_items)
 
 
+def format_status_html(message: str, is_error: bool = False) -> str:
+    status_class = "analysis-status--error" if is_error else ""
+    spinner = "" if is_error else '<span class="analysis-status__spinner" aria-hidden="true"></span>'
+    role = "alert" if is_error else "status"
+
+    return (
+        f'<div class="{status_class}">'
+        f'<div class="analysis-status__content" role="{role}">'
+        f"{spinner}<span>{escape(message)}</span>"
+        "</div>"
+        "</div>"
+    )
+
+
+def format_result_markdown(analysis_id: str, summary: str, action_items: str) -> str:
+    return f"""### Analysis ID
+`{analysis_id}`
+
+### Summary
+{summary}
+
+### Suggested Next Steps
+{action_items}
+"""
+
+
 def format_action_items(action_items: tuple[str, ...]) -> str:
     if not action_items:
         return "No suggested next steps returned."
 
-    return "\n".join(f"{index}. {action_item}" for index, action_item in enumerate(action_items, start=1))
+    return "\n".join(
+        f"{index}. {action_item}" for index, action_item in enumerate(action_items, start=1)
+    )

app/main.py

@@ -4,6 +4,7 @@ from typing import Annotated
 from fastapi import Depends, FastAPI, Query, Request
 from fastapi.responses import JSONResponse
 import gradio as gr
+from pydantic import ValidationError
 
 from app.adapters.openai import OpenAIAdapter
 from app.configurations import EnvConfigs
@@ -13,8 +14,13 @@ from app.schemas import (
     BatchTranscriptAnalysisResponse,
     TranscriptAnalysisResponse,
 )
-from app.errors import AnalysisNotFoundError, InvalidTranscriptError, LLMCompletionError
-from app.frontend import build_gradio_app
+from app.errors import (
+    AnalysisNotFoundError,
+    ConfigurationError,
+    InvalidTranscriptError,
+    LLMCompletionError,
+)
+from app.frontend import APP_CSS, build_gradio_app
 from app.ports import LLm
 from app.repositories import InMemoryTranscriptAnalysisRepository, TranscriptAnalysisRepository
 from app.services import TranscriptAnalysisService
@@ -30,7 +36,12 @@ _repository = InMemoryTranscriptAnalysisRepository()
 
 @lru_cache
 def get_env_configs() -> EnvConfigs:
-    return EnvConfigs()
+    try:
+        return EnvConfigs()
+    except ValidationError as exc:
+        raise ConfigurationError(
+            "OPENAI_API_KEY is not configured. Set it in .env or as an environment variable."
+        ) from exc
 
 
 @lru_cache
@@ -64,6 +75,11 @@ async def analysis_not_found_handler(_: Request, exc: AnalysisNotFoundError) ->
     return JSONResponse(status_code=404, content={"detail": str(exc)})
 
 
+@app.exception_handler(ConfigurationError)
+async def configuration_error_handler(_: Request, exc: ConfigurationError) -> JSONResponse:
+    return JSONResponse(status_code=503, content={"detail": str(exc)})
+
+
 @app.exception_handler(LLMCompletionError)
 async def llm_completion_handler(_: Request, exc: LLMCompletionError) -> JSONResponse:
     return JSONResponse(status_code=502, content={"detail": str(exc)})
@@ -96,4 +112,9 @@ async def analyze_transcripts_batch(
     return to_batch_transcript_analysis_response(analyses)
 
 
-app = gr.mount_gradio_app(app, build_gradio_app(get_gradio_analysis_service), path="/")
+app = gr.mount_gradio_app(
+    app,
+    build_gradio_app(get_gradio_analysis_service),
+    path="/",
+    css=APP_CSS,
+)

tests/api/test_transcript_analysis_api.py

@@ -2,6 +2,7 @@ from pydantic import BaseModel
 import pytest
 from fastapi.testclient import TestClient
 
+from app.errors import ConfigurationError
 from app.main import app, get_analysis_service
 from app.ports import LLm
 from app.repositories import InMemoryTranscriptAnalysisRepository
@@ -96,7 +97,27 @@ def test_analyze_batch_rejects_empty_transcript(client: TestClient) -> None:
     assert response.json()["detail"] == "Transcript cannot be empty."
 
 
-def test_gradio_ui_is_mounted_at_root(client: TestClient) -> None:
+def test_configuration_error_returns_503() -> None:
+    def raise_configuration_error() -> TranscriptAnalysisService:
+        raise ConfigurationError(
+            "OPENAI_API_KEY is not configured. Set it in .env or as an environment variable."
+        )
+
+    app.dependency_overrides[get_analysis_service] = raise_configuration_error
+
+    try:
+        with TestClient(app) as test_client:
+            response = test_client.get("/analyses", params={"transcript": "Discuss rollout plan."})
+    finally:
+        app.dependency_overrides.clear()
+
+    assert response.status_code == 503
+    assert response.json()["detail"] == (
+        "OPENAI_API_KEY is not configured. Set it in .env or as an environment variable."
+    )
+
+
+def test_gradio_ui_is_mounted(client: TestClient) -> None:
     response = client.get("/", follow_redirects=True)
 
     assert response.status_code == 200

tests/frontend/test_gradio_frontend.py

@@ -2,8 +2,18 @@ import gradio as gr
 import pytest
 
 from app.domain import TranscriptAnalysis
-from app.errors import AnalysisNotFoundError, InvalidTranscriptError
-from app.frontend import analyze_transcript, format_action_items, lookup_analysis
+from app.errors import AnalysisNotFoundError, ConfigurationError, InvalidTranscriptError
+from app.frontend import (
+    analyze_transcript,
+    analyze_transcript_for_ui,
+    format_action_items,
+    format_status_html,
+    hide_lookup_loading,
+    lookup_analysis,
+    lookup_analysis_for_ui,
+    show_analyze_failure,
+    show_analyze_loading,
+)
 
 
 class FakeService:
@@ -25,6 +35,14 @@ class FakeService:
         return self.analysis
 
 
+class MisconfiguredService:
+    def analyze(self, transcript: str) -> TranscriptAnalysis:
+        raise ConfigurationError("OPENAI_API_KEY is not configured.")
+
+    def get(self, analysis_id: str) -> TranscriptAnalysis:
+        raise ConfigurationError("OPENAI_API_KEY is not configured.")
+
+
 def test_analyze_transcript_returns_formatted_result() -> None:
     result = analyze_transcript("Discuss roadmap.", FakeService)
 
@@ -35,6 +53,18 @@ def test_analyze_transcript_returns_formatted_result() -> None:
     )
 
 
+def test_analyze_transcript_for_ui_reveals_result_group() -> None:
+    result_visibility, result_markdown = analyze_transcript_for_ui(
+        "Discuss roadmap.",
+        FakeService,
+    )
+
+    assert result_visibility["visible"] is True
+    assert "### Analysis ID\n`analysis-1`" in result_markdown
+    assert "### Summary\nThe team aligned on next steps." in result_markdown
+    assert "### Suggested Next Steps\n1. Confirm owner\n2. Set deadline" in result_markdown
+
+
 def test_lookup_analysis_returns_formatted_result() -> None:
     result = lookup_analysis(" analysis-1 ", FakeService)
 
@@ -45,6 +75,53 @@ def test_lookup_analysis_returns_formatted_result() -> None:
     )
 
 
+def test_show_analyze_loading_sets_status_and_hides_results() -> None:
+    status_visibility, result_visibility, result_markdown, button_state = show_analyze_loading()
+
+    assert status_visibility["visible"] is True
+    assert "Analyzing transcript..." in status_visibility["value"]
+    assert result_visibility["visible"] is False
+    assert result_markdown == ""
+    assert button_state["value"] == "Analyzing..."
+    assert button_state["interactive"] is False
+
+
+def test_lookup_analysis_for_ui_reveals_result_group() -> None:
+    result_visibility, result_markdown = lookup_analysis_for_ui(" analysis-1 ", FakeService)
+
+    assert result_visibility["visible"] is True
+    assert "### Analysis ID\n`analysis-1`" in result_markdown
+    assert "### Summary\nThe team aligned on next steps." in result_markdown
+    assert "### Suggested Next Steps\n1. Confirm owner\n2. Set deadline" in result_markdown
+
+
+def test_hide_lookup_loading_clears_status_and_restores_button() -> None:
+    status_visibility, button_state = hide_lookup_loading()
+
+    assert status_visibility["visible"] is False
+    assert status_visibility["value"] == ""
+    assert button_state["value"] == "Lookup"
+    assert button_state["interactive"] is True
+
+
+def test_show_analyze_failure_sets_error_status_and_restores_button() -> None:
+    status_visibility, result_visibility, result_markdown, button_state = show_analyze_failure()
+
+    assert status_visibility["visible"] is True
+    assert "Could not complete the request." in status_visibility["value"]
+    assert result_visibility["visible"] is False
+    assert result_markdown == ""
+    assert button_state["value"] == "Analyze"
+    assert button_state["interactive"] is True
+
+
+def test_format_status_html_escapes_message() -> None:
+    status_html = format_status_html("<script>alert('x')</script>")
+
+    assert "&lt;script&gt;alert(&#x27;x&#x27;)&lt;/script&gt;" in status_html
+    assert "<script>" not in status_html
+
+
 def test_analyze_transcript_maps_empty_input_to_gradio_error() -> None:
     with pytest.raises(gr.Error, match="Transcript cannot be empty."):
         analyze_transcript("   ", FakeService)
@@ -55,5 +132,10 @@ def test_lookup_analysis_maps_missing_id_to_gradio_error() -> None:
         lookup_analysis("missing-id", FakeService)
 
 
+def test_analyze_transcript_maps_configuration_errors_to_gradio_error() -> None:
+    with pytest.raises(gr.Error, match="OPENAI_API_KEY is not configured."):
+        analyze_transcript("Discuss roadmap.", MisconfiguredService)
+
+
 def test_format_action_items_handles_empty_list() -> None:
     assert format_action_items(()) == "No suggested next steps returned."