DarkGridAI

DarkGridAI is an Android-first disaster resilience assistant that keeps Gemma 4, emergency reference material, and practical response workflows on the device. It is built for degraded connectivity: download the app before an incident, then use chat, briefings, checklists, reports, and photo hazard review when the network is unreliable or unavailable.

The project was built for the Kaggle Gemma 4 Good Hackathon.

Demonstration-Only Notice

DarkGridAI is a competition prototype for demonstration and evaluation only. It must not be used for real emergency response, medical decisions, evacuation decisions, safety-critical operations, professional advice, or any situation where inaccurate, incomplete, delayed, or hallucinated output could cause harm.

No guarantees, warranties, certifications, legal claims, safety claims, medical claims, emergency-management claims, fitness-for-purpose claims, or reliability claims are made about this project, its model outputs, bundled reference material, app behavior, or generated reports. Always rely on qualified professionals, official emergency services, local authorities, and verified public guidance when making real-world decisions.

Install the Competition APK

The competition APK is distributed separately from this GitHub repository because it bundles the on-device Gemma model and is about 2.7GB. Do not clone the repository expecting the APK binary to be checked into Git.

Download the judging APK from the Kaggle Dataset:

https://www.kaggle.com/datasets/gavinwightman/darkgridai-competition-apk

Then follow one of the install paths below.

Requirements

• Android 7.0 or newer, API 24+
• An ARM64 Android device is recommended
• At least 4GB free storage during install
• Internet access only for downloading the APK
• Camera permission only if you use Photo Hazard or Live Camera
• Location permission is optional and non-blocking

The app is designed to run offline after installation. The large APK is intentional: it carries the local Gemma runtime and model instead of depending on a cloud API during a disaster.

Install on a Phone

1. Download DarkGridAI-competition.apk from the Kaggle Dataset linked above.
2. Open the APK from Android's download notification or the Files app.
3. If Android asks, allow that app to Install unknown apps.
4. Tap Install.
5. Wait for Android to finish staging the APK. This can take a while because the model is bundled.
6. Open DarkGridAI.

No model download should be required on first launch.

Install with ADB

adb devices
adb install -r DarkGridAI-competition.apk
adb shell monkey -p org.darkgridai.app -c android.intent.category.LAUNCHER 1

The Android package name is:

org.darkgridai.app

If you are replacing an older test build and want to re-check the first-run permission flow, revoke camera permission before opening the camera tools:

adb shell pm revoke org.darkgridai.app android.permission.CAMERA

APK Hosting Note

Do not move or commit the generated APK into the Git repository. GitHub blocks normal repository files over 100MB, and GitHub release assets must be under 2GiB per file. This APK is larger than that because it includes the local model.

The current judging APK is hosted as a Kaggle Dataset:

https://www.kaggle.com/datasets/gavinwightman/darkgridai-competition-apk

Recommended distribution options for future builds:

• host the APK through the Kaggle submission assets or another large-file download link
• publish a split archive only if the competition accepts reconstruction instructions
• keep a local upload copy outside Git, for example:

mkdir -p release
cp android/app/build/outputs/apk/release/app-release.apk release/DarkGridAI-competition.apk

release/DarkGridAI-competition.apk is only a local staging path for upload. It should not be committed.

What DarkGridAI Does

Emergency Briefing

Guided incident intake that generates a structured action board with severity, immediate priorities, risks, unknowns, and escalation triggers. Briefings can hand off into the Checklist Builder and Situation Report flows.

Photo Hazard and Live Camera

Camera-driven hazard review for quick visual scene assessment. The model output is treated as bounded evidence, not ground truth, and the UI keeps uncertainty and follow-up checks visible.

Checklist Builder

A native checklist workflow that uses Gemma 4 to draft practical actions, then lets the user review, edit, and explicitly save the result.

Situation Report

A responder handoff workflow that separates Observed / Reported facts from Gemma 4 Analysis, with save, edit, export, share, and in-app PDF reopening.

Reference Library

Bundled offline guidance with grounded Q&A. The PDF reader includes Ask this document with document-only retrieval and approximate page citations.

Specialist Modes

• Default
• Medical
• Shelter
• Water & Sanitation
• Navigation & Comms
• Field Repair

These modes bias prompt framing, risk priorities, preferred references, and suggested workflows.

Safety and Trust

• Grounded reference answers are preferred when offline document matches are strong.
• The app does not treat image or location context as perfect ground truth.
• Safety warnings are used for high-risk topics such as fire, generators, carbon monoxide, contaminated water, medical symptoms, evacuation, and structural damage.
• If location is denied or unavailable, the app continues and asks for manual location only when it materially helps.
• DarkGridAI does not replace professional responders, medical professionals, or official emergency management when they are reachable.
• This repository and APK are demonstration artifacts only and are not validated, certified, or warranted for operational use.

Build from Source

See SETUP.md for development setup.

The raw Gemma 4 LiteRT model is not stored in Git. The judging APK linked above already bundles it, but source builds require a local copy staged at assets/models/gemma-4-E2B-it.litertlm.

Quick start:

npm install
./setup-models.sh /absolute/path/to/gemma-4-E2B-it.litertlm
npm run android

Build the standalone competition APK:

npm run android:build:standalone

The generated APK is:

android/app/build/outputs/apk/release/app-release.apk

Useful commands:

# Start Metro
npm run start

# Android development build
npm run android

# Build RAG text/chunk assets from bundled PDFs
npm run build-rag

# Validate bundled document metadata, aliases, and search assets
npm run validate-kb

# Jest
npm test

Repository Notes

• Canonical bundled runtime assets live under assets/**.
• android/app/src/main/assets/** is staged Android bundle output, not the hand-maintained source of truth.
• Competition-facing reference docs live in README.md, SETUP.md, docs/PRD.MD, and docs/competition/.
• The competition-facing app no longer includes the removed plant-identification prototype paths.

License

DarkGridAI source code is licensed under the Apache License 2.0. The bundled Gemma model, third-party dependencies, and emergency reference materials remain under their own licenses and terms; see THIRD_PARTY_NOTICES.md.

Key Implementation Areas

• components/: workflow screens, chat UI, PDF viewer, camera flows, and tools
• utils/: RAG, document search, workflow draft generation, persistence, export, and model management
• services/: camera and Android model service wrappers
• src/personas/: specialist mode definitions and competition-visible curation
• src/context/: shared persona and location context