boc/landvex-ai-training/taxonomy-guide.md

# Landvex AI Training Guide — Urban Taxonomy

## Version 1.0 — 2026-06-28

---

## 1. SIX-LAYER ANALYTICAL FRAMEWORK

### Purpose
Transform raw field observations into structured intelligence by analysing the same location through six distinct lenses. What appears irrational at one layer often becomes fully rational at another.

### The Six Layers

#### Layer 01 — Physical
**Question:** What exists here?
**Data Points:**
- Building types, heights, conditions
- Road quality, traffic patterns
- Signage, storefronts, vacancies
- People density, demographics
- Green space, water features

**AI Training Labels:**
```json
{
  "building_type": ["residential", "commercial", "industrial", "mixed"],
  "building_condition": ["excellent", "good", "fair", "poor", "derelict"],
  "road_quality": ["excellent", "good", "fair", "poor"],
  "pedestrian_density": ["very_high", "high", "moderate", "low", "very_low"],
  "vacancy_rate": "float (0.0-1.0)"
}
```

#### Layer 02 — Operational
**Question:** What is happening?
**Data Points:**
- Business hours, activity levels
- Delivery frequency, logistics
- Customer flows, queue lengths
- Construction, renovation activity
- Event presence, street markets

**AI Training Labels:**
```json
{
  "business_status": ["open_active", "open_quiet", "closed_temporarily", "closed_permanently", "unknown"],
  "activity_level": ["very_high", "high", "moderate", "low", "very_low"],
  "delivery_frequency": ["constant", "frequent", "occasional", "rare", "none"],
  "construction_activity": ["major", "minor", "none"],
  "event_presence": ["large", "small", "none"]
}
```

#### Layer 03 — Economic
**Question:** How is this financed?
**Data Points:**
- Ownership structure (family, corporate, institutional)
- Revenue streams (visible + inferred)
- Cost structure (rent, labour, materials)
- Profitability indicators
- Informal economy presence

**AI Training Labels:**
```json
{
  "ownership_type": ["family_owned", "sole_proprietor", "corporate", "institutional", "government", "unknown"],
  "revenue_visibility": ["fully_visible", "partially_visible", "mostly_hidden", "unknown"],
  "informal_economy_presence": ["high", "moderate", "low", "none", "unknown"],
  "profitability_indicator": ["strongly_profitable", "profitable", "break_even", "loss_making", "unknown"]
}
```

#### Layer 04 — Institutional
**Question:** What rules govern this?
**Data Points:**
- Zoning classification
- Lease terms, rent controls
- Permit status, compliance
- Tax regime, incentives
- Regulatory enforcement level

**AI Training Labels:**
```json
{
  "zoning": ["residential", "commercial", "industrial", "mixed_use", "special"],
  "lease_type": ["long_term", "short_term", "informal", "owner_occupied", "unknown"],
  "permit_status": ["fully_compliant", "minor_violations", "major_violations", "unlicensed", "unknown"],
  "regulatory_enforcement": ["strict", "moderate", "lax", "non_existent", "unknown"]
}
```

#### Layer 05 — Social
**Question:** What networks sustain this?
**Data Points:**
- Family/kinship structures
- Migrant worker presence
- Tourist vs local ratio
- Community organisation
- Social trust indicators

**AI Training Labels:**
```json
{
  "family_business": ["yes", "no", "unknown"],
  "migrant_worker_presence": ["high", "moderate", "low", "none", "unknown"],
  "customer_composition": ["mostly_tourist", "mixed", "mostly_local", "unknown"],
  "social_trust_indicator": ["high", "moderate", "low", "very_low", "unknown"]
}
```

#### Layer 06 — Temporal
**Question:** How does this change over time?
**Data Points:**
- Time of day patterns
- Day of week patterns
- Seasonal variations
- Economic cycle position
- Construction phase

**AI Training Labels:**
```json
{
  "time_pattern": ["rush_hour_peak", "daytime_active", "evening_active", "night_active", "always_quiet"],
  "seasonal_variation": ["very_high", "high", "moderate", "low", "none"],
  "economic_cycle": ["expansion", "peak", "contraction", "trough", "unknown"],
  "construction_phase": ["pre_construction", "active", "recently_completed", "mature", "none"]
}
```

---

## 2. CONTRADICTION DETECTION

### Definition
A contradiction occurs when observations from different layers conflict with each other, or when official narratives conflict with observed reality.

### Types of Contradictions

#### Type A — Cross-Layer Contradiction
**Example:** Physical layer shows "major construction" but Temporal layer shows "no activity for 6+ months" → Likely stalled project

#### Type B — Narrative-Reality Contradiction
**Example:** Official report states "commercial vitality increasing" but Operational layer shows "30% vacancy rate" → Overstated growth

#### Type C — Temporal Contradiction
**Example:** Rush hour observations show low traffic but Evening observations show high activity → Different economic rhythms than expected

