boc/docs/design/LANDVEX_INTELLIGENCE_LAB.md

# LANDVEX INTELLIGENCE LAB

**Internal Development Environment for Control Intelligence**

| | |
|---|---|
| **Version** | 1.0 |
| **Status** | SPECIFICATION |
| **Purpose** | Build, test, and verify LandveX Control Intelligence before production |

---

## Core Principles

**LandveX Intelligence Lab does not produce AI models. It produces verified Control Intelligence.**

This is an internal tool. Never a customer product.

**All artifacts are immutable and versioned.**
- Raw images are never modified
- Annotations are versioned
- Models are versioned
- Evaluation reports are versioned
- Decision Cases are versioned
- Replay results are saved as new artifacts

**Every change must be traceable to a specific experiment, model version, dataset, and decision.**

## Quality Standards for Government & Public Sector

**LandveX serves municipalities, government agencies, and public infrastructure owners. The Intelligence Lab must be built to standards that satisfy public sector procurement, audit, and compliance requirements.**

### Code Quality

| Requirement | Standard | Rationale |
|-------------|----------|-----------|
| **Type Safety** | Strict TypeScript or Rust | Eliminates entire classes of runtime errors |
| **Test Coverage** | ≥80% unit, ≥90% critical paths | Public sector demands verifiable quality |
| **Static Analysis** | ESLint + SonarQube + Snyk | Catch issues before deployment |
| **Code Review** | All changes require 2 approvals | No unreviewed code in production |
| **Documentation** | Every public API documented | Procurement requires documentation |

### Security

| Requirement | Standard | Rationale |
|-------------|----------|-----------|
| **Authentication** | OAuth 2.0 + MFA | Government security requirements |
| **Authorization** | RBAC with audit logging | Who did what, when |
| **Encryption** | AES-256 at rest, TLS 1.3 in transit | Data protection regulations |
| **Secrets Management** | HashiCorp Vault or AWS Secrets Manager | No secrets in code |
| **Vulnerability Scanning** | Weekly automated scans | Continuous security |

### Audit & Compliance

| Requirement | Standard | Rationale |
|-------------|----------|-----------|
| **Immutable Audit Log** | Append-only, signed logs | Tamper-evident history |
| **Data Retention** | Configurable per jurisdiction | GDPR, local laws |
| **Export Capability** | Full data export in standard formats | Freedom of information requests |
| **Accessibility** | WCAG 2.1 AA | Public sector requirement |
| **Localization** | Swedish + English | Government customers |

### Infrastructure

| Requirement | Standard | Rationale |
|-------------|----------|-----------|
| **Deployment** | GitOps (ArgoCD/Flux) | Reproducible, auditable deployments |
| **Observability** | OpenTelemetry + structured logging | Debug production issues |
| **Backup** | 3-2-1 rule, tested restores | Business continuity |
| **Disaster Recovery** | RPO < 1h, RTO < 4h | Critical infrastructure |
| **Scalability** | Horizontal scaling, stateless services | Handle peak loads |

### AI/ML Specific

| Requirement | Standard | Rationale |
|-------------|----------|-----------|
| **Model Versioning** | MLflow or similar | Track every model version |
| **Data Lineage** | Full provenance for all datasets | Explain model decisions |
| **Bias Testing** | Automated fairness metrics | Prevent discriminatory outcomes |
| **Explainability** | SHAP or LIME for all predictions | Right to explanation |
| **Model Cards** | Documented for every model | Transparency |

### Development Practices

| Requirement | Standard | Rationale |
|-------------|----------|-----------|
| **Git Workflow** | Trunk-based or GitFlow | Clear, auditable history |
| **CI/CD** | Automated testing, staging, production | No manual deployments |
| **Infrastructure as Code** | Terraform or Pulumi | Version-controlled infrastructure |
| **Dependency Management** | Renovate or Dependabot | Keep dependencies updated |
| **Incident Response** | Documented runbooks | Handle outages systematically |

## Product Architecture

```
quiXzoom
    ↓
Observations
    ↓
LandveX Intelligence Lab
    ↓
Improved Models
    ↓
LandveX
    ↓
Better Decisions
    ↓
Feedback
    ↓
Intelligence Lab
```

**Two products:**
- **quiXzoom** — produces observations
- **LandveX** — produces decisions
- **Intelligence Lab** — the factory that improves both

---

