deeptutor-knowledge 1.7.0__py3-none-any.whl

deeptutor/capabilities/marginnote4/tools.py

@@ -0,0 +1,329 @@
+"""MarginNote 4 tools -- the seam between the chat loop and the synced store.
+
+Seven tools auto-mounted only when a MarginNote 4 library is the selected KB
+(via :class:`~deeptutor.capabilities.marginnote4.capability.MarginNoteCapability`,
+which runs the turn exclusively on these tools). Five read the synced data
+(search, read, list, links, tags) and two provide structural navigation
+(documents, mindmap). Every tool is a thin wrapper over the pure
+:class:`~deeptutor.capabilities.marginnote4.store.MarginNoteStore` methods.
+
+The store path is injected server-side as ``_db_path`` by the capability's
+``augment_kwargs``; the model never supplies or sees it.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from deeptutor.capabilities.marginnote4.models import ALL_TYPES
+from deeptutor.capabilities.marginnote4.store import MarginNoteStore
+from deeptutor.core.tool_protocol import BaseTool, ToolDefinition, ToolParameter, ToolResult
+
+MARGINNOTE_TOOL_NAMES: tuple[str, ...] = (
+    "marginnote_search",
+    "marginnote_read",
+    "marginnote_list",
+    "marginnote_documents",
+    "marginnote_links",
+    "marginnote_tags",
+    "marginnote_cards",
+)
+
+
+def _store(kwargs: dict[str, Any]) -> MarginNoteStore | None:
+    raw = str(kwargs.get("_db_path") or "").strip()
+    if not raw:
+        return None
+    root = Path(raw)
+    cached = _STORE_CACHE.get(raw)
+    if cached is not None:
+        return cached
+    if not root.parent.exists():
+        return None
+    store = MarginNoteStore(root)
+    _STORE_CACHE[raw] = store
+    return store
+
+
+_STORE_CACHE: dict[str, MarginNoteStore] = {}
+
+
+def _clear_store_cache() -> None:
+    """Drop cached stores (tests that swap db files under the same path)."""
+    _STORE_CACHE.clear()
+
+
+def _no_store_result() -> ToolResult:
+    return ToolResult(
+        content="No MarginNote 4 library is connected on this turn; "
+        "MarginNote tools are unavailable.",
+        success=False,
+    )
+
+
+def _ok(payload: Any) -> ToolResult:
+    return ToolResult(content=json.dumps(payload, ensure_ascii=False), success=True)
+
+
+def _err(message: str) -> ToolResult:
+    return ToolResult(content=message, success=False)
+
+
+def _as_int(value: Any, *, default: int, lo: int, hi: int) -> int:
+    try:
+        out = int(value)
+    except (TypeError, ValueError):
+        return default
+    return max(lo, min(hi, out))
+
+
+class _MN4Tool(BaseTool):
+    """Shared store resolution + uniform error handling for MN4 tools."""
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        store = _store(kwargs)
+        if store is None:
+            return _no_store_result()
+        try:
+            return await self._run(store, kwargs)
+        except Exception as exc:
+            return _err(str(exc))
+
+    async def _run(self, store: MarginNoteStore, kwargs: dict[str, Any]) -> ToolResult:
+        raise NotImplementedError
+
+
+class MarginNoteSearchTool(_MN4Tool):
+    """Full-text search across synced MN4 objects."""
+
+    def get_definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name="marginnote_search",
+            description=(
+                "Search the user's MarginNote 4 library for notes, excerpts, "
+                "cards, or mindmap nodes whose title or content contains the "
+                "query (case-insensitive). Returns matching objects with a "
+                "short snippet. Use this first to find where something lives."
+            ),
+            parameters=[
+                ToolParameter(
+                    name="query",
+                    type="string",
+                    description="Text to search for.",
+                ),
+                ToolParameter(
+                    name="object_type",
+                    type="string",
+                    description=(
+                        "Filter by type: note, excerpt, card, mindmap_node, document, comment."
+                    ),
+                    required=False,
+                    enum=sorted(ALL_TYPES),
+                ),
+                ToolParameter(
+                    name="limit",
+                    type="integer",
+                    description="Max results (default 20).",
+                    required=False,
+                ),
+            ],
+        )
+
+    async def _run(self, store: MarginNoteStore, kwargs: dict[str, Any]) -> ToolResult:
+        query = str(kwargs.get("query") or "").strip()
+        if not query:
+            return _err("marginnote_search needs a non-empty 'query'.")
+        obj_type = str(kwargs.get("object_type") or "").strip()
+        limit = _as_int(kwargs.get("limit"), default=20, lo=1, hi=100)
+        hits = store.search(query, object_type=obj_type, limit=limit)
+        return _ok({"query": query, "count": len(hits), "results": hits})
+
+
+class MarginNoteReadTool(_MN4Tool):
+    """Read a single MN4 object in full."""
+
+    def get_definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name="marginnote_read",
+            description=(
+                "Read a single MarginNote 4 object by its ID. Returns the full "
+                "object: title, content, excerpt, tags, links, source document, "
+                "and timestamps. Use after marginnote_search or "
+                "marginnote_list to drill into a specific item."
+            ),
+            parameters=[
+                ToolParameter(
+                    name="object_id",
+                    type="string",
+                    description="The MN4 object ID from a search or list result.",
+                ),
+            ],
+        )
+
+    async def _run(self, store: MarginNoteStore, kwargs: dict[str, Any]) -> ToolResult:
+        oid = str(kwargs.get("object_id") or "").strip()
+        if not oid:
+            return _err("marginnote_read needs an 'object_id'.")
+        obj = store.get(oid)
+        if obj is None:
+            return _err(f"Object {oid!r} not found in the MarginNote library.")
+        return _ok(obj.to_dict())
+
+
+class MarginNoteListTool(_MN4Tool):
+    """List objects, optionally filtered by type or source document."""
+
+    def get_definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name="marginnote_list",
+            description=(
+                "List MarginNote 4 objects, optionally filtered by type or "
+                "source document. Use to discover structure when you lack a "
+                "search term."
+            ),
+            parameters=[
+                ToolParameter(
+                    name="object_type",
+                    type="string",
+                    description="Filter: note, excerpt, card, mindmap_node.",
+                    required=False,
+                    enum=sorted(ALL_TYPES),
+                ),
+                ToolParameter(
+                    name="document_id",
+                    type="string",
+                    description="Restrict to one source document.",
+                    required=False,
+                ),
+                ToolParameter(
+                    name="limit",
+                    type="integer",
+                    description="Max results (default 200).",
+                    required=False,
+                ),
+            ],
+        )
+
+    async def _run(self, store: MarginNoteStore, kwargs: dict[str, Any]) -> ToolResult:
+        obj_type = str(kwargs.get("object_type") or "").strip()
+        doc_id = str(kwargs.get("document_id") or "").strip()
+        limit = _as_int(kwargs.get("limit"), default=200, lo=1, hi=1000)
+        items = store.list_objects(object_type=obj_type, document_id=doc_id, limit=limit)
+        return _ok({"count": len(items), "objects": items})
+
+
+class MarginNoteDocumentsTool(_MN4Tool):
+    """List source documents with their object counts."""
+
+    def get_definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name="marginnote_documents",
+            description=(
+                "List all source documents (PDFs, books) in the MarginNote "
+                "library with a count of annotations, cards, and nodes each "
+                "contains. Use to scope a search to one document."
+            ),
+            parameters=[],
+        )
+
+    async def _run(self, store: MarginNoteStore, kwargs: dict[str, Any]) -> ToolResult:
+        docs = store.list_documents()
+        return _ok({"count": len(docs), "documents": docs})
+
+
+class MarginNoteLinksTool(_MN4Tool):
+    """Find objects linked to or from a given object."""
+
+    def get_definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name="marginnote_links",
+            description=(
+                "Find MarginNote objects linked TO or FROM the given object. "
+                "Links include mindmap parent/child relationships and card "
+                "links. Pair with marginnote_read to traverse the knowledge "
+                "graph."
+            ),
+            parameters=[
+                ToolParameter(
+                    name="object_id",
+                    type="string",
+                    description="The MN4 object ID to find links for.",
+                ),
+            ],
+        )
+
+    async def _run(self, store: MarginNoteStore, kwargs: dict[str, Any]) -> ToolResult:
+        oid = str(kwargs.get("object_id") or "").strip()
+        if not oid:
+            return _err("marginnote_links needs an 'object_id'.")
+        links = store.linked_objects(oid)
+        return _ok({"object_id": oid, "count": len(links), "links": links})
+
+
+class MarginNoteTagsTool(_MN4Tool):
+    """List all tags ranked by frequency."""
+
+    def get_definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name="marginnote_tags",
+            description=(
+                "List all tags used across the MarginNote library, ranked by "
+                "how many objects use each. Use to map topics before drilling in."
+            ),
+            parameters=[
+                ToolParameter(
+                    name="limit",
+                    type="integer",
+                    description="Max tags (default 200).",
+                    required=False,
+                ),
+            ],
+        )
+
+    async def _run(self, store: MarginNoteStore, kwargs: dict[str, Any]) -> ToolResult:
+        limit = _as_int(kwargs.get("limit"), default=200, lo=1, hi=1000)
+        tags = store.collect_tags(limit=limit)
+        return _ok({"count": len(tags), "tags": tags})
+
+
+class MarginNoteCardsTool(_MN4Tool):
+    """List flashcards for review-scope queries."""
+
+    def get_definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name="marginnote_cards",
+            description=(
+                "List flashcards in the MarginNote library. Returns card "
+                "front/back content, tags, and source document. Use when the "
+                "user asks about their review material or wants to study."
+            ),
+            parameters=[
+                ToolParameter(
+                    name="limit",
+                    type="integer",
+                    description="Max cards (default 100).",
+                    required=False,
+                ),
+            ],
+        )
+
+    async def _run(self, store: MarginNoteStore, kwargs: dict[str, Any]) -> ToolResult:
+        limit = _as_int(kwargs.get("limit"), default=100, lo=1, hi=500)
+        cards = store.list_objects(object_type="card", limit=limit)
+        return _ok({"count": len(cards), "cards": cards})
+
+
+MARGINNOTE_TOOL_TYPES: tuple[type[BaseTool], ...] = (
+    MarginNoteSearchTool,
+    MarginNoteReadTool,
+    MarginNoteListTool,
+    MarginNoteDocumentsTool,
+    MarginNoteLinksTool,
+    MarginNoteTagsTool,
+    MarginNoteCardsTool,
+)
+
+
+__all__ = ["MARGINNOTE_TOOL_NAMES", "MARGINNOTE_TOOL_TYPES"]

deeptutor/capabilities/obsidian/__init__.py

@@ -0,0 +1,6 @@
+"""Obsidian loop capability — agentic retrieval & authoring over a connected vault."""
+
+from deeptutor.capabilities.obsidian.capability import ObsidianCapability
+from deeptutor.capabilities.obsidian.tools import OBSIDIAN_TOOL_NAMES, OBSIDIAN_TOOL_TYPES
+
+__all__ = ["OBSIDIAN_TOOL_NAMES", "OBSIDIAN_TOOL_TYPES", "ObsidianCapability"]

deeptutor/capabilities/obsidian/binding.py

@@ -0,0 +1,75 @@
+"""Resolve which connected Obsidian vault (if any) the current turn targets.
+
+The binding is derived once per turn from the user's selected knowledge bases:
+the first selection whose KB metadata is ``type == obsidian`` wins, and its
+``vault_path`` becomes the live vault the Obsidian tools operate on. The result
+is cached in the extension namespace so ``is_active`` / ``augment_kwargs`` /
+``system_block`` share a single filesystem lookup. Pure read — no audit
+side-effects (unlike ``resolve_for_rag``), and access errors resolve to "no
+vault" rather than raising.
+"""
+
+from __future__ import annotations
+
+from deeptutor.core.context import UnifiedContext
+from deeptutor.knowledge.kb_types import OBSIDIAN_KB_TYPE
+
+# Cached per extension: a {"name", "path"} dict, or "" once we've looked
+# and found none. Absence of the key means "not resolved yet".
+_CACHE_KEY = "_obsidian_vault"
+
+
+def vault_for_turn(context: UnifiedContext) -> dict[str, str] | None:
+    """Return ``{"name", "path"}`` of the selected Obsidian vault, or ``None``."""
+    state = context.extension("obsidian")
+    cached = state.get(_CACHE_KEY, _UNSET)
+    if cached is not _UNSET:
+        return cached or None
+    resolved = _resolve(context)
+    state[_CACHE_KEY] = resolved or ""
+    return resolved
+
+
+def _resolve(context: UnifiedContext) -> dict[str, str] | None:
+    from deeptutor.multi_user.knowledge_access import resolve_kb_metadata
+
+    for ref in context.knowledge_bases or []:
+        ref = str(ref).strip()
+        if not ref:
+            continue
+        meta = resolve_kb_metadata(ref)
+        if not meta or meta.get("type") != OBSIDIAN_KB_TYPE:
+            continue
+        path = str(meta.get("vault_path") or "").strip()
+        if path:
+            return {"name": str(meta.get("name") or ref), "path": path}
+    return None
+
+
+def obsidian_vault_refs(context: UnifiedContext) -> set[str]:
+    """Return every selected KB ref that resolves to a connected Obsidian vault.
+
+    The capability only *operates* on the first vault (see :func:`vault_for_turn`),
+    but all vault refs are reported here so the chat pipeline can exclude them
+    from the ``rag`` surface — ``rag`` has no index for a live vault (issue #650).
+    """
+    from deeptutor.multi_user.knowledge_access import resolve_kb_metadata
+
+    refs: set[str] = set()
+    for ref in context.knowledge_bases or []:
+        ref = str(ref).strip()
+        if not ref:
+            continue
+        meta = resolve_kb_metadata(ref)
+        if (
+            meta
+            and meta.get("type") == OBSIDIAN_KB_TYPE
+            and str(meta.get("vault_path") or "").strip()
+        ):
+            refs.add(ref)
+    return refs
+
+
+_UNSET = object()
+
+__all__ = ["obsidian_vault_refs", "vault_for_turn"]

deeptutor/capabilities/obsidian/capability.py

@@ -0,0 +1,82 @@
+"""Obsidian loop capability — agentic retrieval & authoring over a live vault.
+
+Active whenever the user's selected knowledge base is a connected Obsidian
+vault (resolved by :mod:`deeptutor.capabilities.obsidian.binding`). As a
+:class:`KnowledgeCapability` it owns the turn: the chat loop runs exclusively
+on the nine Obsidian tools (plus the ``ask_user`` floor), navigating and
+editing the vault's Markdown directly rather than retrieving flattened chunks.
+
+The vault root is injected into each tool call as ``_vault_path`` server-side;
+the model never supplies it.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from typing import Any
+
+from deeptutor.capabilities.obsidian.binding import obsidian_vault_refs, vault_for_turn
+from deeptutor.capabilities.obsidian.tools import OBSIDIAN_TOOL_NAMES
+from deeptutor.capabilities.protocol import KnowledgeCapability, PromptBlock
+from deeptutor.core.context import UnifiedContext
+from deeptutor.services.prompt.lookup import prompt_text as _prompt_text
+
+
+class ObsidianCapability(KnowledgeCapability):
+    """Turn-scoped integration for a connected Obsidian vault."""
+
+    name = "obsidian"
+    owned_tools = OBSIDIAN_TOOL_NAMES
+
+    def is_active(self, context: UnifiedContext) -> bool:
+        return vault_for_turn(context) is not None
+
+    def owned_kbs(self, context: UnifiedContext) -> set[str]:
+        # The selected vault KB(s) are read/authored through the Obsidian tools,
+        # never through rag — exclude them so co-selected LlamaIndex KBs keep
+        # their rag surface (issue #650).
+        return obsidian_vault_refs(context)
+
+    def system_block(
+        self,
+        context: UnifiedContext,
+        *,
+        language: str,
+        prompts: dict[str, Any],
+    ) -> PromptBlock | None:
+        binding = vault_for_turn(context)
+        if binding is None:
+            return None
+        override = _prompt_text(prompts, ("obsidian", "system"))
+        content = override or _load_system_prompt(language)
+        return PromptBlock("obsidian", content.replace("{vault_name}", binding["name"]))
+
+    def augment_kwargs(
+        self,
+        tool_name: str,
+        kwargs: dict[str, Any],
+        context: UnifiedContext,
+    ) -> dict[str, Any]:
+        if tool_name not in OBSIDIAN_TOOL_NAMES:
+            return kwargs
+        binding = vault_for_turn(context)
+        if binding is None:
+            return kwargs
+        # Server-owned: overwrite any model-supplied value so the path can't be
+        # forged to read/write outside the connected vault.
+        updated = dict(kwargs)
+        updated["_vault_path"] = binding["path"]
+        return updated
+
+    def pre_loop_seed(self, context: UnifiedContext) -> str:
+        _ = context
+        return ""
+
+
+def _load_system_prompt(language: str) -> str:
+    lang = "zh" if language.lower().startswith("zh") else "en"
+    prompt = resources.files(__package__).joinpath("prompts", lang, "system.md")
+    return prompt.read_text(encoding="utf-8").strip()
+
+
+__all__ = ["ObsidianCapability"]

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

@@ -0,0 +1,32 @@
+# Obsidian Vault
+
+You are connected to the user's Obsidian vault **{vault_name}** — a graph of
+linked Markdown notes. This turn you work *only* with the Obsidian tools; there
+is no web, code, or other knowledge base. The vault is the source of truth:
+read it to answer, write to it to capture.
+
+## Retrieving (answering from the vault)
+
+Don't guess — explore. A typical path:
+
+1. `obsidian_search` for the topic, or `obsidian_tags` / `obsidian_list` to map
+   the vault when you lack a search term.
+2. `obsidian_read` the promising notes.
+3. Follow the graph: `obsidian_backlinks` (what links here) and `obsidian_links`
+   (what this note points to) surface related notes a keyword search misses.
+4. Answer grounded in what you read, citing note names. If the vault doesn't
+   cover it, say so rather than inventing.
+
+## Writing (capturing into the vault)
+
+When asked to save, summarise, or organise:
+
+- `obsidian_create_note` for a new note, `obsidian_append` to extend one,
+  `obsidian_set_property` to set a frontmatter field. Writes are additive —
+  you never overwrite or delete existing prose.
+- Write valid **Obsidian Flavored Markdown**: link related notes with
+  `[[Note Name]]` (not Markdown links), embed with `![[Note]]` or `![[img.png]]`,
+  highlight with callouts `> [!note]` / `> [!tip]` / `> [!warning]`.
+- Put structured metadata (tags, aliases, status, dates) in frontmatter
+  properties, not inline prose.
+- Prefer linking new notes into the existing graph so they're discoverable.

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

@@ -0,0 +1,28 @@
+# Obsidian 知识库
+
+你已连接到用户的 Obsidian 知识库 **{vault_name}**——一张由 `[[双链]]` 连接的
+Markdown 笔记图谱。本轮你**只**使用 Obsidian 工具,没有联网、代码或其它知识库。
+知识库就是真理之源:读它来回答,写它来沉淀。
+
+## 检索(从库中作答)
+
+不要猜,去探索。典型路径:
+
+1. 用 `obsidian_search` 搜主题;没有搜索词时用 `obsidian_tags` / `obsidian_list`
+   先摸清结构。
+2. 用 `obsidian_read` 读有价值的笔记。
+3. 顺着图谱走:`obsidian_backlinks`(谁链到这条)和 `obsidian_links`(这条链向谁)
+   能找出关键词搜不到的关联笔记。
+4. 基于读到的内容作答,注明引用的笔记名。库里没有就如实说,不要编造。
+
+## 写入(沉淀进库)
+
+当用户要求保存、总结或整理时:
+
+- 新建用 `obsidian_create_note`,追加用 `obsidian_append`,设置 frontmatter 字段
+  用 `obsidian_set_property`。写入只增不改——绝不覆盖或删除已有正文。
+- 写合规的 **Obsidian 风味 Markdown**:用 `[[笔记名]]` 链接库内笔记(不要用
+  Markdown 链接),用 `![[笔记]]` 或 `![[图片.png]]` 嵌入,用 callout
+  `> [!note]` / `> [!tip]` / `> [!warning]` 高亮。
+- 把结构化元数据(标签、别名、状态、日期)放进 frontmatter 属性,而非正文。
+- 尽量把新笔记链接进已有图谱,让它可被发现。