kunyi

Generate Anki .apkg decks from JSON (MCQ) or TSV (basic) card data.

Part of the Seya study ecosystem.

---

Installation

pip install kunyi

Or for local development:

git clone https://github.com/LingT03/Kunyi.git
cd Kunyi
pip install -e .

---

CLI usage

# JSON — multiple-choice question cards
kunyi "Cloud Computing" cards.json

# TSV — basic front/back cards
kunyi "Calc 2 Formulas" formulas.tsv

# Explicit output path (recommended for subprocess callers)
kunyi "Cloud Computing" cards.json --output /path/to/deck.apkg

# Override format detection
kunyi "My Deck" cards.data --format tsv

On success the resolved .apkg path is printed to stdout (exit 0).
On failure a human-readable message is printed to stderr (exit 1).

---

Input formats

JSON — MCQ cards

{
  "cards": [
    {
      "question": "What does CPU stand for?",
      "choices": ["Central Processing Unit", "Core Power Unit", "Control Processing Unit"],
      "correct_answer": "Central Processing Unit",
      "explanation": "CPU stands for Central Processing Unit.",
      "tags": ["chapter-1"]
    }
  ]
}

correct_answer must be an element of choices — validated on parse.
tags is optional.

TSV — basic cards

Tab-delimited UTF-8. Optional header row (front\tback) is auto-detected and skipped.

front	back
What is spaced repetition?	A technique that spaces reviews over time.
What is active recall?	Actively retrieving information from memory.

---

Library usage

from pathlib import Path
from kunyi import AnkiCardDeck, MCQCard, BasicCard

deck = AnkiCardDeck(deck_name="My Deck")

deck.add_card(MCQCard(
    question="What does RAM stand for?",
    choices=["Random Access Memory", "Read Access Module"],
    correct_answer="Random Access Memory",
    explanation="RAM is the primary short-term memory of a computer.",
    tags=["hardware"],
))

deck.add_card(BasicCard(
    front="What is a CPU?",
    back="The central processing unit — the brain of a computer.",
))

deck.save_deck(Path("output/my_deck.apkg"))

---

Running tests

pip install pytest
pytest tests/

---

What is Anki?

Anki is a free flashcard program that uses spaced repetition and active recall to maximise long-term retention. kunyi generates .apkg files that can be imported directly into Anki.