gemmate-srs 0.1.0__tar.gz

gemmate_srs-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+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.

gemmate_srs-0.1.0/README.md

@@ -0,0 +1,55 @@
+# 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.

gemmate_srs-0.1.0/gemmate_srs/__init__.py

@@ -0,0 +1 @@
+"""GemMate SRS engine package."""

gemmate_srs-0.1.0/gemmate_srs/engines/__init__.py

@@ -0,0 +1,13 @@
+"""Engines package for GemMate SRS."""
+
+from .cards import generate_cards
+from .mindmap import build_mindmap
+from .quiz import generate_quiz
+from .solver import solve_steps
+
+__all__ = [
+    "generate_cards",
+    "generate_quiz",
+    "build_mindmap",
+    "solve_steps",
+]

gemmate_srs-0.1.0/gemmate_srs/engines/cards.py

@@ -0,0 +1,173 @@
+import sys
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from ..json_repair import robust_json_parse
+from ..models import Card, Deck, SM2State
+from ..sampling import sample
+from ..store import APSStore
+
+SCHEMA_CARDS = {
+    "type": "object",
+    "properties": {
+        "cards": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "front": {"type": "string"},
+                    "back": {"type": "string"},
+                },
+                "required": ["front", "back"],
+                "additionalProperties": False,
+            },
+        }
+    },
+    "required": ["cards"],
+    "additionalProperties": False,
+}
+
+
+def generate_cards(
+    topic: str,
+    count: int = 5,
+    deck_id: str | None = None,
+    invoke_id: str = "",
+    store: APSStore | None = None,
+) -> dict[str, Any]:
+    topic = (topic or "").strip()
+    if not topic:
+        raise ValueError("topic must not be empty")
+
+    count = max(1, min(int(count), 30))
+
+    prompt = (
+        f"Create exactly {count} high-quality flashcards for learning the following topic:\n"
+        f"{topic}\n\n"
+        "Requirements:\n"
+        "1. Each card must test one specific concept, definition, formula, or key fact.\n"
+        "2. 'front' is the prompt or question (concise and clear).\n"
+        "3. 'back' is the answer or explanation (accurate and educational).\n"
+        "4. Return ONLY a JSON object with a 'cards' array of {front, back} objects."
+    )
+
+    system_prompt = (
+        "You are an expert tutor creating spaced-repetition flashcards. "
+        "Context is isolated; rely solely on the provided prompt."
+    )
+
+    raw_resp = sample(
+        invoke_id=invoke_id,
+        prompt=prompt,
+        system=system_prompt,
+        max_tokens=2048,
+        temperature=0.3,
+        schema=SCHEMA_CARDS,
+        schema_name="flashcards_output",
+    )
+
+    parsed = robust_json_parse(raw_resp)
+
+    # Normalize parsed data into a list of raw card objects
+    raw_list: list[dict[str, Any]] = []
+    if isinstance(parsed, list):
+        for item in parsed:
+            if isinstance(item, dict):
+                if "cards" in item and isinstance(item["cards"], list):
+                    for sub in item["cards"]:
+                        if isinstance(sub, dict):
+                            raw_list.append(sub)
+                else:
+                    raw_list.append(item)
+    elif isinstance(parsed, dict):
+        if "cards" in parsed and isinstance(parsed["cards"], list):
+            for item in parsed["cards"]:
+                if isinstance(item, dict):
+                    raw_list.append(item)
+        elif "front" in parsed or "question" in parsed:
+            raw_list.append(parsed)
+
+    validated_cards: list[dict[str, str]] = []
+    seen_fronts: set[str] = set()
+    for item in raw_list:
+        front = str(
+            item.get("front") or item.get("question") or item.get("q") or ""
+        ).strip()
+        back = str(
+            item.get("back") or item.get("answer") or item.get("a") or ""
+        ).strip()
+        # A card missing either side carries no study value; emitting one would
+        # be exactly the placeholder output the platform review rejects.
+        if not front or not back:
+            continue
+        key = front.casefold()
+        if key in seen_fronts:
+            continue
+        seen_fronts.add(key)
+        validated_cards.append({
+            "front": front[:4000],
+            "back": back[:4000],
+        })
+
+    if not validated_cards:
+        raise ValueError("Failed to extract any valid flashcards from model response")
+
+    target_deck_id = (deck_id or "").strip()
+    persisted = False
+    persist_error: str | None = None
+
+    # An explicitly requested deck must exist. Failing loudly here is the whole
+    # point: the previous revision called store.deck_get/deck_create/card_add,
+    # none of which exist, and swallowed the AttributeError -- so every call
+    # reported a deck_id while writing nothing at all.
+    if store is not None and target_deck_id and store.get_deck(target_deck_id) is None:
+        raise ValueError(f"Deck not found: {target_deck_id}")
+
+    if store is not None:
+        try:
+            now = datetime.now(timezone.utc)
+            if not target_deck_id:
+                deck = Deck(
+                    id=f"deck-{uuid.uuid4().hex[:12]}",
+                    name=f"Topic: {topic[:30]}",
+                    created_at=now,
+                )
+                store.save_deck(deck)
+                target_deck_id = deck.id
+
+            for item in validated_cards:
+                store.save_card(
+                    Card(
+                        id=f"card-{uuid.uuid4().hex[:12]}",
+                        deck_id=target_deck_id,
+                        front=item["front"],
+                        back=item["back"],
+                        srs=SM2State(
+                            repetitions=0,
+                            ease_factor=2.5,
+                            interval=0,
+                            next_review=now,
+                        ),
+                        created_at=now,
+                        graded_count=0,
+                    )
+                )
+            persisted = True
+        except Exception as e:
+            # The cards are already generated and the tokens already spent, so
+            # they stay in the response. What must never happen is reporting a
+            # successful save when nothing was written -- surface it instead.
+            persist_error = f"{type(e).__name__}: {e}"
+            print(
+                f"[cards] persistence failed for deck={target_deck_id!r}: {persist_error}",
+                file=sys.stderr,
+            )
+
+    return {
+        "generated": len(validated_cards),
+        "cards": validated_cards,
+        "deck_id": target_deck_id if persisted else "",
+        "persisted": persisted,
+        "persist_error": persist_error,
+    }

