isaac-vault-search

Personal fragment retrieval + composition tool. Obsidian vault → Ollama embeddings → Qdrant → chat + canvas.

Status: v0 — MVP cut.

Design

• DESIGN.md — big-picture: topology, philosophy, boundaries, what's intentionally out of scope.
• docs/IMPLEMENTATION_DESIGN.md — fine-grained: module layout, function signatures, full request/response contracts, canvas JSON schema, fragment card JSON schema, error matrix, performance budgets, and the UI test specification.

Read DESIGN.md first. The implementation doc is its companion and answers the "how" questions.

Repository layout

isaac-vault-search/
├── DESIGN.md, docs/                  # design docs
├── pyproject.toml                    # deps
├── search/                           # FastAPI app (chat + canvas)
├── indexer/                          # CLI (vault -> Qdrant)
├── tests/                            # pytest + UI test spec
├── canvases/                         # saved canvases (.json)
└── README.md                         # this file

Running locally

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Set up env
cp .env.example .env
# Edit .env to fill in QDRANT_API_KEY and any other paths

# Make sure Ollama is running locally with the required models.
ollama serve &
ollama pull qwen2.5:14b
ollama pull nomic-embed-text

# Index the vault (one-shot).
python -m indexer.indexer

# Run the web app.
uvicorn search.app:_build_default_app --factory --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000.

Testing

source .venv/bin/activate
pytest tests/ -v

Tests mock Qdrant and Ollama — no real services required to run the suite.

What's in v0

1. ✅ Vault indexer: walk ~/projects/obsidian/{quotations,facts,thoughts}/, embed each .md with nomic-embed-text, upsert to Qdrant. Idempotent.
2. ✅ Chat panel: send a message → LLM (qwen2.5:14b) with the query_fragments tool → grounded response.
3. ✅ Fragment cards: cited fragments render as draggable cards beneath each LLM response.
4. ✅ Canvas: a 2D surface next to the chat. Drag cards in; reorder; delete.
5. ✅ Save canvas: name it; persist as JSON in canvases/.
6. ✅ Export canvas: download as .md with fragments in order.
7. ✅ List / load / delete canvases.

What's deferred

• Other vault operations from the vault-vector vocabulary (antipode, divergence, bridge, constellate, suture, topology). The LLM tool surface in v0 is query_fragments only.
• Streaming chat responses (v0 is single-shot).
• Persistent chat history (v0 lives in page state).
• Multi-canvas library UI.
• LLM composition assistant.
• Standalone text-search bar (LLM is the search surface).
• Random / shuffle / surprise-me.
• 2D map / UMAP projection.
• Refactor of vault-vector scripts.
• OpenAI / hosted embeddings (local nomic-embed-text only).