## Repository

```
landvex-intelligence-lab
```

Separate from:
- `quixzoom-app`
- `landvex-web`
- `aamos-core`

---

## Architecture

```
LandveX Intelligence Lab
│
┌─────────────────┼─────────────────┐
│                 │                 │
Developer UI    Training API    Experiment API
│                 │                 │
└─────────────────┴─────────────────┘
│
Event Bus / Queue
│
─────────────────────────────────────────────────────
Storage Layer
Images │ Videos │ Missions │ Models │ Logs
S3/R2 Buckets + PostgreSQL + Neo4j
─────────────────────────────────────────────────────
│
Processing Pipelines
```

## Navigation

```
Dashboard
├── Models
├── Datasets
├── Annotations
├── Training
├── Evaluation
├── Decision Cases
├── Replay
├── Validation
├── Promote Model
└── Settings
```

---

## Dashboard

Shows AI status, not business data.

```
┌─────────────────────────────────────┐
│ Datasets                            │
│ Healthy: 12                         │
│ Needs Review: 3                     │
│ Corrupted: 0                        │
├─────────────────────────────────────┤
│ Training Jobs                       │
│ Running: 2                          │
│ Queued: 1                           │
│ Completed: 47                       │
│ Failed: 0                           │
├─────────────────────────────────────┤
│ Decision Cases                      │
│ Validated: 23                       │
│ Pending: 5                          │
│ Rejected: 2                         │
├─────────────────────────────────────┤
│ Replay Jobs                         │
│ Ready: 8                            │
│ Running: 1                          │
│ Finished: 34                        │
└─────────────────────────────────────┘
```

---

## Mission Replay

Click through the entire chain:

```
Video → Frame → Bounding boxes → Detected objects → Evidence → Finding → Decision → Business Impact
```

---

## Annotation

```
┌─────────┬─────────────┬──────────────┐
│ Video   │ AI Suggestion│ Manual       │
│         │              │ Correction   │
├─────────┼─────────────┼──────────────┤
│         │ Object:      │ Correct?     │
│         │ Road Crack   │ YES / NO     │
│         │ Confidence:  │              │
│         │ 82%          │ Severity:    │
│         │              │ Low / Medium │
│         │              │ / High       │
└─────────┴─────────────┴──────────────┘
```

---

## Decision Cases

**The most important asset.**

Not images. Not videos. Not AI models.

But:
```
Observation → Evidence → Finding → Decision → Outcome → Learning
```

After a few years, hundreds of thousands of verified Decision Cases.
Not just a training dataset — a library of how real observations lead to real decisions and real outcomes.

```
Case #4232
├── Reality
├── Observation
├── Evidence
├── Finding
├── Decision
├── Outcome
└── Learning
```

All cases playable.

---

## Benchmark

Compare models:

| Model | Precision | Recall | F1 | Latency | Decision Accuracy |
|-------|-----------|--------|----|---------|-------------------|
| YOLO v8 | 0.89 | 0.87 | 0.88 | 45ms | — |
| Grounding DINO | 0.91 | 0.85 | 0.88 | 120ms | — |
| SAM | 0.88 | 0.90 | 0.89 | 200ms | — |
| Custom | 0.92 | 0.91 | 0.915 | 60ms | 0.87 |

---

## Replay

Find regressions:

```
Mission 213
├── Play
├── Show AI
├── Show Human Annotation
├── Differences
├── New Model
└── Old Model
```

---

## Validation

```
Field Trials
Scenario Tests
Decision Tests
Evidence Tests
Golden Failures
Regression Tests
```

---

## Promote Model (Not Deploy)

```
Development → Validation → Pilot → Production
```

Not "Deploy". "Promote Model".

---

## Experiments

```
Experiments
├── EP-1.0
├── DS-001
├── DS-002
├── DS-003
├── Field Trials
└── Metrics
```

Link experiment protocol to real development and validation data.

---

## Processing Pipelines

### 1. Ingestion Pipeline

**Input:** Images, video, GPS, EXIF, metadata
**Checks:** Checksums, versioning
**Output:** Raw Dataset

### 2. Dataset Pipeline

**Input:** Raw Dataset
**Checks:** Sort, deduplicate, quality control, resolution, blur detection, GPS validation
**Output:** Validated Dataset

### 3. Annotation Pipeline

