Skip to content

fix(research): mount read-only Obsidian tools instead of rag for vault KBs - #756

Merged
pancacake merged 2 commits into
HKUDS:devfrom
szzhoujiarui:260803-fix-research-obsidian-tools
Aug 6, 2026
Merged

fix(research): mount read-only Obsidian tools instead of rag for vault KBs#756
pancacake merged 2 commits into
HKUDS:devfrom
szzhoujiarui:260803-fix-research-obsidian-tools

Conversation

@szzhoujiarui

@szzhoujiarui szzhoujiarui commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Description

When a connected Obsidian vault is selected as the knowledge base, the deep-research pipeline auto-mounts the rag tool even though the vault has no index, producing spurious warnings and misleading evidence. This PR makes ResearchPipeline vault-aware:

  • Resolve KB metadata at construction (resolve_kb_metadata) and record _is_obsidian_kb / _vault_path (pure read, no RAG usage audit).
  • Suppress the rag auto-mount for Obsidian KBs (has_kb=False) and expose the three read-only Obsidian tools obsidian_search / obsidian_read / obsidian_list in the research block loop.
  • Keep Obsidian type detection independent from vault_path availability, so malformed metadata never falls back to index-backed rag; read tools are mounted only when a trusted path exists.
  • Inject _vault_path server-side in _augment_tool_kwargs, overwriting any model-supplied value so the path cannot be forged to read outside the vault.
  • Add the three tools to CITABLE_TOOLS so their evidence is summarised, recorded by the CitationManager, and reaches Phase 4 reporting.
  • Preserve each tool's real citation locator (query, note, or folder), using / for a vault-root listing.
  • Render an Obsidian-specific system note (en/zh) instructing read-only vault retrieval instead of rag.

Indexed KBs, no-KB, and unresolvable references keep their existing behaviour.

Related Issues

Module(s) Affected

  • agents
  • api
  • config
  • core
  • knowledge
  • logging
  • services
  • tools
  • utils
  • web (Frontend)
  • docs (Documentation)
  • scripts
  • tests
  • Other: ...

Checklist

  • I have read and followed the contribution guidelines.
  • My code follows the project's coding standards.
  • I have run pre-commit run --all-files and fixed any issues.
  • I have added relevant tests for my changes.
  • I have updated the documentation (if necessary).
  • My changes do not introduce any new security vulnerabilities.

Additional Notes

  • 23 targeted tests in tests/agents/research/test_research_obsidian_tools.py cover metadata resolution, tool-composition matrix, vault-path injection/forging, real citation locators, and system-note selection.
  • The targeted ResearchPipeline and Obsidian capability suites pass: 52 passed.
  • Full backend suite from the initial implementation run: 3527 passed; 24 pre-existing failures in MCP/partners tests (reproduced on clean dev baseline, unrelated to this change).
  • pre-commit run --all-files was not executed in this environment; the modified files pass ruff check, ruff format --check, and git diff --check locally.

…t KBs

When the selected knowledge base is a connected Obsidian vault, the
research block loop now:

- resolves KB metadata at construction and records the server-side vault
  path (no RAG usage audit);
- suppresses the rag auto-mount (has_kb=False) and exposes the three
  read-only Obsidian tools obsidian_search / obsidian_read / obsidian_list;
- injects _vault_path server-side, overwriting any model-supplied value;
- treats the Obsidian tools as citable so their evidence feeds the
  citation manager and Phase 4 reporting;
- renders an Obsidian-specific system note (en/zh) instructing read-only
  vault retrieval instead of rag.

Indexed KBs, no-KB, and unresolvable references keep their existing
behaviour. Closes HKUDS#752
@pancacake
pancacake merged commit 47b713d into HKUDS:dev Aug 6, 2026
evan188199-tech pushed a commit to evan188199-tech/DeepTutor that referenced this pull request Aug 15, 2026
…ridge

Add MarginNote 4 as a connected knowledge base type that syncs study data
(notes, excerpts, cards, mindmap nodes) from MN4 via the official Add-on API
into a dedicated SQLite store, then exposes it to the chat loop through seven
read-only tools.

New package: deeptutor/capabilities/marginnote4/
- models.py: MarginNoteObject, SyncBatch, PairedDevice, LearningEvent
- store.py: SQLite CRUD + search + device pairing with hashed tokens
- binding.py: per-turn resolution of the selected MN4 library
- tools.py: search, read, list, documents, links, tags, cards
- capability.py: KnowledgeCapability (exclusive turn ownership)
- prompts/{en,zh}/system.md

