Metadata-Version: 2.4
Name: gemmate-srs
Version: 0.1.0
Summary: Spaced-repetition study engine for the GemMate Anna App: SM-2 scheduling, card decks, quiz generation, mind maps and step-by-step math solving.
Author: gemmate-dev
License: MIT
Project-URL: Homepage, https://anna.partners
Project-URL: Source, https://github.com/gemmate-dev/gemmate-anna-app
Keywords: spaced-repetition,supermemo,sm-2,flashcards,executa,anna
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.5.0
Provides-Extra: test
Requires-Dist: pytest>=7.4.0; extra == "test"

# gemmate-srs

The Executa (Anna plugin) behind the **GemMate** Anna App. A single long-running
process that speaks JSON-RPC 2.0 over stdio and exposes the study engine the
app's UI calls into.

## Tools

| Method | What it does |
|---|---|
| `deck.create` / `deck.list` / `deck.delete` | Deck management |
| `card.add` / `card.list` / `card.update` / `card.delete` | Card management |
| `study.session` | Open a review session for a deck (due cards first) |
| `study.grade` | Grade recall 0–5 and compute the next interval via SM-2 |
| `study.stats` | Deck-level counters |
| `cards.generate` | Generate flashcards for a topic, persist them to a deck |
| `quiz.generate` | Generate four-option multiple-choice questions |
| `mindmap.generate` | Extract a hierarchical concept tree from notes |
| `solve.steps` | Step-by-step derivation with a final answer and check |

Scheduling, deck and card state live in Anna Persistent Storage (APS), never in
the iframe, so progress survives window close, reload and device changes.

## SM-2 scheduling

Implements the standard SuperMemo-2 update:

- `quality >= 3` → first pass sets interval 1 day, second sets 6 days, then
  `interval = round(interval * EF)` with `round` matching Dart's
  `double.round()` (half away from zero) — not Python's banker's rounding.
- `quality < 3` → repetitions reset to 0, interval back to 1 day.
- `EF' = max(1.3, EF + (0.1 - (5 - q) * (0.08 + (5 - q) * 0.02)))`, applied on
  every grade including failures, which is what the original GemMate Dart
  implementation does and what existing review history expects.

## LLM use

The four generation tools call the host LLM through Anna sampling
(`sampling/createMessage`). They are additive: review, deck and card management
never touch the LLM, so a user who declines the sampling grant still gets a
fully working spaced-repetition app.

## Development

```bash
uv sync --extra test
uv run pytest -q
uv run gemmate-srs          # the plugin loop; reads JSON-RPC frames on stdin
```

## Distribution

Declared in `executa.json` as `distribution.type = "uv"`. The platform installs
it with `uv tool install gemmate-srs` and launches the `gemmate-srs` console
script.
