# AWARE — Aviation Weighted Active Recall Engine

A cross-platform CLI study tool built for aviation knowledge retention.
Named after the AWARE briefing — the same commitment to situational
awareness in the cockpit, applied to systems knowledge on the ground.

## Quick Start

```bash
cd aware
python3 aware.py
```

## Text-to-Speech

Voice is auto-detected by platform — no configuration needed:

| Platform | Engine | Install |
|----------|--------|---------|
| Linux | espeak-ng | `sudo apt install espeak-ng` |
| macOS | say | Built-in, nothing to install |
| Windows | SAPI (PowerShell) | Built-in, nothing to install |

Toggle voice on/off with `v` from any menu or during a quiz.

### Pronunciation Glossary

The file `tts_glossary.json` (next to `aware.py`) controls how abbreviations are spoken.
Edit it to add, remove, or change pronunciations:

```json
{
  "abbreviations": {
    "APU": "A-P-U",
    "DU": "display unit",
    "FADEC": "FADEC"
  },
  "symbols": {
    ">=": "greater than or equal to",
    "\u00b0": " degrees "
  }
}
```

Abbreviations are matched as **whole words only** — "DU" won't corrupt "DURING" or "PROCEDURE."
Longer abbreviations match first, so "KCAS" is caught before "CAS" can interfere.

### Custom TTS Override

To use a different engine (e.g. `piper` for better voice quality),
create `~/.aware/config.json`:

```json
{
  "tts_command": "piper",
  "tts_args": ["--model", "en_US-lessac-medium", "--output-raw", "{text}"]
}
```

Use `{text}` as the placeholder — it gets replaced with the spoken text.

## Adding New Decks

Drop any `.json` file into the `decks/` folder. Two formats supported:

### Minimal (flat)
```json
{
  "title": "My Study Deck",
  "questions": [
    {"question": "What is X?", "answer": "X is Y."}
  ]
}
```

### Full (with categories and references)
```json
{
  "title": "My Study Deck",
  "categories": [
    {
      "name": "Topic A",
      "questions": [
        {"id": 1, "question": "...", "answer": "...", "ref": "Chapter 3"}
      ]
    }
  ]
}
```

- `id` is auto-assigned if omitted
- `ref` is optional (displays after the answer)
- `category` enables the "By Category" filter in the menu
- `cas` is optional (string or array — displays CAS messages above the question)
- `detail` is optional (extended explanation displayed after the answer)

## Controls

After revealing an answer, grade yourself:

- **n** — Didn't get the answer at all → Bucket 1
- **1** — Got some of the answer → Bucket 2
- **2** — Got about half right → Bucket 3
- **3** — Got most of the answer → Bucket 4
- **y** — Nailed it → promotes by one (max Bucket 5)

Numpad aliases: **-** = n, **+** = y. Bare **Enter** defaults to missed.

Other keys:
- **v** — Toggle text-to-speech on/off
- **q** — Quit current session (progress is saved)
- **d** — Switch to a different deck

## Weighted Repetition

Questions live in 5 buckets:
- **Bucket 1** (No Clue) — 8x selection weight
- **Bucket 2** (Some) — 5x weight
- **Bucket 3** (Half) — 3x weight
- **Bucket 4** (Most) — 2x weight
- **Bucket 5** (Nailed It) — 1x weight

Grades `n` through `3` set the bucket directly based on self-assessment.
Grade `y` promotes by one — meaning you have to nail it from Bucket 4 to reach
Bucket 5, which matches the physical flashcard pattern of "getting it right regularly."

## Progress

Per-deck progress saved to `~/.aware/progress/`.
Reset per-deck via menu option 7, or delete the file to reset:

```bash
rm ~/.aware/progress/deckname_*.json   # single deck
rm -rf ~/.aware/progress/               # all decks
```