readme

README.md

@@ -1,12 +1,81 @@
 ---
-title: Demo
-emoji: 👀
-colorFrom: yellow
-colorTo: gray
+title: HiCoTraj
+emoji: 🗺️
+colorFrom: red
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.6.0
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# HiCoTraj Demo
+
+**Zero-Shot Demographic Reasoning via Hierarchical Chain-of-Thought Prompting from Trajectory**
+*ACM SIGSPATIAL GeoGenAgent Workshop 2025*
+
+---
+
+## Overview
+
+HiCoTraj demonstrates how a large language model can infer demographic attributes — specifically **household income** — from raw human mobility trajectories, using a three-stage hierarchical chain-of-thought (HiCoT) prompting strategy. No training data or fine-tuning is required; the model reasons step-by-step from spatial patterns alone.
+
+---
+
+## Interface Layout
+
+| Component | Description |
+|-----------|-------------|
+| **Agent Cards** | Top panel — 6 showcase agents from the NUMOSIM dataset. Click any card to load that agent's data throughout the interface. |
+| **Trajectory Map** | Interactive map of stay points, ordered chronologically (yellow → dark red). Click any dot for location, time, and activity details. |
+| **Summary Tab** | Rule-based processed data: top locations, temporal distribution, activity breakdown, and observation period. |
+| **Raw Data Tab** | Full daily activity log. Use **Show All Days** to expand beyond the preview. |
+| **CoT Panel** | Right column — step-by-step LLM reasoning. Advance with the ▶ button; each click runs one stage. |
+
+---
+
+## How to Run the Demo
+
+1. **Select an agent** by clicking one of the six cards at the top of the page.
+2. **Explore the Trajectory Map** — hover and click stay-point markers to inspect visit details.
+3. **Switch to the Raw Data tab** and click *Show All Days* to view the complete daily log.
+4. Click **▶ Stage 1: Feature Extraction** to begin the reasoning chain.
+5. Click **▶ Stage 2: Behavioral Analysis** — Stage 1 results are now visible.
+6. Click **▶ Stage 3: Demographic Inference** — all three stages shown simultaneously.
+7. Click **↺ Reset** to clear results and try a different agent.
+
+> 💡 **Tip:** Click **▼ prompt** under each stage header to expand the full prompt specification used for that step.
+
+---
+
+## Hierarchical Chain-of-Thought Stages
+
+### 🔵 Stage 01 — Feature Extraction
+
+The LLM receives raw trajectory data and extracts **objective features without interpretation**: location inventory (POI names, visit counts, price tier), temporal patterns (time-of-day and weekday/weekend split), spatial activity radius, and daily activity sequences.
+
+*Displayed as:* location table with visit bars · time-of-day color segment bar · weekday/weekend split
+
+### 🟠 Stage 02 — Behavioral Analysis
+
+Using Stage 1 features, the model performs **behavioral abstraction** across four dimensions: Routine & Schedule (work pattern type), Economic Behavior (spending tier from venue choices), Social & Lifestyle (leisure and community engagement), and Routine Stability (consistency of movement patterns).
+
+*Displayed as:* 2×2 card grid — one card per behavioral dimension
+
+### 🔴 Stage 03 — Demographic Inference
+
+The model synthesizes Stages 1 and 2 to **infer the agent's household income bracket**, citing specific mobility evidence. The structured output (`INCOME_PREDICTION` / `INCOME_REASONING`) enables reliable extraction and display.
+
+*Displayed as:* income prediction badge · evidence-grounded reasoning text
+
+---
+
+## Dataset
+
+**NUMOSIM** — *NUMoSim: A Synthetic Mobility Dataset with Anomaly Detection Benchmarks.*
+Stanford C., Adari S., Liao X., et al. ACM SIGSPATIAL Workshop on Geospatial Anomaly Detection, 2024.
+
+Synthetic trajectories preserving real population demographics and mobility patterns.
+
+- **Demo subset:** 6 agents
+- **Attribute inferred:** household income bracket
+- **Method:** zero-shot LLM, no fine-tuning