geotruth 1.0.0

Multi-Modal Environmental Coherence Verification for Parametric Insurance

🛡️ GeoTruth™: Multi-Modal Fraud Detection Engine

GeoTruth is a multi-modal fraud detection engine purpose-built for parametric insurance and gig-economy claim verification. It moves beyond obsolete GPS-only checks by cross-validating 7 independent passive signal channels to detect whether a physical environment is real or a digital lie.

---

📖 Table of Contents

• Philosophy
• Architecture
• The 7-Layer Coherence Stack
• Quick Start
• CLI Usage
• Data Manifest
• Grace-First Workflow
• Contributing

---

⚓ Philosophy: Beyond GPS

"GPS tells you coordinates. GeoTruth tells you if they are lived reality."

A genuine delivery partner in a storm and a fraud actor spoofing from a bedroom generate fundamentally different sensor signatures. GeoTruth detects this divergence. By fusing barometric pressure, acoustic fingerprints, network topology, and inertial motion, it creates a high-fidelity evidence vector that is statistically impossible to spoof without physical presence.

---

🏗️ Architecture

GeoTruth employs an Ensemble XGBoost architecture to fuse hardware sensor data with external environmental APIs and platform-side behavioral signals.

graph TD
    A[Claim Initiated] --> B{GeoTruth Engine}
    
    subgraph Layers
    B --> L1[L1: Barometric Pressure]
    B --> L2[L2: Acoustic Environment]
    B --> L3[L3: Network Topology]
    B --> L4[L4: Inertial Motion]
    B --> L5[L5: Zone Coherence]
    B --> L6[L6: Personal Baseline]
    B --> L7[L7: Social Ring Detector]
    end

    L1 & L2 & L3 & L4 & L5 & L6 & L7 --> F[38-Dimensional Feature Vector]
    F --> XG[XGBoost Classifier]
    XG --> T[Tiered Classification]
    
    T --> T0[Tier 0: Auto-Approve]
    T --> T1[Tier 1: Passive Enrichment]
    T --> T2[Tier 2: Soft Proof Request]
    T --> T3[Tier 3: Human Review]
    T --> T4[Tier 4: FROZEN / Ring Alert]

---

🧩 The 7-Layer Coherence Stack

Layer	Insight	Anti-Spoofing Strength
L1: Barometric	Atmospheric pressure drops during storms (Open-Meteo cross-ref)	🛡️🛡️🛡️🛡️🛡️ (Hardware locked)
L2: Acoustic	Edge ML (YAMNet) verifies rain/wind audio signatures locally	🛡️🛡️🛡️🛡️ (Privacy-first)
L3: Network	Cell tower IDs + WiFi SSIDs fingerprint the physical location	🛡️🛡️🛡️🛡️ (GPS Independent)
L4: Inertial	Accelerometer variance detects "shelter-seeking" motion vs stationary	🛡️🛡️🛡️ (Spoof-resistant)
L5: Zone	Cross-verifies claims against neighboring worker activity cliffs	🛡️🛡️🛡️🛡️ (Social proof)
L6: Baseline	Personal behavioral deviation from historical motion norms	🛡️🛡️🛡️ (Anomaly detection)
L7: Social	Temporal burst detection to catch "Telegram coordinate" ring attacks	🛡️🛡️🛡️🛡️🛡️ (Override layer)

---

🚀 Quick Start

Installation

pip install geotruth

Note: For acoustic edge inference (YAMNet), install with pip install geotruth[acoustic].

End-to-End Integration

from geotruth import GeoTruthEngine, ClaimVector, WorkerProfile

# 1. Initialize the Engine (loads pre-trained XGBoost models)
engine = GeoTruthEngine()

# 2. Construct the Claim Data from device sensors
claim = ClaimVector(
    worker_id="PARTNER_123",
    claimed_pincode="600001",
    timestamp=1711900000,
    device_barometer_hpa=991.5,           # L1: Sensor reading
    acoustic_feature_vector=[0.8, 0.2, ...], # L2: Edge-computed (5-dim)
    cell_tower_ids=["H001", "H002"],      # L3: Network Fingerprint
    variance_last_30m=0.042,              # L4: Inertial patterns
    is_mock_location=False
)

# 3. Optional: Provide a Worker Profile (L6 Baseline)
profile = WorkerProfile(
    worker_id="PARTNER_123",
    baseline_accelerometer_variance=0.05
)

# 4. Verify the Claim
result = engine.verify(claim, profile=profile, claim_burst_rate=4.5)

print(f"Result Tier: {result.tier}")
print(f"Coherence Score: {result.coherence_score}/100")
print(f"Reason: {result.recommendation}")

---

💻 CLI Usage

GeoTruth includes a comprehensive CLI for system testing and automated auditing.

# Verify a claim from a JSON file
geotruth --claim data/sample_claim.json --burst 12.5

# Standard Output
============================================================
 GeoTruth Verification Result
============================================================
Tier           : AUTO_APPROVE
Recommendation : APPROVE
Coherence Score: 92/100
Confidence     : 95%
============================================================

---

📋 Data Manifest

The ClaimVector is the primary interface between your mobile SDK and GeoTruth.

Field	Type	Description
device_barometer_hpa	float	Raw hardware barometer reading in hPa.
acoustic_feature_vector	List[float]	5-dimensional probability vector from on-device YAMNet.
cell_tower_ids	List[str]	Hashed IDs of visible cell towers.
variance_last_30m	float	Rolling variance of accelerometer magnitude (30m window).
is_mock_location	bool	High-accuracy flag for Developer Settings spoofing.

---

🛡️ Grace-First Workflow (UX)

GeoTruth is designed to protect the honest, not just catch the fraudulent. We implement a non-punitive, 5-tiered escalation ladder:

[!TIP] Tier 0 (Score < 35): Silent auto-approval. The worker is paid in < 8 minutes.

Tier 1 (Score 36-55): Passive Enrichment. System re-polls zone data for 15 mins without bothering the worker.

Tier 2 (Score 56-74): Soft Proof Request. Asks for a 5-sec video or area name via push notification.

Tier 3 (Score 75-100): Human Review. Worker receives an advance partial payout of ₹200 to show trust while engineers review.

Tier 4 (Ring alert): FREEZE. Triggered by Layer 7 temporal burst detection.

---

🛣️ Roadmap

• v1.1: Integration with real-time IMD satellite precipitation grid.
• v1.2: Advanced Device Fingerprinting (detecting OS-level spoofing hooks).
• v1.3: Dynamic Thresholding based on city-level infrastructure quality.

---

🤝 Contributing

We welcome contributions to the GeoTruth engine!

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/NewLayer).
3. Commit your changes (git commit -m 'Add new acoustic feature').
4. Push to the branch (git push origin feature/NewLayer).
5. Open a Pull Request.

---

HackDragons & GeoTruth — Building the infrastructure of trust for the next billion workers.

© 2026 HACKDRAGONS TEAM | Developed for DEVTrails 2026