interactive-semantic-hunt 0.1.0__py3-none-any.whl

interactive_semantic_hunt-0.1.0.dist-info/METADATA

@@ -0,0 +1,316 @@
+Metadata-Version: 2.4
+Name: interactive-semantic-hunt
+Version: 0.1.0
+Summary: Interactive semantic search for code, inspired by fzf
+Author-email: David Kristiansen <david@kristiansen.tech>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/davetothek/interactive-semantic-hunt
+Project-URL: Repository, https://github.com/davetothek/interactive-semantic-hunt
+Project-URL: Issues, https://github.com/davetothek/interactive-semantic-hunt/issues
+Keywords: search,semantic,embeddings,code,fzf,tui,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.5.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: textual>=0.70.0
+Requires-Dist: tree-sitter>=0.26.0
+Requires-Dist: tree-sitter-c>=0.24.2
+Requires-Dist: tree-sitter-cpp>=0.23.4
+Provides-Extra: llama
+Requires-Dist: llama-cpp-python>=0.2.75; extra == "llama"
+Requires-Dist: huggingface-hub>=0.23.0; extra == "llama"
+Provides-Extra: st
+Requires-Dist: sentence-transformers; extra == "st"
+Dynamic: license-file
+
+# ish — Interactive Semantic Hunt
+
+Semantic search for code, inspired by `fzf`. Point `ish` at a directory. It parses
+each source file into named chunks, embeds them with a local model, and ranks them
+against your query. Everything runs on your machine.
+
+Languages: Python, C and C++, Markdown, and AsciiDoc. Documentation is indexed
+beside the code it describes, so one query searches both.
+
+## Install
+
+```sh
+pip install interactive-semantic-hunt
+```
+
+Nothing in that install compiles: the default backend reaches Ollama over
+HTTP with the standard library. A backend that runs the model in this
+process is an extra — `[llama]` for llama.cpp, `[st]` for
+sentence-transformers.
+
+To work on ish itself, clone it and run `uv sync`.
+
+The default embedding backend is Ollama, which keeps the model resident so no
+run pays a model load. Start it once and pull the embedding model:
+
+```sh
+ollama serve
+ollama pull nomic-embed-text
+```
+
+Set `OLLAMA_HOST` to reach a daemon elsewhere.
+
+Two other backends need no daemon:
+
+- `--embedder llama.cpp` downloads a GGUF model and loads it per run. Slower per
+  query, faster for a first index of a large tree. Needs the `[llama]` extra.
+- `--embedder st` uses sentence-transformers. Needs the `[st]` extra.
+
+## Use
+
+List every chunk under a path:
+
+```sh
+ish src/
+```
+
+```
+src/ish/domain/chunk.py:7-28  class  Chunk
+```
+
+Search for a query:
+
+```sh
+ish "parse a python file" src/
+```
+
+```
+[0.71] src/ish/adapters/parser/python.py:14-31  method  PythonParser.parse
+```
+
+Run the interactive picker and open the selection in your editor. Type to
+search, `up`/`down` or `ctrl+p`/`ctrl+n` to move, `enter` to choose, `escape`
+to quit. Narrow without leaving the query line:
+
+```text
+state machine transitions              every language
+lang:cpp state machine transitions     the implementation
+lang:yaml under:/10.System/ state      the tests that cover it
+type:doc how do I configure this       the prose, not the code
+type:test,doc retry backoff            the tests and what they document
+```
+
+Press Tab to finish a filter word. `ty` becomes `type:`, `lang:cp` becomes
+`lang:cpp`, and `under:/s` becomes `under:/src/`; a word with several answers
+grows as far as they agree and names the rest. `ish-complete` does the work, so
+any picker can call it.
+
+`lang:`, `under:`, and `type:` work in the query line of every interface —
+the command line, the picker, Neovim, and MCP. The words are taken out
+before the query is embedded, so the model sees the question rather than
+how it was narrowed.
+
+A language may be named however it comes to mind. `c`, `c++`, `cxx`, `h`, and
+`hpp` all mean `cpp`, because one parser reads them all; `adoc` means
+`asciidoc`, `md` means `markdown`, `py` means `python`, and `yml` means `yaml`.
+
+`type:` sorts every chunk into exactly one kind. A path decides before a
+language does, so a YAML fixture counts as a test rather than as config:
+
+| kind | what it holds |
+|---|---|
+| `code` | Python, C, C++, and anything a plugin parser adds |
+| `doc` | Markdown and AsciiDoc |
+| `test` | anything under `tests/`, `spec/`, `fixtures/`, plus `test_*` and `conftest.py` |
+| `config` | YAML, JSON, and TOML outside a test path |
+
+A repository that names its trees its own way can say so, in
+`.ish/config.toml`:
+
+```toml
+type_patterns = [
+  "test:/[0-9.]*(Tests|Verification)/",
+  "doc:/[0-9.]*Specification/",
+]
+```
+
+The first match wins; anything unmatched keeps the reading above.
+
+A config beside a subtree adds to the one above it, so a tree settles only
+what it names and inherits the rest. Searching inside an already-indexed tree
+reads that tree's index and narrows the answers to the path, rather than
+starting a second index of the same files.
+
+```sh
+nvim $(ish -i src/)
+```
+
+### Options
+
+| Flag | Purpose |
+|---|---|
+| `-i`, `--interactive` | Run the TUI picker |
+| `--embedder {llama.cpp,ollama,st}` | Select the embedding backend (default: ollama) |
+| `-v`, `-vv` | Increase log detail |
+| `--color {auto,always,never}` | Control log color |
+| `--limit N` | Maximum search results |
+| `--ignore DIR ...` | Directory names to skip (default `.git .venv venv __pycache__`) |
+| `--include REGEX ...` | Index only paths matching these patterns |
+| `--exclude REGEX ...` | Never index paths matching these patterns |
+| `--git`, `--no-git` | Skip files git ignores (default: on) |
+| `--lang LANG ...` | Show results only from these languages |
+| `--under REGEX` | Show results only from matching paths |
+| `--type TYPE ...` | Show results only of these kinds: `code`, `doc`, `test`, `config` |
+| `--type-patterns TYPE:REGEX ...` | Say what a path holds, overriding the built-in reading |
+| `--model NAME` | Override the backend model |
+| `--refresh` | Bring every stored index at or below the path up to date first |
+| `--reindex` | Discard the stored index and build it again |
+| `--no-cache` | Index in memory only, leaving nothing on disk |
+
+Logs go to stderr, so you can pipe stdout safely. A file that cannot be read
+or parsed is counted in one line; `-v` names them.
+
+## Use from Neovim
+
+`contrib/nvim/ish.lua` is an fzf-lua picker. Copy it to `lua/utils/ish.lua` and
+bind it:
+
+```lua
+map('n', '<leader>fi', function() require('utils.ish').search() end,
+    { desc = 'Semantic search (ish)' })
+```
+
+It reads `--format grep`, so the built-in previewer opens each result at its
+line, and prints the rank in the leftmost column. `search_lang({'cpp'})`,
+`search_type({'doc'})`, and `search_here()` narrow it, as does a `lang:`,
+`type:`, or `under:` word typed into the query.
+
+While the index refreshes, `require('utils.ish').statusline()` renders a bar
+for a statusline — `ish ███░░░░░ 38%` — and an empty string when idle. It reads `vim.g.ish_index_status`, which the picker keeps up to date, and
+shows `ish ✓` briefly when a refresh finishes. Nothing is reported through
+`vim.notify`: with `cmdheight = 0` there is no command line to put a message
+in, so nvim draws one over the last screen row — the statusline itself.
+
+The picker never blocks the editor: results are written as they arrive, so
+typing stays smooth however long a search takes.
+
+`contrib/nvim/ish_server.lua` keeps one `ish-mcp` process per session. It
+starts on the first search and is reused after that, which cuts a keystroke
+from about 500 ms to about 150 ms. Copy it beside the picker.
+
+## Use from Python
+
+```python
+from ish.interfaces.python.api import Ish
+
+with Ish("src/") as ish:
+    for chunk, score in ish.search("type:doc how to configure", limit=5):
+        print(score, chunk.path, chunk.symbol)
+    print(ish.status())
+```
+
+`Ish` holds the index open, so a second query costs a search rather than a
+process start. It offers `search()`, `chunks()`, `index()`, `refresh_all()`,
+and `status()`, and reads `lang:`, `type:`, and `under:` out of the query
+exactly as the other interfaces do.
+
+## Use from an agent
+
+`ish-mcp` serves the same search over the Model Context Protocol, so an agent
+can query the index directly. Add it to a project with `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ish": { "command": "uv", "args": ["run", "ish-mcp"] }
+  }
+}
+```
+
+It offers `search_code`, `list_chunks`, `index_status`, and `refresh_index`. The server stays
+resident, so a query costs about 58 ms rather than a process start.
+
+A call may narrow one search with `lang`, `under`, `type`, and `limit`, or
+write the same filters into the query text. It cannot change
+what is indexed — those settings come from `ish.toml` only, so no single call can
+shrink an index that another call depends on.
+
+## Index
+
+The index persists in SQLite under `$XDG_DATA_HOME/ish/`, one file per scanned
+tree. **A search of a parent reads the indexes below it and refreshes none** —
+choosing one of them to write to would be wrong — so it warns and offers
+`--refresh`, which visits each tree in turn. A repeated query reuses it, so only changed files are parsed and only new
+text is embedded. A renamed file re-embeds nothing.
+
+Each index records the tree it was built from, so searching a directory also
+searches every index below it. Index the parts of a large project separately and
+search the whole from its root:
+
+```sh
+ish "warm" project/docs        # index one part
+ish "warm" project/firmware    # and another
+ish "how is exposure set" project    # searches both
+```
+
+Searching a parent never rewrites an index below it. Pass `--no-federate` to use
+only the index of the exact path.
+
+The index records where each chunk is — its path, line range, kind, and name —
+together with the embedding vector. It does not store the source, so it is not a
+second readable copy of your code. Previews are read from the file, which also
+means they always show the current content.
+
+## Configure
+
+Every command-line option is also a key in `ish.toml`, under the same name.
+Put project settings in `ish.toml` at the root of your repository:
+
+```toml
+embedder = "ollama"
+model = "mxbai-embed-large"
+limit = 10
+ignore = [".git", ".venv", "build", "node_modules"]
+
+# Regular expressions, searched against the path.
+exclude = ["/vendor/", "_pb2\\.py$", "(_test|_spec)\\.py$"]
+```
+
+`include` and `exclude` take regular expressions rather than globs, so `/vendor/`
+matches at any depth and alternation works. `exclude` wins over `include`.
+
+`--git` is on by default, so anything a `.gitignore` covers stays out of the
+index. Pass `--no-git` to index it anyway.
+
+`--lang` and `--under` narrow what a search *returns*. They never change what is
+indexed, so a narrowed query cannot shrink the index:
+
+```sh
+ish "how is ranking done" --lang python
+ish "installation steps" --lang markdown asciidoc
+ish "parse a header" --under '/include/'
+```
+
+User-level defaults go in `~/.config/ish/ish.toml`. Later sources win:
+
+```
+defaults < ~/.config/ish/ish.toml < ./ish.toml < ISH_* environment < command line
+```
+
+Set any option from the environment with the `ISH_` prefix, for example
+`ISH_LIMIT=20` or `ISH_IGNORE=build,dist`.
+
+## Develop
+
+```sh
+uv run poe check   # lint, typecheck, test
+```
+
+The architecture is ports and adapters. `spec.md` holds the requirements, and
+`.claude/CLAUDE.md` describes the layers and the composition root.

