spacedrep 0.1.0__tar.gz

spacedrep-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true

spacedrep-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+*.egg-info/
+.ruff_cache/
+.pyright/
+.pytest_cache/
+reviews.db
+*.apkg
+plans/
+designs/
+.claude/
+.mcp.json
+sqlite_mcp_server.db

spacedrep-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: local
+    hooks:
+      - id: gitleaks
+        name: gitleaks
+        entry: gitleaks git --pre-commit --redact --verbose
+        language: system
+        pass_filenames: false
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.12
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

spacedrep-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wpwilson10
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spacedrep-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: spacedrep
+Version: 0.1.0
+Summary: Agent-first flashcard CLI with FSRS scheduling and .apkg support
+Project-URL: Homepage, https://github.com/wpwilson10/spacedrep
+Project-URL: Repository, https://github.com/wpwilson10/spacedrep
+Project-URL: Issues, https://github.com/wpwilson10/spacedrep/issues
+Author-email: wpwilson10 <wpwilson10@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anki,cli,flashcards,fsrs,mcp,spaced-repetition
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: fsrs<7,>=6.3
+Requires-Dist: genanki>=0.13
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.15
+Provides-Extra: dev
+Requires-Dist: mcp>=1.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: optimizer
+Requires-Dist: fsrs[optimizer]; extra == 'optimizer'
+Description-Content-Type: text/markdown
+
+# spacedrep
+
+[![PyPI](https://img.shields.io/pypi/v/spacedrep)](https://pypi.org/project/spacedrep/)
+[![Python](https://img.shields.io/pypi/pyversions/spacedrep)](https://pypi.org/project/spacedrep/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Agent-first flashcard CLI with FSRS scheduling and .apkg support.
+
+A standalone spaced repetition tool that AI coding agents can drive — no Anki desktop required. Import/export .apkg files, schedule reviews with FSRS, manage cards via JSON-native CLI or MCP server.
+
+## Install
+
+```bash
+pip install spacedrep
+
+# With MCP server support
+pip install spacedrep[mcp]
+
+# With FSRS optimizer (requires torch)
+pip install spacedrep[optimizer]
+```
+
+## Quick Start
+
+```bash
+# Initialize database
+spacedrep db init
+
+# Add a card
+spacedrep card add "What is CAP theorem?" "Pick 2 of 3: consistency, availability, partition tolerance" --deck AWS
+
+# Bulk add from JSON
+echo '[{"question":"Q1","answer":"A1","deck":"AWS"}]' | spacedrep card add-bulk
+
+# Study: get next due card, preview outcomes, submit rating
+spacedrep card next
+spacedrep review preview 1
+spacedrep review submit 1 good
+
+# Check what's due
+spacedrep stats due
+
+# Import/export Anki decks
+spacedrep deck import ~/Downloads/deck.apkg
+spacedrep deck export ./export.apkg --deck AWS
+
+# Pipe card IDs for scripting
+spacedrep card list -q | xargs -I{} spacedrep card get {}
+
+# Preview destructive operations
+spacedrep card delete 42 --dry-run
+```
+
+Run `spacedrep --help` for all commands and options.
+
+## Agent-First Design
+
+- **JSON to stdout, errors to stderr** — stdout is the API contract
+- **Meaningful exit codes** — 0=success, 2=usage error, 3=not found
+- **Idempotent** — imports dedup, adds are safe to retry
+- **Non-interactive** — no prompts, no confirmation dialogs
+- **`--quiet` mode** — bare values for piping into `xargs` or `while read`
+- **`--dry-run`** — preview destructive operations without side effects
+
+## How It Works
+
+- **FSRS scheduling** — the same algorithm built into Anki since v23.10, via [py-fsrs](https://github.com/open-spaced-repetition/py-fsrs)
+- **Leech detection** — cards rated "again" 8+ times while in Review/Relearning are auto-suspended
+- **Review preview** — see what each rating would produce before committing
+- **Parameter optimization** — personalize FSRS from your review history (`pip install spacedrep[optimizer]`)
+- **SQLite storage** — single file, SQL-queryable review history
+- **.apkg compatible** — import from and export to Anki
+
+## MCP Server
+
+An MCP server exposes all 20 spacedrep operations as tools for AI agents (Claude Code, Claude Desktop, etc.) over the MCP protocol.
+
+```bash
+pip install spacedrep[mcp]
+```
+
+**Claude Code:**
+```bash
+claude mcp add spacedrep -e SPACEDREP_DB=/path/to/reviews.db -- uv run --directory /path/to/spacedrep spacedrep-mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "spacedrep": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/spacedrep", "spacedrep-mcp"],
+      "env": {
+        "SPACEDREP_DB": "/path/to/reviews.db"
+      }
+    }
+  }
+}
+```
+
+Set `SPACEDREP_DB` to configure the database path (default: `./reviews.db`).
+
+## Development
+
+```bash
+git clone https://github.com/wpwilson10/spacedrep.git && cd spacedrep
+uv venv && uv sync --all-extras
+pre-commit install
+
+uv run pytest              # Test
+uv run pyright .           # Type check
+uv run ruff check .        # Lint
+```
+
+## License
+
+MIT

spacedrep-0.1.0/README.md

@@ -0,0 +1,118 @@
+# spacedrep
+
+[![PyPI](https://img.shields.io/pypi/v/spacedrep)](https://pypi.org/project/spacedrep/)
+[![Python](https://img.shields.io/pypi/pyversions/spacedrep)](https://pypi.org/project/spacedrep/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Agent-first flashcard CLI with FSRS scheduling and .apkg support.
+
+A standalone spaced repetition tool that AI coding agents can drive — no Anki desktop required. Import/export .apkg files, schedule reviews with FSRS, manage cards via JSON-native CLI or MCP server.
+
+## Install
+
+```bash
+pip install spacedrep
+
+# With MCP server support
+pip install spacedrep[mcp]
+
+# With FSRS optimizer (requires torch)
+pip install spacedrep[optimizer]
+```
+
+## Quick Start
+
+```bash
+# Initialize database
+spacedrep db init
+
+# Add a card
+spacedrep card add "What is CAP theorem?" "Pick 2 of 3: consistency, availability, partition tolerance" --deck AWS
+
+# Bulk add from JSON
+echo '[{"question":"Q1","answer":"A1","deck":"AWS"}]' | spacedrep card add-bulk
+
+# Study: get next due card, preview outcomes, submit rating
+spacedrep card next
+spacedrep review preview 1
+spacedrep review submit 1 good
+
+# Check what's due
+spacedrep stats due
+
+# Import/export Anki decks
+spacedrep deck import ~/Downloads/deck.apkg
+spacedrep deck export ./export.apkg --deck AWS
+
+# Pipe card IDs for scripting
+spacedrep card list -q | xargs -I{} spacedrep card get {}
+
+# Preview destructive operations
+spacedrep card delete 42 --dry-run
+```
+
+Run `spacedrep --help` for all commands and options.
+
+## Agent-First Design
+
+- **JSON to stdout, errors to stderr** — stdout is the API contract
+- **Meaningful exit codes** — 0=success, 2=usage error, 3=not found
+- **Idempotent** — imports dedup, adds are safe to retry
+- **Non-interactive** — no prompts, no confirmation dialogs
+- **`--quiet` mode** — bare values for piping into `xargs` or `while read`
+- **`--dry-run`** — preview destructive operations without side effects
+
+## How It Works
+
+- **FSRS scheduling** — the same algorithm built into Anki since v23.10, via [py-fsrs](https://github.com/open-spaced-repetition/py-fsrs)
+- **Leech detection** — cards rated "again" 8+ times while in Review/Relearning are auto-suspended
+- **Review preview** — see what each rating would produce before committing
+- **Parameter optimization** — personalize FSRS from your review history (`pip install spacedrep[optimizer]`)
+- **SQLite storage** — single file, SQL-queryable review history
+- **.apkg compatible** — import from and export to Anki
+
+## MCP Server
+
+An MCP server exposes all 20 spacedrep operations as tools for AI agents (Claude Code, Claude Desktop, etc.) over the MCP protocol.
+
+```bash
+pip install spacedrep[mcp]
+```
+
+**Claude Code:**
+```bash
+claude mcp add spacedrep -e SPACEDREP_DB=/path/to/reviews.db -- uv run --directory /path/to/spacedrep spacedrep-mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "spacedrep": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/spacedrep", "spacedrep-mcp"],
+      "env": {
+        "SPACEDREP_DB": "/path/to/reviews.db"
+      }
+    }
+  }
+}
+```
+
+Set `SPACEDREP_DB` to configure the database path (default: `./reviews.db`).
+
+## Development
+
+```bash
+git clone https://github.com/wpwilson10/spacedrep.git && cd spacedrep
+uv venv && uv sync --all-extras
+pre-commit install
+
+uv run pytest              # Test
+uv run pyright .           # Type check
+uv run ruff check .        # Lint
+```
+
+## License
+
+MIT

spacedrep-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "spacedrep"
+version = "0.1.0"
+requires-python = ">=3.12"
+description = "Agent-first flashcard CLI with FSRS scheduling and .apkg support"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "wpwilson10", email = "wpwilson10@gmail.com" }]
+keywords = ["flashcards", "spaced-repetition", "fsrs", "anki", "mcp", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Education",
+]
+dependencies = [
+    "typer>=0.15",
+    "fsrs>=6.3,<7",
+    "genanki>=0.13",
+    "pydantic>=2.0",
+    "beautifulsoup4>=4.12",
+]
+
+[project.scripts]
+spacedrep = "spacedrep.cli:app"
+spacedrep-mcp = "spacedrep.mcp_server:main"
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0"]
+optimizer = ["fsrs[optimizer]"]
+dev = ["pytest>=8.0", "pyright>=1.1", "ruff>=0.11", "pre-commit>=4.0", "mcp>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/wpwilson10/spacedrep"
+Repository = "https://github.com/wpwilson10/spacedrep"
+Issues = "https://github.com/wpwilson10/spacedrep/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+
+[[tool.pyright.executionEnvironments]]
+root = "tests/test_mcp_server.py"
+reportUnknownVariableType = false
+reportUnknownMemberType = false
+reportAttributeAccessIssue = false
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM", "TCH"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/spacedrep/commands/*.py" = ["B008"]
+"src/spacedrep/cli.py" = ["E402"]

spacedrep-0.1.0/src/spacedrep/__init__.py

@@ -0,0 +1 @@
+"""Agent-first flashcard CLI with FSRS scheduling and .apkg support."""

spacedrep-0.1.0/src/spacedrep/apkg_reader.py

@@ -0,0 +1,195 @@
+"""Parse .apkg files (ZIP'd SQLite) into card records."""
+
+import json
+import sqlite3
+import tempfile
+import zipfile
+from pathlib import Path
+
+from bs4 import BeautifulSoup
+
+from spacedrep.models import CardRecord, DeckRecord
+
+QUESTION_FIELD_NAMES = {"front", "question", "prompt", "q"}
+ANSWER_FIELD_NAMES = {"back", "answer", "implementation", "a", "response"}
+
+
+def read_apkg(
+    apkg_path: Path,
+    question_field: str | None = None,
+    answer_field: str | None = None,
+) -> tuple[list[DeckRecord], list[CardRecord], dict[str, list[str] | str], dict[int, str]]:
+    """Read an .apkg file and return (decks, cards, field_info, note_deck_map).
+
+    field_info contains: fields (list of field names), question_field, answer_field.
+    note_deck_map maps source_note_id to deck name.
+    """
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmppath = Path(tmpdir)
+        with zipfile.ZipFile(apkg_path, "r") as zf:
+            for member in zf.namelist():
+                if member.startswith("/") or ".." in member:
+                    msg = f"Refusing to extract potentially unsafe path: {member}"
+                    raise ValueError(msg)
+            zf.extractall(tmppath)
+
+        # Find the SQLite database
+        db_file = tmppath / "collection.anki21"
+        if not db_file.exists():
+            db_file = tmppath / "collection.anki2"
+        if not db_file.exists():
+            msg = f"No collection database found in {apkg_path}"
+            raise ValueError(msg)
+
+        conn = sqlite3.connect(str(db_file))
+        conn.row_factory = sqlite3.Row
+
+        try:
+            # Parse models and decks from col table
+            col_row = conn.execute("SELECT models, decks FROM col").fetchone()
+            models_json = json.loads(col_row["models"])
+            decks_json = json.loads(col_row["decks"])
+
+            # Build model field mapping: {model_id: [field_names]}
+            model_fields: dict[str, list[str]] = {}
+            for mid, model in models_json.items():
+                model_fields[mid] = [f["name"] for f in model["flds"]]
+
+            # Build deck name mapping: {deck_id: deck_name}
+            deck_names: dict[str, str] = {}
+            for did, deck_data in decks_json.items():
+                deck_names[did] = deck_data["name"]
+
+            # Get card-to-deck mapping
+            card_deck_map: dict[int, str] = {}
+            for row in conn.execute("SELECT nid, did FROM cards").fetchall():
+                card_deck_map[row["nid"]] = str(row["did"])
+
+            # Process notes
+            notes = conn.execute("SELECT id, mid, flds, guid, tags FROM notes").fetchall()
+
+            all_field_names: list[str] = []
+            q_field = ""
+            a_field = ""
+            decks: list[DeckRecord] = []
+            cards: list[CardRecord] = []
+            note_deck_map: dict[int, str] = {}
+            seen_decks: set[str] = set()
+
+            for note in notes:
+                mid = str(note["mid"])
+                fields = note["flds"].split("\x1f")
+                field_names = model_fields.get(mid, [])
+
+                if not all_field_names and field_names:
+                    all_field_names = field_names
+                    qi, ai = detect_field_mapping(field_names, question_field, answer_field)
+                    q_field = field_names[qi]
+                    a_field = field_names[ai]
+
+                qi, ai = detect_field_mapping(field_names, question_field, answer_field)
+
+                question = strip_html(fields[qi]) if qi < len(fields) else ""
+                answer_text = strip_html(fields[ai]) if ai < len(fields) else ""
+
+                # Build extra_fields from remaining fields
+                extra: dict[str, str] = {}
+                for i, fname in enumerate(field_names):
+                    if i != qi and i != ai and i < len(fields):
+                        stripped = strip_html(fields[i])
+                        if stripped:
+                            extra[fname] = stripped
+
+                # Find deck for this note
+                did_str = card_deck_map.get(note["id"], "1")
+                deck_name = deck_names.get(did_str, "Default")
+
+                if deck_name not in seen_decks:
+                    seen_decks.add(deck_name)
+                    decks.append(
+                        DeckRecord(
+                            name=deck_name,
+                            source_id=int(did_str) if did_str.isdigit() else None,
+                        )
+                    )
+
+                note_deck_map[note["id"]] = deck_name
+                raw_tags = note["tags"].strip() if note["tags"] else ""
+                tags = ",".join(raw_tags.split()) if raw_tags else ""
+
+                cards.append(
+                    CardRecord(
+                        deck_id=0,  # will be set during import
+                        question=question,
+                        answer=answer_text,
+                        extra_fields=extra,
+                        tags=tags,
+                        source="apkg",
+                        source_note_id=note["id"],
+                        source_note_guid=note["guid"],
+                    )
+                )
+
+            field_info: dict[str, list[str] | str] = {
+                "fields": all_field_names,
+                "question_field": q_field,
+                "answer_field": a_field,
+            }
+            return decks, cards, field_info, note_deck_map
+
+        finally:
+            conn.close()
+
+
+def detect_field_mapping(
+    field_names: list[str],
+    question_field: str | None,
+    answer_field: str | None,
+) -> tuple[int, int]:
+    """Returns (question_index, answer_index).
+
+    Priority: explicit params > name matching > positional (0, 1).
+    """
+    names_lower = [n.lower() for n in field_names]
+
+    # Question field
+    if question_field:
+        try:
+            qi = names_lower.index(question_field.lower())
+        except ValueError:
+            msg = f"Question field '{question_field}' not found. Available: {field_names}"
+            raise ValueError(msg) from None
+    else:
+        qi = find_field_index(names_lower, QUESTION_FIELD_NAMES)
+        if qi is None:
+            qi = 0
+
+    # Answer field
+    if answer_field:
+        try:
+            ai = names_lower.index(answer_field.lower())
+        except ValueError:
+            msg = f"Answer field '{answer_field}' not found. Available: {field_names}"
+            raise ValueError(msg) from None
+    else:
+        ai = find_field_index(names_lower, ANSWER_FIELD_NAMES)
+        if ai is None:
+            ai = 1 if len(field_names) > 1 else 0
+
+    return qi, ai
+
+
+def find_field_index(names_lower: list[str], candidates: set[str]) -> int | None:
+    """Find the first field name that matches a candidate set."""
+    for i, name in enumerate(names_lower):
+        if name in candidates:
+            return i
+    return None
+
+
+def strip_html(html: str) -> str:
+    """Strip HTML tags, returning plain text."""
+    if not html or "<" not in html:
+        return html.strip()
+    soup = BeautifulSoup(html, "html.parser")
+    return soup.get_text(separator=" ", strip=True)