llama-farm/drone-router-dataset-navlink-v2

---
pretty_name: NAVLINK Drone Router Dataset - Round 2 Snapshot
tags:
- drones
- mavlink
- px4
- function-calling
- edge-ai
- robotics
size_categories:
- 1K<n<10K
task_categories:
- text-generation
language:
- en
---

# NAVLINK Drone Router Dataset — Round 2 Snapshot

This dataset is the exact training/eval snapshot used for the **best reviewed overnight FunctionGemma/NAVLINK run (“10-epoch run 2”)**, which reached:

- **Tool-call exact-match accuracy (line 1): 95.2%**
- **476 / 500 correct**
- **0 safety violations**

This is the dataset snapshot **before** the later waypoint-copy-heavy augmentation that regressed performance.

## Files

- `navlink_train_run2.jsonl` — **4,307** training examples
- `navlink_test_run2.jsonl` — **500** held-out test examples
- `generate.py` — generator used to create the initial NAVLINK dataset family
- `context.md` — exact `[STATE] + [CMD]` contract
- `tools.md` — full tool schemas and routing rules
- `vision_triggers.md` — how live detections become router inputs
- `run2_metadata.json` — snapshot metadata and score summary

## What this dataset is for

This dataset trains a small on-device router model that maps:

1. telemetry + vision state
2. operator command, vision event, or safety event

into:

1. **exactly one drone tool call on line 1**
2. **a short operator-facing message on line 2**

The target runtime is a PX4/MAVLink drone stack with a fixed forward camera and a local vision service.

---

## Exact system prompt used

```text
You are a drone command router. Given [STATE] telemetry and a [CMD] trigger, output exactly one tool call on line 1, and a short operator confirmation on line 2.

Safety rules (override everything):
- battery < 15%: drone_flight(action="land")
- battery < 25%: drone_flight(action="rth")
- gps lost: drone_flight(action="stop")

Routing hints:
- Target not visible + "find X": drone_scan(lock_on_class="X")
- Target visible + "follow/track": drone_track(action="start")
- Multiple waypoints: drone_mission, single GPS point: drone_goto
- Compound commands: first step only

Heartbeats: drone_notify(message="heartbeat") — no line 2.
```

---

## Input contract

Every example uses this interface:

```text
[STATE] <telemetry> | <vision status> [| <optional active detection>]
[CMD] <trigger text>
```

### Canonical telemetry layout

```text
[STATE] phase=AIRBORNE alt=15.2m bat=72% hdg=270° spd=3.1m/s pos=32.851,-97.125 | vision=SCANNING target=person wp=2/5
[CMD] find people and follow them
```

### With an active detection injection

```text
[STATE] phase=AIRBORNE alt=15.0m bat=68% hdg=270° spd=0.0m/s pos=32.852,-97.124 | vision=SCANNING target=person wp=0/0 | det=person conf=0.87 bearing=45° range=15m at=32.853,-97.121
[CMD] person detected at bearing 45°, confidence 87%
```

### Telemetry fields

- `phase` — `GROUNDED`, `AIRBORNE`, `RTL`, etc.
- `alt` — altitude AGL in meters
- `bat` — battery remaining percent
- `hdg` — current heading in degrees
- `spd` — ground speed in meters/sec
- `pos` — current GPS `lat,lon`

### Vision fields

- `vision` — `IDLE`, `SCANNING`, `TRACKING`, `LOST`
- `target` — current scan/track target (`none`, `person`, `vehicle`, `animal`)
- `wp` — waypoint progress like `0/0` or `2/5`

### Optional detection injection

When a live or synthetic detection is active, append a second `|` section:

- `det` — detected class
- `conf` — confidence, usually 2 decimals
- `bearing` — relative bearing from drone
- `range` — estimated range in meters
- `at` — estimated GPS for the detection

---

## Trigger types

The dataset teaches one unified interface for 3 trigger families.

### 1) Pilot commands
Examples:

```text
[CMD] take off
[CMD] find people and follow them
[CMD] go to 32.853, -97.121 and scan
[CMD] status report
```

### 2) Vision triggers
Examples:

```text
[CMD] person detected at bearing 45°, confidence 87%
[CMD] possible vehicle, low confidence 38%
[CMD] lost tracking on person
[CMD] search complete, no targets
```

### 3) Safety triggers
Examples:

```text
[CMD] battery low at 22%
[CMD] battery critical at 12%
[CMD] gps signal lost
```

---

## Output contract

### Standard two-line format

```text
drone_tool(param="value")
Short operator-facing confirmation.
```

### Heartbeat special case

```text
drone_notify(message="heartbeat")
```

No second line is emitted for heartbeat.

### Important evaluation rule

