HF Space prep

HF_SPACES_DEPLOY.md

@@ -0,0 +1,97 @@
+# Hugging Face Spaces Deployment Checklist
+
+## Local Preflight
+
+Run these from the repo root:
+
+```bash
+pip install -r requirements.txt
+pytest
+python app.py
+```
+
+Open:
+
+```text
+http://127.0.0.1:7860
+```
+
+Test a small repo first:
+
+```text
+https://github.com/pallets/itsdangerous
+```
+
+## Create The Space
+
+1. Go to Hugging Face Spaces.
+2. Create a new Space.
+3. Choose SDK: `Gradio`.
+4. Choose hardware: CPU basic for the mock MVP.
+5. Use the AMD hackathon organization if the event requires it.
+
+## Required Files
+
+These must be at the repo root:
+
+```text
+app.py
+requirements.txt
+README.md
+```
+
+The README includes the Space metadata:
+
+```yaml
+sdk: gradio
+sdk_version: 6.14.0
+app_file: app.py
+```
+
+## Environment Variables
+
+For the public mock demo:
+
+```text
+LLM_PROVIDER=mock
+```
+
+For a later AMD/vLLM deployment:
+
+```text
+LLM_PROVIDER=vllm
+LLM_BASE_URL=http://YOUR_VLLM_ENDPOINT/v1
+LLM_API_KEY=not-needed-if-your-endpoint-does-not-require-one
+LLM_MODEL=Qwen/Qwen2.5-Coder-32B-Instruct
+```
+
+## First Hosted Smoke Test
+
+In the deployed Space, test:
+
+```text
+https://github.com/pallets/itsdangerous
+```
+
+Then test:
+
+```text
+https://github.com/psf/requests
+```
+
+Expected behavior:
+
+- Crawler maps files.
+- Chunker creates chunks.
+- Security, Performance, Quality, and Docs agents run.
+- Synthesizer returns a report.
+- Report shows a prioritized subset while preserving total finding counts.
+
+## If The Space Fails
+
+Check the Space logs first. Common issues:
+
+- Dependency install failure: verify `requirements.txt`.
+- App import failure: verify root `app.py`.
+- GitHub clone failure: verify Space has outbound internet access.
+- Large repo timeout: test `pallets/itsdangerous` before larger repos.

README.md

@@ -1,6 +1,19 @@
+---
+title: SwarmAudit
+sdk: gradio
+sdk_version: 6.14.0
+app_file: app.py
+pinned: false
+license: mit
+---
+
 # SwarmAudit
 
-AI-powered multi-agent code auditing for GitHub repositories. Paste a public GitHub URL and get a structured audit report with severity, file references, and suggested fixes.
+Paste any public GitHub URL. Get a structured multi-agent code audit in minutes.
+
+SwarmAudit is an AI-agent code review system for the AMD Developer Hackathon. It clones a public repository, filters and chunks source files, runs specialized review agents, and returns a severity-ranked report with file references and suggested fixes.
+
+The local MVP runs in mock-first mode, so the demo works without waiting for ROCm, vLLM, or MI300X infrastructure. The inference layer is designed to switch to a vLLM-compatible Qwen2.5-Coder endpoint later.
 
 ## MVP
 
@@ -10,6 +23,45 @@ SwarmAudit currently runs with a mock-first LLM interface so the demo is not blo
 GitHub URL -> Crawler -> Chunker -> [Security Agent + Performance Agent + Quality Agent + Docs Agent] -> Synthesizer -> Report
 ```
 
+## Demo Status
+
+Working locally:
+
+- Gradio UI with live agent progress
+- FastAPI `/health` and `/audit` endpoints
+- GitHub clone and repo scan on public repos
+- Four analysis agents plus synthesizer
+- Prioritized report display with full raw finding totals preserved
+- Hugging Face Spaces-style `app.py` entrypoint
+
+Smoke-tested repos:
+
+- `https://github.com/psf/requests`
+- `https://github.com/pallets/itsdangerous`
+
+Example output is available in [`examples/requests_report_excerpt.md`](examples/requests_report_excerpt.md).
+
+## Architecture
+
+```mermaid
+flowchart LR
+    U[User enters GitHub URL] --> API[FastAPI / Gradio]
+    API --> C[Crawler Agent]
+    C --> F[File Filter]
+    F --> K[Chunker]
+    K --> S[Security Agent]
+    K --> P[Performance Agent]
+    K --> Q[Quality Agent]
+    K --> D[Docs Agent]
+    S --> Y[Synthesizer Agent]
+    P --> Y
+    Q --> Y
+    D --> Y
+    Y --> R[Structured Audit Report]
+```
+
+The graph is intentionally modular: each agent returns strict Pydantic findings, and the synthesizer merges, deduplicates, prioritizes, and formats the final report.
+
 ## Quick Start
 
 ```bash
@@ -36,6 +88,14 @@ Health check:
 curl http://127.0.0.1:8000/health
 ```
 