interactive_semantic_hunt-0.1.0.dist-info/RECORD

@@ -0,0 +1,54 @@
+interactive_semantic_hunt-0.1.0.dist-info/licenses/LICENSE,sha256=_tIgsjXEpm2J-zkIN9m7SkL-K2LkgHWfBcS_Y7aFzqY,1074
+ish/__init__.py,sha256=W9wJYhAv0PwnXHkhf6caJfYO5OXH73Y-g_PoehyPLWU,294
+ish/bootstrap.py,sha256=4IiaxP6UaRhSts30Nu4jWWpIX69-pKce0xFMJbWEJhw,13770
+ish/settings.py,sha256=2LhHGDWyhZXTbNq-MlW1sClJjEz5a0Fxs-W1qWHaWmM,12521
+ish/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/adapters/embedder/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/adapters/embedder/llama_cpp.py,sha256=_GnRmYcTiBZ-reMFFMnRuSvWdhIMJTUb33pOXTD224I,1746
+ish/adapters/embedder/ollama.py,sha256=cnLcTgR6mkNf5I4LLcVxXqkpPcBn3gLtBL70SB7BxyM,4209
+ish/adapters/embedder/prefixes.py,sha256=M7ThGfjDL8sV_eVZPiCmXR5IR5CT8d9iT8bEOvm3vKk,3076
+ish/adapters/embedder/sentence_transformer.py,sha256=z9z5CiF1WRZ-_bNVYXBm2jWp58nxw0FbuTd4KYejFKM,1796
+ish/adapters/parser/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/adapters/parser/limits.py,sha256=Vgv9gzsZRpJMcORKgNeJJND6kAfLSN79xzI-6_GQb3g,3161
+ish/adapters/parser/markup.py,sha256=QCwK5ExyqXTkQkmuEfJ3h-7j9OG1mJE4vuuyiZlzQdU,3312
+ish/adapters/parser/plugins.py,sha256=8Ob6J6kPHtp5qVEU9a2Q7AqoIg8ZWvR8EIPNkk9uOZI,4166
+ish/adapters/parser/python.py,sha256=2Oguh249O1EHeuk0Gq1PthSqDFnHFf48xBQ_DzVbU2s,4293
+ish/adapters/parser/structured.py,sha256=HyuKUCVdaz2sJJNWXCcLy1FWob_KywLOJ5pUh4qytRg,8124
+ish/adapters/parser/tree_sitter.py,sha256=KHnWKdMnNke2Y4l3MyeJJDpImtOdZVoyxGFmNUPDjOY,8673
+ish/adapters/vcs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/adapters/vcs/git.py,sha256=nzXiLJHwHTYDaHoAjsEFpNYua-CdRE_MqnEkA7FEW9k,2986
+ish/adapters/vector_store/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/adapters/vector_store/federated.py,sha256=ZmVDXE3LLe225uGNuYCqe-2Drfd-Ef-w5C_0yV-TWzs,4328
+ish/adapters/vector_store/pure_python.py,sha256=fZBmbFlb7zLAEI5wpAHDt3wh9wDpHZBoe4x4ojyt0So,5672
+ish/adapters/vector_store/sqlite.py,sha256=VrnC-Q5rKL0J7Prd7JqVoaOtA89jvhUsLFgpo4mjzzw,20171
+ish/application/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/application/index.py,sha256=AyE8ka8SLBlpS6HPhzvZqp4by2k-lzEUTSB3bFYwFwo,8022
+ish/application/preview.py,sha256=sSIW4vfqpZW6b4Q9CSqdrsl7qyVRqshqFeKQwStLgtU,1320
+ish/application/scan.py,sha256=WVvkownLTP3jBt1VsAaVzw5N3tUxtKDg0zghs6ATwnI,6589
+ish/application/search.py,sha256=0VpiJwUUfVvTWeODy5kXSX5tSEuT15pKdQnqejZnqTM,12265
+ish/application/ports/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/application/ports/embedder.py,sha256=ZBiQ-8gz31XcPRRKUvbICSrTo2Ya8xecogKhimsSRWs,987
+ish/application/ports/parser.py,sha256=KjCaB0YDdKna0O9mdab5B5c5MvntWJMTmzWxXiamapg,1059
+ish/application/ports/vector_store.py,sha256=GlbQc_b0ZEwJaKGegzkDIK7G224BKb3uu-CLemMEFAI,5494
+ish/domain/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/domain/chunk.py,sha256=O5xo3KAaumkScYgGVtX7EAv1oICGKLb1eyjmBAbo66c,1058
+ish/interfaces/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/interfaces/complete.py,sha256=77f0ZK7ozvEFvST6rQtF4n8YqVO58IueQouSjh69_mg,3947
+ish/interfaces/format.py,sha256=EupJWKg65lSAHqvfB6hu-TzlX9Qu5IP9DYfyVIpg_2U,1584
+ish/interfaces/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/interfaces/cli/args.py,sha256=3m_aD8BlmG4steJInPxdkpxeHDwtj1OW6T_ua9HjUOU,5406
+ish/interfaces/cli/complete.py,sha256=4STpIDg17JykuJQvYLDSVYOFM6iyTSP7R3IzrjV1l64,1663
+ish/interfaces/cli/log.py,sha256=UCLJslCcQa-zbBwnYde5KtjmHRZEbtJFzLgEbHSy9j0,3988
+ish/interfaces/cli/main.py,sha256=TCYnKgEmnjc-3xCsYUpX5tR5__GP2KS-VGikPzKvx9A,5188
+ish/interfaces/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/interfaces/mcp/protocol.py,sha256=b8iPjd7u78HR6ss066l2Iew85chjWa0LORwHBLdCpmM,6042
+ish/interfaces/mcp/server.py,sha256=Td-2FA7ZknXcw_-_-xGkX56bihJclbAHhVGEU_qopRg,14628
+ish/interfaces/python/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/interfaces/python/api.py,sha256=PA69SyJ6N2k6ZBVOwzCneCu24D9lSDp69CKElqmOSe4,6687
+ish/interfaces/tui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ish/interfaces/tui/app.py,sha256=aFwwbxFR4iku8H3UxecxTowL_nWrLz51dHbgthcD5VY,14840
+interactive_semantic_hunt-0.1.0.dist-info/METADATA,sha256=M9JZEOFrQJgQ2-28tksaswATOwuvc--jJ6sqGlsOPAc,11636
+interactive_semantic_hunt-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+interactive_semantic_hunt-0.1.0.dist-info/entry_points.txt,sha256=Gw9kcf_Ijny8kgKQ1gDZTdtKrTkp3P1ahGkH7_qRALA,142
+interactive_semantic_hunt-0.1.0.dist-info/top_level.txt,sha256=iEzghqES9lDeQgVwT6pm7BwRfGDSnYFvuQ6jmqbyM50,4
+interactive_semantic_hunt-0.1.0.dist-info/RECORD,,

