--- title: ReliefLens AI emoji: 🚨 colorFrom: red colorTo: blue sdk: docker app_port: 7860 pinned: false --- # ReliefLens AI ReliefLens AI is a multimodal, human-in-the-loop emergency triage demo built for the AMD Developer Hackathon. It accepts public field evidence such as text, image uploads, optional audio, browser location, map-selected location, and textual place references, then produces prioritized incidents with recommended resources, location confidence, and operational explanations. ## Public demo - Hugging Face Space frontend: `https://lablab-ai-amd-developer-hackathon-relieflens-frontend.hf.space` - AMD FastAPI backend: `http://129.212.185.232:8080` ## Application routes - Public portal: `/emergencies` - Private admin: `/admin` - Admin login: `/admin/login` - Admin incident queue: `/admin/incidents` - Admin incident detail: `/admin/incidents/[id]` - Admin telemetry: `/admin/telemetry` The public portal is limited to evidence submission and public-safe confirmation details. Sensitive incident management stays behind authenticated admin routes. ## What the system does - Ingests image, text, optional audio, and location hints - Resolves location from the best available source without inventing exact coordinates - Produces prioritized incidents with severity, findings, and recommended resources - Separates public intake from private incident management - Shows admin telemetry for backend health and AMD demo metrics ## Location resolution ReliefLens does not pretend that a photo alone can reveal exact location. Location is resolved in this order: 1. Browser geolocation, if the user shares it 2. Manual map click, if the user selects or corrects a point 3. Image GPS EXIF, if present 4. Textual location hints such as `Santa Ana` 5. `Location requires human review` when evidence is insufficient If there is no browser location, no map point, no EXIF GPS, and no usable text location, the incident stays unresolved and requires human review. ## Evidence intake behavior The public `/emergencies` portal supports: - image upload - optional audio recording or upload - `What is happening?` - `Where is this happening?` - `Use my current location` - map click to adjust or set location - `Analyze Evidence` Current behavior uses deterministic, rule-based fallback analysis: - text, filenames, and location hints drive incident classification - audio files are accepted but returned as `received_not_transcribed` when no ASR model is connected - images are inspected only for metadata and optional EXIF GPS - the system does not claim real vision inference unless a model is explicitly connected later ## Qwen-powered incident analysis Rescue Evidence Intelligence can analyze submitted evidence with a Qwen model through an OpenAI-compatible API. Required backend variables: - `QWEN_BASE_URL` - `QWEN_API_KEY` - `QWEN_MODEL` - `QWEN_ENABLED` Behavior: - if `QWEN_ENABLED=false`, the backend uses the existing rule-based fallback classifier - if `QWEN_ENABLED=true`, the backend attempts Qwen analysis first - if the model server times out, returns malformed JSON, or is unavailable, the backend falls back to `rule_based_fallback` - the frontend never receives the API key The admin dashboard shows: - incident type - severity - confidence - detected risks - evidence summary - recommended resources - requires human review - analysis provider: `qwen` or `rule_based_fallback` ## Admin incident management Authenticated admins can: - sign in through `/admin/login` - review the full incident queue - inspect detailed evidence metadata - update incident status, review state, notes, and assigned team - inspect backend and AMD telemetry Required backend environment variables: - `ADMIN_USERNAME` - `ADMIN_PASSWORD` - `ADMIN_TOKEN_SECRET` - `ADMIN_TOKEN_EXPIRE_MINUTES` These values must stay on the backend. Do not expose them through `NEXT_PUBLIC_*` variables or commit secrets to git. ## Safety - Synthetic demo data only - Human-in-the-loop required - Not connected to emergency services - Not for real-world dispatch - AI suggestions are advisory only ## Security limitations - The hackathon MVP uses bearer token authentication for `/api/admin/*` - The frontend stores the admin access token in `sessionStorage` - This is acceptable for the demo, but production should use HTTPS end-to-end and secure HttpOnly cookies - Admin credentials must be configured from backend environment variables, not frontend code ## Architecture Local development: `Next.js frontend -> /backend rewrite proxy -> FastAPI backend` Hugging Face Space deployment: `Hugging Face Docker Space -> nginx on :7860 -> Next.js frontend -> AMD FastAPI backend -> AMD Qwen OpenAI-compatible endpoint` The browser does not call `localhost:8080`, `127.0.0.1:8080`, the AMD FastAPI public IP, or the AMD Qwen endpoint directly from client-side code. Local frontend requests use `/backend`. The Hugging Face Space build uses same-origin `/api`, which nginx proxies to the AMD FastAPI backend at runtime. ## Backend endpoints - `GET /health` - `GET /api/demo/incidents` - `GET /api/demo/scenario` - `POST /api/demo/run` - `POST /api/evidence/intake` - `GET /api/evidence/status/{tracking_code}` - `POST /api/demo/analyze-image` - `POST /api/admin/login` - `GET /api/admin/me` - `GET /api/admin/incidents` - `GET /api/admin/incidents/{incident_id}` - `PATCH /api/admin/incidents/{incident_id}` - `GET /api/admin/telemetry` - `GET /api/amd/performance` ## Local development ### Backend ```bash cd backend set ADMIN_USERNAME=admin set ADMIN_PASSWORD=admin123 set ADMIN_TOKEN_SECRET=local-dev-secret-change-me set ADMIN_TOKEN_EXPIRE_MINUTES=720 set QWEN_ENABLED=false python -m pytest tests -v python -m uvicorn main:app --host 0.0.0.0 --port 8080 --reload ``` Run locally with Qwen disabled: - keep `QWEN_ENABLED=false` - the backend will use the rule-based fallback pipeline Run locally with Qwen through vLLM or another OpenAI-compatible server: ```bash cd backend set QWEN_BASE_URL=http://127.0.0.1:8000/v1 set QWEN_API_KEY=token-abc123 set QWEN_MODEL=Qwen/Qwen2.5-7B-Instruct set QWEN_ENABLED=true python -m uvicorn main:app --host 0.0.0.0 --port 8080 --reload ``` ### Frontend ```bash cd frontend npm install npm run build npm run dev ``` Local frontend environment file: ```env NEXT_PUBLIC_API_URL=/backend NEXT_PUBLIC_API_BASE_URL=/backend NEXT_PUBLIC_BACKEND_URL=/backend BACKEND_ORIGIN=http://localhost:8080 ``` Local proxy checks: - `http://localhost:3000/backend/health` - `http://localhost:3000/admin/login` Local admin login test credentials: - username: `admin` - password: `admin123` ## Deployment to AMD Cloud Recommended topology: - AMD VM: FastAPI backend on `:8080` - AMD VM: external Qwen OpenAI-compatible endpoint on `:8000` - Hugging Face Space: public container on `:7860` On the AMD VM: ```bash git clone https://github.com//ReliefLensAI.git cd ReliefLensAI bash scripts/deploy_backend_amd.sh cp backend/.env.example backend/.env ``` Edit `backend/.env` for your VM. Minimum values: ```env APP_ENV=production DEBUG=false DEMO_MODE=false STORAGE_PATH=./data CORS_ORIGINS=https://YOUR_SPACE.hf.space QWEN_ENABLED=true QWEN_BASE_URL=http://127.0.0.1:8000/v1 QWEN_API_KEY=amd-qwen-demo-key QWEN_MODEL=Qwen/Qwen2-7B-Instruct ADMIN_USERNAME=admin ADMIN_PASSWORD=admin123 ADMIN_TOKEN_SECRET=relieflens-demo-secret-change-this ADMIN_TOKEN_EXPIRE_MINUTES=720 ``` Then start the backend: ```bash bash scripts/start_backend_amd.sh curl http://127.0.0.1:8080/health curl http://129.212.185.232:8080/health ``` If Qwen is running separately on the same VM, verify it first: ```bash curl http://127.0.0.1:8000/v1/models -H "Authorization: Bearer amd-qwen-demo-key" ``` ## Deployment to Hugging Face Docker Space The repository now includes a root `Dockerfile` for a single Hugging Face Docker Space container. Container behavior: - Next.js frontend runs internally on `127.0.0.1:3000` - `nginx` exposes only port `7860` - `/` routes to the Next.js frontend - `/api/*` routes to the AMD FastAPI backend via `BACKEND_ORIGIN` - `/health` routes to `${BACKEND_ORIGIN}/health` Public browser behavior: - the browser calls same-origin `/api` in the Hugging Face Space build - no Qwen secret is exposed to the frontend bundle - the Space does not call Qwen directly - Qwen credentials stay only on the AMD backend environment Space variables: - `NEXT_PUBLIC_API_URL=/api` - `NEXT_PUBLIC_API_BASE_URL=/api` - `NEXT_PUBLIC_BACKEND_URL=/api` - `BACKEND_ORIGIN=http://129.212.185.232:8080` Do not put `QWEN_API_KEY`, admin credentials, or token secrets in any `NEXT_PUBLIC_*` variable or Hugging Face frontend variable. Build and push flow: 1. Push this repository to the Hugging Face Space repo. 2. Configure the Space variables above. 3. Wait for the Docker build to finish. 4. Test: - `https://YOUR_SPACE.hf.space/health` - `https://YOUR_SPACE.hf.space/api/demo/incidents` - `https://YOUR_SPACE.hf.space/emergencies` The Space container uses the root `Dockerfile` and serves the full app on port `7860`. Deployment flow: 1. Create a Docker Space on Hugging Face. 2. Push this repository root to the Space repository. 3. Configure these Variables: - `NEXT_PUBLIC_API_URL=/api` - `NEXT_PUBLIC_API_BASE_URL=/api` - `NEXT_PUBLIC_BACKEND_URL=/api` - `BACKEND_ORIGIN=http://129.212.185.232:8080` 4. Wait for the Docker build. 5. Validate: - `https://YOUR_SPACE.hf.space/health` - `https://YOUR_SPACE.hf.space/api/demo/incidents` - `https://YOUR_SPACE.hf.space/admin/login` ## Hugging Face Space + AMD Qwen Deployment This deployment mode keeps both Qwen and FastAPI on AMD infrastructure while Hugging Face hosts only the public UI and reverse proxy. Architecture: `Hugging Face Docker Space -> nginx on :7860 -> Next.js on :3000 -> AMD FastAPI on :8080 -> AMD Qwen OpenAI-compatible endpoint` Required AMD backend runtime variables: - `QWEN_ENABLED=true` - `QWEN_BASE_URL=http://127.0.0.1:8000/v1` - `QWEN_MODEL=Qwen/Qwen2-7B-Instruct` - `QWEN_API_KEY=amd-qwen-demo-key` Required Hugging Face Space variables: - `NEXT_PUBLIC_API_URL=/api` - `NEXT_PUBLIC_API_BASE_URL=/api` - `NEXT_PUBLIC_BACKEND_URL=/api` - `BACKEND_ORIGIN=http://129.212.185.232:8080` Optional local Docker smoke test before pushing to Hugging Face: ```bash docker build -t relieflens-space . docker run --rm -p 7860:7860 \ -e NEXT_PUBLIC_API_URL=/api \ -e NEXT_PUBLIC_API_BASE_URL=/api \ -e NEXT_PUBLIC_BACKEND_URL=/api \ -e BACKEND_ORIGIN=http://129.212.185.232:8080 \ relieflens-space ``` Then test: - `http://localhost:7860/health` - `http://localhost:7860/api/demo/incidents` - `http://localhost:7860/admin/login` ## Final deployment checklist 1. Verify Qwen on AMD: - `curl http://127.0.0.1:8000/v1/models -H "Authorization: Bearer amd-qwen-demo-key"` 2. Start AMD backend: - `bash scripts/start_backend_amd.sh` 3. Verify AMD backend locally: - `curl http://127.0.0.1:8080/health` 4. Verify AMD backend publicly: - `curl http://129.212.185.232:8080/health` 5. Configure Hugging Face Space variables: - `NEXT_PUBLIC_API_URL=/api` - `NEXT_PUBLIC_API_BASE_URL=/api` - `NEXT_PUBLIC_BACKEND_URL=/api` - `BACKEND_ORIGIN=http://129.212.185.232:8080` 6. Push to a new Docker Space. 7. Test: - `https://SPACE.hf.space/health` - `https://SPACE.hf.space/api/demo/incidents` - `https://SPACE.hf.space/emergencies` 8. Submit the seeded flood report and verify the admin dashboard shows `analysis_provider=qwen`. ## Known limitations - Qwen analysis depends on a reachable OpenAI-compatible model server returning valid JSON - If Qwen is disabled or fails, the system falls back to rule-based analysis - Audio is accepted but not transcribed unless an ASR model is connected later - EXIF GPS is only available for images that actually contain GPS metadata - Text-location resolution is intentionally conservative and does not invent precise coordinates - Map clicks are user-provided hints, not verified GPS - Human review remains mandatory for operational use ## Flood demo case To test the seeded flood case in the admin dashboard or API, use evidence like: - Evidence text: `A severe flash flood is affecting a residential area. Streets are partially flooded, several vehicles are stuck, and people may be trapped inside nearby buildings. Water level appears to be rising quickly after heavy rainfall.` - Image findings: `Flooded urban street, muddy water reaching residential entrances, stuck cars, people moving to higher ground.` - Audio transcript: `No audio uploaded.` - Location: browser geolocation with `confidence=0.90` Expected result: - `incident_type=flood` - `severity=critical` - `priority=P0` - `requires_human_review=true` - provider `qwen` when available, otherwise `rule_based_fallback`