gemmate_srs-0.1.0/gemmate_srs/engines/mindmap.py

@@ -0,0 +1,140 @@
+from typing import Any
+
+from ..json_repair import robust_json_parse
+from ..models import Mindmap, MindmapNode
+from ..sampling import sample
+
+LABEL_MAX = 120
+
+SCHEMA_MINDMAP = {
+    "type": "object",
+    "properties": {
+        "topic": {"type": "string"},
+        "children": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "label": {"type": "string"},
+                    "children": {
+                        "type": "array",
+                    },
+                },
+                "required": ["label"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    "required": ["topic", "children"],
+    "additionalProperties": False,
+}
+
+
+def _clean_node(data: Any, current_depth: int, max_depth: int) -> MindmapNode | None:
+    if not isinstance(data, dict):
+        if isinstance(data, str) and data.strip():
+            return MindmapNode(label=data.strip()[:LABEL_MAX], children=[])
+        return None
+
+    label = str(
+        data.get("label") or data.get("title") or data.get("topic") or data.get("name") or ""
+    ).strip()
+    if not label:
+        return None
+
+    children: list[MindmapNode] = []
+    if current_depth < max_depth:
+        raw_children = data.get("children") or data.get("subtopics") or []
+        if isinstance(raw_children, list):
+            for child_item in raw_children:
+                child_node = _clean_node(child_item, current_depth + 1, max_depth)
+                if child_node:
+                    children.append(child_node)
+
+    return MindmapNode(label=label[:LABEL_MAX], children=children)
+
+
+def build_mindmap(
+    source_text: str,
+    max_depth: int = 3,
+    invoke_id: str = "",
+) -> dict[str, Any]:
+    source_text = (source_text or "").strip()
+    if not source_text:
+        raise ValueError("source_text must not be empty")
+
+    depth_limit = max(1, min(int(max_depth), 5))
+
+    prompt = (
+        f"Extract a hierarchical concept mindmap from the following text.\n"
+        f"Max depth level: {depth_limit}.\n\n"
+        f"Source Text:\n{source_text}\n\n"
+        "Requirements:\n"
+        "1. Extract a clear central 'topic' (root concept).\n"
+        "2. Break down into logical branches under 'children', each having 'label' and sub-'children'.\n"
+        "3. Return ONLY a JSON object with 'topic' and 'children' matching the schema."
+    )
+
+    system_prompt = (
+        "You are an expert concept visualizer. "
+        "Context is isolated; all text is supplied directly in the prompt."
+    )
+
+    raw_resp = sample(
+        invoke_id=invoke_id,
+        prompt=prompt,
+        system=system_prompt,
+        max_tokens=2560,
+        temperature=0.3,
+        schema=SCHEMA_MINDMAP,
+        schema_name="mindmap_output",
+    )
+
+    parsed = robust_json_parse(raw_resp)
+
+    # Normalize parsed structure into topic and children
+    root_topic = ""
+    raw_children: list[Any] = []
+
+    root_dict: dict[str, Any] = {}
+    if isinstance(parsed, dict):
+        root_dict = parsed
+    elif isinstance(parsed, list):
+        if len(parsed) == 1 and isinstance(parsed[0], dict) and ("topic" in parsed[0] or "children" in parsed[0]):
+            root_dict = parsed[0]
+        else:
+            raw_children = parsed
+
+    if root_dict:
+        root_topic = str(
+            root_dict.get("topic") or root_dict.get("label") or root_dict.get("title") or ""
+        ).strip()
+        raw_children = root_dict.get("children") or root_dict.get("subtopics") or []
+        if not isinstance(raw_children, list):
+            raw_children = []
+
+    if not root_topic:
+        # Fall back to the user's own text rather than an invented "Mind Map"
+        # label -- the first real line is at least derived from the input.
+        for line in source_text.splitlines():
+            candidate = line.strip()
+            if candidate:
+                root_topic = candidate[:40]
+                break
+
+    if not root_topic:
+        raise ValueError("Could not determine a mindmap root topic from model response")
+
+    nodes: list[MindmapNode] = []
+    for item in raw_children:
+        node = _clean_node(item, current_depth=1, max_depth=depth_limit)
+        if node:
+            nodes.append(node)
+
+    if not nodes:
+        # A lone "Overview" node is a placeholder, not a mindmap. Fail instead
+        # of presenting an empty tree as a result.
+        raise ValueError("Failed to extract any mindmap branches from model response")
+
+    mindmap = Mindmap(topic=root_topic[:LABEL_MAX], children=nodes)
+    return mindmap.model_dump()

gemmate_srs-0.1.0/gemmate_srs/engines/quiz.py

@@ -0,0 +1,161 @@
+from typing import Any
+
+from ..json_repair import robust_json_parse
+from ..models import QuizQuestion
+from ..sampling import sample
+
+SCHEMA_QUIZ = {
+    "type": "object",
+    "properties": {
+        "questions": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "question": {"type": "string"},
+                    "options": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "minItems": 4,
+                        "maxItems": 4,
+                    },
+                    "correct_index": {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 3,
+                    },
+                    "explanation": {"type": "string"},
+                },
+                "required": ["question", "options", "correct_index", "explanation"],
+                "additionalProperties": False,
+            },
+        }
+    },
+    "required": ["questions"],
+    "additionalProperties": False,
+}
+
+
+def generate_quiz(
+    topic: str,
+    count: int = 5,
+    difficulty: str = "medium",
+    source_text: str | None = None,
+    invoke_id: str = "",
+) -> dict[str, Any]:
+    topic = (topic or "").strip()
+    if not topic:
+        raise ValueError("topic must not be empty")
+
+    count = max(1, min(int(count), 20))
+    difficulty = difficulty.strip().lower() if difficulty else "medium"
+    if difficulty not in ("easy", "medium", "hard"):
+        difficulty = "medium"
+
+    source_prompt = f"\n\nSource context / reference text:\n{source_text.strip()}" if source_text and source_text.strip() else ""
+
+    prompt = (
+        f"Generate exactly {count} multiple-choice quiz questions on the topic: '{topic}'.\n"
+        f"Difficulty: {difficulty}.{source_prompt}\n\n"
+        "Requirements:\n"
+        "1. Each question must have exactly 4 distinct, plausible options.\n"
+        "2. 'correct_index' must be 0, 1, 2, or 3 pointing to the single correct option.\n"
+        "3. 'explanation' must explain why the correct option is right and the others wrong.\n"
+        "4. Return ONLY a JSON object with a 'questions' array matching the schema."
+    )
+
+    system_prompt = (
+        "You are an expert assessment examiner. "
+        "Context is isolated; all reference information is supplied in the user prompt."
+    )
+
+    raw_resp = sample(
+        invoke_id=invoke_id,
+        prompt=prompt,
+        system=system_prompt,
+        max_tokens=2560,
+        temperature=0.3,
+        schema=SCHEMA_QUIZ,
+        schema_name="quiz_output",
+    )
+
+    parsed = robust_json_parse(raw_resp)
+
+    raw_questions: list[dict[str, Any]] = []
+    if isinstance(parsed, list):
+        for item in parsed:
+            if isinstance(item, dict):
+                if "questions" in item and isinstance(item["questions"], list):
+                    for sub in item["questions"]:
+                        if isinstance(sub, dict):
+                            raw_questions.append(sub)
+                else:
+                    raw_questions.append(item)
+    elif isinstance(parsed, dict):
+        if "questions" in parsed and isinstance(parsed["questions"], list):
+            for item in parsed["questions"]:
+                if isinstance(item, dict):
+                    raw_questions.append(item)
+        elif "question" in parsed:
+            raw_questions.append(parsed)
+
+    validated_questions: list[dict[str, Any]] = []
+    for item in raw_questions:
+        q_text = str(item.get("question") or "").strip()
+
+        raw_opts = item.get("options")
+        if not isinstance(raw_opts, list):
+            continue
+        opts: list[str] = []
+        seen_opts: set[str] = set()
+        for o in raw_opts:
+            text = str(o).strip()
+            key = text.casefold()
+            if not text or key in seen_opts:
+                continue
+            seen_opts.add(key)
+            opts.append(text)
+
+        # The schema demands exactly 4 distinct options. Padding the list with
+        # synthetic "Option C"/"Option D" text would be the static placeholder
+        # output the platform explicitly excludes from a qualified run, so a
+        # question we cannot assemble correctly is dropped rather than faked.
+        if not q_text or len(opts) < 4:
+            continue
+
+        raw_idx = item.get("correct_index")
+        if raw_idx is None:
+            raw_idx = item.get("correctIndex")
+        if raw_idx is None:
+            raw_idx = item.get("correct")
+        try:
+            correct_idx = int(raw_idx)  # type: ignore[arg-type]
+        except (ValueError, TypeError):
+            # Defaulting to 0 would silently declare the first option correct
+            # and teach the user a wrong answer -- strictly worse than dropping.
+            continue
+
+        if len(opts) > 4:
+            # Only trim when the answer index survives the cut.
+            if correct_idx >= 4:
+                continue
+            opts = opts[:4]
+
+        if not 0 <= correct_idx <= 3:
+            continue
+
+        explanation = str(item.get("explanation") or "").strip()
+
+        # Validate with Pydantic model
+        q_model = QuizQuestion(
+            question=q_text,
+            options=opts,
+            correct_index=correct_idx,
+            explanation=explanation,
+        )
+        validated_questions.append(q_model.model_dump())
+
+    if not validated_questions:
+        raise ValueError("Failed to extract valid quiz questions from model response")
+
+    return {"questions": validated_questions}