interactive_semantic_hunt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

interactive_semantic_hunt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+ish = ish.interfaces.cli.main:main
+ish-complete = ish.interfaces.cli.complete:main
+ish-mcp = ish.interfaces.mcp.server:main

interactive_semantic_hunt-0.1.0.dist-info/licenses/LICENSE

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

interactive_semantic_hunt-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ish

ish/__init__.py

@@ -0,0 +1,6 @@
+"""ish — Interactive Semantic Hunt. A semantic search tool for code.
+
+Keep this module free of layer imports. The package root must not pull
+in interfaces, application, or adapter code — import from the layer
+modules directly, for example ``from ish.interfaces.python.api import Ish``.
+"""

ish/adapters/embedder/llama_cpp.py

@@ -0,0 +1,50 @@
+"""llama.cpp adapter for the Embedder protocol."""
+
+from collections.abc import Sequence
+
+from ish.adapters.embedder.prefixes import PrefixingEmbedder
+
+
+class LlamaCppEmbedder(PrefixingEmbedder):
+    """Generate embeddings using a local GGUF model via llama.cpp.
+
+    Automatically downloads `nomic-embed-text` from Hugging Face if not present.
+    """
+
+    def __init__(
+        self,
+        repo_id: str = "nomic-ai/nomic-embed-text-v1.5-GGUF",
+        filename: str = "nomic-embed-text-v1.5.Q4_K_M.gguf",
+    ) -> None:
+        # Expose the model identity for cache keying.
+        self.model_name = f"{repo_id}/{filename}"
+
+        import os
+
+        from huggingface_hub.utils.logging import set_verbosity_error
+
+        # Suppress huggingface_hub network warnings
+        os.environ["HF_HUB_DISABLE_TELEMETRY"] = "1"
+        os.environ["HF_HUB_DISABLE_SYMLINKS_WARNING"] = "1"
+        set_verbosity_error()
+
+        from huggingface_hub import hf_hub_download
+        from llama_cpp import Llama
+
+        # 1. Download/find the model on disk
+        model_path = hf_hub_download(repo_id=repo_id, filename=filename)
+
+        # 2. Instantiate the engine. verbose=False hides the massive C++ startup logs.
+        self._model = Llama(model_path=model_path, embedding=True, verbose=False)
+
+    def _embed(self, texts: Sequence[str]) -> Sequence[Sequence[float]]:
+        """Encode texts into vectors via llama.cpp."""
+        text_list = list(texts)
+
+        # create_embedding accepts a single string or a list of strings
+        result = self._model.create_embedding(text_list)
+
+        from typing import cast
+
+        embeddings = [item["embedding"] for item in result["data"]]
+        return cast("Sequence[Sequence[float]]", embeddings)

