README.md

---
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/<your-org-or-user>/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`