muninn-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{muninn_cli-0.2.0 → muninn_cli-0.3.0}/.github/workflows/ci.yml

@@ -1,5 +1,9 @@
 name: CI
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 on:
   push:
     branches: ["main"]

muninn_cli-0.3.0/.github/workflows/deploy-docs.yml

@@ -0,0 +1,52 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - ".github/workflows/deploy-docs.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build docs
+        run: uv run zensical build --clean
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

{muninn_cli-0.2.0 → muninn_cli-0.3.0}/.gitignore

@@ -216,3 +216,9 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# Zensical
+site/
+
+# Agent files
+.agent/

muninn_cli-0.3.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: muninn-cli
+Version: 0.3.0
+Summary: Muninn - The Extensible Reciting CLI
+Project-URL: Repository, https://github.com/a1fredbao/muninn
+Project-URL: Issues, https://github.com/a1fredbao/muninn/issues
+Author-email: Alfred <your@email.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,flashcard,memorize,recite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Muninn
+
+Muninn (雾尼) - An Extensible Reciting CLI.
+
+[中文文档](./README_zh.md) &nbsp;|&nbsp;[Documentation](https://a1fredbao.github.io/muninn/)
+
+## What is Muninn?
+
+Muninn is a highly extensible CLI application designed to help you memorize anything. Instead of hardcoding questions, Muninn relies on a **Plugin Architecture**. You can install "Reciting Packs" created by others (like chemistry elements, GRE vocabulary, or historical events) or develop your own packs using Python.
+
+Muninn acts as a "host" that provides:
+
+1. A **Smart Scheduling Algorithm** (focuses on your weak-points).
+2. **Persistent State Management** (remembers your progress across sessions).
+3. A clean, distraction-free **Terminal UI**.
+
+## Installation & Usage
+
+Install Muninn globally using `uv` (recommended) or `pip`:
+
+```bash
+# Using uv (Recommended)
+uv tool install muninn-cli
+
+# Or using pip
+pip install muninn-cli
+```
+
+## Quickstart
+
+```bash
+# Install a pack from GitHub
+muninn install a1fredbao/muninn-chemistry-plugin
+
+# Start reciting
+muninn run muninn-chemistry-plugin
+```
+
+## Commands
+
+| Command                      |                                                              |
+| ---------------------------- | ------------------------------------------------------------ |
+| `muninn install <source>`    | Install a pack (local dir, zip, GitHub URL, or `user/repo`). |
+| `muninn uninstall <pack_id>` | Remove a pack.                                               |
+| `muninn list`                | List installed packs.                                        |
+| `muninn run <pack_id>`       | Start a reciting session.                                    |
+| `muninn new <name>`          | Generate a plugin template.                                  |
+
+## Write a Plugin
+
+See full documentation at: [a1fredbao.github.io/muninn](https://a1fredbao.github.io/muninn/)

muninn_cli-0.3.0/README.md

@@ -0,0 +1,51 @@
+# Muninn
+
+Muninn (雾尼) - An Extensible Reciting CLI.
+
+[中文文档](./README_zh.md)  | [Documentation](https://a1fredbao.github.io/muninn/)
+
+## What is Muninn?
+
+Muninn is a highly extensible CLI application designed to help you memorize anything. Instead of hardcoding questions, Muninn relies on a **Plugin Architecture**. You can install "Reciting Packs" created by others (like chemistry elements, GRE vocabulary, or historical events) or develop your own packs using Python.
+
+Muninn acts as a "host" that provides:
+
+1. A **Smart Scheduling Algorithm** (focuses on your weak-points).
+2. **Persistent State Management** (remembers your progress across sessions).
+3. A clean, distraction-free **Terminal UI**.
+
+## Installation & Usage
+
+Install Muninn globally using `uv` (recommended) or `pip`:
+
+```bash
+# Using uv (Recommended)
+uv tool install muninn-cli
+
+# Or using pip
+pip install muninn-cli
+```
+
+## Quickstart
+
+```bash
+# Install a pack from GitHub
+muninn install a1fredbao/muninn-chemistry-plugin
+
+# Start reciting
+muninn run muninn-chemistry-plugin
+```
+
+## Commands
+
+| Command                      |                                                              |
+| ---------------------------- | ------------------------------------------------------------ |
+| `muninn install <source>`    | Install a pack (local dir, zip, GitHub URL, or `user/repo`). |
+| `muninn uninstall <pack_id>` | Remove a pack.                                               |
+| `muninn list`                | List installed packs.                                        |
+| `muninn run <pack_id>`       | Start a reciting session.                                    |
+| `muninn new <name>`          | Generate a plugin template.                                  |
+
+## Write a Plugin
+
+See full documentation at: [a1fredbao.github.io/muninn](https://a1fredbao.github.io/muninn/)

muninn_cli-0.3.0/README_zh.md

@@ -0,0 +1,51 @@
+# Muninn
+
+Muninn (雾尼) - 高度可扩展的背诵/记忆命令行工具。
+
+[English](./README.md)  | [完整文档](https://a1fredbao.github.io/muninn/)
+
+## Muninn 是什么？
+
+Muninn 是一个高度可扩展的命令行背诵软件，名字取自北欧神话中代表"记忆"的乌鸦雾尼。它不包含任何硬编码的题目，而是采用了 **插件架构**。你可以安装别人编写的"题库包"（比如化学元素表、GRE 单词、历史事件），也可以自己使用 Python 开发题库。
+
+Muninn 作为"宿主"，为你提供了三大能力：
+
+1. **智能出题调度算法**（根据历史正确率和耗时，专门盯着你的薄弱点出题）。
+2. **状态与进度持久化**（你的每一次练习进度都会被保存下来，随时可以继续）。
+3. 干净、无干扰的**终端 UI**。
+
+## 安装与使用
+
+使用 `uv`（推荐）或 `pip` 全局安装 Muninn：
+
+```bash
+# 使用 uv 安装 (推荐)
+uv tool install muninn-cli
+
+# 或者使用 pip 安装
+pip install muninn-cli
+```
+
+## 快速开始
+
+```bash
+# 从 GitHub 安装一个题库包
+muninn install a1fredbao/muninn-chemistry-plugin
+
+# 开始背诵
+muninn run muninn-chemistry-plugin
+```
+
+## 命令一览
+
+| 命令                         |                                                          |
+| ---------------------------- | -------------------------------------------------------- |
+| `muninn install <source>`    | 安装题库包（本地目录、zip、GitHub URL 或 `user/repo`）。 |
+| `muninn uninstall <pack_id>` | 卸载题库包。                                             |
+| `muninn list`                | 列出已安装的题库包。                                     |
+| `muninn run <pack_id>`       | 开始背诵。                                               |
+| `muninn new <name>`          | 生成插件开发模板。                                       |
+
+## 开发插件
+
+完整文档请见：[a1fredbao.github.io/muninn](https://a1fredbao.github.io/muninn/)

muninn_cli-0.3.0/docs/api/base-plugin.md

@@ -0,0 +1,60 @@
+# BaseRecitePlugin
+
+`BaseRecitePlugin` is the lowest-level plugin interface.  Implement all
+five methods for full control over rendering, answer checking, and
+metadata display.
+
+``` python
+from core.base_plugin import BaseRecitePlugin
+
+
+class Plugin(BaseRecitePlugin):
+    def load_data(self):
+        """Load static data from ``self.workspace_dir``.  Called once
+        at initialisation."""
+        pass
+
+    def get_all_problem_ids(self) -> list[str]:
+        """Return every unique problem ID in this pack."""
+        pass
+
+    def render_statement(self, problem_id: str) -> str:
+        """Return the question text shown to the user."""
+        pass
+
+    def check_answer(self, problem_id: str, user_input: str) -> bool:
+        """Return ``True`` if *user_input* is correct."""
+        pass
+
+    def get_expected_display(self, problem_id: str) -> str:
+        """Return the correct answer to show on failure."""
+        pass
+
+    def get_expand_info(self, problem_id: str) -> str:
+        """Optional: return extra info to show on success."""
+        return ""
+```
+
+## Lifecycle
+
+1. Muninn calls `__init__(workspace_dir)`, which calls `load_data()`.
+2. Muninn calls `get_all_problem_ids()` to build the scheduler queue.
+3. For each problem, Muninn calls `render_statement()` → captures user
+   input → calls `check_answer()`.
+4. On correct answer: `get_expand_info()` is shown.
+5. On wrong answer: `get_expected_display()` is shown.
+
+## `workspace_dir`
+
+`self.workspace_dir` points to the pack's private directory under
+`~/.muninn/packs/<pack_id>/`.  Use it to load static assets like CSV or
+JSON files:
+
+``` python
+def load_data(self):
+    import json, os
+
+    path = os.path.join(self.workspace_dir, "data.json")
+    with open(path, encoding="utf-8") as f:
+        self.records = json.load(f)
+```

muninn_cli-0.3.0/docs/api/data-plugin.md

@@ -0,0 +1,90 @@
+# DataPlugin
+
+`DataPlugin` is a higher-level wrapper around `BaseRecitePlugin` designed
+for the common pattern *"a set of records × a set of question
+directions"*.  Declare your question types and Muninn generates all
+problem variants automatically.
+
+## Quick Example
+
+``` python
+import os, json
+from typing import ClassVar
+from core.helpers import DataPlugin, QuestionType, Matchers
+
+
+class Plugin(DataPlugin):
+    QUESTION_TYPES: ClassVar[list[QuestionType]] = [
+        QuestionType(
+            label="Symbol → Name",
+            statement=lambda el: f"Element: {el['sym']}",
+            answer=lambda el: el["name"],
+            matcher=Matchers.case_insensitive("name"),
+        ),
+        QuestionType(
+            label="Name → Number",
+            statement=lambda el: f"Element: {el['name']}",
+            answer=lambda el: str(el["num"]),
+            matcher=Matchers.exact_integer("num"),
+        ),
+    ]
+
+    def load_records(self) -> list:
+        with open(
+            os.path.join(self.workspace_dir, "elements.json"), encoding="utf-8"
+        ) as f:
+            return json.load(f)
+```
+
+With 36 elements and 2 question types, this automatically produces 72
+problems — no manual ID generation, no dispatch tables.
+
+## `QUESTION_TYPES`
+
+A list of [`QuestionType` objects](#questiontype).  Each represents one
+question direction (e.g. "show symbol, ask name").
+
+## `load_records()`
+
+Override to return a list of data dicts from your workspace directory.
+Each dict is passed to every `QuestionType`.
+
+## `filter(record, q_type)`
+
+Optional.  Return `False` to skip a particular record × question-type
+combination.
+
+``` python
+def filter(self, record, q_type):
+    if q_type.label == "Position → Element":
+        return record["group"] != "0"  # skip noble gases
+    return True
+```
+
+## `_resolve(problem_id)`
+
+Returns `(record, QuestionType)` for a given problem ID.  Useful when
+overriding `get_expand_info()`:
+
+``` python
+def get_expand_info(self, problem_id: str) -> str:
+    el, qt = self._resolve(problem_id)
+    return f"{el['name']} — Period {el['period']}, Group {el['group']}"
+```
+
+## Problem ID Format
+
+IDs are generated as `{record_index}__{question_label}`, e.g.
+`0__Symbol → Name`.  You generally don't need to interact with them
+directly — they're used internally by the scheduler and state manager.
+
+## `QuestionType`
+
+`QuestionType` is a dataclass that encapsulates one question direction:
+
+| Field       | Type                  | Description                                                               |
+| ----------- | --------------------- | ------------------------------------------------------------------------- |
+| `label`     | `str`                 | Human-readable name, shown in the problem header.                         |
+| `statement` | `(dict) -> str`       | Function that renders the question text from a record.                    |
+| `answer`    | `(dict) -> str`       | Function that renders the expected answer from a record.                  |
+| `matcher`   | `(dict, str) -> bool` | Function that checks user input. Use [`Matchers`](matchers.md) factories. |

muninn_cli-0.3.0/docs/api/flashcard.md

@@ -0,0 +1,60 @@
+# FlashcardPlugin
+
+`FlashcardPlugin` is the simplest plugin type.  It handles the entire
+"front → back" flashcard pattern with zero boilerplate.
+
+## Quickstart
+
+Create a CSV with `front` and `back` columns:
+
+``` csv
+front,back
+apple,苹果
+dog,狗
+cat,猫
+```
+
+Then write a 3-line plugin:
+
+``` python
+from core.helpers import FlashcardPlugin
+
+
+class Plugin(FlashcardPlugin):
+    DATA_FILE = "words.csv"
+```
+
+That's it.  `FlashcardPlugin` automatically:
+
+- Loads `words.csv` from the workspace directory.
+- Generates one problem per row.
+- Renders `front` as the question, checks against `back`.
+
+## Supported Formats
+
+| Extension | Format                                                   |
+| --------- | -------------------------------------------------------- |
+| `.csv`    | CSV with `front` and `back` columns.                     |
+| `.json`   | JSON array of `{"front": "...", "back": "..."}` objects. |
+
+## Customisation
+
+Override `get_expand_info()` to show extra context on correct answers:
+
+``` python
+class Plugin(FlashcardPlugin):
+    DATA_FILE = "words.csv"
+
+    def get_expand_info(self, problem_id: str) -> str:
+        record, _ = self._resolve(problem_id)
+        return record.get("example", "")
+```
+
+## File Layout
+
+``` bash
+my-flashcards/
+├── manifest.json
+├── plugin.py        # 3 lines
+└── words.csv        # front, back columns
+```

muninn_cli-0.3.0/docs/api/matchers.md

@@ -0,0 +1,79 @@
+# Matchers
+
+Matchers are reusable answer-checking functions.  Instead of writing
+custom regex for every question type, use the built-in `Matchers`
+factories.
+
+## Built-in Matchers
+
+### `Matchers.exact(key)`
+
+Exact match after stripping whitespace.
+
+``` python
+# record: {"name": "hydrogen"}
+Matchers.exact("name")
+# user types "hydrogen" → True
+# user types "Hydrogen" → False
+```
+
+### `Matchers.exact_integer(key)`
+
+Extract digits from the user input and compare as strings (after stripping non-digit characters from the input). Note: this is string-based comparison, so leading zeros are preserved (e.g., "007" != "7").
+
+``` python
+# record: {"num": 17}
+Matchers.exact_integer("num")
+# user types "  17  " → True
+# user types "#17"    → True
+# user types "18"     → False
+```
+
+### `Matchers.case_insensitive(key)`
+
+Case-insensitive match after trimming whitespace.
+
+``` python
+# record: {"sym": "He"}
+Matchers.case_insensitive("sym")
+# user types "he" → True
+# user types "HE" → True
+```
+
+### `Matchers.chinese_symbol_pair(key1, key2)`
+
+Match "Chinese+symbol" or "symbol+Chinese" in either order, ignoring
+whitespace.
+
+``` python
+# record: {"name": "氢", "sym": "H"}
+Matchers.chinese_symbol_pair("name", "sym")
+# user types "氢H"   → True
+# user types "H氢"   → True
+# user types "氢 H"  → True
+```
+
+### `Matchers.any_order(*keys)`
+
+Match when all field values appear somewhere in the input, ignoring
+non-alphanumeric characters and case. Only ASCII letters and digits are retained during normalization; Unicode characters are discarded.
+
+``` python
+# record: {"period": 4, "group": "IVB"}
+Matchers.any_order("period", "group")
+# user types "4 IVB" → True
+# user types "IVB4"  → True
+```
+
+### `Matchers.custom(fn)`
+
+Pass your own function `(data_item: dict, user_input: str) -> bool`.
+
+``` python
+def my_matcher(record, user_input):
+    # custom logic
+    return True
+
+
+Matchers.custom(my_matcher)
+```

muninn_cli-0.3.0/docs/commands.md

@@ -0,0 +1,97 @@
+# Command Reference
+
+## `muninn install`
+
+Install a reciting pack.
+
+```bash
+muninn install <source>
+```
+
+`<source>` accepts:
+
+| Format                    | Example                                 |
+| ------------------------- | --------------------------------------- |
+| Local directory           | `./my-pack` or `/abs/path`              |
+| Local `.zip` file         | `./my-pack.zip`                         |
+| GitHub shorthand          | `user/repo` (defaults to `main` branch) |
+| GitHub shorthand + branch | `user/repo@dev`                         |
+| Full GitHub URL           | `https://github.com/user/repo`          |
+
+The pack is copied to `~/.muninn/packs/<pack_id>/`.  Installing the same
+`pack_id` again overwrites the previous version.
+
+Muninn records the installation source in the pack's `manifest.json` so
+that `muninn upgrade` knows where to check for updates later.
+
+## `muninn upgrade`
+
+Check for and install newer versions of installed packs.
+
+```bash
+# Upgrade all installed packs
+muninn upgrade
+
+# Upgrade a specific pack
+muninn upgrade <pack_id>
+```
+
+How it works:
+
+| Source type                 | Upgrade strategy                                                                                                                    |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| GitHub (`github:user/repo`) | Fetches `manifest.json` from the repository's default branch. If the remote version is newer, the pack is re-installed from GitHub. |
+| Local path (`local:/path`)  | Reads `manifest.json` from the source directory. If it no longer exists, the pack is skipped with a warning.                        |
+
+Packs installed before Muninn 0.3.0 do not have a `source` field and
+cannot be upgraded — reinstall them with `muninn install` to enable
+upgrades.
+
+## `muninn uninstall`
+
+Remove a previously installed pack.
+
+```bash
+muninn uninstall <pack_id>
+```
+
+Deletes `~/.muninn/packs/<pack_id>/`.  Progress data in
+`~/.muninn/states/<pack_id>.db` is **not** deleted — you can reinstall
+later and pick up where you left off.
+
+## `muninn list`
+
+List all installed packs with their metadata (id, name, author, version).
+
+```bash
+muninn list
+```
+
+## `muninn run`
+
+Start a reciting session for a pack.
+
+```bash
+muninn run <pack_id>
+```
+
+The scheduler presents problems based on your historical accuracy and
+response time, favouring topics you struggle with.
+
+During a session:
+
+- Type your answer and press Enter.
+- Type `q` or press `Ctrl+C` to quit and see your session summary.
+
+## `muninn new`
+
+Generate a new plugin template in the current directory.
+
+```bash
+muninn new <pack_name>
+```
+
+Creates a `<pack_name>/` folder containing:
+
+- `manifest.json` — pack metadata
+- `plugin.py` — a skeleton `DataPlugin` with import scaffolding

muninn_cli-0.3.0/docs/getting-started.md

@@ -0,0 +1,48 @@
+# Getting Started
+
+## Installation
+
+Install Muninn globally with `uv` (recommended) or `pip`:
+
+``` bash
+uv tool install muninn-cli
+# or
+pip install muninn-cli
+```
+
+## Basic Commands
+
+``` bash
+# Install a pack from a local directory, zip file, or GitHub repo
+muninn install ./my-pack
+muninn install user/repo
+muninn install user/repo@dev
+muninn install https://github.com/user/repo
+
+# List installed packs
+muninn list
+
+# Run a pack
+muninn run <pack_id>
+
+# Uninstall a pack
+muninn uninstall <pack_id>
+
+# Create a new plugin template
+muninn new <pack_name>
+```
+
+## Data Directory
+
+Muninn stores all user data under `~/.muninn/`:
+
+``` bash
+~/.muninn/
+├── packs/         # Installed reciting packs
+│   └── chemistry/
+└── states/        # Learning progress (SQLite)
+    └── chemistry.db
+```
+
+Progress is per-pack — uninstalling a pack keeps your data unless you
+delete it manually.