aware/docs

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

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:

{
  "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:

{
  "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)

{
  "title": "My Study Deck",
  "questions": [
    {"question": "What is X?", "answer": "X is Y."}
  ]
}

Full (with categories and references)

{
  "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:

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