ish/adapters/embedder/ollama.py

@@ -0,0 +1,112 @@
+"""Ollama adapter for the Embedder protocol.
+
+Call the local Ollama daemon over HTTP with the standard library. The
+daemon holds the model resident, so no process pays a model load, and
+the adapter needs no third-party package.
+"""
+
+import json
+import logging
+import os
+import urllib.error
+import urllib.request
+from collections.abc import Sequence
+
+from ish.adapters.embedder.prefixes import PrefixingEmbedder
+
+log = logging.getLogger(__name__)
+
+DEFAULT_HOST = "http://localhost:11434"
+DEFAULT_MODEL = "nomic-embed-text"
+
+# Send this many texts per request. One request for a whole repository
+# would hold the daemon for minutes and risk the timeout.
+DEFAULT_BATCH_SIZE = 64
+# A batch of large definitions can take minutes on a busy daemon.
+TIMEOUT_SECONDS = 600
+
+
+def _normalize_host(host: str) -> str:
+    """Accept a bare ``host:port`` as well as a full URL."""
+    host = host.rstrip("/")
+    if not host.startswith(("http://", "https://")):
+        return f"http://{host}"
+    return host
+
+
+class OllamaEmbedder(PrefixingEmbedder):
+    """Generate embeddings through a running Ollama daemon.
+
+    Read ``OLLAMA_HOST`` when no host is given, matching the Ollama
+    command-line tools.
+    """
+
+    def __init__(
+        self,
+        model_name: str = DEFAULT_MODEL,
+        *,
+        host: str | None = None,
+        batch_size: int = DEFAULT_BATCH_SIZE,
+    ) -> None:
+        self.model_name = model_name
+        chosen = host or os.environ.get("OLLAMA_HOST") or DEFAULT_HOST
+        self.host = _normalize_host(chosen)
+        self._batch_size = max(1, batch_size)
+
+    def _embed(self, texts: Sequence[str]) -> Sequence[Sequence[float]]:
+        """Encode texts into vectors, one batch of requests at a time."""
+        items = list(texts)
+        vectors: list[Sequence[float]] = []
+        for start in range(0, len(items), self._batch_size):
+            vectors.extend(self._embed_batch(items[start : start + self._batch_size]))
+        return vectors
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _embed_batch(self, batch: list[str]) -> list[Sequence[float]]:
+        """Send one batch and return its vectors."""
+        payload = json.dumps({"model": self.model_name, "input": batch}).encode("utf-8")
+        request = urllib.request.Request(
+            f"{self.host}/api/embed",
+            data=payload,
+            headers={"Content-Type": "application/json"},
+        )
+
+        try:
+            with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
+                body = json.loads(response.read())
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", "replace").strip()
+            if exc.code == 404:
+                hint = f"Pull it with 'ollama pull {self.model_name}'."
+            else:
+                hint = (
+                    f"Confirm that {self.model_name!r} is an embedding model, "
+                    f"not a generation model."
+                )
+            raise RuntimeError(
+                f"Ollama refused the request ({exc.code}): {detail}. {hint}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise RuntimeError(
+                f"Cannot reach Ollama at {self.host}: {exc.reason}. "
+                f"Start it with 'ollama serve', or install another backend "
+                f"and select it, as in "
+                f"'pip install interactive-semantic-hunt[llama]' "
+                f"then '--embedder llama.cpp'."
+            ) from exc
+        except json.JSONDecodeError as exc:
+            raise RuntimeError(
+                f"Ollama at {self.host} returned a reply that is not JSON."
+            ) from exc
+
+        embeddings = body.get("embeddings")
+        if not isinstance(embeddings, list) or len(embeddings) != len(batch):
+            got = len(embeddings) if isinstance(embeddings, list) else 0
+            raise RuntimeError(
+                f"Ollama returned {got} vectors for {len(batch)} texts. "
+                f"Confirm that {self.model_name!r} is an embedding model."
+            )
+        return embeddings

