obsidian-semantic 0.1.0__tar.gz

obsidian_semantic-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Check metadata
+        run: uvx twine check dist/*
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/obsidian-semantic
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish via trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

obsidian_semantic-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Project specific
+.scratch/

obsidian_semantic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Avila
+
+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.

obsidian_semantic-0.1.0/PKG-INFO

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: obsidian-semantic
+Version: 0.1.0
+Summary: Semantic search for Obsidian vaults
+Project-URL: Repository, https://github.com/ravila4/obsidian-semantic-search
+Project-URL: Issues, https://github.com/ravila4/obsidian-semantic-search/issues
+Project-URL: Changelog, https://github.com/ravila4/obsidian-semantic-search/releases
+Author-email: Ricardo Avila <ravila@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: embeddings,lancedb,obsidian,ollama,rag,semantic-search,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: lancedb>=0.5
+Requires-Dist: mcp>=1.26.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: structlog>=24.0
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.5; extra == 'gemini'
+Description-Content-Type: text/markdown
+
+# obsidian-semantic
+
+[![PyPI](https://img.shields.io/pypi/v/obsidian-semantic.svg)](https://pypi.org/project/obsidian-semantic/)
+[![Python](https://img.shields.io/pypi/pyversions/obsidian-semantic.svg)](https://pypi.org/project/obsidian-semantic/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Semantic search for Obsidian vaults. Index your vault into vector embeddings, then search by meaning rather than keywords.
+
+<p align="center">
+  <img src="docs/screenshot.svg" alt="obsidian-semantic CLI" width="600">
+</p>
+
+> **Using this with an AI agent (Claude Code, Cursor, etc.)?** See [SKILL.md](SKILL.md) for agent-facing guidance — score interpretation, workflows, and known gotchas.
+
+## Install
+
+```bash
+# As a standalone CLI (recommended)
+uv tool install obsidian-semantic
+
+# Or with pipx (also installs into an isolated environment)
+pipx install obsidian-semantic
+
+# With Gemini embedder support
+uv tool install "obsidian-semantic[gemini]"
+```
+
+Then configure:
+
+```bash
+obsidian-semantic configure
+```
+
+Configuration is stored in `~/.config/obsidian-semantic/config.yaml`. Supports Ollama (local), LM Studio (local), and Gemini embedders.
+
+### From source
+
+```bash
+git clone https://github.com/ravila4/obsidian-semantic-search
+cd obsidian-semantic-search
+uv sync
+uv run obsidian-semantic configure
+```
+
+## Usage
+
+### Index your vault
+
+```bash
+obsidian-semantic index                # incremental (new/modified files only)
+obsidian-semantic index --full         # reindex everything
+```
+
+### Search
+
+```bash
+obsidian-semantic search "dependency injection patterns"
+obsidian-semantic search "python testing" --limit 5
+obsidian-semantic search "docker" --folder "Programming/"
+obsidian-semantic search "habits" --tag "review"
+obsidian-semantic search "fisher" --score-min 0.6     # drop low-relevance hits
+obsidian-semantic search "fisher" --per-file 0        # show every matching chunk
+```
+
+By default, results are deduped to one chunk per file. Pass `--per-file N` to allow up to N chunks per file (or `0` for unlimited).
+
+`--score-min` thresholds need to account for dedup: the second-best file's surviving chunk often scores ~0.05–0.10 lower than the duplicate chunks it displaced, so a threshold tuned against raw chunk scores can drop relevant notes. Calibrate against the post-dedup output. Useful absolute bands on `ollama+nomic` are roughly: ≥0.65 strong title-level match, ≥0.5 topical, <0.4 likely noise. Other embedders (qwen3, gemini) sit on different scales.
+
+### Find related notes
+
+Find notes similar to a given note, useful for discovering connections, linking, or deduplication.
+
+```bash
+obsidian-semantic related "Programming/Python/Unit Testing.md"
+obsidian-semantic related "Daily/2026-02-05.md" --limit 5
+```
+
+If the note isn't in the index, it's chunked and embedded on the fly.
+
+### Show a note
+
+Print the full contents of a note straight to stdout. Accepts a vault-relative path or a bare filename (with or without `.md`); if the basename is unique, it's resolved automatically. Reads from disk, so it works on un-indexed files too (unlike `search`).
+
+```bash
+obsidian-semantic show "Fisher's Exact in Empiroar.md"
+obsidian-semantic show "Programming/Python/Unit Testing.md"
+obsidian-semantic show "Unit Testing.md#Setup#Installation"   # specific section
+```
+
+Append `#Heading` (or `#Parent#Child` for nested sections) to print just that section. Heading paths are matched against the breadcrumb suffix and are case-insensitive; ambiguous headings are listed with line numbers.
+
+### Suggest missing links
+
+Find semantically similar notes that aren't linked to each other -- surfaces missing wikilinks and potential duplicates.
+
+```bash
+obsidian-semantic suggest-links
+obsidian-semantic suggest-links --threshold 0.85 --limit 10
+obsidian-semantic suggest-links --exclude-same-folder "Daily Log"
+```
+
+Folders to exclude can also be set in config so you don't have to type them every time:
+
+```yaml
+suggest_links:
+  exclude_same_folder:
+    - "Daily Log"
+```
+
+### Status
+
+```bash
+obsidian-semantic status
+```
+
+### Options
+
+All commands accept `--vault <path>` to specify the vault. Alternatively, set `OBSIDIAN_VAULT` or configure a default with `obsidian-semantic configure --vault <path>`.
+
+## Embedding Backends
+
+Configuration lives in `~/.config/obsidian-semantic/config.yaml`. You can also place a `.obsidian-semantic.yaml` in your vault root to override per-vault.
+
+After changing the embedder or model, reindex with `obsidian-semantic index --full`.
+
+### Ollama with Nomic (default)
+
+Local embeddings with [nomic-embed-text](https://ollama.com/library/nomic-embed-text) (768 dimensions). Uses `search_query:`/`search_document:` prefixes for asymmetric retrieval.
+
+```yaml
+vault: ~/Documents/Obsidian-Notes
+embedder:
+  type: ollama
+  model: nomic-embed-text
+  dimension: 768
+  query_prefix: "search_query: "
+  document_prefix: "search_document: "
+```
+
+```bash
+ollama pull nomic-embed-text
+```
+
+### Ollama with Qwen3-embedding
+
+Higher-quality embeddings with [qwen3-embedding](https://ollama.com/library/qwen3-embedding) (4096 dimensions). Uses an instruction prefix for queries to improve retrieval.
+
+```yaml
+vault: ~/Documents/Obsidian-Notes
+embedder:
+  type: ollama
+  model: qwen3-embedding:8b
+  dimension: 4096
+  query_prefix: "Instruct: Given a search query, retrieve relevant notes\nQuery: "
+```
+
+```bash
+ollama pull qwen3-embedding:8b
+```
+
+### LM Studio
+
+Local embeddings via [LM Studio](https://lmstudio.ai)'s OpenAI-compatible API (`/v1/embeddings` on port 1234). Start the server first:
+
+```bash
+lms server start
+```
+
+#### LM Studio with Nomic
+
+```yaml
+vault: ~/Documents/Obsidian-Notes
+embedder:
+  type: lmstudio
+  model: text-embedding-nomic-embed-text-v1.5
+  dimension: 768
+  query_prefix: "search_query: "
+  document_prefix: "search_document: "
+```
+
+```bash
+lms get -y nomic-ai/nomic-embed-text-v1.5
+```
+
+#### LM Studio with Qwen3-embedding
+
+Higher-quality embeddings (4096 dimensions). Like the Ollama variant, uses an instruction prefix for queries to improve retrieval.
+
+```yaml
+vault: ~/Documents/Obsidian-Notes
+embedder:
+  type: lmstudio
+  model: text-embedding-qwen3-embedding-8b
+  dimension: 4096
+  query_prefix: "Instruct: Given a search query, retrieve relevant notes\nQuery: "
+```
+
+### Gemini
+
+Cloud embeddings via Google's [gemini-embedding-001](https://ai.google.dev/gemini-api/docs/embeddings) (3072 dimensions). Handles query vs. document task types automatically -- no prefix config needed. Requires a `GEMINI_API_KEY` environment variable.
+
+```yaml
+vault: ~/Documents/Obsidian-Notes
+embedder:
+  type: gemini
+  model: gemini-embedding-001
+  dimension: 3072
+```
+
+### Advanced Options
+
+**Timeout Configuration**
+
+The embedder request timeout (default: 30 seconds) can be increased for large files or slower models:
+
+```yaml
+embedder:
+  timeout: 60.0  # seconds
+```
+
+If you see timeout errors during indexing, try increasing this value. Very large notes with extensive JSON or code blocks may need 60-120 seconds.
+
+## Automatic Indexing
+
+### Linux (systemd)
+
+Create a service and timer in `~/.config/systemd/user/`:
+
+**`obsidian-semantic-index.service`**
+```ini
+[Unit]
+Description=Index Obsidian vault for semantic search
+
+[Service]
+Type=oneshot
+EnvironmentFile=%h/.config/obsidian-semantic/env
+ExecStart=/home/youruser/.local/bin/obsidian-semantic index
+```
+
+**`obsidian-semantic-index.timer`**
+```ini
+[Unit]
+Description=Run Obsidian semantic index hourly
+
+[Timer]
+OnCalendar=hourly
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+
+The `EnvironmentFile` is optional — use it to store secrets like `GEMINI_API_KEY` outside of the main config.
+
+Enable and start:
+
+```bash
+systemctl --user enable --now obsidian-semantic-index.timer
+```
+
+#### Multiple vaults
+
+To index additional vaults, add more `ExecStart` lines to the service (they run sequentially):
+
+```ini
+[Service]
+Type=oneshot
+EnvironmentFile=%h/.config/obsidian-semantic/env
+ExecStart=/home/youruser/.local/bin/obsidian-semantic index
+ExecStart=/home/youruser/.local/bin/obsidian-semantic index --vault /path/to/second-vault
+```
+
+### macOS (launchd)
+
+A ready-to-edit plist + wrapper script lives in [`scripts/launchd/`](scripts/launchd/). The wrapper opportunistically starts the LM Studio server (`lms server start`) before each run, so the agent works whether or not you remembered to leave the server up.
+
+Install once:
+
+```bash
+# Make obsidian-semantic available on PATH
+uv tool install -e .
+
+# Edit the absolute paths in the plist to match your home directory, then:
+cp scripts/launchd/com.ravila.obsidian-semantic-index.plist ~/Library/LaunchAgents/
+launchctl load -w ~/Library/LaunchAgents/com.ravila.obsidian-semantic-index.plist
+```
+
+Logs land at `~/Library/Logs/obsidian-semantic-index.log`.
+
+To unload or check status:
+
+```bash
+launchctl list | grep obsidian-semantic
+launchctl unload ~/Library/LaunchAgents/com.ravila.obsidian-semantic-index.plist
+```