Add Gradio UI polish and Spaces entrypoint

README.md

@@ -24,6 +24,12 @@ Run the FastAPI backend:
 uvicorn app.main:app --reload
 ```
 
+If port 8000 is busy on Windows, use:
+
+```bash
+uvicorn app.main:app --reload --port 8001
+```
+
 Health check:
 
 ```bash
@@ -36,6 +42,15 @@ Run the Gradio demo:
 python -m app.ui.gradio_app
 ```
 
+For Hugging Face Spaces-style startup:
+
+```bash
+python app.py
+```
+
+The Gradio app includes example repos, a live agent progress panel, and a structured markdown report panel.
+The launcher binds to `0.0.0.0` and uses `PORT` when provided, which matches hosted Gradio deployment expectations.
+
 ## Configuration
 
 Copy `.env.example` to `.env` for local overrides. Default inference mode is:
@@ -68,6 +83,10 @@ Reports preserve full finding totals while displaying a prioritized subset for r
 - Docs Agent: flags incomplete README guidance and public Python symbols missing docstrings.
 - Synthesizer Agent: deduplicates findings, sorts by severity, and builds the final report.
 
+## Hugging Face Spaces
+
+SwarmAudit is ready to launch as a Gradio Space with the root `app.py` entrypoint. Keep `LLM_PROVIDER=mock` for a reliable public demo, then switch to `LLM_PROVIDER=vllm` when an AMD MI300X-hosted Qwen2.5-Coder endpoint is available.
+
 ## Tests
 
 ```bash

app.py

@@ -0,0 +1,8 @@
+from app.ui.gradio_app import build_app, launch_app
+
+
+demo = build_app()
+
+
+if __name__ == "__main__":
+    launch_app()

app/ui/gradio_app.py

@@ -1,3 +1,5 @@
+import os
+
 import gradio as gr
 
 from app.agents.graph import AuditGraph
@@ -5,38 +7,76 @@ from app.schemas import AuditReport
 from app.services.report_formatter import format_report_markdown
 
 
+EXAMPLE_REPOS = {
+    "Requests": "https://github.com/psf/requests",
+    "ItsDangerous": "https://github.com/pallets/itsdangerous",
+    "Flask": "https://github.com/pallets/flask",
+}
+
+
 async def analyze_repo(repo_url: str):
     if not repo_url.strip():
-        yield "Paste a public GitHub repository URL to start."
+        yield "Paste a public GitHub repository URL to start.", ""
         return
 
-    transcript: list[str] = []
+    progress: list[str] = []
+    report_markdown = ""
     try:
         async for event in AuditGraph().run_with_progress(repo_url.strip()):
             if isinstance(event, AuditReport):
-                transcript.append("")
-                transcript.append(format_report_markdown(event))
+                report_markdown = format_report_markdown(event)
             else:
-                transcript.append(event)
-            yield "\n".join(transcript)
+                progress.append(event)
+            yield "\n".join(progress), report_markdown
     except Exception as exc:
-        transcript.append(f"Audit failed: {exc}")
-        yield "\n".join(transcript)
+        progress.append(f"Audit failed: {exc}")
+        yield "\n".join(progress), report_markdown
+
+
+def choose_example(example_name: str) -> str:
+    return EXAMPLE_REPOS.get(example_name, "")
 
 
 def build_app() -> gr.Blocks:
     with gr.Blocks(title="SwarmAudit") as demo:
-        gr.Markdown("# SwarmAudit")
-        gr.Markdown("Paste any public GitHub URL. Get a structured AI code review in minutes.")
-        repo_url = gr.Textbox(
-            label="GitHub Repository URL",
-            placeholder="https://github.com/owner/repo",
+        gr.Markdown(
+            "# SwarmAudit\n"
+            "Paste a public GitHub URL and get a structured multi-agent audit report."
+        )
+
+        with gr.Row():
+            repo_url = gr.Textbox(
+                label="GitHub Repository URL",
+                placeholder="https://github.com/owner/repo",
+                scale=4,
+            )
+            analyze = gr.Button("Analyze", variant="primary", scale=1)
+
+        example = gr.Dropdown(
+            label="Example repos",
+            choices=list(EXAMPLE_REPOS.keys()),
+            value=None,
+            interactive=True,
         )
-        analyze = gr.Button("Analyze")
-        output = gr.Markdown(label="Audit Report")
-        analyze.click(analyze_repo, inputs=repo_url, outputs=output)
+        example.change(choose_example, inputs=example, outputs=repo_url)
+
+        with gr.Row():
+            progress_output = gr.Textbox(
+                label="Agent Progress",
+                lines=10,
+                interactive=False,
+            )
+            report_output = gr.Markdown(label="Audit Report")
+
+        analyze.click(analyze_repo, inputs=repo_url, outputs=[progress_output, report_output])
     return demo
 
 
+def launch_app() -> None:
+    server_name = os.getenv("GRADIO_SERVER_NAME", "0.0.0.0")
+    server_port = int(os.getenv("PORT", os.getenv("GRADIO_SERVER_PORT", "7860")))
+    build_app().queue().launch(server_name=server_name, server_port=server_port)
+
+
 if __name__ == "__main__":
-    build_app().queue().launch()
+    launch_app()

tests/test_gradio_app.py

@@ -0,0 +1,45 @@
+import runpy
+from pathlib import Path
+
+from app.ui.gradio_app import build_app, choose_example, launch_app
+
+
+def test_choose_example_returns_repo_url():
+    assert choose_example("Requests") == "https://github.com/psf/requests"
+
+
+def test_choose_example_returns_empty_string_for_unknown_choice():
+    assert choose_example("Unknown") == ""
+
+
+def test_build_app_creates_gradio_blocks():
+    demo = build_app()
+
+    assert demo is not None
+
+
+def test_root_app_py_exposes_demo_for_spaces():
+    namespace = runpy.run_path(str(Path(__file__).parents[1] / "app.py"))
+
+    assert "demo" in namespace
+
+
+def test_launch_app_uses_spaces_friendly_defaults(monkeypatch):
+    calls = {}
+
+    class FakeQueuedApp:
+        def launch(self, **kwargs):
+            calls.update(kwargs)
+
+    class FakeApp:
+        def queue(self):
+            return FakeQueuedApp()
+
+    monkeypatch.setattr("app.ui.gradio_app.build_app", lambda: FakeApp())
+    monkeypatch.delenv("PORT", raising=False)
+    monkeypatch.delenv("GRADIO_SERVER_PORT", raising=False)
+    monkeypatch.delenv("GRADIO_SERVER_NAME", raising=False)
+
+    launch_app()
+
+    assert calls == {"server_name": "0.0.0.0", "server_port": 7860}