ish/adapters/embedder/prefixes.py

@@ -0,0 +1,87 @@
+"""Apply the task prefixes an embedding model was trained with.
+
+Several retrieval models expect the caller to say whether a text is a
+stored document or a search query, and they lose accuracy without it.
+The convention belongs to the model, not to the backend serving it, so
+both the llama.cpp and the Ollama adapter read the same table.
+
+Measured on this repository with nomic-embed-text, 16 queries: the
+prefixes moved top-1 accuracy from 62% to 75%.
+"""
+
+from collections import OrderedDict
+from collections.abc import Sequence
+
+# Model name prefix -> (document prefix, query prefix).
+# Match on the start of the name, so a tag such as ":latest" still hits.
+_CONVENTIONS: dict[str, tuple[str, str]] = {
+    "nomic-embed-text": ("search_document: ", "search_query: "),
+    "nomic-ai/nomic-embed-text": ("search_document: ", "search_query: "),
+    "mxbai-embed-large": (
+        "",
+        "Represent this sentence for searching relevant passages: ",
+    ),
+}
+
+
+def prefixes_for(model_name: str) -> tuple[str, str]:
+    """Return the (document, query) prefixes for *model_name*.
+
+    Return empty strings for a model with no known convention, which
+    leaves the text untouched.
+    """
+    name = model_name.lower()
+    for known, pair in _CONVENTIONS.items():
+        if known in name:
+            return pair
+    return ("", "")
+
+
+# How many recent queries to keep. Typing walks over the same text as
+# characters are added and removed, so a small cache turns a backspace
+# from a request into a lookup.
+QUERY_CACHE_SIZE = 128
+
+
+class PrefixingEmbedder:
+    """Add task prefixes, then hand the text to the concrete backend.
+
+    Subclasses set ``model_name`` and implement ``_embed``.
+    """
+
+    model_name: str
+
+    def embed_documents(self, texts: Sequence[str]) -> Sequence[Sequence[float]]:
+        """Embed texts that will be stored and searched over."""
+        if not texts:
+            return []
+        prefix, _ = prefixes_for(self.model_name)
+        prepared = [f"{prefix}{text}" for text in texts] if prefix else list(texts)
+        return self._embed(prepared)
+
+    def embed_query(self, text: str) -> Sequence[float]:
+        """Embed one search query, reusing a recent answer.
+
+        An interactive search embeds a query on every keystroke, and
+        deleting a character asks for text already seen.
+        """
+        cache = getattr(self, "_query_cache", None)
+        if cache is None:
+            cache = self._query_cache = OrderedDict()
+        held = cache.get(text)
+        if held is not None:
+            cache.move_to_end(text)
+            return held
+
+        _, prefix = prefixes_for(self.model_name)
+        vectors = self._embed([f"{prefix}{text}" if prefix else text])
+        vector = vectors[0] if vectors else []
+
+        cache[text] = vector
+        if len(cache) > QUERY_CACHE_SIZE:
+            cache.popitem(last=False)
+        return vector
+
+    def _embed(self, texts: Sequence[str]) -> Sequence[Sequence[float]]:
+        """Encode already-prepared texts. Implemented by each adapter."""
+        raise NotImplementedError