vault-ask 0.1.1__tar.gz

vault_ask-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 guillaumevele
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vault_ask-0.1.1/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: vault-ask
+Version: 0.1.1
+Summary: Ask your Obsidian vault, get cited answers, never hallucinate.
+Author: guillaumevele
+License: MIT
+Project-URL: Homepage, https://github.com/guillaumevele/vault-ask
+Project-URL: Repository, https://github.com/guillaumevele/vault-ask
+Project-URL: Issues, https://github.com/guillaumevele/vault-ask/issues
+Keywords: obsidian,rag,llm,cli,knowledge-management,second-brain,ripgrep,grounded-generation,note-taking
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# vault-ask
+
+[![CI](https://github.com/guillaumevele/vault-ask/actions/workflows/ci.yml/badge.svg)](https://github.com/guillaumevele/vault-ask/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![Zero dependencies](https://img.shields.io/badge/dependencies-zero-success.svg)](pyproject.toml)
+
+**Ask your Obsidian vault. Get cited answers. Never hallucinate.**
+
+A tiny (~300-line, dependency-free) grounded question-answering tool over a folder
+of Markdown notes. It finds the relevant notes, asks *your* LLM to answer **only**
+from them, forces a `[[wikilink]]` citation on every claim, and **refuses instead
+of guessing** when the answer isn't in your vault.
+
+```console
+$ vault-ask "what did I decide about the pricing model?"
+Q: what did I decide about the pricing model?
+
+Flat 49 EUR/month, no per-seat pricing, decided after the churn analysis.
+[[Decisions/2026-Pricing|2026-Pricing]]
+
+Notes consulted:
+- [[Decisions/2026-Pricing|2026-Pricing]]
+- [[Meetings/2026-01-pricing-review|2026-01-pricing-review]]
+```
+
+Ask something that isn't in your notes and it won't make anything up:
+
+```console
+$ vault-ask "what is my bank account number?"
+Q: what is my bank account number?
+
+No note in the vault answers this question.
+```
+
+## Why
+
+A second brain is only useful if knowledge comes *back out*. Most "chat with your
+notes" tools either need a vector database and an indexing pipeline, or happily
+hallucinate plausible answers — a dealbreaker when your notes are medical, legal,
+or financial. `vault-ask` is the opposite: zero index, zero database, and a hard
+refusal guarantee. It runs `ripgrep` over your vault, ranks notes by term rarity
+(TF-IDF), and hands the best excerpts to whatever LLM you already use.
+
+## How it works
+
+1. **Candidate search** — `ripgrep` scans the whole vault in milliseconds.
+2. **IDF ranking** — notes are scored by the *rarity* of the query terms they
+   contain, so a rare, specific word (a project codename) outweighs a word that
+   appears in hundreds of notes. No embeddings, no index, no warm-up.
+3. **Focused excerpts** — only the headings and matching lines of the top notes
+   are sent to the model (notes can be long).
+4. **Grounded prompt** — the model must cite each claim as a `[[link]]`, must not
+   add outside knowledge, and must reply with a fixed refusal sentence if the
+   excerpts don't answer the question.
+5. **Robust refusal check** — a refusal (even reworded by the model) is never
+   dressed up as a sourced answer; its citations are stripped.
+
+Nothing leaves your machine except what your own LLM command chooses to send.
+
+## Install
+
+Requires **Python 3.9+** and **[ripgrep](https://github.com/BurntSushi/ripgrep)**
+(`rg`) on your `PATH`.
+
+```bash
+# pip (installs the `vault-ask` command)
+pip install git+https://github.com/guillaumevele/vault-ask.git
+```
+
+Or run it as a single file, no install:
+
+```bash
+git clone https://github.com/guillaumevele/vault-ask.git
+cd vault-ask
+python3 vault_ask.py "your question"
+```
+
+No dependencies beyond the Python standard library and ripgrep.
+
+## Configure your LLM
+
+`vault-ask` shells out to whatever LLM command you set in `VAULT_ASK_LLM`. The
+prompt is piped on **stdin** by default, or substituted for `{prompt}` if the
+command contains that placeholder.
+
+```bash
+# Local model via Ollama (prompt on stdin):
+export VAULT_ASK_LLM='ollama run llama3.1'
+
+# Simon Willison's `llm` CLI (any provider it supports):
+export VAULT_ASK_LLM='llm -m gpt-4o-mini'
+
+# A CLI that takes the prompt as an argument — use the {prompt} placeholder:
+export VAULT_ASK_LLM='your-llm-cli --prompt {prompt}'
+```
+
+Point it at your vault once:
+
+```bash
+export OBSIDIAN_VAULT="$HOME/Obsidian/MyVault"
+```
+
+## Usage
+
+```bash
+vault-ask "what did I decide about X?"
+vault-ask --vault ~/notes "when is the contract renewal?"
+vault-ask --limit 8 --json "summarize my pricing decisions"
+```
+
+No LLM? Use `--sources-only` to just rank the most relevant notes — a smart grep
+for your vault that needs no model at all:
+
+```bash
+vault-ask --sources-only "pricing model"
+# Most relevant notes for: pricing model
+# - [[Decisions/2026-pricing|2026-pricing]]
+# - [[Meetings/2026-01-pricing-review|2026-01-pricing-review]]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--vault` | `$OBSIDIAN_VAULT` or `.` | path to the vault |
+| `--limit` | `5` | max notes to consult |
+| `--llm` | `$VAULT_ASK_LLM` | LLM command (overrides env) |
+| `--sources-only` | off | rank relevant notes, no LLM call |
+| `--json` | off | raw structured output |
+| `--version` | | print version |
+
+## What it's good at — and what it isn't
+
+**Good at:** factual lookups where the words of your question point at a note —
+decisions, numbers, names, "what did I say about …". It's fast and it never lies.
+
+**Not good at:** abstract questions whose vocabulary differs from your notes (you
+ask "my funding strategy", the note says "tax credit"). That's the inherent limit
+of keyword retrieval — proper semantic recall needs embeddings, which this tool
+deliberately avoids to stay zero-dependency and zero-index. When it can't match,
+it refuses honestly rather than guessing.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+## Related
+
+[**voice-to-vault**](https://github.com/guillaumevele/voice-to-vault) is the other
+half of the loop: it routes your voice captures into the Obsidian vault that
+`vault-ask` then answers questions about. One files your thoughts, the other
+brings them back.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

vault_ask-0.1.1/README.md

@@ -0,0 +1,157 @@
+# vault-ask
+
+[![CI](https://github.com/guillaumevele/vault-ask/actions/workflows/ci.yml/badge.svg)](https://github.com/guillaumevele/vault-ask/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![Zero dependencies](https://img.shields.io/badge/dependencies-zero-success.svg)](pyproject.toml)
+
+**Ask your Obsidian vault. Get cited answers. Never hallucinate.**
+
+A tiny (~300-line, dependency-free) grounded question-answering tool over a folder
+of Markdown notes. It finds the relevant notes, asks *your* LLM to answer **only**
+from them, forces a `[[wikilink]]` citation on every claim, and **refuses instead
+of guessing** when the answer isn't in your vault.
+
+```console
+$ vault-ask "what did I decide about the pricing model?"
+Q: what did I decide about the pricing model?
+
+Flat 49 EUR/month, no per-seat pricing, decided after the churn analysis.
+[[Decisions/2026-Pricing|2026-Pricing]]
+
+Notes consulted:
+- [[Decisions/2026-Pricing|2026-Pricing]]
+- [[Meetings/2026-01-pricing-review|2026-01-pricing-review]]
+```
+
+Ask something that isn't in your notes and it won't make anything up:
+
+```console
+$ vault-ask "what is my bank account number?"
+Q: what is my bank account number?
+
+No note in the vault answers this question.
+```
+
+## Why
+
+A second brain is only useful if knowledge comes *back out*. Most "chat with your
+notes" tools either need a vector database and an indexing pipeline, or happily
+hallucinate plausible answers — a dealbreaker when your notes are medical, legal,
+or financial. `vault-ask` is the opposite: zero index, zero database, and a hard
+refusal guarantee. It runs `ripgrep` over your vault, ranks notes by term rarity
+(TF-IDF), and hands the best excerpts to whatever LLM you already use.
+
+## How it works
+
+1. **Candidate search** — `ripgrep` scans the whole vault in milliseconds.
+2. **IDF ranking** — notes are scored by the *rarity* of the query terms they
+   contain, so a rare, specific word (a project codename) outweighs a word that
+   appears in hundreds of notes. No embeddings, no index, no warm-up.
+3. **Focused excerpts** — only the headings and matching lines of the top notes
+   are sent to the model (notes can be long).
+4. **Grounded prompt** — the model must cite each claim as a `[[link]]`, must not
+   add outside knowledge, and must reply with a fixed refusal sentence if the
+   excerpts don't answer the question.
+5. **Robust refusal check** — a refusal (even reworded by the model) is never
+   dressed up as a sourced answer; its citations are stripped.
+
+Nothing leaves your machine except what your own LLM command chooses to send.
+
+## Install
+
+Requires **Python 3.9+** and **[ripgrep](https://github.com/BurntSushi/ripgrep)**
+(`rg`) on your `PATH`.
+
+```bash
+# pip (installs the `vault-ask` command)
+pip install git+https://github.com/guillaumevele/vault-ask.git
+```
+
+Or run it as a single file, no install:
+
+```bash
+git clone https://github.com/guillaumevele/vault-ask.git
+cd vault-ask
+python3 vault_ask.py "your question"
+```
+
+No dependencies beyond the Python standard library and ripgrep.
+
+## Configure your LLM
+
+`vault-ask` shells out to whatever LLM command you set in `VAULT_ASK_LLM`. The
+prompt is piped on **stdin** by default, or substituted for `{prompt}` if the
+command contains that placeholder.
+
+```bash
+# Local model via Ollama (prompt on stdin):
+export VAULT_ASK_LLM='ollama run llama3.1'
+
+# Simon Willison's `llm` CLI (any provider it supports):
+export VAULT_ASK_LLM='llm -m gpt-4o-mini'
+
+# A CLI that takes the prompt as an argument — use the {prompt} placeholder:
+export VAULT_ASK_LLM='your-llm-cli --prompt {prompt}'
+```
+
+Point it at your vault once:
+
+```bash
+export OBSIDIAN_VAULT="$HOME/Obsidian/MyVault"
+```
+
+## Usage
+
+```bash
+vault-ask "what did I decide about X?"
+vault-ask --vault ~/notes "when is the contract renewal?"
+vault-ask --limit 8 --json "summarize my pricing decisions"
+```
+
+No LLM? Use `--sources-only` to just rank the most relevant notes — a smart grep
+for your vault that needs no model at all:
+
+```bash
+vault-ask --sources-only "pricing model"
+# Most relevant notes for: pricing model
+# - [[Decisions/2026-pricing|2026-pricing]]
+# - [[Meetings/2026-01-pricing-review|2026-01-pricing-review]]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--vault` | `$OBSIDIAN_VAULT` or `.` | path to the vault |
+| `--limit` | `5` | max notes to consult |
+| `--llm` | `$VAULT_ASK_LLM` | LLM command (overrides env) |
+| `--sources-only` | off | rank relevant notes, no LLM call |
+| `--json` | off | raw structured output |
+| `--version` | | print version |
+
+## What it's good at — and what it isn't
+
+**Good at:** factual lookups where the words of your question point at a note —
+decisions, numbers, names, "what did I say about …". It's fast and it never lies.
+
+**Not good at:** abstract questions whose vocabulary differs from your notes (you
+ask "my funding strategy", the note says "tax credit"). That's the inherent limit
+of keyword retrieval — proper semantic recall needs embeddings, which this tool
+deliberately avoids to stay zero-dependency and zero-index. When it can't match,
+it refuses honestly rather than guessing.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+## Related
+
+[**voice-to-vault**](https://github.com/guillaumevele/voice-to-vault) is the other
+half of the loop: it routes your voice captures into the Obsidian vault that
+`vault-ask` then answers questions about. One files your thoughts, the other
+brings them back.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

vault_ask-0.1.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vault-ask"
+version = "0.1.1"
+description = "Ask your Obsidian vault, get cited answers, never hallucinate."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "guillaumevele" }]
+keywords = [
+    "obsidian", "rag", "llm", "cli", "knowledge-management",
+    "second-brain", "ripgrep", "grounded-generation", "note-taking",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing :: Indexing",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/guillaumevele/vault-ask"
+Repository = "https://github.com/guillaumevele/vault-ask"
+Issues = "https://github.com/guillaumevele/vault-ask/issues"
+
+[project.scripts]
+vault-ask = "vault_ask:main"
+
+[tool.setuptools]
+py-modules = ["vault_ask"]

vault_ask-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vault_ask-0.1.1/tests/test_vault_ask.py

@@ -0,0 +1,154 @@
+"""Tests for vault-ask. Run: python3 -m unittest discover -s tests
+
+Requires ripgrep (`rg`) on PATH for the candidate-selection tests.
+"""
+from __future__ import annotations
+
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+import vault_ask  # noqa: E402
+
+
+class TestQueryTerms(unittest.TestCase):
+    def test_strips_stopwords_and_short_tokens(self):
+        terms = vault_ask.query_terms("What did I decide about the pricing for Acme?")
+        self.assertIn("decide", terms)
+        self.assertIn("pricing", terms)
+        self.assertIn("acme", terms)
+        self.assertNotIn("what", terms)
+        self.assertNotIn("the", terms)
+        self.assertNotIn("for", terms)
+
+    def test_french_stopwords(self):
+        terms = vault_ask.query_terms("quel est le financement retenu pour le projet")
+        self.assertIn("financement", terms)
+        self.assertIn("projet", terms)
+        self.assertNotIn("quel", terms)
+        self.assertNotIn("retenu", terms)
+
+
+class TestRefusalDetection(unittest.TestCase):
+    def test_exact(self):
+        self.assertTrue(vault_ask.is_refusal(vault_ask.REFUSAL))
+
+    def test_punctuation_and_case_insensitive(self):
+        # A reformulated refusal must still count as a refusal (safety guardrail).
+        self.assertTrue(vault_ask.is_refusal("no note in the vault answers this question"))
+        self.assertTrue(vault_ask.is_refusal("No note in the vault answers this question."))
+
+    def test_real_answer_is_not_a_refusal(self):
+        self.assertFalse(vault_ask.is_refusal("The price is 49 EUR [[Pricing]]."))
+
+
+class TestPromptGuardrails(unittest.TestCase):
+    def test_prompt_carries_sources_and_rules(self):
+        notes = [{"link": "[[Decisions/Pricing|Pricing]]", "excerpt": "Price set to 49 EUR."}]
+        prompt = vault_ask.build_prompt("what is the price", notes)
+        self.assertIn("[[Decisions/Pricing|Pricing]]", prompt)
+        self.assertIn(vault_ask.REFUSAL, prompt)
+        self.assertIn("Use ONLY the note excerpts", prompt)
+        self.assertIn("Price set to 49 EUR", prompt)
+
+
+class TestCandidateSelection(unittest.TestCase):
+    def setUp(self):
+        self.tmp = Path(tempfile.mkdtemp())
+
+    def tearDown(self):
+        for p in sorted(self.tmp.rglob("*"), reverse=True):
+            p.unlink() if p.is_file() else p.rmdir()
+        self.tmp.rmdir()
+
+    def test_rare_term_outranks_ubiquitous_term(self):
+        # "project" is ubiquitous (low IDF); "zylophone" is rare (high IDF).
+        for i in range(8):
+            (self.tmp / f"noise{i}.md").write_text(
+                "# Project\n" + ("project project project\n" * 20), encoding="utf-8")
+        (self.tmp / "target.md").write_text(
+            "# Decision\nThe chosen budget tool is Zylophone, for the project.\n",
+            encoding="utf-8")
+        notes = vault_ask.candidate_notes(self.tmp, "budget zylophone project", limit=5)
+        self.assertTrue(notes)
+        self.assertEqual(Path(notes[0]["file"]).stem, "target")
+
+    def test_no_terms_returns_empty(self):
+        self.assertEqual(vault_ask.candidate_notes(self.tmp, "what is the", limit=5), [])
+
+    def test_excerpt_keeps_answer_on_adjacent_line(self):
+        # The keyword and the actual answer often sit on neighbouring (wrapped)
+        # lines; the context window must keep both.
+        note = self.tmp / "n.md"
+        note.write_text(
+            "# Heading\nThe chosen value is 49 EUR\nfor the pricing plan.\n",
+            encoding="utf-8")
+        excerpt = vault_ask.note_excerpt(note, ["pricing"])
+        self.assertIn("49 EUR", excerpt)        # answer line (no keyword) kept via context
+        self.assertIn("pricing", excerpt)
+
+
+class TestAsk(unittest.TestCase):
+    def setUp(self):
+        self.tmp = Path(tempfile.mkdtemp())
+
+    def tearDown(self):
+        for p in sorted(self.tmp.rglob("*"), reverse=True):
+            p.unlink() if p.is_file() else p.rmdir()
+        self.tmp.rmdir()
+
+    def test_synthesizes_with_citation(self):
+        (self.tmp / "decision.md").write_text(
+            "# Decision\nThe chosen budget tool is Zylophone.\n", encoding="utf-8")
+        answer = "The chosen tool is Zylophone [[decision|decision]]."
+        with patch.object(vault_ask, "run_llm", return_value=answer):
+            res = vault_ask.ask(self.tmp, "which budget tool zylophone")
+        self.assertTrue(res["grounded"])
+        self.assertEqual(res["answer"], answer)
+        self.assertTrue(res["sources"])
+
+    def test_refuses_when_no_candidates(self):
+        with patch.object(vault_ask, "run_llm") as llm:
+            res = vault_ask.ask(self.tmp, "completely unrelated xyzzy quux")
+        llm.assert_not_called()
+        self.assertFalse(res["grounded"])
+        self.assertEqual(res["answer"], vault_ask.REFUSAL)
+
+    def test_refusal_from_llm_drops_sources(self):
+        (self.tmp / "note.md").write_text("# Note\nZylophone budget tool.\n", encoding="utf-8")
+        with patch.object(vault_ask, "run_llm", return_value="No note in the vault answers this question"):
+            res = vault_ask.ask(self.tmp, "zylophone budget")
+        self.assertFalse(res["grounded"])
+        self.assertEqual(res["answer"], vault_ask.REFUSAL)
+        self.assertEqual(res["sources"], [])
+
+    def test_no_llm_returns_candidates_not_hallucination(self):
+        (self.tmp / "note.md").write_text("# Note\nZylophone budget tool.\n", encoding="utf-8")
+        with patch.object(vault_ask, "run_llm", return_value=None):
+            res = vault_ask.ask(self.tmp, "zylophone budget")
+        self.assertFalse(res["grounded"])
+        self.assertIsNone(res["answer"])
+        self.assertEqual(res["reason"], "no-llm")
+        self.assertTrue(res["candidates"])
+
+    def test_sources_only_skips_llm(self):
+        (self.tmp / "note.md").write_text("# Note\nZylophone budget tool.\n", encoding="utf-8")
+        with patch.object(vault_ask, "run_llm") as llm:
+            res = vault_ask.ask(self.tmp, "zylophone budget", sources_only=True)
+        llm.assert_not_called()
+        self.assertEqual(res["mode"], "sources-only")
+        self.assertTrue(res["sources"])
+        self.assertIsNone(res["answer"])
+
+    def test_missing_ripgrep_gives_clear_reason(self):
+        with patch.object(vault_ask.shutil, "which", return_value=None):
+            res = vault_ask.ask(self.tmp, "anything at all")
+        self.assertFalse(res["ok"])
+        self.assertEqual(res["reason"], "ripgrep-not-found")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

vault_ask-0.1.1/vault_ask.egg-info/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: vault-ask
+Version: 0.1.1
+Summary: Ask your Obsidian vault, get cited answers, never hallucinate.
+Author: guillaumevele
+License: MIT
+Project-URL: Homepage, https://github.com/guillaumevele/vault-ask
+Project-URL: Repository, https://github.com/guillaumevele/vault-ask
+Project-URL: Issues, https://github.com/guillaumevele/vault-ask/issues
+Keywords: obsidian,rag,llm,cli,knowledge-management,second-brain,ripgrep,grounded-generation,note-taking
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# vault-ask
+
+[![CI](https://github.com/guillaumevele/vault-ask/actions/workflows/ci.yml/badge.svg)](https://github.com/guillaumevele/vault-ask/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![Zero dependencies](https://img.shields.io/badge/dependencies-zero-success.svg)](pyproject.toml)
+
+**Ask your Obsidian vault. Get cited answers. Never hallucinate.**
+
+A tiny (~300-line, dependency-free) grounded question-answering tool over a folder
+of Markdown notes. It finds the relevant notes, asks *your* LLM to answer **only**
+from them, forces a `[[wikilink]]` citation on every claim, and **refuses instead
+of guessing** when the answer isn't in your vault.
+
+```console
+$ vault-ask "what did I decide about the pricing model?"
+Q: what did I decide about the pricing model?
+
+Flat 49 EUR/month, no per-seat pricing, decided after the churn analysis.
+[[Decisions/2026-Pricing|2026-Pricing]]
+
+Notes consulted:
+- [[Decisions/2026-Pricing|2026-Pricing]]
+- [[Meetings/2026-01-pricing-review|2026-01-pricing-review]]
+```
+
+Ask something that isn't in your notes and it won't make anything up:
+
+```console
+$ vault-ask "what is my bank account number?"
+Q: what is my bank account number?
+
+No note in the vault answers this question.
+```
+
+## Why
+
+A second brain is only useful if knowledge comes *back out*. Most "chat with your
+notes" tools either need a vector database and an indexing pipeline, or happily
+hallucinate plausible answers — a dealbreaker when your notes are medical, legal,
+or financial. `vault-ask` is the opposite: zero index, zero database, and a hard
+refusal guarantee. It runs `ripgrep` over your vault, ranks notes by term rarity
+(TF-IDF), and hands the best excerpts to whatever LLM you already use.
+
+## How it works
+
+1. **Candidate search** — `ripgrep` scans the whole vault in milliseconds.
+2. **IDF ranking** — notes are scored by the *rarity* of the query terms they
+   contain, so a rare, specific word (a project codename) outweighs a word that
+   appears in hundreds of notes. No embeddings, no index, no warm-up.
+3. **Focused excerpts** — only the headings and matching lines of the top notes
+   are sent to the model (notes can be long).
+4. **Grounded prompt** — the model must cite each claim as a `[[link]]`, must not
+   add outside knowledge, and must reply with a fixed refusal sentence if the
+   excerpts don't answer the question.
+5. **Robust refusal check** — a refusal (even reworded by the model) is never
+   dressed up as a sourced answer; its citations are stripped.
+
+Nothing leaves your machine except what your own LLM command chooses to send.
+
+## Install
+
+Requires **Python 3.9+** and **[ripgrep](https://github.com/BurntSushi/ripgrep)**
+(`rg`) on your `PATH`.
+
+```bash
+# pip (installs the `vault-ask` command)
+pip install git+https://github.com/guillaumevele/vault-ask.git
+```
+
+Or run it as a single file, no install:
+
+```bash
+git clone https://github.com/guillaumevele/vault-ask.git
+cd vault-ask
+python3 vault_ask.py "your question"
+```
+
+No dependencies beyond the Python standard library and ripgrep.
+
+## Configure your LLM
+
+`vault-ask` shells out to whatever LLM command you set in `VAULT_ASK_LLM`. The
+prompt is piped on **stdin** by default, or substituted for `{prompt}` if the
+command contains that placeholder.
+
+```bash
+# Local model via Ollama (prompt on stdin):
+export VAULT_ASK_LLM='ollama run llama3.1'
+
+# Simon Willison's `llm` CLI (any provider it supports):
+export VAULT_ASK_LLM='llm -m gpt-4o-mini'
+
+# A CLI that takes the prompt as an argument — use the {prompt} placeholder:
+export VAULT_ASK_LLM='your-llm-cli --prompt {prompt}'
+```
+
+Point it at your vault once:
+
+```bash
+export OBSIDIAN_VAULT="$HOME/Obsidian/MyVault"
+```
+
+## Usage
+
+```bash
+vault-ask "what did I decide about X?"
+vault-ask --vault ~/notes "when is the contract renewal?"
+vault-ask --limit 8 --json "summarize my pricing decisions"
+```
+
+No LLM? Use `--sources-only` to just rank the most relevant notes — a smart grep
+for your vault that needs no model at all:
+
+```bash
+vault-ask --sources-only "pricing model"
+# Most relevant notes for: pricing model
+# - [[Decisions/2026-pricing|2026-pricing]]
+# - [[Meetings/2026-01-pricing-review|2026-01-pricing-review]]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--vault` | `$OBSIDIAN_VAULT` or `.` | path to the vault |
+| `--limit` | `5` | max notes to consult |
+| `--llm` | `$VAULT_ASK_LLM` | LLM command (overrides env) |
+| `--sources-only` | off | rank relevant notes, no LLM call |
+| `--json` | off | raw structured output |
+| `--version` | | print version |
+
+## What it's good at — and what it isn't
+
+**Good at:** factual lookups where the words of your question point at a note —
+decisions, numbers, names, "what did I say about …". It's fast and it never lies.
+
+**Not good at:** abstract questions whose vocabulary differs from your notes (you
+ask "my funding strategy", the note says "tax credit"). That's the inherent limit
+of keyword retrieval — proper semantic recall needs embeddings, which this tool
+deliberately avoids to stay zero-dependency and zero-index. When it can't match,
+it refuses honestly rather than guessing.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+## Related
+
+[**voice-to-vault**](https://github.com/guillaumevele/voice-to-vault) is the other
+half of the loop: it routes your voice captures into the Obsidian vault that
+`vault-ask` then answers questions about. One files your thoughts, the other
+brings them back.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

vault_ask-0.1.1/vault_ask.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+vault_ask.py
+tests/test_vault_ask.py
+vault_ask.egg-info/PKG-INFO
+vault_ask.egg-info/SOURCES.txt
+vault_ask.egg-info/dependency_links.txt
+vault_ask.egg-info/entry_points.txt
+vault_ask.egg-info/top_level.txt

vault_ask-0.1.1/vault_ask.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vault_ask-0.1.1/vault_ask.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vault-ask = vault_ask:main

vault_ask-0.1.1/vault_ask.egg-info/top_level.txt

@@ -0,0 +1 @@
+vault_ask

vault_ask-0.1.1/vault_ask.py

@@ -0,0 +1,379 @@
+#!/usr/bin/env python3
+"""vault-ask — Ask your Obsidian vault, get cited answers, never hallucinate.
+
+A tiny, dependency-free grounded question-answering tool over a Markdown
+knowledge base (built for Obsidian, works on any folder of .md files).
+
+How it works:
+  1. Fast candidate selection with ripgrep over the whole vault.
+  2. Notes are ranked by IDF coverage — rare, specific terms (e.g. a project
+     codename) outweigh ubiquitous ones (e.g. a word in hundreds of notes).
+  3. Query-focused excerpts of the top notes are sent to your LLM with a strict
+     prompt: every claim MUST cite its source note as a [[wikilink]], and if the
+     excerpts don't answer the question the model MUST refuse instead of guessing.
+  4. A robust refusal check guarantees a refusal is never dressed up as a
+     sourced answer.
+
+The LLM is whatever command you configure via $VAULT_ASK_LLM, so it works with a
+local model (Ollama), a CLI like `llm`, or any subscription CLI you already use.
+Nothing leaves your machine except what your own LLM command sends.
+
+Usage:
+    export VAULT_ASK_LLM='ollama run llama3.1'        # or 'llm -m gpt-4o-mini', etc.
+    vault_ask.py --vault ~/Obsidian/MyVault "what did I decide about pricing?"
+
+Requires: Python 3.9+, ripgrep (`rg`) on PATH.
+License: MIT.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import unicodedata
+from pathlib import Path
+
+__version__ = "0.1.1"
+
+REFUSAL = "No note in the vault answers this question."
+
+# Directories that are noise, not knowledge — skipped during candidate search.
+DEFAULT_EXCLUDED_DIRS = (".obsidian", ".trash", ".git", "node_modules")
+
+# Stop / question / function words (EN + FR): noise for keyword candidate search.
+STOPWORDS = {
+    # English
+    "what", "which", "where", "when", "why", "how", "who", "whom", "whose",
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+    "do", "does", "did", "have", "has", "had", "for", "with", "from", "into",
+    "about", "that", "this", "these", "those", "and", "or", "but", "not",
+    "you", "your", "yours", "my", "mine", "our", "their", "its", "his", "her",
+    "can", "could", "should", "would", "will", "shall", "may", "might", "must",
+    "get", "got", "make", "made", "any", "some", "all", "more", "most", "than",
+    # French
+    "quel", "quels", "quelle", "quelles", "pourquoi", "comment", "quand",
+    "qui", "quoi", "est", "sont", "etait", "etre", "avoir", "faut", "fait",
+    "faire", "pour", "avec", "dans", "sur", "sous", "par", "des", "les",
+    "une", "mon", "mes", "ton", "tes", "son", "ses", "nos", "vos", "leur",
+    "leurs", "que", "dont", "cette", "cet", "ces", "celle", "celui", "donc",
+    "alors", "ainsi", "aussi", "plus", "moins", "tout", "tous", "toute",
+    "toutes", "deja", "encore", "vraiment", "bien", "retenu", "retenue",
+}
+
+
+def normalize(text: str) -> str:
+    """Lowercase + strip accents (NFKD) for accent/case-insensitive matching."""
+    decomposed = unicodedata.normalize("NFKD", str(text or ""))
+    stripped = "".join(ch for ch in decomposed if not unicodedata.combining(ch))
+    return stripped.lower()
+
+
+def query_terms(query: str, min_len: int = 3) -> list[str]:
+    """Content terms of the query: tokens >= min_len that are not stopwords."""
+    tokens = re.split(r"[^a-z0-9]+", normalize(query))
+    return [t for t in tokens if len(t) >= min_len and t not in STOPWORDS]
+
+
+def _vault_root(vault: Path) -> Path:
+    return vault.expanduser().resolve()
+
+
+def obsidian_link(vault: Path, path: Path) -> str:
+    """Obsidian-style [[relative/path|title]] link to a note."""
+    try:
+        rel = path.resolve().relative_to(_vault_root(vault))
+    except ValueError:
+        rel = Path(path.name)
+    return f"[[{rel.with_suffix('')}|{path.stem}]]"
+
+
+def note_excerpt(path: Path, terms: list[str], max_chars: int = 650, context: int = 1) -> str:
+    """Query-focused excerpt: headings + lines mentioning a term, plus a small
+    context window around each match (notes can be long, and a matched keyword's
+    answer often sits on the neighbouring wrapped line)."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+    if text.startswith("---\n"):
+        end = text.find("\n---\n", 4)
+        if end != -1:
+            text = text[end + 5:]
+    lines = text.splitlines()
+    keep_idx: set[int] = set()
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if not stripped:
+            continue
+        norm = normalize(line)
+        if stripped.startswith("#") or any(term in norm for term in terms):
+            for j in range(max(0, i - context), min(len(lines), i + context + 1)):
+                keep_idx.add(j)
+    kept = [lines[i].strip() for i in sorted(keep_idx) if lines[i].strip()]
+    body = "\n".join(kept) if kept else "\n".join(
+        l.strip() for l in lines if l.strip()
+    )
+    return body[:max_chars]
+
+
+def candidate_notes(
+    vault: Path,
+    query: str,
+    limit: int = 5,
+    excluded_dirs: tuple[str, ...] = DEFAULT_EXCLUDED_DIRS,
+    timeout_s: int = 20,
+) -> list[dict]:
+    """Select the most relevant notes via ripgrep, ranked by IDF coverage.
+
+    A note that contains rare, specific query terms ranks above a note merely
+    dense in a ubiquitous term, so the discriminating words decide relevance.
+    """
+    root = _vault_root(vault)
+    terms = query_terms(query)
+    if not terms or not root.is_dir():
+        return []
+    excludes: list[str] = []
+    for name in excluded_dirs:
+        excludes += ["-g", f"!{name}/**", "-g", f"!{name}"]
+
+    term_files: dict[str, dict[str, int]] = {}
+    for term in terms:
+        try:
+            proc = subprocess.run(
+                ["rg", "-c", "-i", "--glob", "*.md", *excludes, "--", term, str(root)],
+                capture_output=True, text=True, timeout=timeout_s,
+            )
+        except (OSError, subprocess.SubprocessError):
+            continue
+        if proc.returncode not in (0, 1):  # 1 = no matches, fine
+            continue
+        files: dict[str, int] = {}
+        for raw in proc.stdout.splitlines():
+            path, _, count = raw.rpartition(":")
+            path = path.strip()
+            if not path:
+                continue
+            try:
+                files[path] = int(count)
+            except ValueError:
+                files[path] = 1
+        if files:
+            term_files[term] = files
+    if not term_files:
+        return []
+
+    all_paths: set[str] = set()
+    for files in term_files.values():
+        all_paths |= set(files.keys())
+    total = max(len(all_paths), 1)
+
+    coverage: dict[str, set] = {}
+    idf_coverage: dict[str, float] = {}  # sum of idf over DISTINCT terms matched
+    tf_score: dict[str, float] = {}      # tf*idf, tie-breaker
+    for term, files in term_files.items():
+        idf = math.log((total + 1) / (len(files) + 1)) + 1.0
+        for path, tf in files.items():
+            coverage.setdefault(path, set()).add(term)
+            idf_coverage[path] = idf_coverage.get(path, 0.0) + idf
+            tf_score[path] = tf_score.get(path, 0.0) + min(tf, 8) * idf
+
+    ranked = sorted(
+        idf_coverage,
+        key=lambda p: (idf_coverage[p], tf_score[p]),
+        reverse=True,
+    )
+    notes: list[dict] = []
+    for path_str in ranked[:limit]:
+        path = Path(path_str)
+        notes.append({
+            "file": str(path),
+            "title": path.stem,
+            "link": obsidian_link(vault, path),
+            "excerpt": note_excerpt(path, terms),
+            "matched_terms": sorted(coverage[path_str]),
+        })
+    return notes
+
+
+def build_prompt(query: str, notes: list[dict]) -> str:
+    """Grounded prompt: mandatory [[citations]], explicit refusal if unsupported."""
+    blocks = []
+    for note in notes:
+        excerpt = (note.get("excerpt") or "").strip()
+        if not excerpt:
+            continue
+        blocks.append(f"[Source: {note['link']}]\n{excerpt}")
+    sources = "\n\n---\n\n".join(blocks)
+    return (
+        "You answer questions strictly from a personal Markdown knowledge base.\n"
+        "Use ONLY the note excerpts below. Absolute rules, no exceptions:\n"
+        "1. Every claim MUST be followed by its source as a [[link]], copied "
+        "EXACTLY from the 'Source:' line.\n"
+        "2. Invent nothing; add no outside knowledge.\n"
+        f"3. If the excerpts do not answer the question, reply with EXACTLY this "
+        f"and nothing else: {REFUSAL}\n"
+        "4. Be concise and factual: at most 3 lines, no preamble.\n\n"
+        f"QUESTION: {query}\n\n"
+        f"EXCERPTS:\n{sources}"
+    )
+
+
+def is_refusal(text: str) -> bool:
+    """Robust refusal detection (punctuation/case/accent insensitive). A refusal
+    must never be mistaken for a sourced answer."""
+    norm = normalize(text).strip().rstrip(".").strip()
+    target = normalize(REFUSAL).strip().rstrip(".").strip()
+    return bool(norm) and norm == target
+
+
+def run_llm(prompt: str, *, command: str | None = None, timeout_s: int = 120) -> str | None:
+    """Run the configured LLM command. If the command contains '{prompt}' the
+    prompt is substituted as an argument, otherwise it is piped via stdin.
+    Returns the text answer, or None on any failure (caller falls back)."""
+    command = command or os.environ.get("VAULT_ASK_LLM", "").strip()
+    if not command:
+        return None
+    try:
+        if "{prompt}" in command:
+            full = command.replace("{prompt}", shlex.quote(prompt))
+            proc = subprocess.run(
+                full, shell=True, capture_output=True, text=True, timeout=timeout_s,
+            )
+        else:
+            proc = subprocess.run(
+                shlex.split(command), input=prompt,
+                capture_output=True, text=True, timeout=timeout_s,
+            )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if proc.returncode != 0:
+        return None
+    out = (proc.stdout or "").strip()
+    return out or None
+
+
+def ripgrep_available() -> bool:
+    return shutil.which("rg") is not None
+
+
+def ask(
+    vault: Path,
+    query: str,
+    limit: int = 5,
+    command: str | None = None,
+    sources_only: bool = False,
+) -> dict:
+    """Grounded Q&A over the vault. Always returns a structured result; a missing
+    LLM or zero candidates yields an honest refusal, never a fabricated answer.
+    With sources_only=True, returns the ranked relevant notes and skips the LLM."""
+    query = re.sub(r"\s+", " ", str(query or "").strip())
+    if not query:
+        return {"ok": False, "reason": "empty-query"}
+    if not ripgrep_available():
+        return {"ok": False, "reason": "ripgrep-not-found"}
+    notes = candidate_notes(vault, query, limit=limit)
+    result = {
+        "ok": True,
+        "query": query,
+        "candidates": [{"title": n["title"], "link": n["link"]} for n in notes],
+    }
+    if sources_only:
+        result["answer"] = None
+        result["grounded"] = False
+        result["sources"] = [n["link"] for n in notes]
+        result["mode"] = "sources-only"
+        return result
+    if not notes:
+        result["answer"] = REFUSAL
+        result["grounded"] = False
+        result["sources"] = []
+        return result
+    text = run_llm(build_prompt(query, notes), command=command)
+    if not text:
+        result["answer"] = None
+        result["grounded"] = False
+        result["sources"] = []
+        result["reason"] = "no-llm"
+        return result
+    refused = is_refusal(text)
+    result["answer"] = REFUSAL if refused else text
+    result["grounded"] = not refused
+    result["sources"] = [] if refused else [n["link"] for n in notes]
+    return result
+
+
+def format_result(result: dict) -> str:
+    if not result.get("ok"):
+        reason = result.get("reason", "error")
+        if reason == "ripgrep-not-found":
+            return (
+                "vault-ask: ripgrep (`rg`) was not found on your PATH.\n"
+                "Install it: https://github.com/BurntSushi/ripgrep#installation"
+            )
+        if reason == "empty-query":
+            return "vault-ask: please provide a question."
+        return f"vault-ask: {reason}"
+    cands = result.get("candidates") or []
+    if result.get("mode") == "sources-only":
+        lines = [f"Most relevant notes for: {result['query']}", ""]
+        lines += [f"- {c['link']}" for c in cands] or ["(no matching notes)"]
+        return "\n".join(lines)
+    lines = [f"Q: {result['query']}", ""]
+    if result.get("answer"):
+        lines.append(result["answer"])
+    elif result.get("reason") == "no-llm":
+        lines.append(
+            "(No LLM configured or it failed — set $VAULT_ASK_LLM, "
+            "or use --sources-only. Relevant notes below.)"
+        )
+    if cands:
+        lines += ["", "Notes consulted:"]
+        lines += [f"- {c['link']}" for c in cands]
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Ask your Obsidian vault, get cited answers, never hallucinate.",
+    )
+    parser.add_argument("question", nargs="*", help="your question")
+    parser.add_argument(
+        "--vault",
+        default=os.environ.get("OBSIDIAN_VAULT", "."),
+        help="path to the vault (default: $OBSIDIAN_VAULT or current dir)",
+    )
+    parser.add_argument("--limit", type=int, default=5, help="max notes to consult")
+    parser.add_argument(
+        "--llm", default=None,
+        help="LLM command (default: $VAULT_ASK_LLM). Use '{prompt}' for arg-style.",
+    )
+    parser.add_argument(
+        "--sources-only", action="store_true",
+        help="just list the most relevant notes, no LLM call (a smart grep for your vault)",
+    )
+    parser.add_argument("--json", action="store_true", help="output raw JSON")
+    parser.add_argument("--version", action="version", version=f"vault-ask {__version__}")
+    args = parser.parse_args(argv)
+
+    question = " ".join(args.question).strip()
+    if not question:
+        parser.error("provide a question")
+    result = ask(
+        Path(args.vault), question,
+        limit=args.limit, command=args.llm, sources_only=args.sources_only,
+    )
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(format_result(result))
+    return 0 if result.get("ok") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())