# Startlist AI — User Guide

Startlist AI turns riders' wishes, written in plain language, into a **start order** that respects them.

You type what the rider asks — in any language, the way they said it. The AI reads it, turns it into precise start-order rules, and the extension builds a start order that applies them, then sends it back to Equipe.

The AI runs on your own network: **rider names and requests never leave it**.

This guide is for show secretaries and organisers.

---

## Contents

1. [How it works](#how-it-works)
2. [Opening the extension](#opening-the-extension)
3. [Recording rider requests](#recording-rider-requests)
4. [Writing a good request](#writing-a-good-request)
5. [What the AI understands](#what-the-ai-understands)
6. [Building the start order](#building-the-start-order)
7. [Status icons](#status-icons)
8. [Good practices](#good-practices)

---

## How it works

1. **Collect the wishes** — on the **Rider Requests** screen, record each request as it comes in. The AI reads it as soon as you save it and shows what it understood.
2. **Build the order** — on the **Process Rider Requests** screen, choose a class, let the tool compute the start order, check the result and send it to Equipe.

Two more screens, **Hippodata import** and **Hippodata Viewer**, let you bring in and look at Hippodata data (classes, results, teams, FEI articles) when needed.

---

## Opening the extension

Open it from the show in Equipe: it works directly on that show, with nothing to log into.

The extension opens in the same tab as Equipe. Use **Back to Equipe**, at the top right of every screen, to return to where you were.

---

## Recording rider requests

The screen has a form at the top (**New request to AI**) and the **Requests received** table below.

### Add a request

1. **Choose the rider** — type a rider's or a horse's name and pick it from the list. Choosing a horse selects its rider.
2. **Choose the scope** — by default the request applies to the **whole show**. To limit it, untick **Whole show** and select the classes. For shows over several weeks, use the week tabs.
3. **Write the request** — in any language, as the rider said it.
4. **Save** — within a few seconds, the line shows what the AI understood.

The **help button** next to Save shows examples of well-understood requests.

### The Requests received table

| Column | Content |
|---|---|
| **Rider** | The rider, and the horse if the request concerns one horse |
| **Classes** | *whole show* or the class numbers concerned |
| **AI Request / Response** | The original text, then the ✨ line with what the AI understood, and the time it took |
| **Status** | Where the request stands (see [Status icons](#status-icons)) |

Use ✎ to **edit** a request and 🗑 to **delete** it.

### When the AI needs you

Most requests are understood straight away (green check). Three cases need a decision:

- **Pick one** — the rider named someone ("after Rozier") and several riders match. Choose the right one in the drop-down list.
- **Guessed** — the wording was unusual: the AI proposes the closest rule but leaves it **inactive**. If it is right, click **✓ approve**.
- **Not understood** — the AI could not interpret the text, or the request contradicts itself ("before 10:00 and after 14:00"). The reason is shown; use **rephrase** to reword it.

The counter at the top of the screen shows how many items still need a decision.

---

## Writing a good request

- **Any language** — French, English, Dutch, German, even mixed.
- **The rider's own words** — no keywords needed. "My horse is green, I'd rather go early", "j'arrive du CSI voisin, pas avant 14h" and "graag vroeg starten" all work.
- **Several wishes in one request** — "Not right after Rozier, but with Gonin and Billot, and not before 14:30" gives four rules.
- **Approximate words are fine** — "more or less in the middle", "if possible early", "ideally near the end".

### Examples

| The rider says… | The AI understands |
|---|---|
| "somewhere in the middle please" | start in the middle third |
| "always in the first 4" | within the first 4 to go |
| "between 25 and 40" | start between positions 25 and 40 |
| "I have a pony lesson at 18:00" | must have started **before** 18:00 |
| "I'm coming from the neighbouring CSI, not before 14:00" | cannot start **before** 14:00 |
| "the two horses at least 15 apart" | at least 15 starts between the rider's horses |
| "Cartouche first, then Fais Toi Belle" | fixed order between the rider's horses |
| "keep me next to Tom Green and Lisa Brown" | group the rider with those two |
| "please put all the Beks together" | group every rider named Bek |
| "just before the break" | start just before the break |
| "not right after Rozier, he always takes ages" | keep the rider **far from** Rozier |

---

## What the AI understands

Each request becomes one or more of the rules below; they are what you see on the ✨ line.

### Position in the list

| Rule | Meaning |
|---|---|
| `start_early` | in the first third |
| `start_middle` | in the middle third |
| `start_at_end` | in the last third |
| `start_late` | after the first third |
| `start_last` | the very last |
| `start_within_first` | within the first *N* |
| `start_within_last` | within the last *N* |
| `start_between` | between two positions, e.g. 25–40 |

### Time

| Rule | Meaning |
|---|---|
| `start_before_time` | must have started **before** a time (e.g. another commitment at 18:00) |
| `start_after_time` | cannot start **before** a time (e.g. arriving from another show) |

"Before 10:00" sets the **latest** start; "not before 14:00" sets the **earliest**.

### The rider's own horses

| Rule | Meaning |
|---|---|
| `min_gap_own_horses` | minimum number of starts between the rider's horses |
| `horse_order` | fixed order between the rider's horses |

### Other riders

| Rule | Meaning |
|---|---|
| `after_rider` | after a named rider |
| `before_rider` | before a named rider |
| `near_rider` | close to a named rider |
| `far_from_rider` | far from a named rider (also "not right after X") |
| `group_with` | keep several riders together |
| `coach_far_from_group` | a coach keeps their group together, with more distance from themselves |

**Families:** "all the Beks" or "the three Beks" groups **every entered rider** with that surname — no need to name them one by one.

### The break

| Rule | Meaning |
|---|---|
| `before_break` | just before the break |
| `after_break` | just after the break |

"Before the break" means the break; "before Cyrius" means before that horse or rider.

### Negations and contradictions

Negations are understood: "not after the break" becomes *before the break*, "not too early" becomes *start late*.
A request that can never be met (first **and** after the break; before 10:00 **and** after 14:00) is marked **not understood**, with the reason.
A message that only describes the horse or says thank you is left **unknown** on purpose: the AI does not guess.

---

## Building the start order

On the **Process Rider Requests** screen:

1. **Choose the class** — use the **Week / Day** tabs (the Week row is hidden for a one-week show), then pick the class.
2. **Compute the order** — the tool proposes a start order that meets as many rules as possible.
3. **Check the log** — for each rule: applied, not applicable (with the reason) or still to review. Riders grouped together are highlighted. Requests never understood are listed so none is forgotten.
4. **Watch for overlaps** — a warning appears if a rider would start at the same time in two arenas running in parallel.
5. **Undo if needed** — the history panel restores the previous order of the class.
6. **Apply to Equipe** — send the order to Equipe.

---

## Status icons

**Request status**

| Icon | Status | Meaning |
|---|---|---|
| ⏳ (blue) | received | Saved, waiting for the AI |
| ✅ (green) | interpreted | Understood — rules on the ✨ line |
| ❌ (red) | failed | Not processed — rephrase it |
| ⏹ (yellow) | cancelled | Request cancelled |

**Rules inside a request**

- **✓** — ready.
- **⚠ pick one** — several riders match the name: choose one.
- **guessed / ✓ approve** — proposed from unusual wording: approve to activate.
- **✗ not found / ✗ incomplete** — a rider or horse could not be found, or a group has too few members.

---

## Good practices

- **Record requests as they arrive**: each one is read in a few seconds, and you see straight away what needs a decision.
- **Use the rider's words** rather than your own summary: nuances are kept.
- **Set the scope precisely** when a request concerns only some classes.
- **Read the "not applicable" lines** before applying an order: those are the wishes worth a word with the rider.