boc/docs/design/DECISION_PIPELINE_v1.0.md

# DECISION PIPELINE v1.0

**Transformation Chain from Reality to Decision**

| | |
|---|---|
| **Version** | 1.0 |
| **Status** | DRAFT |
| **Scope** | All Landvex data flows, from collection to decision |

---

## The Pipeline

```
Reality
    ↓
Observation
    ↓
Evidence
    ↓
Finding
    ↓
Decision
    ↓
Action
    ↓
Business Impact
```

---

## Step 1: Observation

| | |
|---|---|
| **Input** | Photo, video, GPS, timestamp, sensor data |
| **Transformation** | AI detects objects, classifies, measures |
| **Output** | Observation (typed, located, timed) |
| **Owner** | Detection Engine |

**Example:**
```
Input: Mobile photo of road + GPS coordinates
Transformation: AI identifies crack, measures 15cm width
Output: Observation {type: "crack", size: "15cm", location: [lat, lng]}
```

---

## Step 2: Evidence

| | |
|---|---|
| **Input** | Observations, history, GIS, weather, traffic |
| **Transformation** | Correlation, deduplication, context enrichment |
| **Output** | Evidence Bundle (linked observations with context) |
| **Owner** | Evidence Engine |

**Example:**
```
Input: 3 crack observations + road age + traffic volume
Transformation: Correlate by location, check against historical data
Output: Evidence {observations: [obs1, obs2, obs3], trend: "increasing", confidence: 0.91}
```

---

## Step 3: Finding

| | |
|---|---|
| **Input** | Evidence Bundle |
| **Transformation** | Rules, thresholds, AI reasoning, pattern matching |
| **Output** | Finding (pattern, conclusion, severity) |
| **Owner** | Analysis Engine |

**Example:**
```
Input: Evidence Bundle (3 cracks, trend increasing)
Transformation: Compare against degradation models, calculate severity score
Output: Finding {description: "Road degraded 15%", severity: "high", confidence: 0.87}
```

---

## Step 4: Decision

| | |
|---|---|
| **Input** | Finding + business rules + priorities + constraints |
| **Transformation** | Recommendation generation, priority scoring, action mapping |
| **Output** | Decision (recommended action, urgency, rationale) |
| **Owner** | Decision Engine |

**Example:**
```
Input: Finding (road degraded 15%) + maintenance schedule + budget constraints
Transformation: Generate recommendation, calculate urgency, map to action
Output: Decision {action: "inspect", urgency: "14 days", rationale: "Safety risk"}
```

---

## Step 5: Action

| | |
|---|---|
| **Input** | Decision + user confirmation + resources |
| **Transformation** | Task creation, scheduling, assignment, tracking |
| **Output** | Action (scheduled, assigned, tracked) |
| **Owner** | Action Engine |

**Example:**
```
Input: Decision (inspect in 14 days) + user approval + inspector availability
Transformation: Create work order, schedule inspection, assign team
Output: Action {task_id: "WO-2026-001", scheduled: "2026-07-16", assigned: "Team A"}
```

---

## Step 6: Business Impact

| | |
|---|---|
| **Input** | Action completion + before/after measurements + costs |
| **Transformation** | Impact calculation, ROI analysis, risk reduction quantification |
| **Output** | Business Impact (measurable effect) |
| **Owner** | Impact Engine |

**Example:**
```
Input: Inspection completed + new measurements + actual costs
Transformation: Compare before/after, calculate risk reduction, quantify savings
Output: Business Impact {risk_reduced: "12% → 3%", cost_avoided: "$50,000", time_saved: "2 weeks"}
```

---

## Step 7: Learning

| | |
|---|---|
| **Input** | Business Impact + original Decision Object + actual outcomes |
| **Transformation** | Compare prediction vs reality, adjust models and rules |
| **Output** | Improved models, updated thresholds, better recommendations |
| **Owner** | Learning Engine |

**Example:**
```
Input: Business Impact + original Decision {confidence: 0.87, action: "inspect"}
Transformation: Was recommendation followed? Did it produce desired effect? Was confidence correct?
Output: Learning {model_adjustment: "increase crack threshold by 5%", confidence_calibration: "0.87 → 0.92"}
```

**Learning questions:**
- Was the recommendation executed?
- Did it produce the desired effect?
- Was the confidence correct?
- Was the recommendation too aggressive or too cautious?
- Do rules or models need adjustment?

---

## Control Intelligence

**LandveX produces Control Intelligence, not AI analysis.**

Control Intelligence consists of:
- Observations
- Evidence
- Findings
- Recommendations
- Business Impact
- Learning

**Not:** "AI analyzes the video"
**But:** "LandveX produces a recommendation to inspect Road A12 within 14 days"

AI is implementation. Control Intelligence is the product.

---

## Architecture Layers

```
┌─────────────────────────────────────┐
│  Presentation Layer                 │
│  Dashboard, API, Reports            │
├─────────────────────────────────────┤
│  Decision Layer                     │
│  Recommendations, Priorities        │
├─────────────────────────────────────┤
│  Intelligence Layer                 │
│  Findings, Analysis                 │
├─────────────────────────────────────┤
│  Knowledge Layer                    │
│  Observations, Evidence, History    │
├─────────────────────────────────────┤
│  Reality Layer                      │
│  Collection, Sensors, Mobile        │
└─────────────────────────────────────┘
```

| Layer | Components | Responsibility |
|-------|-----------|----------------|
| **Reality** | quiXzoom app, drones, sensors, cameras | Collect raw data |
| **Knowledge** | Detection Engine, Evidence Engine | Structure and enrich |
| **Intelligence** | Analysis Engine | Find patterns |
| **Decision** | Decision Engine | Generate recommendations |
| **Presentation** | Dashboard, API, Reports | Show decisions |

**Plus Learning Loop:** Business Impact feeds back to Intelligence Layer to improve future recommendations.

---

## Communication Principle

**Not:**
```
Video → AI → Score
```

**But:**
```
Observation → Analysis → Recommendation
```

AI is implementation. Recommendation is the product.

---

## Target Customer Cases

Three customer types to validate the pipeline:

| Customer Type | Decision | Why Important |
|---------------|----------|---------------|
| **Municipality** | "Inspect or wait?" | Maintenance and prioritization |
| **Property Owner** | "Repair now or plan later?" | Cost vs risk |
| **Contractor/Operations** | "Which action first?" | Operational planning |

**Goal:** Same Decision Pipeline works for three different customer types, not just three technical scenarios.

## Validation Requirements

Before freezing Decision Pipeline v1.0:

1. **Three real customer cases** — municipalities, property owners, or contractors follow the full chain
2. **Run each case through entire Decision Pipeline** — from observation to business impact to learning
3. **Document where pipeline breaks** — not where you think it might break
4. **Revise only after** — model changes when data contradicts model, not before
5. **Empirical validation** — same Decision Object works for real data
6. **End-to-end test** — from observation to business impact

---

## ändringshistoria

| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial decision pipeline with 6 steps, 5 layers, validation requirements |

---

## STATUS

**DRAFT — Awaiting empirical validation with real customer cases**