### Scoring
```
Contradiction Index = (Number of detected contradictions / Number of possible cross-layer checks) × 100
```

**Interpretation:**
- 0-20: High consistency, reliable data
- 21-40: Minor inconsistencies, verify key assumptions
- 41-60: Significant contradictions, investigate further
- 61-80: Major contradictions, likely data quality issues or hidden dynamics
- 81-100: Critical contradictions, do not rely on single data source

---

## 3. AGGREGATE SCORES

### Opportunity Score (0-100)
Weighted combination of:
- Physical accessibility (15%)
- Operational activity (20%)
- Economic diversity (20%)
- Institutional support (15%)
- Social dynamism (15%)
- Temporal stability (15%)

### Growth Score (0-100)
Weighted combination of:
- Construction activity (25%)
- Business formation rate (25%)
- Investment flows (25%)
- Population trends (25%)

### Commercial Vitality Score (0-100)
Weighted combination of:
- Business density (20%)
- Customer traffic (25%)
- Revenue visibility (20%)
- Lease activity (15%)
- Night-time economy (20%)

### Infrastructure Stability Score (0-100)
Weighted combination of:
- Road quality (20%)
- Utility reliability (25%)
- Public transport (20%)
- Digital connectivity (15%)
- Maintenance schedules (20%)

### Investment Confidence Score (0-100)
Weighted combination of:
- Regulatory clarity (20%)
- Contract enforcement (20%)
- Currency stability (15%)
- Political risk (20%)
- Exit liquidity (25%)

---

## 4. TRAINING DATA REQUIREMENTS

### Minimum Observations per District
- **Physical:** 50+ geo-tagged images
- **Operational:** 10+ time-distributed observations
- **Economic:** 20+ business interviews/observations
- **Institutional:** Document review + 5+ expert interviews
- **Social:** 30+ behavioural observations
- **Temporal:** 4+ observations at different times

### Quality Thresholds
- GPS accuracy: <10m
- Image resolution: minimum 12MP
- Time stamp accuracy: <1 minute
- Contributor verification: ID + training completion
- AI review pass rate: >95%

### Bias Mitigation
- Rotate observation times (avoid only rush hour)
- Distribute observers across demographics
- Cross-validate with satellite imagery
- Compare with official statistics quarterly

---

## 5. OUTPUT FORMAT

### District Intelligence Card
```json
{
  "district_id": "string",
  "city": "string",
  "country": "string",
  "last_updated": "ISO-8601",
  "layer_scores": {
    "physical": {"score": 0-100, "confidence": 0-100},
    "operational": {"score": 0-100, "confidence": 0-100},
    "economic": {"score": 0-100, "confidence": 0-100},
    "institutional": {"score": 0-100, "confidence": 0-100},
    "social": {"score": 0-100, "confidence": 0-100},
    "temporal": {"score": 0-100, "confidence": 0-100}
  },
  "aggregate_scores": {
    "opportunity": 0-100,
    "growth": 0-100,
    "commercial_vitality": 0-100,
    "infrastructure": 0-100,
    "investment_confidence": 0-100,
    "contradiction_index": 0-100
  },
  "contradictions": [
    {
      "type": "A|B|C",
      "severity": "low|medium|high|critical",
      "description": "string",
      "layers_involved": ["string"],
      "recommended_action": "string"
    }
  ],
  "observation_count": integer,
  "contributor_count": integer,
  "data_quality_flag": "green|yellow|red"
}
```

---

## 6. CONTINUOUS IMPROVEMENT

### Feedback Loop
1. Deploy observations
2. AI analyses layers
3. Detect contradictions
4. Human expert review
5. Adjust weights/scoring
6. Retrain models
7. Repeat

### Model Update Cadence
- **Daily:** New observations ingested
- **Weekly:** Layer scores recalculated
- **Monthly:** Contradiction index updated
- **Quarterly:** Full model retraining
- **Annually:** Framework version update

---

## 7. EXAMPLE: BANGKOK ANALYSIS

### Observed Contradictions
1. **Physical vs Economic:** Luxury mall adjacent to informal market → Different economic systems coexisting
2. **Operational vs Temporal:** Massage salon empty at noon but full at midnight → Non-standard business hours
3. **Institutional vs Social:** Strict zoning but informal settlements persist → Enforcement gap

### Aggregate Scores (Example)
- Opportunity: 78/100
- Growth: 82/100
- Commercial Vitality: 71/100
- Infrastructure: 65/100
- Investment Confidence: 58/100
- Contradiction Index: 34/100 (moderate inconsistencies)

### Key Insight
Bangkok exhibits high opportunity and growth but lower investment confidence due to institutional-social contradictions. The informal economy provides operational resilience but creates regulatory uncertainty for formal investors.

---

*Document version: 1.0*
*Last updated: 2026-06-28*
*Next review: 2026-09-28*