+Audit endpoint:
+
+```bash
+curl -X POST http://127.0.0.1:8000/audit \
+  -H "Content-Type: application/json" \
+  -d '{"repo_url":"https://github.com/psf/requests"}'
+```
+
 Run the Gradio demo:
 
 ```bash
@@ -61,6 +121,15 @@ LLM_PROVIDER=mock
 
 Later, set `LLM_PROVIDER=vllm` and point `LLM_BASE_URL` at an OpenAI-compatible vLLM endpoint running Qwen2.5-Coder.
 
+Key safety limits:
+
+```text
+MAX_FILES=200
+MAX_FILE_SIZE_KB=250
+MAX_CHARS_PER_CHUNK=12000
+CLONE_BASE_DIR=.swarm_audit_tmp
+```
+
 ## Report Schema
 
 Each finding includes:
@@ -87,6 +156,25 @@ Reports preserve full finding totals while displaying a prioritized subset for r
 
 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.
 
+See [`HF_SPACES_DEPLOY.md`](HF_SPACES_DEPLOY.md) for the deployment checklist.
+
+Recommended Space settings:
+
+- SDK: Gradio
+- App file: `app.py`
+- Python: 3.11 or newer
+- Default env: `LLM_PROVIDER=mock`
+
+## AMD MI300X Roadmap
+
+The current code path is intentionally mock-first. The next inference phase is:
+
+1. Start a Qwen2.5-Coder vLLM server on AMD Developer Cloud.
+2. Expose an OpenAI-compatible `/v1/chat/completions` endpoint.
+3. Set `LLM_PROVIDER=vllm`, `LLM_BASE_URL`, and `LLM_MODEL`.
+4. Add LLM enrichment to agent findings while keeping static rules as deterministic guardrails.
+5. Add a benchmark tab with MI300X latency and throughput numbers.
+
 ## Tests
 
 ```bash

examples/requests_report_excerpt.md

@@ -0,0 +1,48 @@
+# SwarmAudit Example Report Excerpt
+
+Repository: `https://github.com/psf/requests`
+
+This excerpt comes from a local smoke test using the mock-first MVP pipeline.
+
+## Summary
+
+- Files scanned: `41`
+- Files skipped: `122`
+- Total findings: `217`
+- Findings displayed: `34`
+- Hidden lower-priority findings: `183`
+
+## Severity Summary
+
+- CRITICAL: `0`
+- HIGH: `4`
+- MEDIUM: `121`
+- LOW: `92`
+
+## Agent Summary
+
+- Security Agent: `4`
+- Performance Agent: `115`
+- Quality Agent: `48`
+- Docs Agent: `50`
+
+## Example Finding
+
+### [HIGH] TLS certificate verification disabled
+
+- File: `tests/test_requests.py:2908-2908`
+- Agent: `Security Agent`
+
+Disabling TLS verification can allow man-in-the-middle attacks.
+
+**Why it matters:** Attackers often search repos for exposed credentials and unsafe execution paths.
+
+**Suggested fix:**
+
+```text
+Remove verify=False and use a trusted CA bundle if needed.
+```
+
+## Display Policy
+
+SwarmAudit preserves full finding totals but displays a prioritized subset for readability. High-severity findings are shown first, repeated low-severity findings are summarized, and report warnings explain when lower-priority findings are hidden from the demo view.

requirements.txt

@@ -1,11 +1,11 @@
-fastapi
-uvicorn[standard]
-gradio
-gitpython
-pydantic
-pydantic-settings
-langgraph
-langchain-core
-httpx
-python-dotenv
-pytest
+fastapi==0.128.0
+uvicorn[standard]==0.40.0
+gradio==6.14.0
+gitpython==3.1.49
+pydantic==2.12.5
+pydantic-settings==2.14.0
+langgraph==1.1.10
+langchain-core==1.3.2
+httpx==0.28.1
+python-dotenv==1.2.1
+pytest==9.0.3