HTTP bridge: deeptutor/api/routers/marginnote4.py
- POST /pair (session auth) -- register a device, get one-time token
- POST /sync (device-token auth) -- incremental upsert + tombstones
- POST /heartbeat (device-token auth) -- liveness + object count
- GET /devices, DELETE /devices/{id}, GET /status (session auth)

Integration points:
- kb_types.py: MARGINNOTE4_KB_TYPE added to CONNECTED_KB_TYPES
- manager.py: db_path surfaced in get_metadata allowlist
- registry.py: MarginNoteCapability registered in LOOP_CAPABILITIES
- builtin/__init__.py: MARGINNOTE_TOOL_TYPES in BUILTIN_TOOL_TYPES
- api/main.py: router mounted at /api/v1/marginnote4

Phase 1 scope: device pairing, read-only sync, tool navigation.
Write-back (propose/apply/verify), learning events, and mastery bridge
are planned for Phase 2-3.

Refs: HKUDS#756 (Obsidian external knowledge source pattern), HKUDS#180
pancacake added a commit that referenced this pull request Aug 21, 2026
* feat(marginnote4): add connected KB type, read-only tools, and sync bridge

Add MarginNote 4 as a connected knowledge base type that syncs study data
(notes, excerpts, cards, mindmap nodes) from MN4 via the official Add-on API
into a dedicated SQLite store, then exposes it to the chat loop through seven
read-only tools.

New package: deeptutor/capabilities/marginnote4/
- models.py: MarginNoteObject, SyncBatch, PairedDevice, LearningEvent
- store.py: SQLite CRUD + search + device pairing with hashed tokens
- binding.py: per-turn resolution of the selected MN4 library
- tools.py: search, read, list, documents, links, tags, cards
- capability.py: KnowledgeCapability (exclusive turn ownership)
- prompts/{en,zh}/system.md

HTTP bridge: deeptutor/api/routers/marginnote4.py
- POST /pair (session auth) -- register a device, get one-time token
- POST /sync (device-token auth) -- incremental upsert + tombstones
- POST /heartbeat (device-token auth) -- liveness + object count
- GET /devices, DELETE /devices/{id}, GET /status (session auth)

Integration points:
- kb_types.py: MARGINNOTE4_KB_TYPE added to CONNECTED_KB_TYPES
- manager.py: db_path surfaced in get_metadata allowlist
- registry.py: MarginNoteCapability registered in LOOP_CAPABILITIES
- builtin/__init__.py: MARGINNOTE_TOOL_TYPES in BUILTIN_TOOL_TYPES
- api/main.py: router mounted at /api/v1/marginnote4

Phase 1 scope: device pairing, read-only sync, tool navigation.
Write-back (propose/apply/verify), learning events, and mastery bridge
are planned for Phase 2-3.

Refs: #756 (Obsidian external knowledge source pattern), #180

* fix(marginnote4): search scope, store caching, prompts, KB registration

Testing and experience improvements:

- Search now includes document_title in scope: searching for a textbook
  name returns results instead of zero hits
- Store instances cached by db_path so schema init runs once, not per
  tool call within a turn
- object_type parameters carry enum constraints so the LLM knows valid
  types without guessing
- System prompts (en/zh) rewritten with domain context: explains the
  five object types, link traversal strategy, and citation guidance
- KB registration: register_marginnote4_kb manager method +
  /connect-marginnote4 API endpoint, mirroring the Obsidian connect flow
- Fix indentation inconsistencies in manager.py and main.py
- New tests: document_title search scope, KB registration (create,
  default path, duplicate rejection)

65 tests pass, 0 regressions, ruff clean.

* style(marginnote4): apply repository formatter

* fix(marginnote4): keep MN4 libraries out of the rag_search sweep

``MARGINNOTE4_KB_TYPE`` joined ``CONNECTED_KB_TYPES`` but not
``NON_RETRIEVABLE_KB_TYPES``, so ``supports_rag_retrieval`` answered true
for a library that has no index and no retrieval API — its objects live
in ``mn4_objects`` and are reachable only through the seven
``marginnote_*`` tools. Book's source explorer would have swept it,
gotten nothing back, and reported it as a source with no relevant
content rather than one that needs its own tools.

MN4 belongs with ``obsidian`` and ``subagent``, not with ``linked`` /
``lightrag_server`` / ``ima``, which do resolve to an index or an HTTP
retrieval API. Tests pin both halves of that split, since collapsing it
the other way has cost Book its connected sources before.

---------

Co-authored-by: XZH <cto@xzh.ai>
Co-authored-by: evan <evan@dazongguandeMac-mini.local>
Co-authored-by: Bingxi Zhao (Frank) <13051345080@163.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants