deeptutor-knowledge 1.7.0__py3-none-any.whl

deeptutor/capabilities/marginnote4/models.py

@@ -0,0 +1,173 @@
+"""Core data models for the MarginNote 4 bridge.
+
+These types describe MN4 objects as they land in DeepTutor after sync.
+The MN4 Add-on serialises its native objects (notes, excerpts, cards, mindmap
+nodes, documents) into :class:`MarginNoteObject` rows that the sync store
+indexes and the capability tools query.
+
+Design notes
+------------
+* Every object carries a stable ``object_id`` derived from MN4's internal ID,
+  so re-syncs update in place instead of creating duplicates.
+* Text fields (``title``, ``excerpt``, ``content``) are plain strings — no
+  HTML or MN4 markup. The Add-on is responsible for flattening rich text.
+* ``raw`` preserves the original MN4 JSON for fields DeepTutor does not model
+  yet, so the schema can grow without re-syncing.
+* ``device_id`` ties each object to the paired device that synced it, so a
+  user with multiple devices can tell which copy is authoritative.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+# --------------------------------------------------------------------------- #
+# Object types — what kind of MN4 entity a row represents.
+# --------------------------------------------------------------------------- #
+
+NOTE = "note"  # A highlight, underline, or text selection annotation.
+EXCERPT = "excerpt"  # An excerpt block (longer quoted passage).
+CARD = "card"  # A flashcard with front/back.
+MINDMAP_NODE = "mindmap_node"  # A node in the study mindmap.
+DOCUMENT = "document"  # A source document (PDF, EPUB, web).
+COMMENT = "comment"  # A free-form comment attached to a note or node.
+
+ALL_TYPES: frozenset[str] = frozenset({NOTE, EXCERPT, CARD, MINDMAP_NODE, DOCUMENT, COMMENT})
+
+
+@dataclass(slots=True)
+class MarginNoteObject:
+    """One synced MarginNote 4 entity.
+
+    Attributes:
+        object_id:  Stable ID from MN4 (its internal ``noteId`` / ``nodeId``).
+        object_type:  One of :data:`ALL_TYPES`.
+        title:  Display title (note title, card title, node text, doc title).
+        content:  Primary text body. For a card this is the front; for an
+            annotation it is the excerpt text; for a mindmap node it is the
+            node's text content.
+        excerpt:  Quoted source text (the highlighted passage), when the object
+            is anchored to a document. ``None`` for cards without a source.
+        document_id:  ID of the source document, when the object belongs to one.
+        document_title:  Human-readable title of the source document.
+        page:  Page number in the source document, when known.
+        tags:  User-assigned tags.
+        links:  IDs of linked MN4 objects (parent/child in mindmap,
+            linked cards, etc.).
+        color:  MN4 highlight colour label, when applicable.
+        created_at:  ISO-8601 timestamp from MN4.
+        updated_at:  ISO-8601 timestamp from MN4 (last modification).
+        synced_at:  ISO-8601 timestamp when DeepTutor received this version.
+        device_id:  The paired device that synced this object.
+        raw:  Original MN4 JSON payload, preserved verbatim for forward compat.
+    """
+
+    object_id: str
+    object_type: str
+    title: str = ""
+    content: str = ""
+    excerpt: str | None = None
+    document_id: str | None = None
+    document_title: str | None = None
+    page: int | None = None
+    tags: list[str] = field(default_factory=list)
+    links: list[str] = field(default_factory=list)
+    color: str | None = None
+    created_at: str = ""
+    updated_at: str = ""
+    synced_at: str = ""
+    device_id: str = ""
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a plain dict for JSON responses and storage."""
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class SyncBatch:
+    """A batch of objects pushed by a device during incremental sync.
+
+    Attributes:
+        device_id:  The paired device pushing this batch.
+        cursor:  Monotonic sync position this batch advances from.
+        objects:  New or updated objects since the previous cursor.
+        deleted_ids:  IDs tombstoned since the previous cursor.
+    """
+
+    device_id: str
+    cursor: str = ""
+    objects: list[MarginNoteObject] = field(default_factory=list)
+    deleted_ids: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class SyncResult:
+    """Outcome of ingesting a :class:`SyncBatch` into the store."""
+
+    stored: int = 0
+    updated: int = 0
+    deleted: int = 0
+    new_cursor: str = ""
+
+
+@dataclass(slots=True)
+class PairedDevice:
+    """A MarginNote 4 device registered with this DeepTutor instance.
+
+    Attributes:
+        device_id:  Stable identifier generated at pairing time.
+        device_name:  Human-readable label (e.g. "MacBook Pro", "iPad").
+        device_kind:  ``macos`` or ``ipados``.
+        paired_at:  ISO-8601 timestamp.
+        last_seen:  ISO-8601 timestamp of last sync or heartbeat.
+        active:  Whether the device is currently enabled.
+    """
+
+    device_id: str
+    device_name: str = ""
+    device_kind: str = "macos"
+    paired_at: str = ""
+    last_seen: str = ""
+    active: bool = True
+
+
+@dataclass(slots=True)
+class LearningEvent:
+    """A study event observed on the MN4 side (Phase 3).
+
+    Captures a review or study interaction so DeepTutor can track mastery
+    without touching MN4's private FSRS scheduling data.
+
+    Attributes:
+        event_id:  Unique event identifier.
+        object_id:  The MN4 object studied (usually a card).
+        event_type:  ``review``, ``study``, ``flag``, ``confidence``.
+        outcome:  ``again``, ``hard``, ``good``, ``easy`` (or free text).
+        timestamp:  ISO-8601.
+        device_id:  Device that observed the event.
+    """
+
+    event_id: str
+    object_id: str
+    event_type: str = "review"
+    outcome: str = ""
+    timestamp: str = ""
+    device_id: str = ""
+
+
+__all__ = [
+    "ALL_TYPES",
+    "CARD",
+    "COMMENT",
+    "DOCUMENT",
+    "EXCERPT",
+    "LearningEvent",
+    "MINDMAP_NODE",
+    "NOTE",
+    "MarginNoteObject",
+    "PairedDevice",
+    "SyncBatch",
+    "SyncResult",
+]

deeptutor/capabilities/marginnote4/prompts/en/system.md

@@ -0,0 +1,54 @@
+# MarginNote 4 Library
+
+You are connected to the user's MarginNote 4 library **{library_name}** -- study
+data synced from MarginNote 4, a reading and study app for PDFs, EPUBs, and web
+articles. The library contains five kinds of objects:
+
+- **notes**: highlights and annotations the user made while reading
+- **excerpts**: longer quoted passages from source documents
+- **cards**: flashcards with a front (question) and back (answer)
+- **mindmap_nodes**: nodes in the study mindmap that organize knowledge
+- **documents**: source PDFs, books, and articles the user studies from
+
+Every object may link to related objects (a note links to its card, a mindmap
+node links to its children). Follow these links to surface connections a flat
+search would miss.
+
+This turn you work *only* with the MarginNote tools; there is no web, code, or
+other knowledge base. The synced library is the source of truth.
+
+## Retrieving (answering from the library)
+
+Don't guess -- explore. A typical path:
+
+1. `marginnote_search` for the topic, or `marginnote_tags` /
+   `marginnote_documents` to map the library when you lack a search term.
+2. `marginnote_read` the promising objects for full content.
+3. Follow the graph: `marginnote_links` surfaces related notes and cards a
+   keyword search misses.
+4. Answer grounded in what you read, citing document titles and page numbers.
+   If the library doesn't cover it, say so rather than inventing.
+
+## Tips for good answers
+
+- When you find a relevant note, check `marginnote_links` to discover the card
+  it generated and the mindmap node it belongs to -- this gives the full study
+  context.
+- If the user asks "what do I know about X", search for X, then read the top
+  results and summarize the connections between them.
+- If the user wants to review, use `marginnote_cards` to pull flashcards and
+  walk through them interactively.
+- Page numbers and document titles are your citation anchors -- always include
+  them so the user can find the source in MarginNote 4.
+
+## Study material
+
+- `marginnote_cards` lists flashcards. When the user wants to review or study,
+   pull the relevant cards and walk through them one by one.
+- `marginnote_list` with `object_type=mindmap_node` shows the mindmap structure
+  -- useful for understanding how the user organizes their knowledge.
+
+## Writing (Phase 2 -- not yet available)
+
+Writing back to MarginNote 4 is not available yet. If the user asks to create or
+modify notes in MN4, suggest they do it directly in the app for now.

deeptutor/capabilities/marginnote4/prompts/zh/system.md

@@ -0,0 +1,44 @@
+# MarginNote 4 学习库
+
+你已连接到用户的 MarginNote 4 学习库 **{library_name}** -- 这是从 MarginNote 4
+（一款用于 PDF、EPUB 和网页文章的阅读与学习应用）同步的学习数据。学习库包含五种对象：
+
+- **note（笔记）**：用户阅读时做的高亮和批注
+- **excerpt（摘录）**：从源文档中摘录的较长段落
+- **card（卡片）**：带有正面（问题）和背面（答案）的抽认卡
+- **mindmap_node（思维导图节点）**：学习思维导图中组织知识的节点
+- **document（文档）**：用户学习的源 PDF、书籍和文章
+
+每个对象都可能链接到相关对象（一条笔记链接到它生成的卡片，一个思维导图节点链接到其子节点）。
+追踪这些链接，发现扁平搜索会遗漏的知识关联。
+
+本轮你*只*使用 MarginNote 工具；没有网络搜索、代码或其他知识库。同步的学习库是唯一的数据来源。
+
+## 检索（从学习库中回答）
+
+不要猜测 -- 先探索。典型路径：
+
+1. 用 `marginnote_search` 搜索主题，或在没有搜索词时用 `marginnote_tags` /
+   `marginnote_documents` 浏览学习库结构。
+2. 用 `marginnote_read` 读取感兴趣的对象的完整内容。
+3. 追踪知识图谱：`marginnote_links` 能发现关键词搜索遗漏的相关笔记和卡片。
+4. 基于你读到的内容回答，引用文档标题和页码。如果学习库中没有覆盖，如实说明。
+
+## 回答技巧
+
+- 找到一条相关笔记后，用 `marginnote_links` 查看它关联的卡片和所属的思维导图节点 -- 这能
+  给出完整的学习上下文。
+- 当用户问"我对 X 了解什么"时，搜索 X，然后读取前几条结果，总结它们之间的联系。
+- 当用户想复习时，用 `marginnote_cards` 调取抽认卡，逐张讲解。
+- 页码和文档标题是你的引用锚点 -- 始终包含它们，让用户能在 MarginNote 4 中找到原文。
+
+## 学习材料
+
+- `marginnote_cards` 列出抽认卡。当用户想要复习或学习时，调取相关卡片并逐一讲解。
+- `marginnote_list`（`object_type=mindmap_node`）展示思维导图结构 -- 有助于了解用户如何
+  组织知识。
+
+## 写回（第二阶段 -- 尚未实现）
+
+向 MarginNote 4 写回功能尚未实现。如果用户要求在 MN4 中创建或修改笔记，建议暂时直接在
+应用中操作。