For this dataset family, **line 1 is the hard contract**.

- **Line 1**: exact string match
- **Line 2**: semantically helpful operator feedback; wording may vary in production

This means the dataset is optimized primarily for deterministic tool routing accuracy.

---

## Tool surface

This snapshot routes across 9 tools:

- `drone_flight(action)`
- `drone_move(direction, distance_m)`
- `drone_yaw(degrees|heading)`
- `drone_goto(lat, lon, alt_m, speed_mps, on_arrival)`
- `drone_look(action)`
- `drone_scan(lock_on_class)`
- `drone_track(action, target_class)`
- `drone_mission(action, target, pattern, waypoints)`
- `drone_notify(message)`

See `tools.md` for the full schema and decision table.

---

## How to format real live inputs

### A. Plain operator command

```text
[STATE] phase=AIRBORNE alt=12.0m bat=61% hdg=45° spd=0.0m/s pos=32.853,-97.123 | vision=IDLE target=none wp=0/0
[CMD] take a photo
```

### B. Vision bridge injection

When the vision service sees a confirmed target, the agent bridge should convert that event into the same text interface:

```text
[STATE] phase=AIRBORNE alt=15.0m bat=68% hdg=270° spd=0.0m/s pos=32.852,-97.124 | vision=SCANNING target=person wp=0/0 | det=person conf=0.87 bearing=45° range=15m at=32.853,-97.121
[CMD] person detected at bearing 45°, confidence 87%
```

### C. Lost-track trigger

```text
[STATE] phase=AIRBORNE alt=15.0m bat=50% hdg=315° spd=1.0m/s pos=32.852,-97.124 | vision=LOST target=person wp=0/0
[CMD] lost tracking on person
```

### D. Battery trigger

```text
[STATE] phase=AIRBORNE alt=20.0m bat=22% hdg=180° spd=2.0m/s pos=32.854,-97.122 | vision=TRACKING target=person wp=0/0
[CMD] battery low at 22%
```

### E. Map-click / external UI injection

If a UI or operator map click provides a GPS point, convert it into the same `[CMD]` contract:

```text
[STATE] phase=AIRBORNE alt=15.0m bat=70% hdg=0° spd=0.0m/s pos=32.851,-97.125 | vision=IDLE target=none wp=0/0
[CMD] go to 32.853, -97.121 and scan
```

---

## How to add chat / operator text

The dataset assumes that any upstream chat or radio input has already been reduced into a single `[CMD]` line.

Recommended bridge pattern:

1. receive operator text / chat message / speech transcript
2. normalize it into plain text
3. append current `[STATE]`
4. produce:

```text
[STATE] ...
[CMD] <normalized operator text>
```

If the operator message references something visual (“check that out”, “follow that”), the bridge should preserve any active detection context in the `[STATE]` line so the router can resolve the reference.

Example:

```text
[STATE] phase=AIRBORNE alt=15.0m bat=65% hdg=45° spd=0.0m/s pos=32.852,-97.124 | vision=IDLE target=none wp=0/0 | det=unknown conf=0.55 bearing=90° range=20m at=32.852,-97.122
[CMD] check that out
```

---

## Safety policy embedded in the dataset

The dataset teaches strict overrides:

- `battery < 15%` → `drone_flight(action="land")`
- `battery < 25%` → `drone_flight(action="rth")`
- `gps lost` → `drone_flight(action="stop")`

These rules override mission/tracking/operator intent.

---

## Why this is the round-2 snapshot

This snapshot captures the dataset state that produced the best reviewed overnight result.

It includes the targeted fixes that improved:

- `arm` vs `takeoff`
- `stop` vs `move(stop-like phrasing)`
- `abort mission` vs `stop`
- `spiral` pattern handling

It does **not** include the later large waypoint-copy augmentation that pushed the model into a regression.

---

## Evaluation summary for the associated best run

- **Accuracy:** 95.2% (`476/500`)
- **Safety violations:** `0`
- Strong tools in that run included:
- `drone_flight`: 98%
- `drone_look`: 100%
- `drone_notify`: 100%
- `drone_scan`: 100%
- `drone_track`: 100%
- `drone_yaw`: 100%
- Main remaining weakness:
- `drone_mission` waypoint-heavy exact-match cases

---

## Limitations

The main residual failure mode in this family is exact verbatim copying of arbitrary GPS waypoint sequences for `drone_mission(..., waypoints="...")` under strict string-match eval.

Operationally, this matters less when waypoints come from structured UI/map interactions rather than freeform natural language, but it is still the main benchmark gap.

---

## License / intended use

This dataset is intended for small on-device drone routing experiments, evals, and edge deployment workflows where deterministic line-1 tool routing is more important than verbose language generation.