**Input:** Validated Dataset
**Process:** AI suggestions, manual correction, label versions, consensus
**Output:** Verified Dataset

### 4. Training Pipeline

**Input:** Verified Dataset
**Process:** Start training, hyperparameters, checkpoints, GPU jobs
**Output:** Model Artifact

### 5. Evaluation Pipeline

**Input:** Model Artifact
**Metrics:** Precision, recall, F1, decision accuracy, regression
**Output:** Evaluation Report

### 6. Replay Pipeline

**Input:** Old missions, Model v14, Model v15
**Process:** Run both models, compare differences
**Output:** Regression Report

### 7. Decision Validation Pipeline

**Input:** Observation
**Process:** Full chain — Observation → Evidence → Finding → Decision → Business Impact
**Output:** Decision Validation Report

---

## Bucket Structure

```
raw-images/
raw-video/
missions/
datasets/
annotations/
training/
models/
replays/
evaluation/
decision-cases/
field-trials/
exports/
archives/
```

All content is versioned:
```
model-v14/
model-v15/
model-v16/
```

---

## AI Job Queue

All jobs are asynchronous:

```
Upload → Queue → Worker → GPU → Storage → Notification
```

Not synchronous API calls.

---

## What This Tool Collects

- Model training
- Annotation
- Datasets
- Replay
- Decision chains
- Validation
- Regression tests
- Experiments
- Model promotion

---

## New Developer Experience

A new AI engineer should open the repo and within minutes understand:

**"This is the tool where we build, test, and verify LandveX Control Intelligence before anything reaches production."**

---

## Relationship to Principles

- All development in Git
- All experiments reproducible
- All models traceable from training to validation to production
- Version control and traceability

---

## MVP Milestone: "First Verified Decision"

**Definition:**
A developer can:
1. Film a real object with quiXzoom
2. Import material to Intelligence Lab
3. Review and correct AI interpretation
4. Create a Decision Case
5. Follow the entire chain from observation to decision with full traceability

**When this works, you have the first complete, verifiable Control Intelligence pipeline.**

## Development Phases

### Phase 1 — Essential (for pilot missions)

| Feature | Purpose |
|---------|---------|
| **Ingestion** | Upload images/video, show metadata (GPS, time, device), store raw data immutably |
| **Dataset Explorer** | Browse missions, filter, search, open a mission |
| **Annotation** | AI suggestions, manual correction, version history |
| **Decision Case Viewer** | Observation → Evidence → Finding → Decision → Business Impact → Learning |

**This is the heart.**

### Phase 2 — Scale (when running many missions)

| Feature | Purpose |
|---------|---------|
| **Replay** | Compare model versions on same mission |
| **Benchmark** | Model comparisons |
| **Evaluation** | Regression tests |

### Phase 3 — Advanced (when having multiple models)

| Feature | Purpose |
|---------|---------|
| **GPU Jobs** | Training queue |
| **Hyperparameter Runs** | Automated experiments |
| **Model Promotion** | Development → Validation → Pilot → Production |
| **Canary Releases** | Gradual rollout |

## New Areas

### Data Quality

Before training anything:

```
Images
├── Healthy
├── Blurred
├── Duplicate
├── Wrong GPS
├── Night
├── Rain
└── Occluded
```

Coverage:
```
Roads, Buildings, Signs, Drainage, Vegetation
```

Quickly shows why a model performs well or poorly.

### Decision Analytics

Not AI metrics. Decision metrics.

| Metric | Question |
|--------|----------|
| Acceptance Rate | How many recommendations were accepted? |
| Ignore Rate | How many were ignored? |
| Accuracy | How many proved correct? |
| Insufficient Evidence | How many lacked enough evidence? |
| Data Collection Value | How often did "Collect more data" lead to a better decision? |

Closer to LandveX business value than traditional AI metrics.

---

## ändringshistoria

| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial specification for LandveX Intelligence Lab |
| 1.1 | 2026-07-02 | Added architecture, pipelines, immutability |
| 1.2 | 2026-07-02 | Added MVP milestone, development phases, Data Quality, Decision Analytics |
| 1.3 | 2026-07-02 | Added Government Quality Standards for public sector compliance |

---

## STATUS

**SPECIFICATION — Awaiting development decision**

**Next decision:** Begin MVP implementation (Phase 1: Ingestion, Dataset Explorer, Annotation, Decision Case Viewer) or wait for further input.